LoRaWAN

 
 
LoRaWAN (Long Range Wide Area Network) is a specification for a telecommunication network suitable for long-distance communication with little power. The technology is used for machine-to-machine communication (Internet of Things).

The architecture consists of gateways, network servers and application servers. There are RF chips from Semtech used to transmit a spread spectrum.

More information about LoRaWAN can be found at:
https://www.lora-alliance.org/
https://www.thethingsnetwork.org/







Install and configure ChirpStack components with Semtech UDP packet-forwarder backend



Information
This tutorial describes how to configure the ChirpStack components to use the Semtech UDP packet forwarder.

ChirpStack provides open source components for building LoRaWAN networks.
More information: https://www.chirpstack.io/

ChirpStack consists of four major components:
  1. ChirpStack Gateway Bridge
  2. ChirpStack Network Server
  3. ChirpStack Application Server
  4. ChirpStack Geolocation Server
In this tutorial the ChirpStack components 1, 2, 3 and their dependencies will be installed on a single server instance.

This user manual is part of LoRa/LoRaWAN tutorial 31.
https://www.mobilefish.com/download/lora/lora_part31.pdf Procedure

Step A. Install ChirpStack Gateway Bridge.
  1. Upgrade the Raspberry Pi packages.
    Type: sudo apt-get update && sudo apt-get upgrade -y

  2. ChirpStack Gateway Bridge makes use of MQTT for publishing and receiving application payloads.
    Type: sudo apt-get install mosquitto -y
    Type: sudo apt-get install mosquitto-clients -y

  3. ChirpStack provides pre-compiled binaries packaged as Debian (.deb) packages.
    In order to activate this repository, execute the following commands:
    Type: sudo apt install apt-transport-https dirmngr -y
    Type: sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00
    Type: sudo echo "deb https://artifacts.chirpstack.io/packages/3.x/deb stable main" | sudo tee /etc/apt/sources.list.d/chirpsstack.list
    Type: sudo apt-get update

  4. Install the ChirpStack Gateway Bridge.
    Type: sudo apt-get install chirpstack-gateway-bridge

    Note 1:
    This will setup an user and group, create start scripts for systemd or init.d
    (this depends on your version of Debian / Ubuntu).
    Note 2:
    chirpstack-gateway-bridge configuration file is installed at:
    /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml
    chirpstack-gateway-bridge executable is installed at: /usr/bin/chirpstack-gateway-bridge
    Note 3:
    More information: /usr/bin/chirpstack-gateway-bridge --help
    Note 4:
    Start:
    sudo systemctl start chirpstack-gateway-bridge
    Restart:
    sudo systemctl restart chirpstack-gateway-bridge
    Stop:
    sudo systemctl stop chirpstack-gateway-bridge
    Display logs:
    sudo journalctl -f -n 100 -u chirpstack-gateway-bridge

  5. Modify the ChirpStack Gateway Bridge configuration file:
    /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml.
    Type: sudo su
    Type: cd /etc/chirpstack-gateway-bridge
    Type: nano chirpstack-gateway-bridge.toml

    [general]
    # debug=5, info=4, warning=3, error=2, fatal=1, panic=0
    log_level=4

    # Gateway backend configuration.
    [backend]
    type="semtech_udp"
    # Semtech UDP packet-forwarder backend.
    [backend.semtech_udp]
    udp_bind = "0.0.0.0:1700"

  6. Start ChirpStack Gateway Bridge.
    Type: sudo systemctl start chirpstack-gateway-bridge

    If your distribution uses systemd or init.d, use one of the following commands:
    Note: Raspberry Pi uses systemd.
    [systemd] Type: sudo systemctl [start|stop|restart|status] chirpstack-gateway-bridge
    [init.d] Type: sudo /etc/init.d/chirpstack-gateway-bridge [start|stop|restart|status]

  7. Verify if the ChirpStack Gateway Bridge is running and check if there are no errors.
    Type: systemctl status chirpstack-gateway-bridge

  8. Check ChirpStack Gateway Bridge log output.
    [systemd] Type: journalctl -f -n 50 -u chirpstack-gateway-bridge
    [init.d] Type: tail -f -n 50 /var/log/chirpstack-gateway-bridge/chirpstack-gateway-bridge.log

  9. Start chirpstack-gateway-bridge on boot.
    Type: sudo systemctl enable chirpstack-gateway-bridge

    Note:
    To disable the ChirpStack Gateway Bridge so it doesn't start on boot.
    Type: sudo systemctl disable chirpstack-gateway-bridge
