The Message Submit function allows customers to send downlink messages to their IoT Devices. Uplink messages from the device can be viewed in the Device Message Queue page or can be received/retrieved using the Messaging API service.

To send a message to the device fill in the required fields and any other optional field according to your device setup and press “Send Message“.

 

Instant Message Delivery

If the message is submitted with high priority (priority 1 or priority 2) the message will be instantly delivered if it matches the conditions for Instant Message Delivery.

 

Note:

• Devices in a service template where the “Device idle threshold” parameter is set to 0 are “Online by default” type devices.
• Devices in a service template where the “Device idle threshold” parameter is set to 1 – N are “Offline by default” type devices.
• To use high priority messaging you must be subscribed to the Priority 1 and or Priority 2 Messaging service and the subscribed priority must be set (allowed) in the device service template.
• The best delivery priority allowed for a device is controlled by the device service template. Any message submitted with a priority better than the priority in the device service template is reset to the service template “delivery priority” value.
• Messages submitted with Priority 1 (highest) or 2 (next best) get routing/transmission priority
• Priority 3-n messages can be used freely and are mainly relevant for message ordering in the device “pending message queue”.

 

Sumbit Message Parameters

“Messaging API Authentication”

Select which Messaging Endpint Profile to use for the submit message request. The submit message function in principle an API client that makes use of the IoTGtw Messaging API to submit your request just as you would with any other API client.

The message submit function constructs the submit message API using the Inbound authentication credentials of the selected Messaging Endpoint Profile. If the Profile is not correctly configured the message submit request will fail. It is recommended to use the “Default Messaging Profile” which was autogenerated at account creation and in principle should always have the correct settings for successful message submit request. The default Messaging profile is pre-selected for you.

The submit function also allows you to test the inbound (IoTGtw bound) configuration of any Messaging Endpoint you previously created on your account by selecting them from the list to be used for the message submit request.

 

“Device Identity”

The identify fields of the device to which you want to send a downlink message to are retrieved and presented in their corresponding fields as read-only. The UDID is mandatory so is always present. The other fields are optional and will have a value depending on the customer device configuration.

• Device ID
• Device Name
• UDID
• IMSI

 

“Device Last Used SAP”

The Last Accessed SAP field shows the last known SAP the device used in connecting into the IoTGTw service. If the device has never connected to the service this field may be empty.

 

“Device IP”

The last known IP address with which the device connected to the IoTGtw service is retrieved and presented in the device IP field. The device IP field is a read-only field as the device IP address is automatically detected.

 

“Device Port”

The last known source port with which the device connected to the IoTGtw service is retrieved and presented in the device port field as a “visible placeholder” just to indicate the last known device port. The field actually remains empty untill a specific port is manually keyed in.

It is highly recommended to leave the device port field empty if you want the message to be delivered over any socket with which the device connects to the IoTGtw service.

If a static port is keyed in for the delivery of the message to the device you must ensure that:

1. The device is configured to establish a socket to the IoTGtw service using the specified port as its source port or
2. If the specified port is a service port on the device i.e. the device is listening on the service port for incoming connection you must make sure that the “Permit New Socket Establishment” parameter is enabled on the device service template. To permit the IoTGtw service to establish a socket to the device on the specified port if/when the device is reachable.

 

“Service Template ID”

This field shows the Service Template the device is associated with. The service template settings may contain some restrictions such as Max payload size, delivery priority limit, restricted service access point device can access etc. Please make sure you familarize yourself with the device service template settings and imposed restrictions otherwise you may find that certain fields such as delivery priority are being overritten to the max values permitted by the service template and the message submit attempt may be rejected if the payload size exceeds the payload size permitted on the device service template.

 

“Service Access Point (SAP)”

You may select any SAP from the drop down list that best matches the type of transport protocol (UDP/TCP), application data (Raw, SimplyTiny, CoAP or MQTTSN) supported by the device. In principle a SAP in any region that has the required setup can be selected.

 

“Delivery Restriction”

The delivery restriction option is used to indicate whether the message may be delivered or not when: 1) The device connection (sockets) in the selected service region is for a different SAP other than the one specified in the message submit request.

• Specified SAP – Only transmit to device if/when there is a valid connect (socket) from device to the selected SAP
• Specified Framework – Transmit if/when there is a valid connection (socket) from device to any SAP with the selected framework (Raw, SimplyTiny, CoAP, MQTT-SN, etc)
• Any SAP – Transmit if/when there is a valid connection (socket) from device to any SAP

