...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

SmartServer Pi is available with SmartServer 4.2 and higher.

You can use SmartServer Pi to integrate and manage LoRaWAN (Long Range Wide Area Network) devices.  LoRaWAN is a low power, wide area (LPWA) networking protocol designed to wirelessly connect battery (class A) and line-powered (class C) devices to a network providing bi-directional communication, end-to-end security, mobility, and localization services. The SmartServer LoRaWAN driver sends and receives data to and from LoRaWAN devices via a LoRa Network Server (LNS), which in the case of SmartServer 4.2 and higher is ChirpStack 4.2.

This section describes how to get started using LoRaWAN devices and consists of the following:

LoRaWAN Architecture

A typical LoRaWAN architecture is shown below:

Setting up LoRaWAN

To set up and use LoRaWAN with SmartServer Pi, follow these steps:

1. Acquire and configure a LoRaWAN Gateway as described on this page.
   
   
2. Enable LoRaWAN and ChirpStack on your SmartServer Pi as described on this page. With SmartServer 4.2 and higher, the LoRaWAN driver is disabled by default. 
   
   
3.  Add LoRaWAN Device Profiles in ChirpStack as described on this page.
   
   
4. Optionally, change the LoRaWAN frequency settings, which default to European frequencies, to the region that matches your LoRa gateway and actual LoRa devices as described on this page.
   
   
5. Import, or create a LoRaWAN device interface (XIF) and device type definition as described on this page.
   
   
6. Discover devices as described in Site Provisioning.
   
   
7. Optionally, provide a BACnet interface for your LoRaWAN device; see Setting up the BACnet Server. This capability allows you to use a BACnet workstation with your LoRaWAN device.

Receiving Uplink Data from Edge Devices

LoRaWAN devices will send unconfirmed uplink data regularly, along with alarm data as necessary. Regular uplink data may consist of one or more packets, separated by a few seconds. The regular update interval is configurable either using an NFC app or via downlink data and determines battery life for class A devices. Devices send an encrypted base64-encoded hex string over the air that represents all the sensor data, the LNS decrypts the data, converts from base64-encoded to a hex string and the relevant device profile codec converts the hex string to a JSON object which is passed to IAP using MQTT. The entire hex string prior to JSON encoding is available in IAP if required.

Sending Downlink Data to Edge Devices

The LoRaWAN driver sends downlink data to the LNS using MQTT. The LNS forwards the data to edge devices. The LoRaWAN driver uses an LNS-specific MQTT topic, base64-encoded data, and the fport number configured in the XIF for the device type and the datapoint in question.  For non binary applications, external encoders can be used to generate the downlink data.  The data is sent to the LoRaWAN device using a confirmed message. Downlink data may relate to a specific datapoint, or may be a hex string that can be used to configure the regular uplink period, alarm thresholds or form part of a request response mechanism in conjunction with the subsequent uplink data.

Defining the IAP Device UNID

The LoRaWAN device DevEUI is used as the IAP unid. It is either acquired when using automatic discovery for LoRaWAN (the preferred mechanism) or added when manually creating devices.

Acquiring the LoRaWAN Gateway

Purchase an external LoRaWAN gateway such as a RAK 7268 or Multitech MTCAP for the relevant local frequency band. 

Configuring the LoRaWAN Gateway

Ensure that the LoRaWAN gateway is set for Semtech Packet Forwarding on UDP port 1700 for both uplink and downlink connections and that the LNS server IP address is set to the IP address of SmartServer Pi.  

An example RAK gateway configuration is shown below. Make a note of the Gateway EUI, which is needed to configure ChirpStack.

Using Redundant LoRaWAN Gateways

ChirpStack supports redundant gateways, either for enhanced coverage or for true redundancy.

Enabling the LoRaWAN Driver and ChirpStack

With SmartServer 4.2 and higher, the LoRaWAN driver and ChirpStack are disabled by default for SmartServer Pi. Do not use the SmartServer Pi Configuration page to enable LoRaWAN and ChirpStack –– follow these steps:

1. Open a SmartServer Pi terminal connection.
   Image Removed
   Image Added
   
   

2. Ensure that the SmartServer Pi can access the internet by using the following command in an SSH session:
   

   Code Block
   ping google.com

   You should see a response similar to the following:
   

   Code Block

   apollo@smartserver-hsbcw69:~$ ping google.com PING google.com (192.168.4.146) 56(84) bytes of data. 64 bytes from 192.168.4.146 (192.168.4.146): icmp_seq=1 ttl=114 time=47.9 ms 64 bytes from 192.168.4.146 (192.168.4.146): icmp_seq=2 ttl=114 time=45.1 ms 64 bytes from 192.168.4.146 (192.168.4.146): icmp_seq=3 ttl=114 time=41.5 ms 64 bytes from 192.168.4.146 (192.168.4.146): icmp_seq=4 ttl=114 time=54.7 ms

   Use CTRL-C to stop pinging. You should then see a summary similar to the following:
   

   Code Block
   --- google.com ping statistics --- 4 packets transmitted, 4 received, 0% packet loss, time 7054ms rtt min/avg/max/mdev = 41.503/47.285/54.658/4.825 ms

   If there is an issue with internet access, then correct the problem as needed.
   
   

