gateway api documentation - eu-api.segway.pt api documentation v1.1.… · this manual provides the...

GATEWAY API DOCUMENTATION

Version: 1.1

JUNE 11, 2019 SEGWAY DISCOVERY

14 Technology Dr, Bedford, NH 03110

i

Revision history:

Version Published date Remarks

V1.0 2018-09-03 First Edition

V1.1 2019-06-11 Changes in Get Current Status, Lock, Set upload Interval

ii

About this manual.

This manual provides the detail information of Restful API required for communicating with Segway discovery scooters. It is maintained by the Segway Discovery team and is available on the website https://api.segway.pt/doc/. This manual refers to the API version 0.3.1

The first section “FUNCTION” gives us information about a selected function. It shows what are the parameter required for executing the selected function and what are the possible outcome from function. All the desired behavior for scooter like locked, unlocked, power on, power off, toot, setting values etc. are achieved with the help of the function so one will have to find which function provides satisfy the users requirement.

The second section is about the FILEDS. A function can have several field that either can be input or also can be the output. In this section one can find what is the field name and what function that field is related to. The final section i.e. third section of the manual gives some steps involved in achieving some behaviors like changing the scooters status’s data uploading behaviors, lock, unlock of the scooter.

https://api.segway.pt/doc/

iii

Table of Contents 1. FUNCTION ...................................................................................................................................... 1

1.1. Request the access token ........................................................................................................... 1

1.2. Get current firmware version .................................................................................................... 1

1.3. Get Current Status ..................................................................................................................... 2

1.4. Get Scooter Battery Info ........................................................................................................... 4

1.5. Headlight On/OFF .................................................................................................................... 5

1.6. Light Flicker ON/OFF .............................................................................................................. 5

1.7. Unlock ....................................................................................................................................... 6

1.8. Lock .......................................................................................................................................... 7

1.9. Power Up/Down ........................................................................................................................ 7

1.10. Speed Mode .......................................................................................................................... 8

1.11. Throttle Response ON/OFF .................................................................................................. 9

1.12. Toot ....................................................................................................................................... 9

1.13. Get Bluetooth Key .............................................................................................................. 10

1.14. Set Bluetooth Key ............................................................................................................... 11

1.15. Set Upload Interval ............................................................................................................. 12

1.16. Set Scooter Setting .............................................................................................................. 12

1.17. Set Speed Limit ................................................................................................................... 13

1.18. Push Scooter Alert .............................................................................................................. 14

1.19. Push Scooter Fault .............................................................................................................. 15

1.20. Push scooter status .............................................................................................................. 15

1.21. Push Scooter when upgrade complete ................................................................................ 16

1.22. Get Firmware List ............................................................................................................... 16

1.23. Upgrade device ................................................................................................................... 17

1.24. Get Firmware Upgrade task ................................................................................................ 17

1.25. Get firmware ....................................................................................................................... 18

1.26. Get Scooter IoT Binding Info. ............................................................................................ 19

1.27. Scooter IoT Binding ............................................................................................................ 19

2. FIELDS ........................................................................................................................................... 21

2.1. Content Type ........................................................................................................................... 21

iv

2.2. Authorization .......................................................................................................................... 21

2.3. Client Id .................................................................................................................................. 22

2.4. Client Secret ............................................................................................................................ 22

2.5. Grant Type .............................................................................................................................. 22

2.6. IoT Code ................................................................................................................................. 23

2.7. Vehicle Code ........................................................................................................................... 23

2.8. Real Time Status ..................................................................................................................... 24

2.9. Real Time Location ................................................................................................................. 24

2.10. Control Type ....................................................................................................................... 25

2.11. Head Light Flicker .............................................................................................................. 25

2.12. Tail Light Flicker ................................................................................................................ 25

2.13. Speed Mode ........................................................................................................................ 25

2.14. Key ...................................................................................................................................... 26

2.15. Upload Interval ................................................................................................................... 26

2.16. BssDisplay .......................................................................................................................... 27

2.17. Cruise Control ..................................................................................................................... 27

2.18. Button Switch Speed Mode................................................................................................. 27

2.19. Low Speed Limit ................................................................................................................. 27

2.20. Medium Speed Limit .......................................................................................................... 28

2.21. High Speed Limit ................................................................................................................ 28

2.22. Signature ............................................................................................................................. 28

2.23. Type/ Firmware Type.......................................................................................................... 28

2.24. Upgrade Task ID ................................................................................................................. 29

2.25. Firmware ID ........................................................................................................................ 29

2.26. Vehicle IoT Codes .............................................................................................................. 29

2.27. Upgrade ALL Devices ........................................................................................................ 29

2.28. SN ....................................................................................................................................... 29

2.29. ICCID .................................................................................................................................. 30

2.30. QRCODE ............................................................................................................................ 30

2.31. BLEMAC ............................................................................................................................ 30

2.32. Access Token ...................................................................................................................... 30

2.33. Token Type ......................................................................................................................... 30

2.34. Expires in ............................................................................................................................ 31

v

2.35. Scope ................................................................................................................................... 31

2.36. IoT Version ......................................................................................................................... 31

2.37. Vehicle Controller Version ................................................................................................. 31

2.38. Vehicle Dashboard Version ................................................................................................ 32

2.39. Vehicle BuildInBattery Version .......................................................................................... 32

2.40. Vehicle PlugInBattery Version ........................................................................................... 32

2.41. Online .................................................................................................................................. 32

2.42. Locked................................................................................................................................. 32

2.43. LockVoltage ........................................................................................................................ 33

2.44. Charging .............................................................................................................................. 33

2.45. Power Percent ..................................................................................................................... 33

2.46. Speed ................................................................................................................................... 33

2.47. Odometer ............................................................................................................................. 34

2.48. Remaining Range ................................................................................................................ 34

2.49. Total Riding Secs ................................................................................................................ 34

2.50. Status UtcTime .................................................................................................................... 34

2.51. Latitude ............................................................................................................................... 34

2.52. Longitude ............................................................................................................................ 34

2.53. Satellite Number ................................................................................................................. 34

2.54. Hdop (Horizontal Dilution of precision) ............................................................................. 35

2.55. Altitude ............................................................................................................................... 35

2.56. Gps UtcTime ....................................................................................................................... 35

2.57. Controller Voltage .............................................................................................................. 35