In any case if no valid connection is available and “Permit Downlink Connection Establishment” is enabled in the device service template and device is currently reachable and a device_port is specified in the message submit request, the cloud service will attempt to transmit the message to the device using the selected SAP.

 

“Use Private SAP Only”

This option is used to further restrict the selected “Delivery Restriction” options of (Specified framework and Any SAP) to private SAP subset only. This field is only visible/applicable if thre is one or more private SAP subscribed/configured to your account.

 

“Delivery Priority”

The Delivery priority field be equal or lower (lower=higher numerical value) than the value set in the device service template. If a message is submitted with a higher priority setting than the service template allows, the priority is overwriten to the service template value. The same applies when a message is submitted with no priority setting.

Note: Priority 3 to N can be used freely and are mainly relevant for message ordering in the device “Pending” Queue. Messages submitted with Priority 1 (highest) or 2 (next best) get routing priority and are delivered instantly if device is awake or always-on. Ensure your subscription + service template settings allows use of high priority messaging before attempting to use it.

 

“Queueing Time”

The max number of minutes the message may be spend in the queue before being “expired” (marked as failed).

Note that the queueing time must be equal or lower than the queueing time limit configured in the device service template.

 

“Delivery Ack Required”

This service is only applicable if the message queueing service is enabled in the device service template.

This field is used to indicate the message should be transmitted to the device as a confirmable message. If set, an ACK response will be expected back from the device, the message will remain in the “Pending” queue untill a matching ACK is received or untill expired.

• CoAP Messages – An ACK response must echo back the same token (request ID) as the initial request message with the ACK flag set.
• MQTTSN Messages – An ACK response must carry the same message ID as the initial request message in a PUBACK response.
• SimplyTiny Messages – An ACK response must carry the same message ID as the initial request message with the message type indicator set to “4”.

 

“Message ID”

This field is optional, if not provided a message ID will be automatically generated. When submitting a message to devices using CoAP or MQTTSN it is recommended to use the message ID to number the messages submitted sequentially in ascending order.

 

“Payload Content Type”

The payload content type is an optional field it does not play any role in the message delivery and is merely for meta-data purposes.This field is currently hidden in the Message Submit Portal.

 

“Payload”

This field is used to specify the payload to be transmitted to the device. The minimum payload allowed is 1 byte. The maximum payload size is governed by the service template “Payload Limit Per Message” setting.

 

Additional Fields

CoAP Specific Fields

When a CoAP service SAP is selected for the message submit the CoAP specific fields are shown.

• Token – This field is encoded in the token field of the CoAP packet that will be sent to the device. If not provided it shall be autogenerated. The token is also used to match message acknowledgement received from device.
• Deliver Path – This field is optional and can be provided if a specific delivery path is to be encoded into the CoAP packet transmitted to the device.
• Delivery Method – Select the delivery method to encode in the CoAP message to be transmitted to the device
• Resource Observe – This fied is optional and can be provided if the resource observe indication is to be set in the CoAP message transmitted to the device.

 

MQTTSN Specific Fields

When a MQTTSN enabled SAP is selected for the message submit the MQTTSN specific fields are shown. Please note that the main function of MQTTSN in the message submit context is to efficiently, push (downlink publish), receive (uplink publish), queue messages if required and process message acknowledgements.

• Msg Type – The message to be sent to the device will use the MQTTSN “PUBLISH” message to publish the payload to the specified Topic ID.
• Topic ID – This field holds the topic ID pre-defined on the device or that device has subscribed to.
• Topic Type – If the selected topic type is “short-name” then the Topic ID should be 2 characters. If the Topic Type is “normal” or “pre-defined” then the Topic ID should be an integer value that represents the ID mapped to the accepted by the device (i.e. pre-defined).  
  
• MSG QoS – The MQTTSN QoS -1 is the recommended QoS to be used. Thanks to the SimplyTiny service message acknowledgement is provided using the SimplyTiny acknowledgement over MQTTSN. Other QoS (0, 1, 2 & 3) can be used on experimental basis i.e. If the device supports/requires MQTTSN packet level ACK then QoS 1 can be used. 
  
• MSG Retain – Select whether to set the message retain flag to true or false.Only set to true if using normal Topic Type and if your application relies on the retain flag in maintaining messages published to the specified Topic.