Step B. Install ChirpStack Network Server.
  1. Install PostgreSQL.
    Type: sudo apt-get install postgresql -y

  2. Install Redis server and Redis tools.
    Type: sudo apt-get install redis-server -y
    Type: sudo apt-get install redis-tools -y

  3. ChirpStack Network Server needs its own database.
    To create a new database, start the PostgreSQL prompt as the postgres user.
    Type: sudo -u postgres psql

  4. Within the PostgreSQL prompt, enter the following queries:
    Type: create role chirpstack_ns with login password 'dbpassword';

    Note: The database password is: 'dbpassword'
    Change this to something more secure.

    Type: create database chirpstack_ns with owner chirpstack_ns;

  5. Enable the pg_trgm (trigram) and hstore extensions.
    Type: \c chirpstack_ns
    Type: create extension pg_trgm;
    Type: create extension hstore;
    Type: \q

  6. Verify if the user and database have been setup correctly, try to connect to it:
    Type: psql -h localhost -U chirpstack_ns -W chirpstack_ns
    Type: \q

  7. Install ChirpStack Network Server.
    Type: sudo apt-get install chirpstack-network-server -y

    Note 1:
    ChirpStack Network Server configuration file is installed at:
    /etc/chirpstack-network-server/chirpstack-network-server.toml
    ChirpStack Network Server executable is installed at: /usr/bin/chirpstack-network-server
    Note 2:
    More information: /usr/bin/chirpstack-network-server --help
    Note 3:
    Start:
    sudo systemctl start chirpstack-network-server
    Restart:
    sudo systemctl restart chirpstack-network-server
    Stop:
    systemctl stop chirpstack-network-server
    Display logs:
    sudo journalctl -f -n 100 -u chirpstack-network-server

  8. Modify the ChirpStack Network Server configuration file /etc/chirpstack-network-server/chirpstack-network-server.toml.
    Type: sudo su
    Type: cd /etc/chirpstack-network-server
    Type: nano chirpstack-network-server.toml

    Make the following changes, EU868 configuration example.
    For other examples: https://www.chirpstack.io/guides/debian-ubuntu/

    [general]
    # debug=5, info=4, warning=3, error=2, fatal=1, panic=0
    log_level=4

    [postgresql]
    dsn="postgres://chirpstack_ns:[email protected]/chirpstack_ns?sslmode=disable"

    [network_server]
    net_id="000000"

    [network_server.band]
    name="EU_863_870"

    [[network_server.network_settings.extra_channels]]
    frequency=867100000
    min_dr=0
    max_dr=5

    [[network_server.network_settings.extra_channels]]
    frequency=867300000
    min_dr=0
    max_dr=5

    [[network_server.network_settings.extra_channels]]
    frequency=867500000
    min_dr=0
    max_dr=5

    [[network_server.network_settings.extra_channels]]
    frequency=867700000
    min_dr=0
    max_dr=5

    [[network_server.network_settings.extra_channels]]
    frequency=867900000
    min_dr=0
    max_dr=5

    [network_server.gateway.backend.mqtt]
    server="tcp://localhost:1883"

    [metrics]
    timezone="Local"


    Note 1: dsn
    Given you used the password dbpassword when creating the PostgreSQL database.
    Note 2: name
    LoRaWAN regional band configuration. Valid values:
    AS_923
    AU_915_928
    CN_470_510
    CN_779_787
    EU_433
    EU_863_870
    IN_865_867
    KR_920_923
    RU_864_870
    US_902_928
    Note 3: timezone
    The timezone is used. Example: "Europe/Amsterdam" or "Local" for the the system's local time zone.
    Note 4: server
    MQTT broker address and port

    Type: exit (After changes)

  9. Start ChirpStack Network Server.
    Type: sudo systemctl start chirpstack-network-server

    If your distribution uses systemd or init.d, use one of the following commands:

    Note: Raspberry Pi uses systemd.
    [systemd] Type: sudo systemctl [start|stop|restart|status] chirpstack-network-server
    [init.d] Type: sudo /etc/init.d/chirpstack-network-server [start|stop|restart|status]

  10. Verify if the ChirpStack Network Server is running.
    Type: systemctl status chirpstack-network-server

  11. Check ChirpStack Network Server log output.
    [systemd] Type: journalctl -f -n 50 -u chirpstack-network-server
    [init.d] Type: tail -f -n 50 /var/log/chirpstack-network-server/chirpstack-network-server.log

  12. Start ChirpStack Network Server on boot.
    Type: sudo systemctl enable chirpstack-network-server

    Note:
    To disable the ChirpStack Network Server so it doesn't start on boot.
    Type: sudo systemctl disable chirpstack-network-server