2.58. Battery Circle Number ........................................................................................................ 35

2.59. Battery Percent1 .................................................................................................................. 35

2.60. Battery Percent2 .................................................................................................................. 35

2.61. Build in Battery Temp1....................................................................................................... 35

2.62. buildin Battery Temp2 ........................................................................................................ 36

2.63. plugin Battery Temp1 ......................................................................................................... 36

2.64. plugin Battery Temp2 ......................................................................................................... 36

2.65. Success ................................................................................................................................ 36

2.66. Message ............................................................................................................................... 37

2.67. Code .................................................................................................................................... 37

vi

2.68. Error .................................................................................................................................... 38

2.69. Error Description ................................................................................................................ 39

2.70. Network Signal ................................................................................................................... 39

3. EXAMPLE ...................................................................................................................................... 40

3.1. Get Authorization key ............................................................................................................. 40

3.2. To find if scooter is charging or not ........................................................................................ 40

3.3. To lock the scooter .................................................................................................................. 41

3.4. To change the upload interval to 20 secs when the scooter is in unlocked state..................... 41

3.5. To Change the upload interval to 5 min when the scooter is in locked state .......................... 41

1

1. FUNCTION 1.1. Request the access token

Access token key is required for all the other API call actions or functions. In order to have an

access token, the user must have a client Id and the password (Client secret) which they can get

from Segway team. There are only 2 possible outcomes i.e. success or failure of request. If the

request is success it will return the access token along with other information like the expiry

time of the access token, the token scope and its type. If the request is failed it will give the

error with error description.

Function Input Output Wrapped Heading Field Field Type

Required Input

Header Content-Type String

Parameter

Client Id String

Client secret String

Grant type String

Possible Output

Success (200)

access token Guid

token type String

expires in Int

scope String[]

Failed (401)

Unauthorized

Error String

Error Description String

NOTE: Once you call this function you will be provided with access token that is valid for 12 hours. This access token has to be saved in your server as it is necessary for creating request. Please do not call this function until the access token expires i.e. once you get the access token it is not suggested to call this function again until the access token expires.

1.2. Get current firmware version We use this function to get the current firmware version installed on scooter components as

given: plugged in battery, built in battery, IoT, vehicle dashboard and vehicle controller.

Authorization, IoT Code and the Vehicle Code are three field required to get this query feedback

successfully. In case of failure there will be two possible outcomes from the server, one is failed

400 and another 401.

Function Input Output Wrapped Heading Field Field Type

Required Input Header

Authorization String

2

Parameter IoT Code String

Vehicle Code String

Possible Output

Success (200)

IoT Code String

Vehicle Code String

IoT Version String

Vehicle

Controller

Version

Number

Vehicle

Dashboard

Version

Number

Vehicle

BuildInBattery

Version

Number

Vehicle

PlugInBattery

Version

Number

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String

Error

Description String

1.3. Get Current Status We use this function to get the current status of the scooter. This function’s output parameters

are also pushed to the attached server by the push notification function (For timing please refer

field upload Interval). In case of failure there will be two possible outcomes from the server one

is failed 400 and another 401.

Function Input Output

Wrapped Heading Field Field Type

Required Input Header Authorization String


3

Vehicle Code String

Real Time Status(optional) Boolean

Real Time Location(optional) Boolean

Possible Output

Success (200)

online Boolean

iotCode String

vehicleCode String

Locked Boolean

lockVoltage Number

Network signal Number

charging Boolean

Power Percent Number

Speed Mode Number

speed Number

odometer Number

Remaining Range Number

Total Riding Secs Number

Status UtcTime Date

latitude Number

longitude Number

Satellite Number Number

hdop Number

altitude Number

Gps UtcTime Date

Failed (400)

IoT Code

Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

Code Number

Failed (401)

Unauthorized

Error String


NOTE:

a) The Real Time Location field is discarded but for now there will not be any error even if you use this function. It is recommended not to use this function anymore as it will be removed fully from our system.

b) When the scooter is locked and there is a need of real time location then follow the steps as given below.

4

i. Change the upload interval to 10 sec ii. Get the location by calling [ get Current Status]

iii. Set upload interval back to 15 min

1.4. Get Scooter Battery Info This query gives us the information about the batteries. IF there is no external (plugged in) battery

available then the values will be zero for the same. In order for this query to execute the

Authorization, IoT code and Vehicle code are necessary. If the execution fails or the query could

not execute there will be either 400 or 401 error output.



Required Input

Header Authorization String


Vehicle Code String

Possible Output

Success (200)

Iot Code String

Vehicle Code String

charging Boolean

Controller Voltage String

Battery Circle Number Number

Battery Percent1 Number

Battery Percent2 Number

building Battery Temp1 Number

building Battery Temp2 Number

plugin Battery Temp1 Number

plugin Battery Temp2 Number

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (401)

Device Offline

Success Boolean

Message String

Code Number

Failed (401)

Unauthorized

Error String


5

1.5. Headlight On/OFF This will change the state of the scooter headlight. If the command is success the headlight will

either lit on or off depending upon the control signal (Control Type).



Required Input



Parameter

Control Type Number

IoT Code String

Vehicle Code String

Possible Output

Success (200) success Boolean

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String


1.6. Light Flicker ON/OFF Using this function in API we can check if the light in the vehicle is working or not. Both the

light in the front and the back will flicker depending upon the value sent. Given that the

headlight is ON state and the light flicker function for headlight is called then we cannot see

the headlight flickering as headlight will glow continuously.



Required Input



Parameter

Headlight Flicker Number

Taillight Flicker Number

IoT Code String

6

Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String


1.7. Unlock This control parameter will unlock the scooter. When the unlocked function is called the value

for the upload interval field is changed back to default (10 sec). In order for this query to execute

the Authorization, IoT code and Vehicle code are necessary. If the execution fails or the query

could not execute there will be either 400 or 401 error output.



Required Input




Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean Message String

Code Number

Failed (400)

Device Offline


code Number

Failed

(200) Time Out


code Number

Failed (401) Error String

7

Unauthorized

Success (200) Error Description

String

1.8. Lock This control parameter will lock the scooter. When we call this function the set upload interval

time is set to 15min. In order for this query to execute the Authorization, IoT code and Vehicle

code are necessary. If the execution fails or the query could not execute there will be either 400

or 401 error output.



