Parameters:

Socket Service Gateway *

Assigned Service Port *

This parameter is only applicable to TCP and UDP socket service for upstream data delivery. It provides a list of dedicated socket gateway ports available to the customer account.

Customer_Application_MQTT

This option can be used if you wish to configure MQTT based integration between the IoTGtw cloud service and your upstream MQTT application.

Uplink Messages

Uplink messages from devices will be published to the configured customer upstream MQTT application to the topic string set in parameter:  Upstream_MQTT_Pub_Topic (socket_service_router.upstream_mqtt_pub_topic). if the Upstream public topic is not set, the message will be published using the device identity according to the identity type is set in the device_identifier_uplink parameter.

Downlink messages

To receive downlink messages from the customer upstream MQTT application for transfer to a specific device, the topic configured in the parameter Upstream_MQTT_Sub_Topic is subscribed to (using QoS 1), in order to receive device bound messages. To properly identify the device a message is meant for, It is recommended for the customer application to provide the device identity value as the MQTT routing key of the message.

Alternatively if the customer upstream MQTT application does not properly support the use of routing keys (or if you have no control over the routing key usage), such customer upstream MQTT application may use the device identity value as the topic name to publish downlink messages in order to indicate the target device.

The preferred device identity type to be expected either as routing key or topic name for downlink messages should be set in device_identifier_type_downlink.

For example: A specific device is setup with the following device identities: IMSI: 121212112121212, udid: 8ba912b2375d610c29a1 and device_d: dev10005920. If the customer preferred identity to use for identifying target device of downlink messages is the device_id, then the device_identifier_downlink parameter must be set to: device_id  In that case the device identity that will be passed on as the routing key or topic name will be dev10005920. The same applies to uplink messages. The identity value passed on in the routing key or topic name will be according to what has been set in the device_identifier_uplink parameter.

Note: Customer MQTT upstream applications that need to use device identity based topic name for uplink and downlink but require the uplink and downlink topic names for each device to be distinct (for example to avoid vicious message loops), in that case, the prefix “dl_” (short for downlink) may be appended to the device identity based downlink topic name. Reusing the previous example it would then become: dl_dev10005920. Please note that this prefix is not mandatory and only should be used by customer MQTT applications with above mentioned limitation.

 Client ID

This parameter is used to specify the Client ID of the MQTT account that is authorised to access the upstream MQTT application. The client ID field is an optional field. If left blank a client_id will be automatically generated instead. The automatically generated ID is normally in the format (without the brackets): iotgtw_[8 random digits]. However the username and password fields (see field definition in sections below) are mandatory and must be supplied.

 Upstream_MQTT_Pub_Topic

This parameter is used to specify the MQTT topic name to be used for publishing messages to the customer upstream MQTT Application.

This field can be set to the literal “device_id” or “imsi” or “udid” or set to an arbitrary static string such as “iot_uplink_queues” depending on the topic name / routing key the upstream application is expecting to receive.

 Upstream_MQTT_Sub_Topic*

This parameter is used to specify the MQTT topic name that the IoTGtw service must subscribe to in order to receive messages from the customer application to be transmitted to the device if/when device is available.

Customer_Application_AWS_SQS

This option can be used if you wish to integrate your AWS cloud workloads as your upstream application. This service will send and receive IoT data between your IoT devices and AWS cloud workloads using the Amazon Web Services – Simple Qeueuing Service. More information about this service can be found in the section:  Customer Upstream Application (RESTful API, MQTT, AWS-SQS, TCP, UDP).

The other SQS specific fields are as follows:

Uplink Queue URL *

The uplink queue URL is used to provide your SQS queue URL which you can obtain by login in to AWS console and in the SQS portal obtain the queue URL specifically created for receiving device uplink messages.

Example:  https://sqs.us-west-2.amazonaws.com/0123456789123/iotgtw_queue_ul

Downlink Queue URL

The downlink queue URL is similar to its uplink counter part except that it is the queue from which the IoTGtw service will receive downlink messages which are to be transferred to the device.

Example: https://sqs.us-west-2.amazonaws.com/0123456789123/iotgtw_queue_dl.fifo

IoTGtw AWS SQS ARN

The SQS service can be setup in two ways:

1: Use the IoTGtw AWS ARN (arn:aws:iam::537537994548:user/iotgtw_sqs_flow) by allowing this specific ARN to access the designated uplink and downlink queues. To use this method leave the Access Key ID and Secret Key fields blank. For most customers this method represents the least impact way of integrating to their SQS workloads.

2: Alternatively you may explicitly specify an AWS Access Key ID and Secret Key credentials designated for this specific SQS queue operations.

In either case ensure the following SQS actions are permitted on the chosen ARN (either IoTGtw or ARN of the explicitly provided credentails):
SQS:SendMessage for the uplink queue
SQS:ReceiveMessage and SQS:DeleteMessage in the downlink queue.

Access Key ID

The SQS access key id you created in the AWS SQS console for this connection.

Secret Key

The SQS secret key you generated in the AWS SQS console for this connection.

Include Message Attributes

This option is used to indicate whether to include the device identifiers such as udid, imsi or device_id (depending on the identity type selected as preferred in the device

Customer_Application_SMPP

This option can be used if you wish to integrate your SMPP/SMS based backend application, SMS Gateway or an SMS Center (SMSC). This service will send and receive IoT data between your IoT devices using the industry standard SMPP protocol.

COMMON Parameter fields:

Upstream Application Data Framework

In the case of uplink messages: this parameter is used to indicate whether to transfer the message to the customer upstream application as received or whether to take the received message, envelope it into a new JSON wrap (using the SimplyTiny JSON) before sending it on to the upstream application. The advantage of this method is that additional meta-data information such as as device identity, device IP, device port, service access point are included in the JSON wrap which may help the upstream easily identify the device the message originated from.

If the Upstream Application Data Framework field is left blank, any received messages will be transferred as received to the upstream application with no additional meta-data. If the upstream application protocol in use supports Message Attribute Headers and you do want to receive the said meta-data in the header, then set the parameter “Include Message Attribute” to true. For example if the upstream protocol is SQS, the meta-data can be included in the SQS MessageAttributes. In this case if device_id is set as the preferred uplink device identity then the id will be set in message.attributes.device_id or if IMSI was set as the preferred identity type then the device IMSI identity value will be set in message.attributes.imsi.

The reverse applies for downlink messages. The Upstream Application Data Framework field indicates whether the upstream application will deliver downlink messages wrapped in SimplyTiny JSON or as opaque data. If the JSON option is selected, on receiving the downlink message, the JSON will be unpacked to extract the meta-data information to identity target device information as well as to extract the actual message to be sent to the target device. The actual message is extracted from the payload section of the SimplyTiny JSON. This extracted message is what will be passed onward for delivery to the device. If left blank, on receiving a downlink message, the gateway will look for the target device identity in the message attributes for exampe (message.attributes.device_id).

 Include Message Attributes

This parameter is used to indicate whether to inject the message meta-data into the upstream protocol header in the cases where messages received are sent as-is i.e. Upstream Application Data Framework field is not set (empty).

 username*

This parameter is used to specify the target application username for example the MQTT account username. This field is mandatory when MQTT selected.

 password*

This parameter is used to specify the target application password for example the MQTT account password. This field is mandatory when MQTT selected.