Step C. Install ChirpStack Application Server.
  1. ChirpStack Application Server persists the gateway data into a PostgreSQL database.
    ChirpStack Application Server needs its own database.
    To create a new database, start the PostgreSQL prompt as the postgres user:
    Type: sudo -u postgres psql

  2. Within the PostgreSQL prompt, enter the following queries:
    Type: create role chirpstack_as with login password 'dbpassword';
    Type: create database chirpstack_as with owner chirpstack_as;

  3. Enable the pg_trgm (trigram) and hstore extensions.
    Type: \c chirpstack_as
    Type: create extension pg_trgm;
    Type: create extension hstore;
    Type: \q

  4. Verify if the user and database have been setup correctly, try to connect to it:
    Type: psql -h localhost -U chirpstack_as -W chirpstack_as
    Type: \q

  5. Install ChirpStack Application Server.
    Type: sudo apt-get install chirpstack-application-server

    Note 1:
    chirpstack-application-server configuration file is installed at:
    /etc/chirpstack-application-server/chirpstack-application-server.toml
    chirpstack-application-server executable is installed at: /usr/bin/chirpstack-application-server
    Note 2:
    More information: /usr/bin/chirpstack-application-server --help
    Note 3:
    Start:
    sudo systemctl start chirpstack-application-server
    Restart:
    sudo systemctl restart chirpstack-application-server
    Stop:
    sudo systemctl stop chirpstack-application-server
    Display logs:
    sudo journalctl -f -n 100 -u chirpstack-application-server

  6. Create a JSON Web Token (jwt). Open a terminal.
    Type: openssl rand -base64 32
    For example: e3+eD7zcVFJF3EFpPnM1oMj02DqUZxt5wR4IfPBpbtA=
    Copy and save the output. Will be used at the next step. Keep this secret!

  7. Modify the chirpstack-application-server configuration file.
    /etc/chirpstack-application-server/chirpstack-application-server.toml.
    Type: sudo su
    Type: cd /etc/chirpstack-application-server
    Type: nano chirpstack-application-server.toml

    Make the following changes (if needed):
    [general]
    # debug=5, info=4, warning=3, error=2, fatal=1, panic=0
    log_level=4

    [postgresql]
    dsn="postgres://chirpstack_as:[email protected]/chirpstack_as?sslmode=disable"

    [application_server.external_api]
    jwt_secret="e3+eD7zcVFJF3EFpPnM1oMj02DqUZxt5wR4IfPBpbtA="

    [application_server.integration.mqtt]
    server="tcp://localhost:1883"

    [application_server.api]
    public_host="localhost:8001"


    Note 1: dsn
    Given you used the password dbpassword when creating the PostgreSQL database.
    Note 2: jwt_secret
    jwt_secret, see step 6.
    Note 3: server
    MQTT broker address and port
    Note 4: public_host
    The Internal API Server is used by ChirpStack Network Server to communicate with ChirpStack Application Server

    Type: exit (After changes)

  8. Start ChirpStack Application Server.
    Type: sudo systemctl start chirpstack-application-server

    If your distribution uses systemd or init.d, use one of the following commands:
    Note: Raspberry Pi uses systemd.
    [systemd] Type: sudo systemctl [start|stop|restart|status] chirpstack-application-server
    [init.d] Type: sudo /etc/init.d/chirpstack-application-server [start|stop|restart|status]

  9. Verify if the ChirpStack Application Server is running.
    Type: systemctl status chirpstack-application-server

  10. Check ChirpStack Application Server log output.
    [systemd] Type: journalctl -f -n 50 -u chirpstack-application-server
    [init.d] Type: tail -f -n 50 /var/log/chirpstack-application-server/chirpstack-application-server.log

  11. Start ChirpStack Application Server on boot.
    Type: sudo systemctl enable chirpstack-application-server

    Note:
    To disable the ChirpStack Application Server so it doesn't start on boot.
    Type: sudo systemctl disable chirpstack-application-server
