NAV

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

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:

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
email 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
email 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
email 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

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:

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:

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).