1. Home
  2. Docs
  3. IoTGtw Introduction
  4. SimplyTiny for IoT Devices

SimplyTiny for IoT Devices

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.

SimplyTiny For IoT Supports:

  • Device Authentication
  • Device bootstrapping
  • Message Acknowledgement
  • Periodic Auth token update/refresh
  • 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 blob data between Device and Upstream application
  • Receiving Device Data for Storage Purposes (if required)
  • Supports simple string format or JSON based format

SimplyTiny message can be used over any of the supported service access point framework such as CoAP, MQTT-SN and or directly over RAW TCP or UDP sockets for an even higher efficiency.

 

SimplyTiny works as follows:

  • 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 plussign 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.

 

Field Description:

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.
  • 4 = The message is an ACK response message
  • 6 = The message is a ping request message (An ACK is returned/expected back)
  • 7 = The message  is a Device 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.
  • 9 = Device Bootstrap service request. Device can request to be bootstrapped and to receive service settings such as UDID, device token and SAP settings.

 

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, device settings is validated to determine if the device is in bootstrap mode. If device is not in bootstrap mode the message is ignored. If in bootstrap mode (device_bootstrap_mode = true), the bootstrap service will respond with a message containing the bootstrap settings. Please refer to the SimplyTiny Bootstrapping Service section for more details. >>>Goto the Device Bootstrap Service Section

Was this article helpful to you? Yes No

How can we help?