Required Input




Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.9. Power Up/Down This control parameter will power up or down the scooter depending upon the value provided in

control type (Control type value1 for power up and zero for power down). If the button on the

8

handle is pressed, then the scooter will get powered on given the condition that the scooter was

powered off. Generally, we recommend to keep the scooter in power off mode when they are in

garage or inventory and power on the scooter when they are deployed in the street. In order for

this query to execute the Authorization, IoT code and Vehicle code are necessary. If the execution

fails or the query could not execute there will be either 400 or 401 error output.



Required Input



Parameter

Control Type Number

IoT Code String

Vehicle Code String

Possible Output


Failed

(200) TimeOut

Success Boolean

Message String

code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String


1.10. Speed Mode This function objective is to change the scooter riding mode. Based on the speed mode the

acceleration of the scooter changes. One can also limit the speed of scooter for each type of speed

mode (for more information check field 2.13). In order for this function to execute Content Type,

Authorization, IoT code, Vehicle code and Speed mode field value are necessary. If the execution

fails or the query could not execute there will be either 400 or 401 error output.



Required Input



Parameter Speed Mode Number

IoT Code String

9

Vehicle Code String

Possible Output


Failed

(200) TimeOut

Success Boolean

Message String

code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String


1.11. Throttle Response ON/OFF This control parameter will change the throttle response active or inactive. In order for this query

to execute the Authorization, IoT code and Vehicle code are necessary. If the execution fails or

the query could not execute there will be either 400 or 401 error output.



Required Input



Parameter

Control Type Number

IoT Code String

Vehicle Code String

Possible Output


Failed

(200) TimeOut

Success Boolean

Message String

code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Error String


1.12. Toot This control parameter will make the scooter to beep and the lights will blink/flicker for 3 sec.

This function is useful when we are finding a scooter. In order for this query to execute the

10

Authorization, IoT code and Vehicle code are necessary. If the execution fails or the query could

not execute there will be either 400 or 401 error output.



Required Input




Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.13. Get Bluetooth Key This function will give the value of Bluetooth key of IoT device (for more information on key

please refer to 2.14). In order for this query to execute the Authorization, IoT code and Vehicle

code are necessary. If the execution fails, there will be either 200 or 400 or 401 error output.



Required Input

Header Authorization String


Vehicle Code String

Possible Output Success (200)

IoT Code Boolean

Vehicle Code Boolean

Key String

Failed (400) Success Boolean

11

IoT Code Invalid Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.14. Set Bluetooth Key This function is used to assign a new Bluetooth key to the scooter IoT device. Before deploying

scooter to the streets, it is recommended that the Bluetooth key of the scooter is changed to new

one for safety. In order for this query to execute the Authorization, IoT code and Vehicle code

are necessary. If the execution fails or the query could not execute there will be either 400 or 401

error output.



Required Input

Header Content Type String


Parameter

Key String

IoT Code String

Vehicle Code String

Possible Output

Success (200) Success Boolean

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401) Error String

12

Unauthorized

Success (200) Error Description String

1.15. Set Upload Interval This control parameter will set time interval for the scooter (for more information refer to section

2.15). In order for this query to execute the Authorization, IoT code and Vehicle code are

necessary. If the execution fails or the query could not execute there will be either 400 or 401

error output.



Required Input



Parameter

Upload Interval String

IoT Code String

Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


Note: We use the title Set Upload Interval in place of set location upload interval.

1.16. Set Scooter Setting This function is used for changing scooter features like cruise control, speed unit display etc. In

order for this query to execute the Authorization, IoT code and Vehicle code are necessary. If the

execution fails or the query could not execute there will be either 400 or 401 error output.

13



Required Input



Parameter

bssDisplay Number

Cruise Control Number

Button Switch Speed

Mode Number

IoT Code String

Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.17. Set Speed Limit This function is used for changing the speed limit of three different modes. Changing the low,

medium and high limit will change the maximum speed limit of eco, distance and speed mode

rides respectively. In order for this query to execute the Authorization, IoT code and Vehicle

code are necessary. If the execution fails or the query could not execute there will be either 400

or 401 error output.



Required Input



Parameter

Low Speed Limit Number

Medium Speed Limit Number

High Speed Limit String

IoT Code String

14

Vehicle Code String

Possible Output


Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (400)

Device Offline

Success Boolean

Message String

code Number

Failed

(200) Time Out

Success Boolean

Message String

code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.18. Push Scooter Alert This function sents alert message to the attached server when the following situation is detected.

1. Illegal move

If the scooter is locked, but still someone tries to ride it or the scooter is dragged then

this module will get activated.

2. Scooter down

This module get activated when the scooter falls down. This module is triggered based

on the IoT orientation. If the IoT is orientated horizontally then this module is active.

3. Illegal IoT remove

This module get activated if the IoT is removed from the scooter illegally.

6. Scooter is lifted

When the scooter is lifted then this module is activated. By lifted we means the vehicle

is lifted back to upright position (normal) from the fallen down position.

This alert notification will no more gets pushed to server once the problem is solved.



Required Input


Parameter

IoT Code String

Vehicle Code String

Alert Code String

15

Signature String

Possible Output Success (200) success Boolean

1.19. Push Scooter Fault When the scooter has fault, it notifies the IoT and the IoT will push the detail of the fault with

scooter information to the attached server. For now the fault message is sent only once and that

is at the time of error. To know more about the faults codes their reasons and solutions, please

download the manual from the API website.



Required Input


Parameter

IoT Code String

Vehicle Code String

Fault Code String

Signature String

Possible Output Success (200) success Boolean

NOTE: We will upload the fault code at the time it occurred and when the problem is

resolved we will send a value 0 which signifies that the problem has been solved.

1.20. Push scooter status This function will send the fields that are under query->currentstatus to the attached server. Our

server updates these value automatically and save the latest status’s data of scooter and this

update is done according to Upload Interval time. If the upload interval time is 120 sec then this

signify that the push notification data might lag for maximum time of only 2 min.



Required Input


Parameter

IoT Code String

Vehicle Code String

Query-> CurrentStatus String

Signature String

Possible Output Success (200) success String

16

1.21. Push Scooter when upgrade complete This function will notify the attached server that the upgrade firmware task has been successfully

completed or is failed. This module is activated once the firmware update action is completed

and is given only once for one task.



Required Input