Step D. Modify ChirpStack Gateway Bridge configuration.
  1. Modify the ChirpStack Gateway Bridge configuration file:
    /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml.
    Type: sudo su
    Type: cd /etc/chirpstack-gateway-bridge
    Type: nano chirpstack-gateway-bridge.toml

    Make the following changes (if needed):
    server="tcp://127.0.0.1:1883"

    Note: server
    MQTT broker address and port

    Type: exit (After changes)
Step E. Modify Packet Forwarder configuration.
  1. Modify the packet forwarder global_conf.json file.
    In the RAK831 Pilot Gateway this file can be found at:
    /opt/ttn-gateway/packet_forwarder/lora_pkt_fwd

    Type: cd /opt/ttn-gateway/packet_forwarder/lora_pkt_fwd
    Type: sudo nano global_conf.json

    Make the following changes (if needed):
    "serv_port_down": 1700,
    "serv_port_up": 1700,
    "server_address": "localhost",


    Note:
    Originally the server_address was "router.eu.thethings.network".
    The gateway now sends UDP data to the ChirpStack Gateway Bridge.

  2. Reboot the Gateway.
    Type: sudo reboot



Step F. Check if all required services are running
  1. Type: systemctl status ttn-gateway
    Type: systemctl status mosquitto
    Type: systemctl status chirpstack-gateway-bridge
    Type: systemctl status chirpstack-network-server
    Type: systemctl status chirpstack-application-server
