LoRaWAN

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

1. ChirpStack Gateway Bridge
2. ChirpStack Network Server
3. ChirpStack Application Server
4. ChirpStack Geolocation Server

• In this manual a RAK831 Pilot Gateway is used.
  This gateway uses a Raspberry Pi 3 as the Micro Controller Unit (MCU) and the following software are already installed:
  
  • LoRa packet forwarder (v4.0.1):
    https://github.com/Lora-net/packet_forwarder
  • LoRa gateway (v5.0.1):
    https://github.com/Lora-net/lora_gateway
    See Tutorial 28.1:
    https://youtu.be/aR9-gbZvBh0
  
  
• This manual assumes:
  • The gateway is used in the Netherlands (EU) and operates in the 863-870 MHz frequency band.
  • The gateway has ip address: 192.168.1.71 (IP address does not change, it is static.)
  
  
• To access the gateway from a computer:
  Open a terminal
  Type: ssh [email protected] (Gateway)

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
   
   Note:
   Start mosquitto on boot.
   Type: sudo systemctl enable mosquitto
   
   To disable mosquitto so it doesn't start on boot.
   Type: sudo systemctl disable mosquitto
   
   
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

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:dbpassword@localhost/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

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:dbpassword@localhost/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

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)

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
   
   
   
   
   

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

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

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.
   
   

1. Login
2. Select menu: Applications
3. Select: AppB
4. Select Device: TESTDEVICE1
5. Select menu: LIVE DEVICE DATA
   
   

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/