Parameter

IoT Code String

Vehicle Code String

Upgrade Task ID Number

Firmware Type Number

Status Number

Signature String

Possible Output Success (200) success String

1.22. Get Firmware List This function will provide the list of available firmware in response. The filed type signify the

firmware type and can only accept the value of number. The available types and their number

are listed below:

1. Firmware of IoT (0)

2. Firmware of Scooter Controller (1)

3. Firmware of Scooter Dashboard (2)

4. Firmware of Scooter Build-In Battery (3)

5. Firmware of Scooter Plug-In Battery (4)




Parameter Type Number

Possible Output

Success (200)

id Number

Type Number

Version Number

Description String

Failed (401)

Unauthorized

Error String


17

1.23. Upgrade device This is the function is used for upgrading a selected firmware for the scooter component (as

described by firmware type). Upon execution of this function a unique task id will be given for

each scooter which helps us to find whether or not the upgrade has been completed for that

specific scooter. According to your own choice you can either upgrade firmware for all the

scooter by giving value of upgradealldevice field as true or upgrade just selected ones by

providing the vehicleiotcodes field. If upgradealldevice fields is true then values in

vehicleiotcodes will be ignored and all the scooter selected firmware will be upgraded.



Required Input



Parameter

Firmware ID Number

VehicleIOTCodes Object[]

UpgradeAllDevices Boolean

Possible Output

Success (200)

Success Boolean

Message String

data Object[]

IoT Code String

Vehicle Code String

Success Boolean

UpgradeTaskID Number

Message String

Code Number

Failed (401)

Unauthorized

Success (200)

Error String


Note: It is recommended to check the current IoT version (from get current firmware) first

before executing this function as upgrading same version only increasing on data usages.

There will be a limitation on number of scooters upgrading at the same time.

1.24. Get Firmware Upgrade task This function provides information about the scooter and related upgrade task information like

time of upgrade and status of upgrade task etc. of that scooter. This function requires task id

18

which gets assigned when the upgrade firmware task ID is created. This function gives all the

information which is related to this upgrade task id.




Parameter Upgrade Task ID Number

Possible Output

Success (200)

Id Number

IoT Code String

Vehicle Code String

Progress Value Number

Firmware ID Number


Version Number

Started At Date

Finished At Date

Status Number

Failed (400)

IoT Code Invalid


Failed (401)

Unauthorized

Success (200)

Error String


1.25. Get firmware This is the function that provides information on firmware. When firmware ID is known the

related information about that firmware is given similar to the get firmware list. Since this

function just provides information of one firmware, the data usage is less as compared with

firmware list function.




Parameter Firmware ID Number

Possible Output Success (200)

Id Number


Version Number

Description String

Failed (400) Success Boolean

19

IoT Code Invalid Message String

Failed (401)

Unauthorized

Success (200)

Error String


1.26. Get Scooter IoT Binding Info. This is the function that provides relationship of iotcode , vehicle code, iccid, qrCode, blekey,

blemac with the platform user (scooter owner/client id)



Required Input




Vehicle Code String

Possible Output

Success (200)

IoT Code String

Vehicle Code String

ICCID String

QR Code Number

BLE Key String

BLE MAC String

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (401)

Unauthorized

Success (200)

Error String


1.27. Scooter IoT Binding This is the function binds information of scooter, IoT, sim card and Bluetooth. This function can

only be executed by the manufacturer or the supplier.

FIELD

TYPE HEADING FIELD FIELD TYPE

Required Input



Parameter SN String

ICCID String

20

QR Code String

BLE Mac String

IoT Code String

Vehicle Code String

Possible Output

Success (200) Success Boolean

Failed (400)

IoT Code Invalid

Success Boolean

Message String

Code Number

Failed (401)

Unauthorized

Success (200)

Error String


21

2. FIELDS 2.1. Content Type

This is a required input field (Header) in order to get the access token. The value of this field

can only be a string type. Following given are the allowable value for content type for the given

API functions.

• Auth, Push Notification-"application/x-www-form-urlencoded".

• Control, Setting, Firmware, Scooter IoT -"application/json"

S.N Function containing this field Field Type 1 Auth -> request the access token. Input 2 Control->Head Light On-OFF Input 3 Control->Light Flicker ON-OFF Input 4 Control->Lock Input 5 Control->Unlock Input 6 Control->Power UP-DOWN Input 7 Control->Speed Mode Input 8 Control->Throttle response ON-OFF Input 9 Control->Toot Input

10 Setting->Set Bluetooth Key Input 11 Setting->Set Upload Interval Input 12 Setting->Set Scooter Setting Input 13 Setting->Set Speed Limit Input 14 Push Notification->Push Scooter alert Input 15 Push Notification->Push Scooter fault Input 16 Push Notification->Push Scooter status Input 17 Push Notification->Push Scooter When

Upgrade Complete Input

18 ScooterIoT->Get Scooter IoT Binding Infor Input 19 ScooterIoT-> Scooter IoT Binding Input

2.2. Authorization This field is composed of the access token and token type. First the token type is written and the

access token is concatenated along with the white space. This key is only valid as long as the

access token is valid. For more information on access token please refer to section 2.32

S.N Function containing this field Field Type 1 Query -> get current firmware version Input 2 Query->get current status Input 3 Query->get scooter battery information Input 4 Control->Headlight On Off Input 5 Control->Light Flicker On-Off Input 6 Control->Lock Input 7 Control->Unlock Input

22

8 Control->Power UP-DOWN Input 9 Control->Speed Mode Input 10 Control->Throttle response ON-OFF Input 11 Control->Toot Input 12 Setting->Get Bluetooth Key Input 13 Setting->Set Bluetooth Key Input 14 Setting->Set Upload Interval Input 15 Setting->Set Scooter Setting Input 16 Setting->Set Speed Limit Input 18 Firmware->Get Firmware List Input 19 Firmware->Get Firmware upgrade task Input 20 Firmware->Get Firmware Input 21 Firmware->Upgrade Device Input 22 ScooterIoT->Get Scooter IoT Binding Infor Input 23 ScooterIoT-> Scooter IoT Binding Input

2.3. Client Id This is a required input field in order to get the access token. It is a 5 number digits that are unique

to every client of Segway. In order to get your client ID please contact with Segway officials.

After the vehicle are purchased from Segway, we will register the purchased vehicle under your