Step G. ChirpStack Application Server Web Interface
  1. Open a web browser and enter the IP address where the ChirpStack Application Server is installed,
    followed by port 8080. In this manual the ChirpStack Application Server is installed on the Gateway.
    For example: http://192.168.1.71:8080

  2. Login with the default credentials:
    user: admin
    password: admin

  3. Select menu: Network-servers
    Press button: ADD
    Tab: GENERAL
    Network-server name: LoRaServer1
    Network-server server: localhost:8000
    Note 1: Use localhost, if ChirpStack Network Server is installed on the same host as ChirpStack Application Server.
    Note 2: The ChirpStack Application Server can connect to multiple ChirpStack Network Server instances.

    Tab: GATEWAY DISCOVERY
    Uncheck: Enable gateway discovery

    Note 3: In this manual I assume you only have one gateway.
    Therefore gateway discovery is disabled.

    Select: ADD NETWORK-SERVER or UPDATE NETWORK-SERVER

  4. Select menu: Gateway-Profiles
    Nothing done

  5. Select menu: Organizations
    Select: loraserver

    Change Organization name: mobilefish
    The name may only contain words, numbers and dashes.

    Display name: Mobilefish Research and Development

    Check: Organization can have gateways
    When checked, it means that organization administrators are able to add their own gateways to the network. Note that the usage of the gateways is not limited to this organization.

    Select: UPDATE ORGANIZATION

  6. Select menu: Service-Profiles

    Note:
    A service-profile connects an organization to a network-server and defines the features that an organization can use on this network-server.

    Press button: CREATE

    Service-profile name: ServiceProfile1
    A name to identify the service-profile.

    Network-server: LoRaServer1
    The network-server on which this service-profile will be provisioned. After creating the service-profile, this value can't be changed.

    Check: Add gateway meta-data
    GW metadata (RSSI, SNR, GW geoloc., etc.) are added to the packet sent to the application-server.

    Uncheck: Enable network geolocation
    When enabled, the network-server will try to resolve the location of the devices under this service-profile. Please note that you need to have gateways supporting the fine-timestamp feature and that the network-server needs to be configured in order to provide geolocation support.

    Device-status request frequency: 0
    Frequency to initiate an End-Device status request (request/day). Set to 0 to disable.

    Minimum allowed data-rate: 0
    Minimum allowed data rate. Used for ADR. This applies for the EU.

    Maximum allowed data-rate: 5
    Maximum allowed data rate. Used for ADR. This applies for the EU.

    Select: CREATE SERVICE-PROFILE

  7. Select menu: Device-Profiles

    Note:
    A device-profile defines the capabilities and boot parameters of a device. You can create multiple device-profiles for different kind of devices.

    Press button: CREATE

    Device-profile name: DEVPROF-EU868
    A name to identify the device-profile.

    Network-server: LoRaServer1
    The network-server on which this device-profile will be provisioned.
    After creating the device-profile, this value can't be changed.

    LoRaWAN MAC version: 1.0.2
    The LoRaWAN MAC version supported by the device.
    I will use the Arduino LMIC Library when I upload my sketch (Step H).
    https://github.com/matthijskooijman/arduino-lmic

    The Arduino LMIC Library supports LoRaWAN MAC version 1.0.2 revision A
    See also:
    https://forum.chirpstack.io/t/generic-arduino-lmic-based-devices/2991

    LoRaWAN Regional Parameters revision: A
    Revision of the Regional Parameters specification supported by the device.

    MAX EIRP: 0

    Select: CREATE DEVICE-PROFILE

  8. Select Device-profile: DeviceB
    Select tab: JOIN (OTAA/ABP)
    Check: Device supports OTAA
    Select tab: Class-B
    Uncheck: Device supports Class-B (I have disabled this because I have not done any testing with Class B before)
    Select tab: Class-C
    Uncheck: Device supports Class-C (I have disabled this because I have not done any testing with Class C before)

    Select: UPDATE DEVICE-PROFILE

  9. Select menu: Gateways
    Press button: CREATE

    Gateway name: RAK831
    The name may only contain words, numbers and dashes.

    Gateway description: RAK831 Pilot Gateway

    Gateway ID: B827EBFFFEC74B36

    Note:
    The gateway ID can be found in the local_conf.json file.
    In the RAK831 Pilot Gateway this file can be found at:
    /opt/ttn-gateway/packet_forwarder/lora_pkt_fwd

    https://github.com/robertlie/RAK831-LoRaGateway-RPi/
    blob/master/configuration_files/local_conf.json#L3


    Network-server: LoRaServer1
    Select the network-server to which the gateway will connect. When no network-servers are available in the dropdown, make sure a service-profile exists for this organization.

    Gateway-Profile:
    An optional gateway-profile which can be assigned to a gateway. This configuration can be used to automatically re-configure the gateway when ChirpStack Gateway Bridge is configured so that it manages the packet-forwarder configuration.

    Uncheck: Gateway discovery enabled
    When enabled (and ChirpStack Network Server is configured with the gateway discover feature enabled), the gateway will send out periodical pings to test its coverage by other gateways in the same network.

    Gateway altitude (meters): 10
    When the gateway has an on-board GPS, this value will be set automatically when the network received statistics from the gateway.

    Gateway location: <drag the marker to the location of the gateway> Drag the marker to the location of the gateway. When the gateway has an on-board GPS, this value will be set automatically when the network receives statistics from the gateway.

    Select: CREATE GATEWAY

  10. Select menu: Applications
    Press button: CREATE

    Application name: AppB
    The name may only contain words, numbers and dashes.

    Application description: AppB

    Service-profile: ServiceProfile1
    The service-profile to which this application will be attached.
    Note that you can't change this value after the application has been created.

    Payload codec: Custom Javascript codec functions
    By defining a payload codec, ChirpStack Application Server can encode and decode the binary device payload for you.

    I have entered a Decode function which is based on an end node and sketch which is explained in step H.

    Enter the following:
    // Decode decodes an array of bytes into an object.
    // - fPort contains the LoRaWAN fPort number
    // - bytes is an array of bytes, e.g. [225, 230, 255, 0]
    // The function must return an object, e.g. {"temperature": 22.5}

    function Decode(fPort, bytes) {
       if(bytes.length == 1) {
          if(bytes[0] == 1) {
             return {
                'button': 'activated'
             }
          } else {
             return {
                'error': 'button action unknown'
             }
          }
       } else if(bytes.length == 4) {
          var humidity = (bytes[0]<<8) | bytes[1];
          var temperature = (bytes[2]<<8) | bytes[3];
             return {
                'humidity': humidity/ 100,
                'temperature': temperature/100
             }
          } else {
             return {
                'error': 'payload unknown'
             }
          }
       }
    }


    Select: CREATE APPLICATION

    Select: App1
    Select tab: DEVICES
    Press button: CREATE

    Device name: TESTDEVICE1
    The name may only contain words, numbers and dashes.

    Device description: TESTDEVICE1

    Device EUI: <generate_a_device_eui>
    Generate a new Device EUI. Make sure you select LSB!
    Copy the generated Device EUI, you will need it in step H.
    For example: c6 50 16 27 67 60 64 11 (LSB)
    This is the same as "DEVEUI" in the Arduino sketch.

    Device-profile: DEVPROF-EU868

    Check: Disable frame-counter validation
    Note that disabling the frame-counter validation will compromise security as it enables people to perform replay-attacks.

    Select tab: KEYS (OTAA)

    Application key (LoRaWAN 1.0): <generate_an_application_key>
    Generate a new Application Key. Make sure you select MSB!
    Copy the generated Application Key, you will need it in step H.
    For example: eb f3 a6 6d 69 66 6b 31 e2 5f 9a 13 29 44 6b 4a (MSB)
    This is the same as "APPKEY" in the Arduino sketch.

    Press button: SET DEVICE-KEYS
