Learning Node-RED: 06/04/16

Seeedstudio deployed two exchange servers that expose APIs for communicating with WioLink boards. I am using the international server from US and can tell you that the response time is awesome.

https://us.wio.seeed.io
https://cn.wio.seeed.io

There is a comprehensive API guide on Seedstudio webpage. It can be visited by clicking on this link.

I will share some flows that I have used to test the communication via API.

When testing API is very helpful to use a tool like postman or insomnia

You will need a running Node-RED instance and again I suggest you to try FRED to keep things easy. I will assume you already have a WIO Link board online with some Grove module connected. For this post I am using the temperature and humidity sensor.

I have built flows to test 8 different APIs and all of them works in the same general way:

An inject node will launch the flow.
A function node will prepare the required properties in the msg object.
The HTTP Request node will send the requests to the exchange server.
The result will be displayed in the debug node of Node-RED and also sent via Dweet to allow you to better visualize the results in a web page.

I remind you that it is necessary to use two different tokens when playing with WioLink APIs. One of them is the user token and is required by some APIs (Eg. to log in, retrieve the password and change the password). The other token is the node token and it is used by the APIs that read and write to the Grove modules (sensors and actuators).

The first flow depicted above will test the API "User Login". As a result, it will provide the user token that was assigned when you created your login in the app (Android or IOS). This user token will be stored in a global variable in Node-RED. Storing the token will make easier testing another API´s.

In order to test your WioLink board with these flows, you will need to modify the parameters in the dialog box of the inject node "email + password" by using the same data that you informed when configuring your board in the app.

The second flow will test the API "Node List" that lists the WIO Link boards configured under your account. This flow also stores the node token of the first WIO Link (the flow need to be modified if you have more than one WioLink board).

Before you can test the other flows you must first trigger these two initial flows. The reason, like I said before, is that we need to store the user token and the node token before using the next flows. You can play with the flows and modify them to suit your purposes and, if you want, you can hardcode your tokens in the nodes.

The next three flows require the user token and will test the APIs: Boards List, Scan Drivers, and Scan status. Note that the Scan Drivers result in a quite long reply and therefore it will not work with Dweet that limits the payload of the message to 2.000 characters.

The following two APIs are: Node config and Node .well known.

Finally, the last API test the temperature and humidity sensor.

Understanding the nodes used in the flows:

Node-RED can easily access WIO Link exchange servers (in fact any HTTP server) thanks to the function node "HTTP Request".

My choice was not to configure the parameters in the dialog box of the HTTP Request node. When we leave the parameters blank in the configuration box it means that the node expects to receive a msg object from the previous node with some properties configured in advance.

Those properties are:
msg.url
msg.method
msg.headers
msg.payload

Below picture shows that "HTTP Request" dialog boxes have not been configured.

In my flows, I have inserted a "function" node before each "HTTP Request" node. Those function nodes are responsible to set up the msg properties with the right values.

Below picture shows how the function node is configured for one of the flows. Note the way to set up and read global variables in Node-RED by using the functions: global.set() and global.get().

Using Dweet.io is straightforward. The good thing about this environment is that it requires no login and not set up. You just send the information to their servers and read the results in a web browser.

I configured the Dweet node as below.

In such case, I will read the results on this link:

https://dweet.io/get/latest/dweet/for/my-wio

You better to select another "Thing" name, instead of "my-wio" to avoid getting confused by reading my own dweets.

See the results I got from Dweet for the APIs:

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T22:07:48.193Z","content":{"token":"PPxxPQlS7gwSLfwsQyYO9ZxRwq9EuLodP2swG2SpNsaY","user_id":1829}}]}

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T22:11:04.226Z","content":{"nodes":[{"name":"AIOT","node_key":"a1adldfa6dc7726333d49962dde5599b","node_sn":"1c754d28816062345523164b75ccd147","dataxserver":null,"board":"Wio Link v1.0","online":true}]}}]}

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T21:51:16.758Z","content":{"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":17},"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},{"board_flash_spi_mode":"QIO","board_builtin":{"FUNCTION_KEY":0,"STATUS_LED":2,"GROVE_POWER_SWITCH":15},"interfaces":{"A0":{"type":"ANALOG","pin":17},"UART0":{"pintx":1,"pinrx":3,"type":"UART"},"I2C0":{"pinscl":3,"type":"I2C","pinsda":1},"I2C1":{"pinscl":5,"type":"I2C","pinsda":4},"D0":{"type":"GPIO","pin":3},"D1":{"type":"GPIO","pin":5}},"board_name":"Wio Node v1.0","board_flash_map":6,"board_vendor":"seeedstudio","board_flash_spi_speed":40}]}}]}

This one will not work with Dweet since the payload size is greater than 2.000 characters.

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T21:54:54.005Z","content":{"msg":"scanned 42 grove drivers at 2016-05-12 11:21:59.295065","result":"OK"}}]}

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T21:55:52.127Z","content":{"type":"json","config":{"board_name":"Wio Link v1.0","connections":[{"sku":"101020019-ffff","port":"D0"}]}}}]}

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T21:58:04.302Z","content":{"name":"AIOT","well_known":["GET /v1/node/GroveTempHumD0/humidity -> float humidity","GET /v1/node/GroveTempHumD0/temperature -> float celsius_degree","GET /v1/node/GroveTempHumD0/temperature_f -> float fahrenheit_degree"]}}]}

{"this":"succeeded","by":"getting","the":"dweets","with":[{"thing":"my-wio","created":"2016-06-04T21:59:07.684Z","content":{"celsius_degree":20}}]}

Below the JSON with the flows. You can copy and import to Node-RED.

Learning Node-RED

Saturday, June 4, 2016

WIO Link - HTTP Requests from Node-RED