3. Enter the following command to enable LoRaWAN and ChirpStack:
   

   Code Block
   $ ssctl enable chirpstack lorawan

   
   

4. Enter the following command to reboot SmartServer Pi:
   

   Code Block
   $ sudo reboot

   
   

5. Once SmartServer Pi has finished rebooting, open a terminal connection again.

   
   

6. Enter the following command to verify that LoraWAN and ChirpStack are running:
   

   Code Block
   $ ssctl status chirpstack lorawan

   You should see a result similar to the following:

   Code Block

   pi@smartserver-hsbcw69:~ $ ssctl status chirpstack lorawan chirpstack-bridge active since Tue 2023-11-21 15:46:10 EST; 3min 39s ago chirpstack-gateway active since Tue 2023-11-21 15:46:10 EST; 3min 39s ago chirpstack-postgresql active since Tue 2023-11-21 15:46:09 EST; 3min 40s ago chirpstack-redis active since Tue 2023-11-21 15:46:09 EST; 3min 40s ago lorawan active since Tue 2023-11-21 15:46:40 EST; 3min 9s ago pi@smartserver-hsbcw69:~ $

   
   

   The  SmartServer Pi Configuration page will also show the LoRaWAN interface is enabled. Disregard the Install ChirpStack button; ChirpStack is installed by default in SmartServer Pi.
   
   
   
   

7. Once ChirpStack is running, you can log into the ChirpStack administration page by entering http://<SmartServer Pi IP address>:8080 in a web browser URL.

   Code Block
   title Example
   http://192.168.4.146:8080

   The ChirpStack administration login page appears.
   

   
   
   
   
8. Enter the login username / email and password (default is admin / admin), and click Submit.
   
   The ChirpStack Dashboard appears.
   
   
   
   
9. Add LoRaWAN Device Profiles in ChirpStack. See the Adding LoRaWAN Device Profiles in ChirpStack section below. 
   
   
10. Optionally, change the LoRaWAN frequency settings. See the Changing the LoRaWAN Frequency Settings section below. 

Disabling the LoRaWAN Driver and ChirpStack

Do not use the SmartServer Pi Configuration page to disable LoRaWAN and ChirpStack –– follow these steps:

1. Open a SmartServer Pi terminal connection.
   
   
   
   

2. Enter the following command to disable LoRaWAN and ChirpStack:
   

   Code Block
   $ ssctl disable chirpstack lorawan

   
   

3. Enter the following command to reboot SmartServer Pi:
   

   Code Block
   $ sudo reboot

   
   

4. Once SmartServer Pi has finished rebooting, open a terminal connection again.
   
   

5. Enter the following command to verify that LoraWAN and ChirpStack are not running:
   

   Code Block
   $ ssctl status chirpstack lorawan

   You should see a result similar to the following:

   Code Block
   pi@smartserver-hsbcw69:~ $ ssctl status chirpstack lorawan chirpstack-bridge inactive chirpstack-gateway inactive chirpstack-postgresql inactive chirpstack-redis inactive lorawan inactive pi@smartserver-hsbcw69:~ $

   
   

   The  SmartServer Pi Configuration page will also show that the LoRaWAN interface is not enabled.
   
   

Adding LoRaWAN Device Profiles in ChirpStack

In order to use the LoRaWAN device type packages (.dtp), which are files available from the SmartServer GitHub Repository, you have to add a Device Profile in ChirpStack for each device you want to use.  Device Profiles also include the corresponding codec, which are also available at SmartServer GitHub Repository.  The Device Profiles' Region field has to specify the appropriate region that matches your LoRa gateway and actual LoRa devices. 

...

1. Log into the ChirpStack administration page by entering http://<SmartServer Pi IP address>:8080 in a web browser URL.

   Code Block
   title Example
   http://192.168.4.146:8080

   The ChirpStack administration login page appears.
   

   
   
   
   
2. Enter the login username / email and password (default is admin / admin), and click Submit.
   
   The ChirpStack Dashboard appears.
   
   
   
   

3. Click the Device profiles tab on the left-side contents.
   
   
   
   

4. Click the Add Device Profile button.
   
   The Add Device Profile view appears.
   
   
   
   