Step H. Modify and upload a sketch to the end node.
  1. I have built my own LoRa end node using an Arduino Pro Mini and HopeRF RFM95 LoRa transceiver module, see:
    https://www.mobilefish.com/developer/lorawan/ lorawan_quickguide_build_lora_node_rfm95_arduino_pro_mini.html

    This LoRa end node consist of:
    • Arduino Pro Mini (ATmega328P / 3.3V / 8 MHz)
    • LoRa HopeRF RFM95 module with dipole antenna
    • DHT11 module (Humidity and temperature sensor)
    • Push button
    • Two LEDs
    • OLED display module (0.96")

    I am using this Arduino sketch:
    https://www.mobilefish.com/download/lora/lmic-ttn-otaa-pro-mini-sensors-oled.ino.txt

    In this sketch the end node uses OTAA to register itself.

  2. Modify this sketch.
    • Change the DEVEUI. Enter the Device EUI from previous step!
      static const u1_t PROGMEM DEVEUI[8]={ 0xC6, 0x50, 0x16, 0x27, 0x67, 0x60, 0x64, 0x11 };

    • Change the APPKEY. Enter the Application Key from previous step!
      static const u1_t PROGMEM APPKEY[16] = { 0xEB, 0xF3, 0xA6, 0x6D, 0x69, 0x66, 0x6B, 0x31, 0xE2, 0x5F, 0x9A, 0x13, 0x29, 0x44, 0x6B, 0x4A };

    • LoRaServer does not use the APPEUI value.
      You can use any value, for example:
      static const u1_t PROGMEM APPEUI[8]={ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };

  3. Upload the sketch to the device.

Step I. Check if sensor data is displayed in the ChirpStack Application Server web interface.
  1. Login
  2. Select menu: Applications
  3. Select: AppB
  4. Select Device: TESTDEVICE1
  5. Select menu: LIVE DEVICE DATA

Step J. Check the chirpstack-gateway-bridge, chirpstack-network-server and chirpstack-application-server for errors.
This step is only needed if you encounter problems.
  1. Check if packet forwarder sends data:

    Type: sudo tcpdump -AUq -i lo port 1700
    Type: journalctl -f -n 50 -u chirpstack-gateway-bridge
    Type: journalctl -f -n 50 -u chirpstack-network-server
    Type: journalctl -f -n 50 -u chirpstack-application-server

    More troubleshooting:
    https://www.chirpstack.io/guides/troubleshooting/gateway/