/virtual-lorawan-device

A utility that attaches to a Semtech UDP Host and pretends to be a LoRaWAN Device

Primary LanguageRustApache License 2.0Apache-2.0

Continuous Integration

virtual-lorawan-device

This utility allows you to run one or more LoRaWAN devices in pure software (ie: virtually). It leverages a Rust-based LoRaWAN device stack and implements its "Radio trait" with the Semtech GWMP over UDP interface (see udp_radio.rs). This allows you to attach to any Semtech GWMP over UDP Host, such as a traditional LoRaWAN Network Server (LNS), Helium Miner, or the Helium Light Hotspot.

To the Semtech GWMP over UDP Host, the default configuration of this utility looks like a single packet forwarder with one or more devices. It is possible to configure many packet forwarders with many different hosts as well. PLease see the configuration examples below.

Configuration

You'll want to create a file called settings.toml and define one more devices. By default, this file is expected in the settings directory from where the application is launched. This may be overriden with the --settings option.

A simple configuration

If you want to run one or more virtual devices, your settings.toml file may look like this:

# Optionally override host IP
#[packet_forwarder.default]
#host = "127.0.0.1:1681"

[device.one.credentials]
dev_eui = "3ED43BEF1857EF4B"
app_eui = "35BEED137AC3344B"
app_key = "275AD3615ACA47A381E6B79A832CC5AE"

[device.two.credentials]
dev_eui = "3ED43BEF18D7EE4B"
app_eui = "35BEED137ACD384B"
app_key = "275AD3615ACB47AA81E6B79A832CC5AE"

A single "virtual packet forwarder" will be instantiated and it will connect to the default_host. The two devices will transmit and receive their packets via the single packet forwarder.

Region

The default region is US915. EU868 is also supported and may be configured in the following way:

[device.one]
region = "EU868"
[device.one.credentials]
dev_eui = "3ED43BEF1857EF4B"
app_eui = "35BEED137AC3344B"
app_key = "275AD3615ACA47A381E6B79A832CC5AE"

A more complicated configuration

More complicated configurations are possible. You could have multiple virtual packet forwarders:

[packet_forwarder.pf_one]
mac = "0807060504030201"
host = "127.0.0.1:1691"

[packet_forwarder.pf_two]
mac = "0807060504030202"
host = "127.0.0.1:1692"

[device.one]
packet_forwarder = "pf_one"
server = "prod"
secs_between_transmits = 120
[device.one.credentials]
dev_eui = "3ED43BEF1857EF4B"
app_eui = "35BEED137AC3344B"
app_key = "275AD3615ACA47A381E6B79A832CC5AE"

[device.two]
packet_forwarder = "pf_two"
server = "staging"
[device.two.credentials]
dev_eui = "3ED43BEF18D7EE4B"
app_eui = "35BEED137ACD384B"
app_key = "275AD3615ACB47AA81E6B79A832CC5AE"

In this configuration, we've created two packet forwarders and attached one device to each. In addition, we've given them different server labels. This will put their data reported to Prometheus under different labels. The transmit time of device one is also set to 120 seconds.

Example to build project with docker

docker buildx build . -t virtual-lorawan-device:latest

Example docker compose

version: '3'
services:
  lorawan-virtual-devices:
    image: virtual-lorawan-device:latest
    container_name: lorawan-virtual-device
    restart: unless-stopped
    volumes:
      - ./settings/default.toml:/etc/virtual-lorawan-device/default.toml