The message format structure (data framework/resource model) used in conveying messages between the platform and an upstream application is dependent on two things, 1) The upstream application target application type and 2) Whether an Upstream application framework is explicitly specified in the Upstream Application Profile settings.
The following framework is available on each type of upstream application definition. In most cases the preferred format to use is configurable in the Upstream Application profile.
RESTful API
- SimplyTiny JSON
- BLOB
MQTT
- SimplyTiny JSON
- BLOB
ASW SQS
- SimplyTiny JSON
- BLOB (supported in upstream direction only)
Azure IoT Hub
- SimplyTiny JSON
- BLOB
SMPP
- SimplyTiny JSON
- BLOB
SimplyTiny JSON
The SimplyTiny JSON format is the same as the one available for device to platform data exchange the difference being that it is expanded with some additional meta-data attributes relevant for upstream message delivery. The attribute names are not abbreviated. The option of abbreviating the SimplyTiny JSON attribute names is available on the device to platform interfaces (service access points) for the purpose of saving valuable bandwidth for constrained devices on LPWA networks. It is worth noting that the device interfaces (service access points) do support using SimplyTiny with the full name attributes as opposed to the abbreviated attribute names.
Below is an example format of a the SimplyTiny JSON used exchanging messages between the platform and Customer Upstream Applications. The SimplyTiny Message helps convey message payload in the data section as well as additional meta data information such as device identity, transaction id, etc.
|
1 2 3 4 5 6 7 8 9 10 11 |
{ udid: "", //the unique device identifier assigned to the device when it was created device_id: "", //the custom device_id if configured by customer imsi: "", //the device SIM IMSI if configured by the customer device_ip: "", //device source IP address device_port: "", //device source port service_access_point: 0, //the service access point name used for the transaction message type indicator transaction_id: 0, //message transaction id data: "", //opaque/blob data custom_attributes: {...} //one or more custom attributes as configured on the device service profile to be augmented to upstream messages } |
Azure IoT Hub Resource Model (Azure IoT JSON)
All messages bound for the Azure IoThub Upstream Application are wrapped with the the IoT Hub Message Resource model as described in the Azure cloud documentation.
There are two available options:
- Tthe message payload and meta-data can be constructed in SimplyTiny JSON format and then the SimplyTiny JSON is wrapped and transferred to the Azure IoThub with the Azure IoThub resource model. This method of transfer is very usefull as it enriches the message to the Azure IoThub with meta-data as well as additional/custom attributes (if configured in the service profile).To enable this option, set the Data Framework parameter to “SimplyTiny JSON” in the Upstream Application Profile.
- Tthe message payload (content data without meta data) from the device is wrapped and transferred to the Azure IoThub with the Azure IoThub resource model.
Augmenting the Upstream Messages With Additional Attributes (Custom Attributes)
The standard message attributes in SimplyTiny JSON as well as Azure IoT Messages can be augmented with additional attributes. The attribute
|
1 |
custom_attribute_list |
accepts a list (array) of attribute names in the service profile settings. It is used to instruct the platform which additional attributes (over and above the standard ones as listed in the simplytiny sample are to be extracted from the platform or device network and augmented to the upstream messages.
For example, when the a device service profile parameter custom_attribute_list is configured with the list: [‘region_id’, ‘gpsloc_lat’, ‘gpsloc_long’, ‘signal_strength’]. With this configuration, when transferring a message from the device to the upstream application, the listed attributes and their corresponding values will be extracted by the platform and augmented to the SimplyTiny JSON custom_attributes section.
The list of attributes names that the service profile > custom_attribute_list parameter accepts are:
|
1 |
['customer_id', 'device_name', 'device_type', 'device_management_id', 'gpsloc_lat', 'gpsloc_long', 'signal_strength', 'device_timestamp', 'power_usage_info', 'service_template_id', 'serial_number', 'device_type', 'connection_time', 'custom_field_1', 'custom_field_2', 'sap_meta_data', 'region_id', 'port', 'protocol', 'device_application_data_framework', 'encryption', 'service_template_id', 'device_delivery_encoding', 'server_delivery_encoding', 'payload_limit_bytes', 'payload_storage_retainment_hours', 'metadata_storage_retainment_hours'] |
BLOB
In order to send the message payload as opaque or blob data to the customer upstream application, the Upstream Application Data Framework attribute in the Upstream Application Profile can be set to null/emtpy. In this case, the message payload is transferred to the upstream application endpoint without being wrappend in the SimplyTiny JSON format.