Operations Hub M2M Device RESTful APIs

Operations Hub allows sensors to connect directly to the Operations Hub server using RESTful services to broadcast sensor data and receive commands. The connection to the Operations Hub server uses Standard REST POST calls.

The Operations Hub gateway identifies the information source based on the following parameters::
  • Remote Device Unique Identifier: By remote device, we refer to gateways of any type supporting an http connection. Usually, the best way to create a unique ID is by using the gateway’s MAC address.
  • Remote Sensor/Controller Unique Name: Any name can be used as long as it is unique to the gateway. It could be a logical name (for example, Sensor1 or the address of the sensor (if it has one)).
  • The Operations Hub Account: Account username and password.

API Handshakes

The handshakes define the message structure and message types exchanged between the device and the Operations Hub cloud. The Operations Hub API supports 3 types of request:
  • Login: The device asks to be authenticated.
  • Publish: The device sends new sensor data to Operations Hub.
  • Subscribe: The device requests new commands or control instructions from Operations Hub.

JSON Message Format

Messages exchanged between the Operations Hub server and the device client are in the JSON format. JSON is a string representation of data; it is lighter than XML, and hence, it is more suitable for M2M messages. JSON messages are formatted as name/value pairs: "variable name":"variable value"

Messages can contain more than one variable using a comma as the delimiter: {"variable name1":"variable value1","variable name2":"variable value2"}

The variable value can be a list of parameters, enclosed in curly braces {} using a comma as the delimiter. For example: {"variable name":{"parameter1":"value1","parameter2":"value2"}}

Client Login

Before communicating with the Operations Hub server, the device client must login to the server. The login URL is: https://<Operations Hub_Site_URL>/app/iqp/rest/login

  1. To login, the client sends a login request: {"handshake":{"stage":"login"},"login":{"username":"user name of the user","password":"password of the user"}}
  2. The server responds with a success or failure message: If authentication succeeds; the server responds with code 1 and provides the client with a token: {"handshake":{"stage":"login","code":"1"},"token":"token number"}. If authentication fails, the server responds with code 0: {"handshake":{"stage":"login","code":"0"}}. If the login fails, the client must request the login again.
  3. The token returned by the server is a unique identifier, which serves to identify the client during further communications with the server. The token must be included in all the publish and subscribe messages from the client to the server. The token remains valid as long as the client communicates with the server. If the device is inactive for 20 minutes or longer, the token will expire. If the client attempts to communicate with the server using the token after it has expired, an unauthorized message will be returned by the server. When this happens, the client must login again to receive a new token.

Publishing M2M Data

