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