-
Notifications
You must be signed in to change notification settings - Fork 64
API Documentation
There're two kinds of tokens: user token and node token.
The /node/* API calls need node token specified.
- with query string: xxxx/xxxx?access_token=[your token here]
- with "Authorization" header: Authorization: token [your token here]
Arguments in post body must be specified in application/x-www-form-urlencoded format: arg1=xxx&arg2=xxx, application/json and multipart/form-data are not accepted.
Access with User Token
curl -d email=[email here] -d password=[password here] https://iot.seeed.cc/v1/user/create
response:
{"status": 200, "msg": "User created", "token": "9L0_ofzPHnan91UQbtcCS4KzCI8BGQk6-OgMOtmnI3Q"}
curl -d password=[new password here] https://iot.seeed.cc/v1/user/changepassword?access_token=9L0_ofzPHnan91UQbtcCS4KzCI8BGQk6-OgMOtmnI3Q
response:
{"status": 200, "msg": "Password changed, new token is given", "token": "aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA"}
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.
curl -d email=[new email here] https://iot.seeed.cc/v1/user/retrievepassword
response:
{"status": 200, "msg": "The password has been sent to your email address\n"}
curl -d email=[email here] -d password=[password here] https://iot.seeed.cc/v1/user/login
response:
{"status": 200, "msg": "Logged in", "token": "aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA"}
Access with User Token
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" -d name=node_1 https://iot.seeed.cc/v1/nodes/create
response:
{"status": 200, "msg": "Node created", "node_key": "85a7c2b2fd97c357137414733e65d516", "node_sn": "200d8a94ac5f0905e1fbf9acdfcaba78"}
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://iot.seeed.cc/v1/nodes/list
response:
{"status": 200, "msg": "", "nodes": [{"node_key": "d6d68b4b6b43f213569f5832dd8277b2", "name": "node_1", "node_sn": "f70fd643b73f0c721b007ce453bafddd"}, {"node_key": "85a7c2b2fd97c357137414733e65d516", "name": "node_2", "node_sn": "200d8a94ac5f0905e1fbf9acdfcaba78"}]}
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://iot.seeed.cc/v1/nodes/rename -d node_sn=160769ffa50feae76ec6f7a4fb95bf6c -d name=new_name
response:
{"status": 200, "msg": "Node renamed", "name": "node_2"}
curl -H "Authorization: token StiLU1g5SNfQYWQLKpB7uMuE4l2uQuamKMBsIW1RGgA" https://iot.seeed.cc/v1/nodes/delete -d "node_sn=bac0df2d1b01b32c8ad3a0efbfc31c5f"
response:
{"status": 200, "msg": "Node deleted"}
Access with User Token
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://iot.seeed.cc/v1/scan/drivers
response:
{"status": 200, "msg": "", "drivers": [{"SKU": "104030003", "Files": ["grove_4_digit.cpp", "grove_4_digit.h"], "ClassFile": "grove_4_digit.h", "GroveName": "Grove - 4-Digit Display", "Inputs": {"write_display_point": ["uint8_t display"], "write_display_digits": ["uint8_t start_pos", "char *chars"], "write_clear": [""], "write_display_one_digit": ["uint8_t position", "char *chr"], "write_brightness": ["uint8_t brightness"]}, "Outputs": {}, "ImageURL": "http://www.seeedstudio.com/depot/bmz_cache/3/3a9f79323a82950c12fc7e69fa9fab4d.image.530x397.jpg", "ID": 0, "ClassName": "Grove4Digit", "HasPowerOnFunc": true, "CanGetLastError": true, "InterfaceType": "UART", "HasEvent": false, "IncludePath": "./grove_drivers/grove_4_digit", "HasPowerOffFunc": true, "Events": {}, "ConstructArgList": ["int pintx", "int pinrx"]}]}
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://iot.seeed.cc/v1/scan/status
response:
{"status": 200, "msg": "", "scan_status": {"msg": "scanned 40 grove drivers at 2015-12-23 22:56:48.246117", "result": "OK"}}
or
{"status": 200, "msg": "", "scan_status": {"status":"Failed", "msg":"Fail cause"}}
Access with User Token
curl -H "Authorization: token aKleqQebIsjmQMSCokemtgNXMD4Y7OTe3uyzEL1iwwA" https://iot.seeed.cc/v1/boards/list
response:
{"status": 200, "msg": "", "boards": [{"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}}, "board_name": "Wio Link v1.0", "board_flash_map": 6, "board_vendor": "seeedstudio", "board_flash_spi_speed": 40}]}Access with Node Token
Access through Data Exchange Server
".well-known" API prints all the available resources on that node. This API needs the node online.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/.well-known
response:
{"status": 200, "msg": [
"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"]}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.
Access through Data Exchange Server
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
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/Grove_Example1/temp
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/Grove_Example1/with_arg/90
response:
{"status": 200, "msg": {"temp": 30}}
{"status": 200, "msg": {"cz": 78.0, "cy": 45.6, "cx": 12.3, "degree": 90}}
{"status": 205, "msg": null}
{"status": 205, "msg": "error description here."} #if driver tells the error reason
Access through Data Exchange Server
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
Note2: Only this API supports application/json post body.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" -d "{\"f\":10.5}" https://iot.seeed.cc/v1/node/Grove_Example1/float_value
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/Grove_Example1/multi_value/10/10.5/445566
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" -d "a=10&b=10.5&c=445566" https://iot.seeed.cc/v1/node/Grove_Example1/multi_value
response:
{"status": 200, "msg": "OK"}
{"status": 205, "msg": "Failed"}
{"status": 205, "msg": "failure reason here."} #if driver tells the fail reason
Access through Data Exchange Server
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 the usb to serial chip 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.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" -d "sleep_time_sec=5" https://iot.seeed.cc/v1/node/pm/sleep
or
curl -X POST https://iot.seeed.cc/v1/node/pm/sleep/5?access_token=d6d68b4b6b43f213569f5832dd8277b2
response:
{"status": 200, "msg": "ok, deep sleep"}
Access through OTA Server
This API shows a web page that displays the APIs available.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/resources
response:
A web page.
Access through OTA Server
This API let user trigger the OTA process, with a configuration description in json format.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/user/download -d '{"board_name": "Wio Link v1.0", "connections":{"UART0": "111020001"}}'
response:
if the OTA is triggered successfully
{"status": 200, "msg": "", "ota_msg": "Building the firmware..", "ota_status": "going"}Access through OTA Server
This API let user retrieve the last config file.
curl -H "Authorization: token d6d68b4b6b43f213569f5832dd8277b2" https://iot.seeed.cc/v1/node/config
response:
{"status": 200, "msg": "{\"board_name\": \"Wio Link v1.0\", \"connections\": {\"UART0\": \"111020001\"}}", "type": "json"}Access through OTA Server
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. And the configured data exchange server can be queried with the nodes/list API.
curl -X POST https://iot.seeed.cc/v1/node/setting/dataxserver/192.168.31.2?access_token=d6d68b4b6b43f213569f5832dd8277b2
If you want to get the node event at any time, you should open a websocket in the client's background. After, send the Node Key to complete the handshake. Like this:
<script>
var ws = new WebSocket('wss://iot.seeed.cc/v1/node/event');
ws.onopen = function() {
ws.send("d6d68b4b6b43f213569f5832dd8277b2");
};
ws.onmessage = function (evt) {
alert(evt.data);
};
</script>Then, the onmessage will get event data when node post it.
The event data format like this:
{'event_name_here': 'event_data_here'}