The publish stage is used by the Gateway/Device/Sensor to send new data to the Operations Hub server. The publish URL is: https://Operations Hub site URL/app/iqp/rest/publish. The published data is in the form of a JSON string. Each message contains the following information:
  • Data Channel: The Data Channel tells the server where the data is coming from. The source is represented as a data source path, which is composed of 3 parameters, a combination of its Account name/Gateway id/Sensor id. For example: "REST_DEMO/01-23-45-67-89-ab/temperature0".
    • For the Gateway id, it is recommended to use the device MAC Address or IMEI number.
    • The Sensor id can be any logical name. The name must be unique to this gateway.
    Note: The application developer in Operations Hub will use the sensor name to build their application. For this reason, it is recommended to use a logical name describing the sensor or device. For example, if the device represents a temperature sensor, use the word temperature in the name and add a number to make it unique: temperature9
    Important: For HTTP requests, avoid using spaces in names and ids.
  • Metrics: The Metric Data Message defines a set of data from the sensor/device as a series of keyname:value pairs. The “keyname” in the keyname value pair defines the field in the Operations Hub M2M_data entity where the “value” will be stored. The following Keynames are supported.
    Keyname M2M_data Field Storage Format
    met metric String Developer-defined String (compulsory field)
    val data String Developer-defined value (compulsory field)
    lat latitude String WGS84 recommended for online map compatibility (common field)
    long longitude String WGS84 recommended for online map compatibility (common field)
    time timestamp DateTime ISO 8601 “YYYY-MM-DDThh:mm:ss.sss±TZ” (common field)
    alt altitude String Developer-defined value (common field)
    desc description String Developer-defined string
    type data_type String Data type of the data field “String” or “Number”
    gen1 generic_1 String Developer-defined string or value
    gen2 generic_2 String Developer-defined string or value
    • All Operations Hub payload messages must contain the metric and data keyname value pairs.
    • All other keyname value pairs are optional.
    • The order of the keyname value pairs in the payload is not compulsory.
    • If included, Timestamps must be formatted according to the ISO 8601 format specified above.
    • The Data Type entry can be used in cases where Operations Hub does not automatic identify the data type correctly.
  • The Publish request process: To publish a message to the server, the client uses the following format: 
    {"handshake":{"stage":"publish"},"token":"token number","messages":[
                        {"dc":"data channel","cloud":"cloud server timestamp","data":[                              
                        {"alt":"value","lat":"value","long":"value","time":"timestamp recorded in the device","mets":[
                        {"met":"value","val":"value","type":"value","desc":"value","gen1":"value","gen2":"value",}
                        ]
                        }
                        }]}
    The server will respond with a success failure message: {"handshake":{"stage":"publish","code":"<0/1>","dc":"data channel"}}, where code=1 represents success, and code=0 represents failure to process the message. The returned Data channel is the channel that was sent in the publish request that the response is replying to.
  • Sending Multiple Metrics: Multiple metric data entries can be sent in a single publish message using the JSON array format. Arrays in JSON are in the format of "[array data]". For example: one published payload could contain several messages for a car’s speed, engine temperature, fuel level, odometer, etc. or from an intermediary data server, it could contain multiple messages from several different devices. An example of a JSON publish request containing several entries: 
    {"handshake":{"stage":"publish"},"token":"00000000-00000000-00409DFF-FF521DB2", "messages":[
                        {"dc":"Operations Hub_Testing/REST_Device/Vehicle2","cloud":"2015-03-26T18:46:38.237+09:00","data":[
                        
                        {"alt":"1234","lat":"35.587562","long":"139.668916","time":"2015-03-26T18:44:38.195+09:00","mets":[
                        {"met":"Speed","val":"100","type":"double","desc":"kmh"},
                        {"met":"Heading","val":"180","type":"double","desc":"degrees"},
                        {"met":"Temperature","val":"98","type":"double","desc":"degrees"}
                        ]
                        },
                        {"alt":"1240","lat":"35.587565","long":"139.668920","time":"2015-03-26T18:45:38.195+09:00","mets":[
                        {"met":"Speed","val":"75","type":"double","desc":"kmh"},
                        {"met":"Heading","val":"237","type":"double","desc":"degrees"},
                        {"met":"Temperature","val":"96","type":"double","desc":"degrees"}
                        ]
                        }
                        ]
                        }]}

Subscribing to receive M2M commands

The subscribe stage is used by the Gateway/Device/Sensor to check the Operations Hub server for commands. The subscribe URL is: https://<Operations Hub_Site_URL>/app/iqp/rest/subscribe. In the M2M world, Gateways/Devices can lose connection to the server from time-to-time. For this reason, the Operations Hub server does not push commands to devices. It is up to the embedded code in the device to periodically check with the server for any available commands. Subscribe requests use the following information:
  • Data channel: The Gateway/Device asks the server for all commands available for a Data channel. Command requests may be for specific sensors, for all commands for a Gateway/Device or all commands for an account. The corresponding Data channel formats are as follows:
    • Specific sensor: Account_name/Gateway_ID/Sensor_ID
    • Specific Gateway: Account_name/Gateway_ID
    • Specific account: Account_name
  • Request type: The request type identifies what stage of the subscription process we are in. The available request types are:
    • subscribe: The client requests for available commands.
    • command_list: The server sends a list of the commands.
    • no_commands: The server notifies the client that no commands are available.
    • result: The server replies to confirm whether or not the request has been processed correctly.
  • Commands: The command or commands to execute. Commands are usually vendor-specific or device-specific. The commands could be AT commands or client code specific implementation commands.
Subscribe requests have the following stages.
  1. Client to Server: The client requests for available commands. The client initiates the process by sending a subscribe request to the server: {"handshake":{"stage": "subscribe"},"token":"<token>", "payload":{"dc":"<channel>","request_type":"subscribe"}}
  2. Server to Client: The server sends a list of commands to the client. If the server has commands available for the device, it will return a command list: {"handshake":{"stage":"subscribe"},"payload":{"request_type":command_list", commands: [{"dc":"<channel>","command":"<command>"}]}}
    Important: The server will return an array of channel specific commands. If the subscribe request was for all available commands for an account Data channel. The server response will be an array of commands where the Data channel for each command is specific to the gateway, device, or sensor that the command is assigned to.
    If the server has no commands available for the device, it will return a no_commands response: {"handshake":{"stage":"subscribe"},"token":"<token>","payload":{"request_type":" no_commands","dc":"<channel>"}}. The datachannel, in this case, is the channel of the original request. For example, if it was for a device, it would be account/device.

M2M Device API Error codes

If an error occurs while processing requests, the server will return the following message: {"handshake":{"stage":"error","code":"<code>"}}

Possible error codes are:
  • 1: Bad JSON Format
  • 2: Unauthorized user