ID. The value type of this field is String.

S.N Function containing this field Field Type 1 Auth -> request the access token. Input

2.4. Client Secret This is the password for the client id. This is a required input field in order to get the access token

which later will be used for all API calls. The value type of this field is String. Client secret is

needed for creating the signature filed in push notification function.


2.5. Grant Type This is a required input field in order to get the access token. The client id might have different

grant type. This is useful when a client has authority level in their operation. For now

“client_credentials” is the only allowable variable.


23

2.6. IoT Code This is the unique code given to an IoT device that is installed in the scooter. It is a string that is

combination of digits and alphabets and the allowable maximum length of the code is 32

characters. Every IoT device has a unique code and this code is the IMEI Code of Vehicle. This

field value is used to make the value of signature field in Push Notification Function. In the

firmware function, this field value is combined with vehicle code to make the VehicleIoTCodes

field value so that mass upgrade of scooter firmware can be achieved.

S.N Function containing this field Field Type 1 Query -> get current firmware version Input, Output 2 Query -> get current status Input, Output 3 Query->get scooter battery information Input, Output 4 Control->Headlight On Off Input 5 Control->Light flicker On Off Input 6 Control->Lock Input 7 Control->Unlock Input 8 Control->Power UP-DOWN Input 9 Control->Speed Mode Input 10 Control->Throttle response ON-OFF Input 11 Control->Toot Input 12 Setting->Get Bluetooth key Input, Output 13 Setting->Set Bluetooth Key Input, Output 14 Setting->Set Upload Interval Input, Output 15 Setting->Set Scooter Setting Input, Output 16 Setting->Set Speed Limit Input, Output 17 Push Notification->Push Scooter alert Input 18 Push Notification->Push Scooter fault Input 19 Push Notification->Push Scooter status Input

20 Push Notification->Push Scooter When Upgrade Complete Input

21 Firmware->Get Firmware List Input 22 Firmware->Get Firmware upgrade task Input 23 Firmware->Upgrade Device Output 24 ScooterIoT->Get Scooter IoT Binding Infor Input, Output 25 ScooterIoT-> Scooter IoT Binding Input

2.7. Vehicle Code This is the unique code given to each scooter and is also a scooter number. The vehicle code is

the combination of digits and alphabet and can be maximum length of 32 characters. It is also

used for making the signature filed value under push notification function. This code can be

modified according to the vehicle owner need and is bound with QR code, IMEI code and IoT

Serial Number

S.N Function containing this field Field Type

24

1 Query -> get current firmware version Input, Output 2 Query -> get current status Input, Output 3 Query->get scooter battery information Input, Output 4 Control->Headlight On Off Input 5 Control->Light flicker On Off Input 6 Control->Lock Input 7 Control->Unlock Input 8 Control->Power UP-DOWN Input 9 Control->Speed Mode Input 10 Control->Throttle response ON-OFF Input 11 Control->Toot Input 12 Setting->Get Bluetooth key Input, Output 13 Setting->Set Bluetooth Key Input, Output 14 Setting->Set Upload Interval Input, Output 15 Setting->Set Scooter Setting Input, Output 16 Setting->Set Speed Limit Input, Output 17 Push Notification->Push Scooter alert Input 18 Push Notification->Push Scooter fault Input 19 Push Notification->Push Scooter status Input 20 Push Notification->Push Scooter When

Upgrade Complete Input

21 Firmware->Get Firmware List Input 22 Firmware->Get Firmware upgrade task Input 23 Firmware->Upgrade Device Output 24 ScooterIoT->Get Scooter IoT Binding Infor Input, Output 25 ScooterIoT-> Scooter IoT Binding Input

2.8. Real Time Status This field takes the Boolean value. If the value is true, then the server will ask for the real time

data while inquiring the scooter status. If the value is false (also a default value in case of no

input) the server will return the field with those scooter’s data/information which were stored

previously in the server. The server will update the scooter’s data in every 4min.

S.N Function containing this field Field Type 1 Query -> get current status Input

Note: All the feedback fields (except IoT Vehicle code and online field) from the Query->get

status will be 0 and there will be no field of statusUtcTime if vehicle is offline at the moment

of request.

2.9. Real Time Location This field is similar to the real time status and takes a Boolean input too. If this field is false (also

a default value in case of no input) then returned field’s data for vehicle status under query

command will provide the last location recorded data on server.

25

S.N Function containing this field Field Type 1 Query -> get current status Input

Note: The Real Time Location field is discarded but for now there will not be any error

even if you use this function. It is recommended not to use this function anymore as it will

be removed fully from our system. Please refer to section 1.3 for more info.

2.10. Control Type This field decides whether the control module is going to execute or not. The allowable value

is either 0 or 1 in which 1 means the control will get execute whereas 0 mean the control will

not be executed. For example in Headlight ON OFF, 1 means the headlight will be switched

ON and 0 means the headlight will get switched OFF. There is no time limit for the execution

of the defined control and the reaction of the scooter only depends on the value of this field. It

means if the control type value for Headlight ON-OFF is 1 then headlight will lit ON until the

value of control type is changed to 0.

S.N Function containing this field Field Type 1 Control ->Head Light On-OFF Input 2 Control->Power Up Down Input 3 Control->Throttle response On-Off Input

2.11. Head Light Flicker This is a field that accept the value of either 1 or 0. For the given vehicle of provided IoT Code

and Vehicle Code, when 1 is assigned in this field the headlight will start to blink once in time

interval of 1sec. When the value is assigned to 0 then the blinking will stop.

S.N Function containing this field Field Type 1 Control -> Light Flicker ON-OFF Input

2.12. Tail Light Flicker This is a field that accept the value of either 1 or 0. For the given vehicle of provided IoT Code

and Vehicle Code, when 1 is assigned in this field the tail light will start to blink with time

interval of 50millisec. When the value is assigned to 0 then the blinking will stop.

S.N Function containing this field Field Type 1 Control -> Light Flicker ON-OFF Input

2.13. Speed Mode There are total 3 modes of riding, Economical (1), Distance (2) and Speed (3). Depending upon

the mode, the mileage and the performance of the scooter varies. Scooter can provide the

26

maximum performance under speed mode (3) and the maximum mileage can be achieved when

the riding mode is 1 i.e. Economical. A vehicle owner can change the maximum speed under a

