Configure Stream API for WebSocket connection

Introduction

X-ON 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 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 for individual device EUI. The stream service is hierarchical, which means that it can support applications and device streams simultaneously. 

X-ON stream supports Secure WebSocket only using TLS. Stream requires token authentication. Each X-ON global instance listens for incoming WebSocket. X-ON provides a listening socket for stream on WebSocket and expects connections on port 8443 over TLS.

Enabling Stream for WebSocket

Log in to X-ON and navigate to the Applications that needs to be export WebSocket device data, then select the Stream tab. 

Figure 1: Selecting an application

Figure 2: Switch to Stream tab

Select the Add Stream button and select the default type of WebSocket and default format of JSON. A token will be automatically generated, or you may choose to enter a manual value. Then select Save to make the new stream service active.

Figure 3: WebSocket Stream Configuration

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 WebSocket application. WebSocket applications and open source code are available from a large number of vendors and online communities. We use Simple Websocket Client available both for Firefox and Chrome. The format for the WebSocket connection is as follows.

https://[server]:8443?token=[topic]

The server and token are both displayed on the Streams summary page.

For example:

wss//:us1-stream.haxiot.com:8443?token=kGVWsvZKjd4d0rGZ2_pcwXfiLHtPtmDgvh0cISiXc-k

The device payload is customizable with Stream Device Templates. By default, the Payload is not modified by Stream. Both device and radio fields are added to device messages.

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",
  "SNR":"13.2"
  }
}

Type: 2 = Unconfirmed Uplink 
         4 = Confirmed Uplink
DeviceEUI:  Unique device identifier
AppEUI:      Unique application identifier
Timestamp:  Unix timestamp when the 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
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