LoRaWAN (Long Range Wide Area Network) is a low-power, long-range wireless protocol, enabling efficient communication over large distances with minimal energy usage. For more on why this is useful, see the article on the Viam blog.
This module combines the functionality of a LoRaWAN gateway and network server, enabling communication between LoRaWAN sensors and the Viam app. It handles packet forwarding, device management, and message routing to allow LoRaWAN sensor data to be viewed and managed directly in Viam. This module provides the following models:
sx1302-waveshare-hat: Sensor model for the waveshare loRaWAN gateway hatsx1302-hat-generic: Sensor model for other SX1302 LoRaWAN concentrator hats.node: Sensor model for any class A, US915/EU868 LoraWAN end device.dragino-LHT65N: Sensor model for the dragino LHT65N temperature and humidity sensor.milesight-ct101: Sensor model for the milesight ct101 current transformer.milesight-em310-tilt: Sensor model for the milesight em310 tilt sensor.
You'll configure the sx1302-gateway model, and one or more nodes depending on how many sensors you have.
Compatible with:
- US915 or EU868 frequency band
- Class A Devices
- LoraWAN MAC version 1.0.3
Hardware Required:
- Raspberry Pi (any model with GPIO pins)
- SX1302 Gateway HAT/concentrator board
- LoRaWAN sensors
See Hardware Tested Section for hardware we have used this module with successfully.
Navigate to the CONFIGURE tab of your machine in the Viam app and click the + button. Add sx1302-gateway to your machine.
Example gateway configuration:
{
"board": "rpi",
"spi_bus": 0,
"reset_pin": int,
"power_en_pin": int,
"region_code": "US915"
}The following attributes are available for viam:sensor:sx1302-gateway sensors:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| board | string | yes | - | Name of the board connected to the HAT. The board communicates with the gateway through SPI |
| reset_pin | int | yes | - | GPIO pin number for sx1302 reset pin |
| spi_bus | int | no | 0 | SPI bus number (0 or 1) |
| power_en_pin | int | no | - | GPIO pin number for the power enable pin |
| region_code | string | no | US915 | frequency region of your gateway (US915 or EU868) |
Navigate to the CONFIGURE tab of your machine in the Viam app and click the + button. Add sx1302-hat-generic to your machine.
Example gateway configuration - note - the gpio pins MUST be set to the gpio pin numbers on your board connected to the reset and power-enable pins of the sx1302 hat to avoid a 15-minute reset loop.
{
"board": "rpi",
"spi_bus": 0,
"reset_pin": int,
"power_en_pin": int,
"region_code": "US915"
}The following attributes are available for viam:sensor:sx1302-hat-generic sensors:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| board | string | yes | - | Name of the board connected to the HAT. The board communicates with the gateway through SPI |
| reset_pin | int | yes | - | GPIO pin number for sx1302 reset pin |
| spi_bus | int | no | 0 | SPI bus number |
| power_en_pin | int | no | - | GPIO pin number for the power enable pin |
| region_code | string | no | US915 | frequency region of your gateway (US915 or EU868) |
Navigate to the CONFIGURE tab of your machine in the Viam app and click the + button. Add sx1302-waveshare-hat to your machine.
Example gateway configuration:
{
"board": "rpi",
"spi_bus": 0,
"region_code": "US915"
}The following attributes are available for viam:sensor:sx1302-waveshare-hat sensors:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| board | string | yes | - | Name of the board connected to the HAT. The board communicates with the gateway through SPI |
| spi_bus | int | no | 0 | SPI bus number (0 or 1 on a raspberry pi) |
| region_code | string | no | US915 | frequency region of your gateway (US915 or EU868) |
As when configuring the gateway, use the + button on your machine's CONFIGURE tab to add the viam:sensor:node model to your machine.
The node model supports any class A V1.0.3 device sending on EU868 or US915 frequency band. The node component supports two types of activation: OTAA (Over-the-Air Activation) and ABP (Activation by Personalization).
Example OTAA node configuration:
{
"join_type": "OTAA",
"decoder_path": "/path/to/decoder.js",
"dev_eui": "0123456789ABCDEF",
"app_key": "0123456789ABCDEF0123456789ABCDEF",
"uplink_interval_mins": 10,
"gateways": ["gateway-1"]
}Example ABP node configuration:
{
"join_type": "ABP",
"decoder_path": "/path/to/decoder.js",
"dev_addr": "01234567",
"app_s_key": "0123456789ABCDEF0123456789ABCDEF",
"network_s_key": "0123456789ABCDEF0123456789ABCDEF",
"uplink_interval_mins": 10,
"gateways": ["gateway-1"],
"fport": "55"
}| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| decoder_path | string | yes | - | Path to the payload decoder script. This must be a .js file. If the device provides multiple decoder files, use the chirpstack version. |
| join_type | string | no | "OTAA" | Join type ("OTAA" or "ABP"). |
| uplink_interval_mins | float64 | yes | - | Expected interval between uplink messages sent by the node. The default can be found on the datasheet and can be modified using device specific software. |
| gateways | []string | yes | - | gateways the node can send data to. Can also be in the Depends on drop down. |
| fport | string | no | - | port (in hex) to send downlinks to the device. |
The node registers itself with the gateway so the gateway will recognize messages from the node.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_eui | string | yes | - | Device EUI (8 bytes in hex). Unique indentifer for the node. Can be found printed on your device or on the box. |
| app_key | string | yes | - | Application Key (16 bytes in hex). Used to securely join the network. The default can normally be found in the node's datasheet. |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_addr | string | yes | - | Device Address (4 bytes in hex). Used to identify uplink messages. Can normally be found on datasheet or box. |
| app_s_key | string | yes | - | Application Session Key (16 bytes in hex) Used to decrypt uplink messages. Default can normally be found on the node's datasheet or box. |
| network_s_key | string | yes | - | Network Session Key (16 bytes in hex) Used to decypt uplink messages. Default can normally be found on the node's datasheet or box. |
The sensor node model uses DoCommands to send downlinks to sensors from the gateway.
This command will send a generic downlink payload to the gateway. The string is expected to be a set of bytes in hex.
{
"send_downlink": "<BYTESINHEX>"
}Example OTAA node configuration:
{
"join_type": "OTAA",
"dev_eui": "0123456789ABCDEF",
"gateways": ["gateway-1"]
}Example ABP node configuration:
{
"join_type": "ABP",
"dev_addr": "01234567",
"gateways": ["gateway-1"]
}| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| join_type | string | no | "OTTA" | Join type ("OTAA" or "ABP") |
| uplink_interval_mins | float64 | no | 10 for the ct101 and 1080 for the em310-tilt | Desired interval between uplink messages sent by the node. The sensor will send a set interval downlink if configured. |
| gateways | []string | yes | - | gateways the node can send data to. Can also be in the Depends on drop down. |
The node registers itself with the gateway so the gateway will recognize messages from the node.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_eui | string | yes | - | Device EUI (8 bytes in hex). Unique indentifer for the node. Can be found printed on your device or on the box. |
| app_key | string | no | 5572404C696E6B4C6F52613230313823 | Application Key (16 bytes in hex). Used to securely join the network. |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_addr | string | yes | - | Device Address (4 bytes in hex). Used to identify uplink messages. Can normally be found on datasheet or box. |
| app_s_key | string | no | 5572404C696E6B4C6F52613230313823 | Application Session Key (16 bytes in hex) Used to decrypt uplink messages. |
| network_s_key | string | no | 5572404C696E6B4C6F52613230313823 | Network Session Key (16 bytes in hex) Used to decypt uplink messages. |
The milesight models uses DoCommands to send downlinks to sensors from the gateway. A purple light will flash after the sensor sends an uplink once a downlink has been successfully sent. The sensor must already be connected for downlink requests to work.
This command will update the interval the milesight sends data at. This can also be set via the 'uplink_interval_mins' field in the config.
{
"set_interval": 1.0
}This command will restart the milesight sensor, triggering a new join request.
{
"restart_sensor": ""
}This command will send a generic downlink payload to the gateway. the string is expected to be a set of bytes in hex. See the em310 tilt sensor user guide or the ct101 user guide for their respective downlink commands.
{
"send_downlink": "<BYTESINHEX>"
}Example OTAA node configuration:
{
"join_type": "OTAA",
"dev_eui": "0123456789ABCDEF",
"app_key": "0123456789ABCDEF0123456789ABCDEF",
"gateways": ["gateway-1"]
}Example ABP node configuration:
{
"join_type": "ABP",
"dev_addr": "01234567",
"app_s_key": "0123456789ABCDEF0123456789ABCDEF",
"network_s_key": "0123456789ABCDEF0123456789ABCDEF",
"gateways": ["gateway-1"]
}| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| join_type | string | no | "OTAA" | Join type ("OTAA" or "ABP") |
| uplink_interval_mins | float64 | no | 20 | Desired interval between uplink messages sent by the node. The sensor will send a set interval downlink if configured. |
| gateways | []string | yes | - | gateways the node can send data to. Can also be in the Depends on drop down. |
The node registers itself with the gateway so the gateway will recognize messages from the node.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_eui | string | yes | - | Device EUI (8 bytes in hex). Unique indentifer for the node. Can be found printed on your device or on the box. |
| app_key | string | yes | - | Application Key (16 bytes in hex). Used to securely join the network. Unique to the specific device, can be found on the box. |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| dev_addr | string | yes | - | Device Address (4 bytes in hex). Used to identify uplink messages. Can normally be found on datasheet or box. |
| app_s_key | string | yes | - | Application Session Key (16 bytes in hex) Used to decrypt uplink messages. Default can normally be found on the node's datasheet or box. |
| network_s_key | string | yes | - | Network Session Key (16 bytes in hex) Used to decypt uplink messages. Default can normally be found on the node's datasheet or box. |
The dragino model uses DoCommands to send downlinks to sensors from the gateway. A purple light will flash after the sensor sends an uplink once a downlink has been successfully sent. The sensor must already be connected for downlink requests to work.
This command will update the interval the dragino sends data at. This can also be set via the 'uplink_interval_mins' field in the config.
{
"set_interval": 1.0
}This command will restart the dragino sensor, triggering a new join request.
{
"restart_sensor": ""
}This command will send a generic downlink payload to the gateway. the string is expected to be a set of bytes in hex. See the LHT64 temperature sensor user guide for other downlink commands.
{
"send_downlink": "<BYTESINHEX>"
}When the gateway is properly configured, the pwr LED will be solid red and the rx and tx LEDs will be blinking red.
It may take several minutes after starting the module to start receiving data, especially if your node transmits on more than 8 frequency channels. The gateway will log info logs when it has received a join request or data uplink.
The gateway communicates through SPI, so ensure that SPI in enabled on the Pi.
To avoid capturing duplicate data, set the data capture frequency equal to or less than the expected uplink interval.
If you see the error ERROR: Failed to set SX1250_0 in STANDBY_RC mode in logs, unplug the Raspberry Pi for a few minutes and then try again.
The sx1302-gateway model has been tested with:
Waveshare Gateway HAT
The node model has been tested with:
Milesight CT101 Smart Current Transformer
Milesight EM310 Tilt Sensor
Dragino LHT65 Temperature & Humidity Sensor