given mode if needed. The speed mode can be changed Over the Air (OTA), or by button on

the handle bar.

S.N Function containing this field Field Type 1 Query -> get current status Output 2 Control -> Speed Mode Input

Note: In order to change speed mode using button, configuration must be enabled first at control.

2.14. Key This field when called from function “Get Bluetooth key” provides the value of the Bluetooth

key which is required for successful Bluetooth connection to the IoT. It is also a field that is

used in the “Bluetooth set key” function to set the new Bluetooth key for the IoT device. For

now 8 characters that is combination of either number or alphabets are allowed for the key field

value.

S.N Function containing this field Field Type 1 Control -> Get Bluetooth Key Output 2 Setting->Set Bluetooth Key Input 3 ScooterIot->Get Scooter IoT Binding Info. Output

Note: The default value of the Bluetooth key is 4BKNwi77

2.15. Upload Interval This field sets the time interval in which status’s data gets uploaded to the server and can be

edited using the function “Set Upload Interval” (function 1.15). This field resets when the

scooter is locked or unlocked. The data type is numeric and the data unit is in second. The

values allowable for this field is in between 10 to 99999 milliseconds (if you want the interval

less than 10 seconds please contact with Segway discovery staff).

S.N Function containing this field Field Type 1 Setting -> Set Upload Interval Input

Note: The default value of Upload Interval that gets assigned while locking and unlocking

the scooters are 15min and 10 seconds respectively. If someone want to change upload

interval default value, then first they should get feedback from unlocked/locked function

as true.

27

2.16. BssDisplay This field is used in order to show the unit of speed on the scooter dashboard under the speed

value. The unit will be either km/hr (SI unit) or mph (British metric unit) for speed based on

this value. If the value of this filed is 0 then speed unit will be displayed in SI unit and if the

value is 0 for this field the unit of speed will be in mph.

S.N Function containing this field Field Type 1 Setting -> Set Scooter Setting Input

2.17. Cruise Control This filed is used for achieving a cruise control of the scooter i.e. the scooter will start to cruise

at the same speed when this mode is activated. Once this control is activated there is no need

for pressing the throttle.


NOTE: In order to active the cruise control the speed should become constant for 5 sec

and the cruise control filed value should be 1. Cruise control will be deactivated if the

throttle or brake switch is pressed

2.18. Button Switch Speed Mode This filed value determines if the speed mode can be changed from handle bar button. If the

value of this filed is 1 then the speed mode can be changed by pressing the Button twice. When

this field value is 0 then speed mode cannot be changed using button.


2.19. Low Speed Limit This field value determines the maximum speed for riding mode 1(Economical riding mode)

The allowable value for this field is from 6 to 25 meaning that the maximum speed limit for the

speed mode 1 can be between the value of 6 to 25 km/hr.

S.N Function containing this field Field Type 1 Setting -> Set Speed Limit Input

28

2.20. Medium Speed Limit This filed value determines the maximum speed for riding mode 2(Distance riding mode) The

allowable value for this field is from 6 to 25 meaning that the maximum speed limit for the



2.21. High Speed Limit This filed value determines the maximum speed for riding mode 3(Speed riding mode) The

allowable value for this field is from 6 to 25 meaning that the maximum speed limit for the



2.22. Signature This filed is calculated by combining all the status field (except signature) and client secret and then converting it into a string based on algorithm. Please ask Segway team if you need information for calculating procedure (algorithm).

S.N Function containing this field Field Type 1 Push Notification -> Push Scooter Alert Input

Note: The signature is calculated as provided in the following steps

i. Rearrange/Sort KV pair (message excluding KV pair of signature) based on the Key

according to ASCII

ii. Combine all the sorted KV pair with ‘&’. After combining, append

‘client_secret=please_input_your_client_secret_here’ to get pre-sign string

iii. Calculate the hash using md5 algorithm. The input is pre-signed string as input eg.

Md5(pre-string). The result 32-byte string is the signature result string.

2.23. Type/ Firmware Type There are five kind of firmware each firmware is assigned a number for identification based

on this field (0: IoT; 1: Scooter Controller; 2: Scooter Dashboard (BLE); 3: Scooter Build-In

Battery; 4: Scooter Plug-In Battery ;). This field is used while filtering the firmware according

to the type.

S.N Function containing this field Field Type

https://en.wikipedia.org/wiki/ASCII

29

1 Push Notification->Push Scooter When Upgrade Complete Input

2 Firmware-> Get Firmware List Input, Output 3 Firmware->Get Firmware Upgrade Task Output 4 Firmware->Get Firmware Output

2.24. Upgrade Task ID This field is assigned based on the upgrade task and is auto numbered. This field help us in

checking a given upgrading task as individual upgrade task has individual Id.

S.N Function containing this field Field Type 1 Push Notification -> Push Scooter Alert Output 2 Firmware->Get Firmware upgrade Task Input 3 Firmware->Upgrade Device Output

2.25. Firmware ID This is the ID given for each firmware regardless of their version or type.

S.N Function containing this field Field Type 1 Firmware-> Get Firmware Upgrade Task Output 2 Firmware->Get Firmware Input, Output 3 Firmware->Upgrade Device Input

2.26. Vehicle IoT Codes This is the field that value is made from Vehicle code and IoT Code. This field is utilized for

upgrading a fleet of scooter.

S.N Function containing this field Field Type 1 Firmware->Upgrade Device Input

2.27. Upgrade ALL Devices This is the field is a Boolean type and the default value is false. When the value is true all the

device under the selected operator will be upgraded given the case scooter is locked and

online.

S.N Function containing this field Field Type 1 Firmware->Upgrade Device Input

2.28. SN A sticker in the cover of IoT device is that IoT device serial Number.

30

S.N Function containing this field Field Type 1 Scooter IoT->Scooter IoT binding Input

2.29. ICCID This is the unique identifier of the sim that is installed in the IoT device.


2.30. QRCODE It is string that is given to a scooter for their identification. This string can be achieved by

using scanner.


2.31. BLEMAC This is a unique identifier (MAC ID) of the Bluetooth and cannot be changed. It is a read only

field which is used to establish communication with scooter via Bluetooth.


2.32. Access Token This is an output field. This field is required for all task in the API. The value of Access Token

will be of 34 character (number or alphabets or combination of both with -separated). The key

