Configure Stream API for MQTT over Websocket

Introduction

X-ON cloud provides the ability to use multiple server-to-server stream protocols to send uplink data to a cloud application and route downlink data to a device. Stream supports a number of protocols and endpoint types, including the popular MQTT over WebSocket protocol. The stream can be configured at the application level, which will send data for all devices configured under a specific LoRaWAN application EUI to/from a cloud application. Stream may also be configured as a server-to-server API at the individual device EUI level. Per device stream should only be used for troubleshooting due to the high load it places on both server systems. The stream service is hierarchical, which means that it can support applications and device streams simultaneously. 

X-ON stream supports MQTT over WebSocket using TLS only. X-ON will operate as an MQTT broker. Stream requires a token for authentication, which is symmetrical for Publish (downlink) and Subscribe (uplink) data connections. each X-ON global instance listens for incoming MQTT over WebSocket connection requests. X-ON provides a listening socket for Stream on MQTT over WebSocket and expects connections on port 8883 over TLS.

X-ON supports hierarchical stream services for multiplexing applications and devices. The gateway stream contains all applications and devices received through a single gateway. The application stream contains all devices across any number of gateways. The device stream contains all messages for a single device through multiple gateways. Stream may contain any number of these hierarchical message services simultaneously between N number of server-to-server connections.

Enabling Stream for MQTT over WebSocket

In the example below, we will create a stream for an application. You can create streams for gateways and devices too.

Log in to X-ON and navigate to an Applications then select the Stream tab.

Figure 1: Selecting an application

Figure 2: Switch to stream tab

Click the Add Stream button and select Transport and Transform Provider as shown below. A token will be automatically generated, or you may choose to enter a manual value. The token value is used as the MQTT Subscribe (receiving) and Publish (sending) of data messages to devices. Then select Save to make the new stream service active.

Figure 3: Stream configuration window

The server value is the URL of the Haxiot MQTT broker that your remote application server should use to establish a connection. Transform provider is how data transformation templates are applied to inbound and outbound data. Transform can be applied on-the-fly to Uplink and Downlink data as an adapter between different data formats supported natively by LoRaWAN and any other application server API.

Once the stream service is active, connection details for the remote cloud application server will be displayed on the Streams Summary Page.

Figure 4: Stream tab

Access the Stream Service

The Stream service can be accessed using a standards-compliant MQTT 3.1 or higher WebSocket application. MQTT WebSocket applications and open source code are available from a large number of vendors and online communities. The access details for the MQTT connection is as follows:

The assigned token value is used to determine the channel. Configure MQTT to Subscribe using the token. The same token can optionally be used to Publish, which will send Downlink messages to the device. We will show how to setup MQTTBox with this information.

MQTTBox Configuration

1) Download MQTTBox and install. Open the software.

Figure 5: MQTTBox window

2) Click 'Create MQTT Client' and fill up the boxes as shown below. Note MQTT Client ID is the topic from X-ON. Use your X-ON username and password for the MQTTBox username and password. Click 'Save' once you are done.

Figure 6: MQTT client setup

3) Once you are back to the main window it will show the server is 'Connected' with the host. Use X-ON stream Topic for 'Topic to subscribe'.

Figure 7: MQTTBox main window

Figure 8: Topic to subscribe

The device payload is customizable with Stream Device Templates. By default, the Payload / Data field is not modified by Stream and is in the JSON format. XML is supported and can be configured in X-ON. Both device and radio fields are added to device messages. To have a custom Stream Device Template added to your service, please contact support@haxiot.com. 

Uplink Default Format

Uplink packets may be duplicated if received by multiple gateways.

{
"Message":
 {"Type":"2",
  "DeviceEUI":"E000000000000003",
  "GatewayEUI":"B827EBFFFF7ABE89",
  "AppEUI":"C9EB3DD500000002",
  "Timestamp":"1516906010.76694",
  "Port":"2",
  "Data":"6A69",
  "Frequency":"903.1",
  "RSSI":"-15",
  "SeqNo":"121,
  "SNR":"13.2"
  }
}

Type:          2 = Unconfirmed Uplink 
                  4 = Confirmed Uplink
DeviceEUI:  Unique device identifier
AppEUI:      Unique application identifier
Timestamp: Unix timestamp when packet was received by Conductor to +/- 1 second
Port:           1-223 
Data:          Payload for the device in HEXADECIMAL
                  1 - 242 bytes, depending on Region & Data Rate
Frequency:  Received frequency
RSSI:          0 to -137 Received Signal Strength Indicated radio quality measurement
SeqNo:        Sequence number of uplink packets since last authentication
SNR:           20 to -20 Signal-to-Noise radio quality measurement

Downlink Format

{
"Message":
 {
 "Type":"3",
 "Port":"2",
 "DeviceEUI":"C0A1D10000000012",
 "Data":"C0C0C0FFEE"
 }
}

Type:          3 = Unconfirmed Downlink 
                  5 = Confirmed Downlink
Port:           1-223 
DeviceEUI:  Unique device identifier
Data:          Payload for the device in HEX

Each module's different vendor will receive downlink LoRaWAN messages on the device in a slightly different manner, depending on their implementation of LoRaWAN. The Haxiot HXC series client modules will receive Downlink data messages and send the Data payload as unsolicited messages directly to the UART.

Using the above API Downlink example, the HXC client module will send the following message to the UART serial interface.

rxdata:0,2,23

Sending uplinks

We set up an HXC Client Expansion Board to send an uplink. We used terminal software to directly use AT commands.

Figure 9: Executing AT commands to send an uplink

Figure 10: X-ON log is showing received uplink

Figure 11: MQTTBox is showing both join request and uplink packets