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