will be in the format “xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx”. When the key is sent

once, it will expire after a 12 hour and the time is given along with this output

S.N Function containing this field Field Type 1 Auth -> request the access token. Output

2.33. Token Type This is the field which tell the user the type of the access token. For now only the token type of

bearer is available. This information is necessary in order to access API features as it is used

for building authorization key.


31

NOTE: The only allowable value for Token Type is “bearer” for now.

2.34. Expires in This field is the time in which an access token sent by the server will expire. The time given is

in seconds. If the time says 3600 then the access token will expire 1 hour. This time will keep

on reducing until the value is reached to zero for a given access token key.


Note: Expire time of an access token is 43199sec. This time cannot be reset for a given access token until it expires.

2.35. Scope As name suggest this field tell the user what is the scope of the sent access token. This field

depends upon the token type and for the bearer token type the scope is read and write trusted.


NOTE: For now the only value is read write trust.

2.36. IoT Version This field information provides the current firmware version of an installed IOT device. In

order to get this Authorization key, Iot Code and Vehicle code are required. It is read only

data and cannot be changed from API. One can update the controller firmware over the air.

Please refer to the firmware manual for more information on how to change firmware.

S.N Function Description Field Type 1 Query -> get current firmware version Output

2.37. Vehicle Controller Version This field provides the information about scooter’s controller firmware version. One can update

the controller firmware over the air. Please refer to the firmware manual for more information

on how to change firmware.


32

2.38. Vehicle Dashboard Version The display on the middle of the handle bar is a dashboard. Vehicle Dashboard Version field

give us the firmware version of the dashboard. One can update the controller firmware over the

air. Please refer to the firmware manual for more information on how to change firmware.


2.39. Vehicle BuildInBattery Version This field gives us the firmware version of in built in battery’s BMS controller in the scooter.

This battery is a main energy source for powering the scooter. In order to upgrade or downgrade

the firmware, please refer to the firmware manual.


2.40. Vehicle PlugInBattery Version When there is an external battery available then this field will provide the firmware of that

external battery’s controller (plugged in battery’s firmware). Only some series of the scooter

has this feature of extendable battery when the scooter does not have external battery, the value

of this field is 0. Please refer to the manual in case of requirement for upgrade and downgrade

of the firmware.


2.41. Online This field is a Boolean type and is assigned true if the IoT device can communicate with the server. It is assigned false if it cannot communicate with server.

S.N Function Description Field Type 1 Query -> get current status Output

2.42. Locked This filed gives the locked status of the scooter. It can either be true or false at a given time. If

the value is true then the scooter is locked and if false then scooter is unlocked. This field is

important in the aspect of renting a scooter.

33

S.N Function containing this field Field Type 1 Query -> get current status Output

Note: Every time when the vehicle is locked status’s data are sent to server in every 15min.

2.43. LockVoltage It is the Voltage of IoT battery and the unit is in 0.01V.


2.44. Charging This field gives the Boolean value of True or False. If the vehicle is charging (plugged in for

charge) the value will be true or else value will be false.

S.N Function containing this field Field Type 1 Query -> get current status Output 2 Query-> get scooter battery information Output

Note: This field will be updated at least once in every 4 min in case calling function get

current status.

2.45. Power Percent This gives an average value for total remaining charge of two batteries (inbuilt and external

battery). The output value 80 represents the 80% power percentage.


Note: When there is not external battery available then the power percentage is same as

charge level of inbuilt battery

2.46. Speed This field gives the information about the speed in km/hr.


34

2.47. Odometer This field gives the total distance travel by the scooter. If the device goes offline then this value is reset to zero. The value is in m.


2.48. Remaining Range This field gives the remaining distance (in 10 m) that scooter can travel for a remaining charge level of scooter.


2.49. Total Riding Secs This field gives the total riding time in sec.


2.50. Status UtcTime This field gives the information of the time for the scooter status data excluding the GPS data.


2.51. Latitude Information in this field provides the geological latitude point of the vehicle.


2.52. Longitude Information in this field provides the geological longitude point of the vehicle.


2.53. Satellite Number Information in this field provides the geological longitude point of the vehicle.


35

2.54. Hdop (Horizontal Dilution of precision) This information in this field is about quality of the GPS data. If the value is less it is considered that the quality of GPS is good.


2.55. Altitude Information in this field provides the altitude of the vehicle in meter. The altitude is measured from the sea level.


2.56. Gps UtcTime This field gives the information of the time when the GPS data were updated in the server.


2.57. Controller Voltage This is the reading of driver voltage (controller) and the unit is in V.

S.N Function containing this field Field Type 1 Query->get scooter battery information Output

2.58. Battery Circle Number This field refers to battery cycle number. This increase with the total number of charge and discharge cycle of the inbuilt battery but not plugged in battery.


2.59. Battery Percent1 It gives the charge percentage of the main (inbuilt) battery.


2.60. Battery Percent2 It gives the charge percentage of the plugged in battery.


2.61. Build in Battery Temp1 It gives the temperature reading in degree Celsius of the built in battery in point 1.


36

2.62. buildin Battery Temp2 It gives the temperature reading in degree Celsius of the built in battery in point 2.


2.63. plugin Battery Temp1 It gives the temperature reading in degree Celsius of the plugged in battery at first point.


2.64. plugin Battery Temp2 It gives the temperature reading in degree Celsius of the plugged in battery at second point.


2.65. Success This field shows if the operation of the API request has been successfully completed or was

failed. This field has value assigned as true in case of successful operation. In case of failure it

is assigned as false. Although this field value is usually assigned by our server for most function

calls, in case of push notification client server must provide us the feedback so that we can

decide if the push notification is completed.

S.N Function containing this field Field Type 1 Query -> get current firmware version Output(False) 2 Query -> get current status Output(False) 3 Query->get scooter battery information Output(False) 4 Control-> Head Light ON-OFF Output(true/false) 5 Control-> Light Flicker ON-OFF Output(true/false) 6 Control->Lock Output(true/false) 7 Control->Unlock Output(true/false) 8 Control->Power UP-DOWN Output(true/false) 9 Control->Speed Mode Output(true/false) 10 Control->Throttle response ON-OFF Output(true/false) 11 Control->Toot Output(true/false) 12 Setting->Get Bluetooth key Output(False) 13 Setting->Set Bluetooth Key Output(True/False) 14 Setting->Set Location Interval Output(True/False) 15 Setting->Set Scooter Setting Output(True/False) 16 Setting->Set Speed Limit Output(True/False) 17 Push Notification->Push Scooter alert *Output(True) 18 Push Notification-> Push Scooter Fault *Output(True) 19 Push Notification->Push Scooter Status *Output(True)

