Mbed/mbed Device Connector

From ESS-WIKI
Jump to: navigation, search

Introduction

ARM mbed Device Connector provides a service for mbed developer to connect mbed device to mbed cloud. The service makes IoT device messaging, provisioning and updates available to other software, web applications and cloud through easily-integrated REST APIs.

Account and Security Key

Create your account and login. In Dashboard you can see information about your device and security related topics.


Mbed connector dashboard.png


Security credentials

Click Security credentials under My Devices, then click GET MY DEVICE SECURITY CREDENTIALS.


Mbed connector securityCredentials.png


The security credential required for your device to successfully register to mbed connector service is created. Copy and paste all the content to 'security.h' file in your mbed client source tree.


Access keys

Click Access keys under My Applications, then click CREATE NEW ACCESS KEY to create access key for your application in order to connect to mbed Device Connector REST API.


Mbed connector accessKey.png


API Console

After connecting mbed device to mbed Device Connector, confirm it by checking Connected Devices under My Devices.


Mbed connector connectedDevice.png


Then go to API Console under Device Connector. API Console lets you simulate your application requests against mbed Device Connector REST API.


Mbed connector apiConsole.png


For example, you can send a request to GET the data of resources exposed in your device. First, select endpoint (device) and resource-path (see "53b4decc-eb52..." and "/3304/0/5700" in example image below). Then click TEST API. The endpoint and resource-path here are also used as {endpoint-name} and {resource-path} in a REST API call, explained in 4. Get Data from mbed Connector in NodeRED


Mbed connector restRequest.png


Then check the result of your request in Response area. The data of this requested resource, Humidity value (/3304/0/5700), is reported in "payload" field in Base64 format.


Mbed connector restRequestResult.png


Get Data from mbed Connector in Node-RED

API Console is a convenient tool to check your device and resources on it. It helps you easily verify the result of your application sending requests against mbed Device Connector REST API. In real cases you will need to get this data in your software, web applications or cloud through these REST APIs. Below is an example using Node-RED to get this Humidity value.


Mbed connector nodered.png


Nodes in this flow:

  • Authorization : Include authentication information in http request header in order to access your device. Refer to 2.2 Access keys for valid authentication access key.
  • http request humidity : To call mbed connector REST API, the endpoint resource representation in http URL is in format
    https://api.connector.mbed.com/endpoints/{endpoint-name}/{resource-path}
    Refer to 3. API Console for valid {endpoint-name} and {resource-path}.
  • http request result : The 'http request humidity' REST API is asynchronous API, meaning that the return of this API request does NOT contain the result. So this 'http request result' node uses 'long polling' to request for the actaul result of 'http request humidity'. To send a long polling request, the URL of the http request is
    https://api.connector.mbed.com/notification/pull
  • result parsing : The return of 'http request result' contains all the notification messages, including response of 'http request humidity'. 'result parsing' node finds this response and parses the data value in Base64 foramt.


Control Flow Code 

Copy and import below code in Node-RED to deploy the complete control flow as illustrated in image above:

[{"id":"259b0850.aa2b08","type":"http request","z":"200412fa.2e065e","name":"http request result","method":"GET","ret":"txt","url":"https://api.connector.mbed.com/notification/pull","x":610,"y":250,"wires":[["df224b13.6d7d08","cacec099.6356c"]]},{"id":"cacec099.6356c","type":"debug","z":"200412fa.2e065e","name":"","active":false,"console":"false","complete":"payload","x":1013,"y":250,"wires":[]},{"id":"468f5044.aa333","type":"inject","z":"200412fa.2e065e","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"x":124,"y":78,"wires":[["771e818f.dcca","fcaf680b.816658"]]},{"id":"5367618e.e4444","type":"http request","z":"200412fa.2e065e","name":"http request humidity","method":"GET","ret":"txt","url":"https://api.connector.mbed.com/endpoints/5eb4decc-eb52-4b5a-abb6-be42d1d05b9e/3304/0/5700","x":609,"y":77,"wires":[["76011900.e09cf8"]]},{"id":"91544a3e.d76438","type":"function","z":"200412fa.2e065e","name":"Authorization","func":"msg.headers = {\n    \"Authorization\": \"Bearer your-access-key\",\n};\n\nreturn msg;","outputs":1,"noerr":0,"x":431,"y":251,"wires":[["259b0850.aa2b08"]]},{"id":"771e818f.dcca","type":"delay","z":"200412fa.2e065e","name":"","pauseType":"delay","timeout":"2","timeoutUnits":"seconds","rate":"1","rateUnits":"second","randomFirst":"1","randomLast":"5","randomUnits":"seconds","drop":false,"x":277,"y":253,"wires":[["91544a3e.d76438"]]},{"id":"76011900.e09cf8","type":"debug","z":"200412fa.2e065e","name":"","active":false,"console":"false","complete":"false","x":1012,"y":78,"wires":[]},{"id":"9d815e3b.f02cc","type":"inject","z":"200412fa.2e065e","name":"","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"x":125,"y":353,"wires":[["df224b13.6d7d08"]]},{"id":"df224b13.6d7d08","type":"function","z":"200412fa.2e065e","name":"result parsing","func":"var str = msg.payload;\nmsg.payload = '';\n\nvar dataIdxPos = str.lastIndexOf('/3304/0/5700');\nif (dataIdxPos > -1) {\n    var errPos = str.indexOf(\"error\", dataIdxPos+1);\n    var dataValStartPos = str.indexOf(\"payload\", dataIdxPos+1);\n    if (dataValStartPos > -1) {\n        if ( (errPos > -1) && (errPos < dataValStartPos) ) {\n            return msg;\n        }\n\n        var dataValEndPos = str.indexOf(\",\", dataValStartPos+1);\n        if (dataValEndPos > -1) {\n            var dataVal_base64 = str.slice(dataValStartPos+10, dataValEndPos-1);\n            var buf = new Buffer(dataVal_base64, 'base64');\n            var tempVal = buf.toString();\n            msg.temp = tempVal;\n            return msg;\n        }\n    }\n}\n","outputs":1,"noerr":0,"x":823,"y":350,"wires":[["d6945e51.9a79c"]]},{"id":"d6945e51.9a79c","type":"debug","z":"200412fa.2e065e","name":"","active":true,"console":"false","complete":"false","x":1012,"y":350,"wires":[]},{"id":"fcaf680b.816658","type":"function","z":"200412fa.2e065e","name":"Authorization","func":"msg.headers = {\n    \"Authorization\": \"Bearer your-access-key\",\n};\n\nreturn msg;","outputs":1,"noerr":0,"x":425,"y":78,"wires":[["5367618e.e4444"]]}]