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.
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 firstname.lastname@example.org.
Uplink Default Format
Uplink packets may be duplicated if received by multiple gateways.
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
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
Type: 3 = Unconfirmed Downlink
5 = Confirmed Downlink
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.
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
Jul 21, 2023