37

20 Push Notification->Push Scooter When upgrade Complete *Output(True)

21 Firmware->get Firmware upgrade task Output(False) 22 Firmware->Get Firmware Output(False) 23 Firmware->upgrade device Output(True) 24 ScooterIoT->Get Scooter IoT Binding Info. Output(false) 25 ScooterIoT->Scooter IoT Binding Output(true/False)

NOTE: In case of query, if the request is successful then it will show the values of field

request but not the success field value on the display.

2.66. Message This is field that has more information about the failure for API request. For example in case of

offline scooter, message field will contain “the device is currently offline”.

S.N Function containing this field Field Type 1 Query -> get current firmware version Output 2 Query -> get current status Output 3 Query->get scooter battery information Output 4 Control->Head Light ON-OFF Output 5 Control-> Light Flicker ON-OFF Output 6 Control->Lock Output 7 Control->Unlock Output 8 Control->Power UP-DOWN Output 9 Control->Speed Mode Output 10 Control->Throttle response ON-OFF Output 11 Control->Toot Output 12 Setting->Get Bluetooth key Output 13 Setting->Set Bluetooth Key Output 14 Setting->Set Location Interval Output 15 Setting->Set Scooter Setting Output 16 Setting->Set Speed Limit Output 17 Firmware->Get firmware Upgrade task Output 18 Firmware->Get firmware Output 19 Firmware->Upgrade Device Output 20 ScooterIoT->Get scooter IoT binding Info. Output 22 ScooterIoT->Scooter IoT Binding Output

2.67. Code This field contain four digit number, this number is a unique ID of the fault and varies according

to fault type. For example, the error code for Invalid IoT code is 1000 and the error code for

Device Offline is 1001.

S.N Function containing this field Field Type 1 Query -> get current firmware version Output

38

2 Query -> get current status Output 3 Query->get scooter battery information Output 4 Control->Head Light ON-OFF Output 5 Control-> Light Flicker ON-OFF Output 6 Control->Lock Output 7 Control->Unlock Output 8 Control->Power UP-DOWN Output 9 Control->Speed Mode Output 10 Control->Throttle response ON-OFF Output 11 Control->Toot Output 12 Setting->Get Bluetooth key Output 13 Setting->Set Bluetooth Key Output 14 Setting->Set Upload Interval Output 15 Setting->Set Scooter Setting Output 16 Setting->Set Speed Limit Output 17 Firmware->Upgrade Device Output 18 ScooterIoT->Get scooter IoT binding Info. Output 19 ScooterIoT->Scooter IoT Binding Output

2.68. Error This field is only provided when there is an attempt of unauthorized access, for example wrong

authorization key or invalid password). This field can contain the string which gives

information on error type for example “invalid_clients”, “invalid_taken”,

unsupported_grant_type, “unauthorized” etc. The invalid_clients indicates invalid

authorization key or invalid password (client secret).

S.N Function containing this field Field Type 1 Auth -> request the access token. Output 2 Query -> get current firmware version. Output 3 Query -> get current status. Output 4 Query -> get scooter battery information. Output 5 Control-> Head Light ON OFF Output 6 Control->Light Flicker ON OFF Output 7 Control->Lock Output 8 Control->Unlock Output 9 Control->Power UP-DOWN Output 10 Control->Speed Mode Output 11 Control->Throttle response ON-OFF Output 12 Control->Toot Output 13 Setting->Get Bluetooth key Output 14 Setting->Set Bluetooth Key Output 15 Setting->Set Upload Interval Output 16 Setting->Set Scooter Setting Output 17 Setting->Set Speed Limit Output

39

2.69. Error Description This field gives more information on the error field. This is useful while knowing what kind

of error occurred when the request is failed.

NOTE: This field always follows the error field as it provides more information about the

given error.

2.70. Network Signal This is the quality if the signal that the IoT is receiving for the simcard. The lowest value is 2

and the highest is 32. IF the higher value is high it represents the signal is stronger.


40

3. EXAMPLE In this section we will see how the API function described above can help us achieve desired results

like information about the scooter, turning on and off the vehicle etc. Figure below shows the simple

outline of process flow diagram of API function selection and usage.

3.1. Get Authorization key

Step 1. The access token and token type (required to make authorization key) is provided under Request the access token function. Provide the required input from the function namely: Content-Type, Client Id, Client secret and Grant type.

Step 2. Concatenate access token and token type along with white space and the final result is authorization key.

3.2. To find if scooter is charging or not

Step 1. Charging status is available from two function, either from get current status or from get scooter battery information. Provide the input Parameter-Authorization, IoT Code and Vehicle Code for function to know if the vehicle is charging

No

Yes

41

Step 2. If the reply contains the charging field and its value, then the function is successfully executed. If there is error, check the description and act accordingly (For example if the error is Invalid IoT Code make sure you provide the correct IoT code in function Input)

3.3. To lock the scooter

Step 1. Locking of scooter is achieved by executing the Lock function under Control subheading. This function takes input of Content-Type, Authorization, IoT Code, and Vehicle Code.

Step 2. If the feedback from the function contain success field with assigned value of true, then the scooter has been successfully locked. If the execution is failed, the error message along with fault code will be returned by the function.

3.4. To change the upload interval to 20 secs when the scooter is in unlocked state

Step 1. Unlock the scooter (function 1.7.) Step 2. Receive the feedback from the function as “success”: true, this confirms the

scooter has been successfully unlocked. Step 3. Change the value of upload interval (field 2.15) to desired value (in this case

20secs) using the function 1.15.

3.5. To Change the upload interval to 5 min when the scooter is in locked state

Step 1. Lock the scooter (function 1.8.) Step 2. Receive the feedback from the function as “success”: true, this confirms the

scooter has been successfully locked. Step 3. Change the value of upload interval (field 2.15) to desired value (in this case 5

minutes) using the function 1.15.

gateway api documentation - eu-api.segway.pt api documentation v1.1.… · this manual provides the...

Documents