5. Enter a Name for the Device Profile and define the other fields as needed for your LoRa device. The name of the Device Profile must match the name of the corresponding .lorawan file, which is included in the .dtp. Use the Region field pull-down menu to select the appropriate region for your implementation (i.e., EU868 is changed to US915 in the example below).
   
   
   
   

6. Optionally, if the device supports Class-C communications, then perform the following steps:

   1. Click the Class-C tab.

      1. Enable the Device supports Class-C option.

      2. Set theClass-C Confirmed downlink timeout period (seconds) field.
         
         
         
         

   2. Click the Codec tab.
      1. Select Javascript Functions from the Payload codec drop-down menu.
      2. Delete the existing content from the Codec functions field.
      3. Add the required codec content.
         
         
         
         

7. Click Submit to save the Device Profile.
   
   
   
   

8. Repeat these steps to add additional Device Profiles.
   
   
9. Optionally, change the LoRaWAN frequency settings as described in the Changing the LoRaWAN Frequency Settings section below. 

(Optional) Changing the LoRaWAN Frequency Settings

The SmartServer Pi LoRaWAN frequency settings default to European frequencies. For non-European, SmartServer Pi LoRaWAN implementations, the frequency settings need to be changed to the region that matches your LoRa gateway and actual LoRa devices. These settings need to be changed in the SmartServer Pi chirpstack-gateway-bridge.toml file as described in the steps that follow, and set in the Device Profiles that are defined in ChirpStack as described in the Adding LoRaWAN Device Profiles in ChirpStack section above.

To change the LoRaWAN frequency settings in the SmartServer Pi chirpstack-gateway-bridge.toml file, perform the following steps:

1. Use an SCP or SFTP client tool (e.g., WinSCP) to copy the chirpstack-gateway-bridge.toml file to your local PC and save a backup. The chirpstack-gateway-bridge.toml file is found at /var/smartserver/conf.d/chirpstack/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml. 
   
   
2. Copy the original chirpstack-gateway-bridge.toml file and keep the same name.
   
   

3. Modify the three topic templates listed under the [integration.mqtt] section shown below by replacing the eu868 region references with the region that matches your LoRa gateway and actual LoRa devices.

   Code Block
   [integration.mqtt] event_topic_template="eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}" state_topic_template="eu868/gateway/{{ .GatewayID }}/state/{{ .StateType }}" command_topic_template="eu868/gateway/{{ .GatewayID }}/command/#"

   Some LoRa regions, like the United States, support multiple, uplink sub-bands (8). In these cases, the region must also reference the actual uplink sub-band that is in use by the LoRaWAN gateway and the devices. Example: if you are using the SmartServer Pi to interface to a LoRaWAN gateway and sensors in the United States using the LoRa 8-channel, uplink sub-band 0 (902.3 - 903.7), modify the topic templates in the chirpstack-gateway-bridge.toml file by changing eu868 to us915_0 as shown in the example below: 

   
   
   Default European frequency settings
   
   
   Modified United States frequency settings
   
   

4. Save the modified chirpstack-gateway-bridge.toml file.
    

5. Replace the chirpstack-gateway-bridge.toml file on the SmartServer Pi with the modified file.
   
   

6. Rebooting SmartServer Pi, or restart the SmartServer Pi LoRaWAN driver by disabling it and then re-enabling it as described in the Enabling the LoRaWAN Driver and ChirpStack and Disabling the LoRaWAN Driver and ChirpStack sections. 

Importing and Creating LoRaWAN Device Interface (XIF) and Device Type Definitions

You can import and optionally modify LoRaWAN device interface (XIF) and device type definitions. You can also manually create custom LoRaWAN XIF and device type definitions. To import and modify LoRaWAN device interface (XIF) and device type definitions, follow these steps:

1. Each of the Device Templates that are added during the ChirpStack installation have a matching LoRaWAN device type package (.dtp) that are available at the SmartServer GitHub Repository. A list of the supported device types can be found here. The .dtp files include the relevant .lorawan, .dtd, .dla, and .btm files. The .dla files define event-driven updates for each datapoint in the .lorawan files.
   
   Download the required LoRaWAN .dtp files.   
   
   
2. To create a custom LoRaWAN XIF definition (.LoRaWAN), see Creating a LoRaWAN Device Interface (XIF) Definition. You will also need a corresponding ChirpStack device template that will include the relevant codec.
   
   
3. To create a custom LoRaWAN device type definition (.dtd), see Defining Device Types.
   
   
4. Import the LoRaWAN device type package (.dtp) or device interface (XIF) or device type definitions (.dtd) using the Import / Export button () on the SmartServer app bar.

...