Preface
About tokens
There’re two kinds of tokens: user token and node token.
And there will be a specification under each category of APIs. Please access the API endpoint with the right token, or you will get a 403 HTTP status code and a error message.
The user token can be obtained with /v1/user/create, /v1/user/changepassword, /v1/user/login API endpoints.
The node token can be obtained with /v1/nodes/create, /v1/nodes/list API endpoints, it’s the value of “node_key” in the response.
Authorization
- with query string: xxxx/xxxx?access_token=[your token here]
- with “Authorization” header: Authorization: token [your token here]
Status code and format of the response
GET request succeed:
{"key": "value", "key2": "value2"}
POST request succeed:
{"result":"ok"}
All other error responses:
{"error": "error message here"}
Status Code | Meaning |
---|---|
200 | OK - API call successfully executed. |
400 | Bad Request - Wrong Grove/method name provided, or wrong parameter for method provided |
403 | Forbidden - Your access token is not authorized. |
404 | Not Found - The device you requested is not currently online, or the resource/endpoint you requested does not exist. |
408 | Timed Out - The server can not communicate with device in a specified time out period. |
500 | Server errors - It’s usually caused by the unexpected errors of our side. |
If the debug mode is enabled, the error message will also include a field “traceback” whose value is the traceback of the error.
Server URLs
Now SEEED have three servers running, the URLs of them are:
- https://iot.seeed.cc
- https://us.wio.seeed.io
- https://cn.wio.seeed.io
The first server iot.seeed.cc is the original global server which is now the transition server for non-Chinese users, and it will be closed after September 1st. From now on, it’s recommended that you register your Wio devices on us.wio.seeed.io / cn.wio.seeed.io. All the API URLs following in this reference are illustrated with us.wio.seeed.io, for Chinese users please replace them with cn.wio.seeed.io.
User management APIs
The Wio server can host self user database - with the following APIs. But also the server can collaborate with external user system with a webhook mechanism, and based on this, we connect SEEED bazaar’s user database with Wio. In the Wio App, the user registration and login are directed to SEEED bazaar’s user portal, and the authentications are transferred to the Wio server if the credential is correct.
So if you develop some system to interact with SEEED’s Wio servers, please follow the chapter “Use SEEED’s user system”.
Use SEEED’s user system
Sign-up a user
Please go to http://www.seeedstudio.com/register.html and finish the registration form.
Login to get the user token
Please go to https://wio.seeed.io/login and login with your SEEED account or Facebook account or Google+ account. After the successfully login, you will finally get a web page with some json string there. Please set down the token for further use.
{"token": "HHFLGW8dGRRGExMY", "user_id": 80733}
Retreive the password
Please go to http://www.seeedstudio.com/find_psw.html and follow the instruction there.
Currently we haven’t opened an API system to invoke SEEED’s user portal.
The following APIs are for self deployed Wio servers.
Create a user account
curl -d email=[email here] -d password=[password here] https://us.wio.seeed.io/v1/user/create
{
"token": "JLvvpkpmyMWQCOqUqPd5e4wR2f7wxM7fDmenWuxrcLs"
}
POST /v1/user/create
Parameter | Type | Description |
---|---|---|
string | The email address | |
password | string | The password |
Change the password
curl -d password=[new password here] https://us.wio.seeed.io/v1/user/changepassword?access_token=9L0_ofzPHnan91UQbtcCS4KzCI8BGQk6-OgMOtmnI3Q
{
"token": "aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA"
}
POST /v1/user/changepassword
Parameter | Type | Description |
---|---|---|
password | string | The new password |
Retreive the password
curl -d email=[new email here] https://us.wio.seeed.io/v1/user/retrievepassword
{
"result": "ok"
}
If you forget your password, you can retrieve it by this API. You should specify the right email address, otherwise you will not receive the email with new password attached.
POST /v1/user/retrievepassword
Parameter | Type | Description |
---|---|---|
string | The email address of which account you want to retrieve password for |
User login
curl -d email=[email here] -d password=[password here] https://us.wio.seeed.io/v1/user/login
{
"token": "JLvvpkpmyMWQCOqUqPd5e4wR2f7wxM7fDmenWuxrcLs",
"user_id": 21
}
POST /v1/user/login
Parameter | Type | Description |
---|---|---|
string | The email address | |
password | string | The password |
Nodes management APIs
Create a node
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" -d name=node_1 -d board="Wio Link v1.0" https://us.wio.seeed.io/v1/nodes/create
{
"node_key": "e3d3b0fe920ddc3c69393fdbf83a2114",
"node_sn": "819554bd9519c94a19cc7fbd32447118"
}
POST /v1/nodes/create
Parameter | Type | Description |
---|---|---|
name | string | The name for the new node |
board | string | The board type of the new node, can be one of “Wio Link v1.0”, “Wio Node v1.0” for now. If not present, the default board type will be Wio Link v1.0. |
Fields of response | Type | Description |
---|---|---|
node_key | string | The node token |
node_sn | string | The series number of this node |
List all nodes of a user
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://us.wio.seeed.io/v1/nodes/list
{
"nodes": [
{
"name": "hhhh",
"node_key": "15f96fe2ababdf7d177bd0d8c19cdf31",
"node_sn": "7168f50df4a48fb2d21c8e37b01dd210",
"dataxserver": "192.168.1.2",
"board": "Wio Link v1.0",
"online": false
},
{
"name": "nnnn",
"node_key": "4ffef50da2d50b9a40443947c75901ad",
"node_sn": "98058f29c3621a396b7c96978b25f3d1",
"dataxserver": null,
"board": "Wio Link v1.0",
"online": true
}
]
}
List all the nodes belong to a specific user, corresponding with the user token provided.
GET /v1/nodes/list
Fields of response | Type | Description |
---|---|---|
name | string | The name of this node |
node_key | string | The node token |
node_sn | string | The series number of this node |
dataxserver | string | The “dataxserver” is the data exchange server which is one of the two channels Wio Link talks with server(s). See https://github.com/Seeed-Studio/Wio_Link/wiki/Server%20Deployment%20Guide#3-deploy-a-local-lean-data-exchange-server for more detail. The default data exchange server is the same as OTA server when the node is created, and will be displayed “null” here. If set by API /v1/node/setting/dataxserver, the set address will be stored in database and will be displayed here. |
board | string | The board type of the node. |
online | string | The “online” fields stands for the connection status of the data channel. When one node has connected to a data exchange server, it will also sync the status with OTA server, then the OTA server will dispatch the status through this API. |
Rename a node
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://us.wio.seeed.io/v1/nodes/rename -d node_sn=160769ffa50feae76ec6f7a4fb95bf6c -d name=new_name
{
"result": "ok"
}
POST /v1/nodes/rename
Parameter | Type | Description |
---|---|---|
node_sn | string | The SN of this node, get the SN with nodes/list API |
name | string | The new name for this node |
Delete a node
curl -H "Authorization: token StiLU1g5SNfQYWQLKpB7uMuE4l2uQuamKMBsIW1RGgA" https://us.wio.seeed.io/v1/nodes/delete -d "node_sn=bac0df2d1b01b32c8ad3a0efbfc31c5f"
{
"result": "ok"
}
POST /v1/nodes/delete
Parameter | Type | Description |
---|---|---|
node_sn | string | The SN of this node, get the SN with nodes/list API |
Grove driver APIs
Get all grove drivers’ information
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://us.wio.seeed.io/v1/scan/drivers
{
"drivers": [
{
"SKU": "104030003",
"Files": [
"grove_4_digit.cpp",
"grove_4_digit.h"
],
"ClassFile": "grove_4_digit.h",
"GroveName": "Grove - 4-Digit Display",
"ImageURL": "http://www.seeedstudio.com/depot/bmz_cache/3/3a9f79323a82950c12fc7e69fa9fab4d.image.530x397.jpg",
"Writes": {
"write_display_point": {
"Arguments": [
[
"uint8_t",
"display"
]
]
},
"write_brightness": {
"Arguments": [
[
"uint8_t",
"brightness"
]
]
}
},
"HasPowerOffFunc": true,
"ClassName": "Grove4Digit",
"Reads": {},
"CanGetLastError": true,
"Events": {},
"HasEvent": false,
"InterfaceType": "UART",
"IncludePath": "./grove_drivers/grove_4_digit",
"HasPowerOnFunc": true,
"ID": 0,
"ConstructArgList": [
"int pintx",
"int pinrx"
]
}
]
}
Get the driver database which is generated by the scanning process.
GET /v1/scan/drivers
Get the status of last driver scanning
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://us.wio.seeed.io/v1/scan/status
{
"msg": "scanned 40 grove drivers at 2015-12-25 15:22:10.796713",
"result": "OK"
}
{
"msg": "error message here",
"result": "Failed"
}
The scanning process can be scheduled to be done periodically. Or triggered by the new driver commit at github.
GET /v1/scan/status
Boards/Platform APIs
List all supported boards
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://us.wio.seeed.io/v1/boards/list
{
"boards": [
{
"board_name": "Wio Link v1.0",
"board_vendor": "seeedstudio",
"board_flash_map": 6,
"board_flash_spi_speed": 40,
"board_flash_spi_mode": "QIO",
"board_builtin": {
"FUNCTION_KEY": 0,
"STATUS_LED": 2,
"GROVE_POWER_SWITCH": 15
},
"interfaces": {
"UART0": {
"pintx": 1,
"pinrx": 3,
"type": "UART"
},
"D2": {
"type": "GPIO",
"pin": 13
},
"A0": {
"type": "ANALOG",
"pin": 15
},
"I2C0": {
"pinscl": 5,
"type": "I2C",
"pinsda": 4
},
"D0": {
"type": "GPIO",
"pin": 14
},
"D1": {
"type": "GPIO",
"pin": 12
}
}
}
]
}
Currently, only Wio Link board is supported. Welcome the community to add in more boards.
GET /v1/boards/list
Single node APIs
Print the well-known of a node
Access through Data Exchange Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/.well-known
{
"name": "node name",
"well_known": [
"GET /v1/node/GroveAccMMA7660/accelerometer -> float ax, float ay, float az",
"GET /v1/node/Grove_Example1/with_arg/{int arg} -> float cx, float cy, float cz, int degree",
"POST /v1/node/Grove_Example1/float_value <- float f",
"HasEvent Grove_Button1 button_pressed",
"POST /v1/node/Grove_Gyro_ITG3200/zerocalibrate <- void"
]
}
GET /v1/node/.well-known
“.well-known” API prints all the available resources on that node. This API needs the node online.
The items on the right of the right arrow “->” are the properties that you can read via that API call, while the items on the right of the left arrow “<-” are the values that you can write to that method/action.
“HasEvent” keyword indicates that there’s a particular event which will be reported by that grove module, you can receive an explicit semantic event message from the event reporting websocket, e.g. {u'msg’: {u'button_pressed’: u'0’}} which means the button attached to GPIO0 is pressed.
Read the property of a Grove module
Access through Data Exchange Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/Grove_Example1/temp
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/Grove_Example1/with_argument/90
{
"temp": 30
}
{
"cz": 78.0,
"cy": 45.6,
"cx": 12.3,
"degree": 90
}
Read a specified property of a specified grove instance on that node, returns the json expression of the property.
Note: Get to know the type of arguments with .well-known API output
GET /v1/node/GroveInstanceName/Property/{arg1}[/{arg2}][/{arg3}][/{arg4}]
Parameter | Type | Description |
---|---|---|
GroveInstanceName | string | The instance name of the connected grove module, this is generated. |
Property name | string | The readable property name of this module, get to know by the output of well-known API. |
arg1, arg2, arg3, arg4 | string, number | The arguments for the read function of the driver, the count of the arguments is not fixed, depending on the signature of the function. |
Write to a Grove module
Access through Data Exchange Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/Grove_Example1/float_value/10.5
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/Grove_Example1/multi_value/10/10.5/445566
{
"result": "OK"
}
Write or set the value to a specified property/method/action of a specified grove instance on that node. By writting, you can pass data down to the grove hardware ,or trigger an action, or do some configuration onto the hardware.
Note: Get to know the type of arguments with .well-known API output
POST /v1/node/GroveInstanceName/Property-or-Method-or-Action/{arg1}[/{arg2}][/{arg3}][/{arg4}]
Parameter | Type | Description |
---|---|---|
GroveInstanceName | string | The instance name of the connected grove module, this is generated. |
Property-or-Method-or-Action | string | The writable property name / action / method of this module, get to know by the output of well-known API. |
arg1, arg2, arg3, arg4 | string, number | The arguments for the write function of the driver, the count of the arguments is not fixed, depending on the signature of the function. |
Put the node into sleep mode
Access through Data Exchange Server
curl -X POST https://us.wio.seeed.io/v1/node/pm/sleep/5?access_token=d6d68b4b6b43f213569f5832dd8277b2
{
"result": "OK"
}
Put the node into deep sleep mode in which the whole board’s power will be shut down except that power of CP2102 if the system is powered by USB.
This will reduce the current consumption of the board to ~10mA if it’s powered by micro USB (due to CP2102). And the current will drop to ~1mA if the board is powered by battery.
The sleep will not be intermittently triggered. You need to call the sleep API every time you want the node to sleep. You can continue to send GET/POST requests after a sleep command has been executed, the node will return a 404 status code and a message saying it’s offline. Then the node wake up and join the router within about 5 seconds. You do some stuff and put the node into sleep again.
POST /v1/node/pm/sleep/{sleep_time_sec}
Parameter | Type | Description |
---|---|---|
sleep_time_sec | number | How many seconds you want the node to sleep |
Get the API reference page
Access through OTA Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/resources
An API reference web page will be rendered. With this reference page, you can lookup the URL of the APIs exposed and the events that node can produce.
GET /v1/node/resources
Trigger the OTA process for node
Access through OTA Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" -H "Content-Type: application/json" https://us.wio.seeed.io/v1/ota/trigger -d '{"board_name": "Wio Link v1.0", "connections":[{"port":"UART0", "sku":"111020001"},{"port":"I2C0", "sku":"101020050"}]}'
Configuration example
{
"board_name": "Wio Link v1.0",
"connections": [
{
"port": "UART0",
"sku": "111020001"
},
{
"port": "I2C0",
"sku": "101020050"
}
]
}
Response if the OTA is triggered successfully:
{
"ota_msg": "Building the firmware..",
"ota_status": "going"
}
This API let user trigger the OTA process, with a configuration description in json format. The request should be sent in ‘application/json’ content-type and the request body is a json object describes the connection of grove modules on the node.
If the OTA has been executed, a response with “ota_status” field will be returned. This is the first status of the OTA process - “Building the firmware”. Then you can poll the “/v1/ota/status” API to track the OTA states.
POST /v1/ota/trigger
The OTA process can also be split into two phases:
- Phase1 - Generate source files
- Phase2 - Build the firmware and transfer over the air to the node
To specify the phase, you can pass a parameter build_phase in the URL.
Parameter | Type | Description |
---|---|---|
build_phase | number | 1 - Only do phase 1 2 - Only do phase 2 3 or without this parameter - Do two phases |
Only phase 1
curl -H "Content-Type: application/json" https://us.wio.seeed.io/v1/ota/trigger?access_token=d6d68b4b6b43f213569f5832dd8277b2&build_phase=1 -d '{"board_name": "Wio Link v1.0", "connections":[{"port":"UART0", "sku":"111020001"},{"port":"I2C0", "sku":"101020050"}]}'
Only phase 2 (Must pass phase 1 before)
curl -X POST https://us.wio.seeed.io/v1/ota/trigger?access_token=d6d68b4b6b43f213569f5832dd8277b2&build_phase=2
Track the OTA status
Access through OTA Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/ota/status
Different states will be returned continuously
{
"ota_msg": "Downloading the firmware..",
"ota_status": "going"
}
{
"ota_msg": "Failed to send the binary",
"ota_status": "error"
}
{
"ota_msg": "Firmware updated",
"ota_status": "done"
}
User can send long-poll GET request to retrieve the OTA states. The request will be timeout after 3 minutes if there’s no states reported. Or a json response carrying the OTA state will be returned. The “ota_status” will have 3 values: going, done, error.
going - the OTA is still going on, will report more going state.
done - the OTA has succeeded, the firmware of node has been updated.
error - error happened during the OTA process.
GET /v1/ota/status
Get the configuration of node
Access through OTA Server
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://us.wio.seeed.io/v1/node/config
Response if the OTA is triggered successfully:
{
"config": {
"board_name": "Wio Link v1.0",
"connections": [
{
"port": "UART0",
"sku": "111020001"
},
{
"port": "I2C0",
"sku": "101020050"
}
]
},
"type": "json"
}
This API let user retrieve the configuration file uploaded in last OTA process.
GET /v1/node/config
Change the data exchange server for node
Access through OTA Server
curl -X POST -d dataxurl=https://example.com https://us.wio.seeed.io/v1/node/setting/dataxserver/192.168.31.2?access_token=d6d68b4b6b43f213569f5832dd8277b2
{
"result": "OK"
}
Change the data exchange server for a specific node. As the changing will be taken place at the node side, this API needs the node online. This API will cause the node reboot once. After rebooted, the node will interact with the configured data exchange server for data and event transmission. This API endpoint needs two parameters, one is in the url path, another is in the post body. The IP address in the url path will be sent to the node over the air while the dataxurl will be stored in the database. The stored url of data exchange server can be queried with the nodes/list API.
POST /v1/node/setting/dataxserver/{address}
Parameter | Type | Description |
---|---|---|
address | string | The IP address of data exchange server. Only IP address supported. |
dataxurl | string | The url of data exchange server. e.g. https://my-domain.com or http://192.168.1.2 |
Node Event API (use Websocket)
connect wss://iot.seeed.cc/v1/node/event
Example code:
var ws = new WebSocket('wss://iot.seeed.cc/v1/node/event');
ws.onopen = function() {
ws.send("d6d68b4b6b43f213569f5832dd8277b2");
};
ws.onmessage = function (evt) {
alert(evt.data);
};
The event data format like this:
{
"event_name_here": "event_data_here"
}
If you want to get the event from node at more real time, you can connect to the event reporting endpoint with WebSocket. After, send the Node Key to complete the handshake. Then, the onmessage
will get event data when node post it.
Coding on the fly
User’s logic block
User’s logic block (ULB) is a piece of c++ code which will be compiled into the firmware and run natively on Wio Link. One can modify the ULB between build phase 1 and build phase 2. The ULB has an Arduino style sketch which consists of setup and loop functions. The ULB will be uploaded onto the server and put into a build directory related to a particular node.
Access through OTA Server
Upload ULB:
curl -H "Content-Type: application/json" https://us.wio.seeed.io/v1/cotf/project?access_token=d6d68b4b6b43f213569f5832dd8277b2 -d '{
"./Main.h": "source code here",
"./Main.cpp": "source code here",
"./other_file.cpp": "source code here",
"./dir1/file1.h": "source code here"
}'
{
"result": "OK"
}
Download ULB:
curl https://us.wio.seeed.io/v1/cotf/project?access_token=d6d68b4b6b43f213569f5832dd8277b2
{
"./Main.h": "source code here",
"./Main.cpp": "source code here",
"./other_file.cpp": "source code here",
"./dir1/file1.h": "source code here"
}
Program ULB
uint32_t time;
void setup()
{
time = millis();
}
void loop()
{
if (millis() - time > 1000)
{
time = millis();
//do things here...
}
}
In the ULB, you can call the functions of all the grove modules selected in build phase 1. The grove modules selected in build phase 1 will expose read/write API endpoints and events congenitally. The event will be duplicated and be buffered in two event queue: the external event queue and the internal event queue. The events in external event queue will be dispatched to the event API (websocket). The events in internal event queue can be fetched by the ULB. Both queue has a depth of 100.
In the ULB, you can also interact with outside with the following functionalities:
- Register a variable, read and write the value of it through API
- Register a function, call it through API
- Post events
You should use delay very carefully because the watch dog will reset the Wio Link if delay more over 10ms. And the worst thing is that the Wio Link can never be OTAed if you programmed a bad ULB which causes the Wio Link reboot again and again. Once your Wio Link run into this situation, you can fix it with the guide of this document. We highly recommend use the time-point-check model to handle time.
Variable
Register a variable
int var1 = 100;
float f = 123.45;
String s;
...
wio.registerVar("var1", var1);
wio.registerVar("var2", f);
wio.registerVar("var3", s);
Read a variable
Access through Data Exchange Server
curl https://us.wio.seeed.io/v1/node/variable/var1?access_token=d6d68b4b6b43f213569f5832dd8277b2
Data type supported:
bool, uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, float, const char *, String.
All data types support reading.
All data types support writing except for const char * and String.
GET /v1/node/variable/{variable name}
Write a variable
Access through Data Exchange Server
curl -X POST https://us.wio.seeed.io/v1/node/variable/var1/200?access_token=d6d68b4b6b43f213569f5832dd8277b2
POST /v1/node/variable/{variable name}/{variable value}
Function
Register a function
void myfunc(String para)
{
Serial1.println(para);
}
...
wio.registerFunc("func1", myfunc);
...
Call a function
Access through Data Exchange Server
curl -X POST https://us.wio.seeed.io/v1/node/function/func1?access_token=d6d68b4b6b43f213569f5832dd8277b2 -d arg="argument here"
Only support one String type parameter.
POST /v1/node/function/{function name}
Parameter | Type | Description |
---|---|---|
arg | string | The argument for the registered function, POST should be sent in x-www-form-urlencoded format. |
Read events from connected grove modules
event_t event;
...
if (wio.eventAvailable())
{
wio.getEvent(&event);
if (strcmp(event.event_name, "encoder_position") == 0)
{
int32_t event_data = event.event_data.s32;
Serial1.println(event_data);
}
if (strcmp(event.event_name, "ir_recv_data_hex") == 0)
{
char *event_data = event.event_data.p_str;
Serial1.println(event_data);
}
}
...
To get the event data, you should read the correct item of the union:
union
{
uint8_t raw[4];
uint8_t u8;
uint16_t u16;
uint32_t u32;
bool boolean;
int8_t s8;
int16_t s16;
int32_t s32;
int integer;
float f;
char *p_str;
void *ptr;
}event_data;
Post events
wio.postEvent("my_event", event_data_var);
Data types supported for event data:
bool, uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, float, const char *, String
wio.postEvent() will post an event into external event queue, and then can be fetched with the Node Event API (use Websocket).