Service API¶
Service API enables using external applications/scripts with IoT
Service connects to IoT through TCP connection, if Service TCP server is enabled in IoT.
Functionality
- Service can HTTP API for sending requests to IoT
- It sends data and feedback directlythrough TCP connection
- It allows connecting to and monitoring active device parameters
- It can send notifications to IoT
Data Format¶
Data terminator for both request and reply is ‘nn’ reply can have format <METHOD><space><BODY>
Currently needed methods/keywords:
- REPLY - Generic reply to request
- HREPLY - HTTP request reply, containing response code and mimetype besides response body
- STOP - Signals to notification that it must close connection
- IDENT - service name, vendor, version, transmitted on connecting and on demand
- CONNECT - connect to device parameter to notify updates to service
- DISCONNECT - disconnect device parameter notifications from service
- SIGNAL - denote device parameter notification
- NOTIFY - general notification
Usage¶
Service status can be accessed by using ‘status’ parameter:
me/services/<service_name>(.json)?action=status
Other actions supported currently are ‘ident’ and ‘stop’
using ?action=ident with GET request translates to a body of:
{"action":"ident"}
which signals to serivce that it should return its service details preceded by IDENT keyword,
IDENT {"name":"IOT service 1", "vendor":"Isotel", "version":"1.0"}
Upon finalizing, DISCONNECT should be sent back to IoT, so it can safely unbind service
DISCONNECT
For normal replies to requests, REPLY keyword is used, followed by json/string data:
REPLY {"value":123}
If a reply requires additional HTTP response information, HREPLY keyword can be used:
HREPLY {"status":200, "mime":"application/json", "body":{"value":123}}
Connecting to parameters
Connecting to parameters is done by sending CONNECT command to IoT
CONNECT <parameter_uri>
CONNECT /me/device0/ec/E
IoT send back a reply with status:
CONNECT /me/device0/ec/E {"status":"OK"}
or, on failure to connect
CONNECT /me/device0/ec/E {"status":"Error"}
When successfuly connected to device parameter, IoT sends data notifications on message updates, keword used is SIGNAL
SIGNAL <parameter_uri> <data>
SIGNAL /me/device0/ec/E {"status":"OK","E":{"value":"12.75"},"time":"1444751862.112"}
Disconnect is performed in the same manner by sending DISCONNECT to IoT
DISCONNECT <parameter_uri>
DISCONNECT /me/device0/ec/E
Connect parameters can be specifies in json form, example request:
CONNECT me/device0/ec/E\r\n{"debounce_time": 1000, "send_data": false}\n\n
Where debounce time is the max frequency of updates, and send_data specifies if SIGNAL notifications should contain parameter data as well
Notifications
Notifications can be sent from service by using NOTIFY keyword, followed by space and json data in the same format as /me/activity.json data is given:
NOTIFY {"module": "service component X", "severity": "API", "message": "content..."}\n\n
NOTIFY {"severity": "SYSLOG", "message": "content...", "receiver": "app1"}\n\n
Only ‘message’ parameter is mandatory, other fields default to following values if omitted:
- ‘module’ defaults to service name
- ‘severity’ defaults to ‘API’
- ‘receiver’ remains null