SimplyTiny for IoT is a string based method for exchanging meta-data and or blob data between an IoT device and your upstream application server via the IoTGtw data orchestration cloud service.
It is a simple and efficient with little or no impact to low complexity IoT devices. SimplyTiny was specifically designed with simply tiny IoT devices, objects and sensors in mind.
It works out of the box on 99.9% of new or existing IoT devices and does not require any firmware upgrade or software/library install on the device in order to use it!
SimplyTiny For IoT Supports:
- Device Authentication
- Device bootstrap
- Auto Capture Device Auth Token
- Device Auth Token distribution
- Device PSK / X.509 Certificate Distribution
- Periodic Device Auth Token Update/Refresh
- Messaging / Conveying structured or blob data
- Message Acknowledgement
- Traffic Distinguishing / Split Routing
- Ping / Keep-alive
- Dynamic Service Access Point/Settings Retrieval
- Device shadow copy update which can be directly viewed on the portal and portal map as well as retrieved via APIs. Device shadow copy includes gps coordinates, signal strength information, power usage information, device timestamp, etc.
- Transmitting structured or blob/opaque data between Device and Upstream application
- Device Management Functions: Device Auto Configuration & Firmware management (update and retrieve Device Twin / Configuration)
The SimplyTiny framework is very easy to use and can be used in any of these methods:
- Simple strings (minimalist and efficient – use a specific character of your choice as separator/delimiter to send parameters, enclose your IoT opaque data within the data section then send the entire string as the payload of your device preferred IoT protocol such as UDP socket, TCP socket, MQTT-SN, CoAP with or without DTLS/TLS encryption. See example below )
- JSON (The relevant parameter JSON structured, your opaque IoT data is enclosed in the data section of the JSON and the entire JSON is sent as the payload of your device preferred IoT protocol such as UDP socket, TCP socket, MQTT-SN, CoAP with or without DTLS/TLS encryption – See example below)
- URL parameters (Allows to use simplytiny over URI string while leaving the payload section of your chosen protocol untouched and entirely for your blob/opaque IoT data. The parameters are passed as part of URI query strings. i.e. in CoAP URI)
- Bring Your Own Custom JSON – Supports use of your custom or existing JSON format already in use by your device. Requires Private SAP with custom schema which can be easily requested on the Portal from the service access point page.
Access SECURITY
- All the above can be done over secure and encrypted bearer with any of the support protocols and application framework from any of your preferred regions.
- The device must provide a valid device identity in the SimplyTiny message i.e. udid or customer_id + custom_device_id or customer_id + imsi
- The device must provide an authentication token (at) in the SimplyTiny message, the auth token must match the current auth token set on the platform for the device.
- When performing bootstrap operation the device must provide the bootstrap token set on the platform for the device in the SimplyTiny message.
- A SimplyTiny bootstrap operation request from device is only accepted if the supplied bootstrap token is valid AND if the specific bootstrap operation being requested has been explicitly set/allowed on the device service template for more information see the bootstrap service for IoT section
- All other operations including “auto capture auth key”, “periodic auth key refresh”, “message acknowledgement”, “split routing”, etc can also be allowed/disallowed on the device service template to tightly control what operations device out in the field is allowed to perform.
SimplyTiny Strings
- SimplyTiny string based format has up to 10 header fields
*field1*field2*field3*field4*field5*field6*field8*)device-blob-goes-here - The header fields are used to convey meta-data information such as device identity and device auth token. The blob section is used to convey any data from device to be passed on an upstream application or to be stored depending on configuration
- The first character indicates the field separator/delimiter for that particular message. In the above sample the * is the delimiter (field separator character).
- Various characters can be used as the delimiter. In any case the preferred delimiter must be placed in the first character position and subsequently used to separate the header fields.
- The end of the header section is the start of the payload section and is demarcated with the preferred delimiter AND an a right parenthesis ) character.
- The header field delimiter can be any one of the following safe characters:
_ .+ ! *, ( [ ) ]
- Namely, underscore or dot or plus–sign or exclamation mark or asterisk or comma, or left parenthesis or left bracket or right-parenthesis or right bracket
For example, if the asterisk * character is the chosen delimiter to be used for sending a message from a device, the asterisk character * is put as the first character of the sting, and becomes the field separator. The asterisk character plus the right parenthesis *) will act as the demarcation indicating the section that holds the device payload.
*header1*header2*header3*)any-content-data-goes-here
It is recommended to always choose a delimiter that will not conflict with the values conveyed within the header field. Therefore choose the field separator carefully.
SimplyTiny String Format Field Delimiter:
The field delimiter is the first character at char 0 position that will be used as the field separator key.
Each header field is dedicated for conveying specific meta-data information as required. The header field names are as follows (assuming asterisk as delimiter):
*udid*device_auth_token*message_id*message-type-indicator*split_traffic_profile_number*gps_lat*gps_long* signal_strength*power_usage_info*timestamp*)large_or_tiny_data_content
Apart from the udid header field, all other header fields are optional. Note that if device authentication is enabled for a device then that device must must provide its authentication token in every message (except in ack messages).
Optional fields can be left empty.
The header fields provided will be available on the Portal along with other meta-data information. Depending on the account setup, the received meta-data information can be pushed to the customer upstream application or can be retrieved using the GET device provisioning API service and for historical information using the messaging API service.
SimplyTiny JSON Format
SimplyTiny JSON Format is the JSON formatted version of the SimplyTiny but supports additional meta-data fields such as (custom device id, customer id) to allow customers to configure their devices to use customer set device ID in combination with the customer id for message/service requests. Note that when using SimplyTiny JSON format, device must supply either 1) “udid” (recommended) or 2) “device_id” AND “customer_id” or 3) “imsi” + “customer_id”. Either of these sets of fields must be supplied in the JSON message to enable successful identification and authentication of the device.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
{ udid: "", //unique device identifier assigned to the device when it was created dvid: "", //custom device_id set by customer on the device object imsi: "", //custom device IMSI id set by customer cid: "", //customer account id at: "", //device authentication token mti: 0, //message type indicator trpn: 0, //traffic routing profile Number msgid: "", //message id lat: "", //gps geo-coordinate latitude long: "", //GPS geo-coordiante longitude ss: "", //Wireless Device Signal Strength pw: "", //Device power usage information tmst: "", //Device timestamp of when the message was generated/left the device data: "" //actual device blob payload } |
SimplyTiny in URI
The simplytiny parameters can be embedded as part of the existing protocol URI for example:
……..?simplytiny=1&udid=54ed2597a78b651334&at=Kh_12rD2w&msgid=532&mti=1
……..?simplytiny=1&dvid=54ed2597a78b651334&cid=59566fbccb6a2ed10e165c&at=Kh_12rD2w&msgid=532&&mti=1
SimplyTiny Parameter Descriptions
UDID
The Unique Device Identifier (UDID) field can be used to supply the device identifier assigned to the device during device creation onto the cloud service. The udid of each device can be found by login into the portal (under “Manage Device”) or can be retrieved using the provisioning API (retrieve devices endpoint).
When using SimplyTiny String based format, the udid must be presented in all messages exchanged between the IoT device and the IoTGtw cloud service.
When using SimplyTiny JSON based format, then device must provide either: 1) “udid” or 2) “device_id” AND “customer_id” or 3) “imsi” + “customer_id”. Either of these sets of fields must be supplied in the JSON message to enable successful identification and authentication of the device.
Device Auth Token
This field is used to convey the authentication token with which the device object is configured on the IoTGtw service. This field must be provided if the device is configured with a device authentication token on the IoTGtw service.
Message ID
The message ID is used to correlate messages requests and their associated ack responses. When a message is sent as message type 1 (ack required) a message ID is expected to be provided in the message. The message ID is echoed back in the ACK response in order for the receiving entity (device or IoTGtw service) to correlate the request as being successfully received. The message ID may use random or sequential alphanumeric characters. It is recommended to use numeric message ID of at least 6 digits.
Message-Type-Indicator (MTI)
The message-type-indicator field can be used to indicate the type of message and for example if an acknowledgement is expected back. The following are the valid values and their description of the message-type-indicator header field.
- 0 or empty = The message does not require acknowledgement.
- 1 = The message is a confirmable message, an ACK response is expected back.
- 2 = reserved
- 3 = reserved
- 4 = The message is an ACK response message
- 5 = reserved
- 6 = The message is a ping request message (An ACK is returned/expected back)
- 7 = The message is a Device Auth Token Update request (An ACK is returned if operation was accepted/successful)
- 8 = The message is a Service Access Point list request. If authentication successful the SAP list is sent to the device. if SAP list restriction is enabled only white listed SAP are sent.
- 9 = reserved
- 10 = reserved
- 11 = Device Management: Get Device Twin (Retrievies the currently set device Twin Desired Configuration)
- 12 = Device Management: Update Device Twiin (Report/Update the device Twin)
- 90 to 99 = Device Bootstrap service request. Device can request configuration settings such as UDID, device auth token, encryption PSK, X.509 PEM certificates. For security the Bootstrap service must first be explicitly enabled in the device service template and can be disabled again at anytime to control when device is allowed to perform bootstrap operations. See Bootstrap Service for more info.
Traffic Routing Profile Number
This field is used to classify/distinguish the data into different traffic types in order to perform split routing based on the Traffic Routing Profile Number. In essence the number is used to indicate to IoTGtw to invoke the split routing configuration on the device service template and use the messaging endpoint profile set N to deliver the message to the customer. So if this field is set to 3, on receiving the SimplyTiny Message, IoTGtw cloud service will use the messaging endpoint profile configured as the 3rd strand/set in the device service template split routing configuration.
GPS LAT / GPS LONG Fields
These two fields can be used by the device to provide its current GPS location latitude and longitude in their respective header fields. If provided the device location and status can be displayed on the Portal Map along with the device status information. The current/last-known device location can be pushed upstream or retrieved with the GET device provisioning API service or the historical location information can be fetched using the messaging API service. For example a device reporting its current location from a sea port in Lagos, Nigeria the device would supply its latitude as: 6.4499982 and its longitude as: 3.3666652 in the gps_lat and gps_long header fields respectively.
Wireless Device Signal Strength
The device may provide relative signal strength information or other type of device coverage information such as % in relation to the expected or ideal strength, etc.
Device Power Usage Status
The device may provide its current power usage information or other type of key resource utilisation information in this field.
If provided the information will be available on the Portal along with other meta-data information and can be pushed upstream or fetched with the GET device provisioning API service and or the historical power info can be fetched using the messaging API service.
Device Timestamp
The device may use this field to provide the timestamp of when the message was transmitted out of the device or the field may be used to provide some other timestamp of a specific event occurrence on the device.
Sample Messages
Example #1:
A IoT device with udid 54ed2597a78b651334 wants to send an opaque base64 encoded data bXkgc2Vuc29yIGRhdGE= with a message_id S105 with no other header fields (assuming token validation is not configured for the device) then SimplyTiny message would look as follows:
*54ed2597a78b651334**S105*)bXkgc2Vuc29yIGRhdGE=
Note that the device auth token field is blank and all the other fields after the message id are left out because they are optional fields with no values.
Example #2: The same device wants to send JSON payload: {"sensor1":400, "sensor5":"low"} and device auth token is configured. In that case the IoT device must provide a valid auth token Kh_12rD2w that matches the one configured in the IoTGtw device object. Assuming the device is also configured to add a timestamp 1348276362 of when the data left the device for diagnostics and analytics purposes. The IoT device would construct the data as follows for transmission over UDP, TCP or CoAP / MQTT-SN.
*54ed2597a78b651334*Kh_12rD2w*******1514936975*) {"sensor1":400, "sensor5":"low"}
Note that if an optional field is used to propagate a value, all preceding optional fields that have no value must be included as empty slots in order to properly identify the header field for which the value is being propagated.
Example #3: If the same device in example 2 wants to send the same message but also wants to add a message id value of i2356
*54ed2597a78b651334*Kh_12rD2w*i2356******1514936975*) {"sensor1":400, "sensor5":"low"}
Using Message Acknowledgement Examples
Example #4: if message acknowledgement is required i.e. device expects the platform to return an acknowledgement (or vice versa for downlink messages), then the message type indicator field (MTI) field must be set to 4.
*54ed2597a78b651334*Kh_12rD2w*i2356*<strong>4</strong>*****1514936975*) {"sensor1":400, "sensor5":"low"}
The Ack response will look as follows (returns last 4 digits of the device identifier, echo’s back the message id and sets the MTI to 0 to indicate no ack required back for the ack message):
*1334**i2356*<strong>0</strong>
Ping
If the PING service is enabled in the device service template, devices may send ping requests (uplink ping) to the IoTGtw cloud service. On receiving a ping message the service responds with a SimplyTiny ACK response. A ping from device may serve as a way for device to advertise its availability even if it has no data to send, device verifying its connection to the service, device checking if any message has been queue while it was offline and for device to update the IoTGtw cloud service (its shadow copy) with a “last activity” status and or current location information as required.
With each ping received from the device, the device last activity time is updated, if there are any pending downlink messages in the device queue, the appropriate delivery process is kicked off, if additional meta-data is included in the ping such as power usage stats, GPS location, device time etc, the device object (device shadow copy) is updated accordingly.
Device initiated pings do not result in message records being generated into the device message queues. If a message record is required to be generated and stored for every interaction with the device then it is recommended for device to use MTI 0 or 1 (regular message) rather than MTI 6 (ping).
Note that max 6 (six) pings per minute per device is allowed. Devices performing excessive pings above the policy limit for a sustained period will flag up as potentially participating in an organised DDOS attack and may be permanently blocked and or the account struck out.
Customer may also trigger a downlink ping (send ping to device) to be generated and transmitted to a specified device. A downlink ping is triggered using the messaging API endpoint pingRequest endpoint.The request will result in an empty payload SimplyTiny message with MTI set to 6 being sent to the device. The device is expected to return a SimplyTiny ACK message within two minutes on receiving the ping request and must use the same message_id as received in ping request.
Bootstrap Service
Device can send a bootstrap request by using the SimplyTiny for IoT format with the message-type-indication field set to 9 and by providing the bootstrap token pre-configured in the device_bootstrap_token field in the device settings. On receiving a bootstrap request, if the device bootstrap mode is enabled in the device service template on the platform, the bootstrap service will respond with the required bootstrap setting according to the bootstrap mode settings in the device service template. If the device is not in bootstrap mode any bootstrap request from device is silently ignored. Please refer to the SimplyTiny Bootstrapping Service section for more details. >>>Goto the Device Bootstrap Service Section