LoRaWAN devices are supported with SmartServer 4.0 and higher.

The SmartServer ships with support for a range of LoRaWAN device types. While you can create your own LoRaWAN device interface definitions, device type definitions and associated LNS profiles, they must not conflict with the supplied types and associated LNS device profiles.

This section provides information on how to create a LoRaWAN device interface (XIF) definition and consists of the following:  

Supported Devices

The table below lists the device types that were tested with SmartServer 4.0.

LoRaWAN XIF Definition

To create a LoRaWAN XIF definition, follow these steps:

• A file type specification that identifies the file as a LoRaWAN XIF file.
• A product details section that specifies the program ID, version, product name, and manufacturer for the LoRaWAN device.
• A datapoint list that specifies the datapoints on the device to be available to the SmartServer. The first line of the datapoint list is a header with column headings for a datapoint list. 

The following figure illustrates the top portion of a LoRaWAN XIF file.

#filetype,lorawan_xif
#program_ID,9B008C011E00BB05
#version,beta
#product_name,NetvoxR718N17
#manufacturer,Netvox
#description,xif with all uplink datapoints
Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,IAP Field,Write Enable,Downlink Encoder,Downlink Code,Downlink Port,Downlink String Length,Downlink Binary 0 Constant,Downlink Binary 1 Constant,Precision,Description,Native Value 1,Native Value 2,Scaled Value 1,Scaled Value 2,Range Min,Range Max,ASCII Length

File Type Specification

The file type for a LoRaWAN XIF file must be specified using a #filetype metadata tag name and a LoRaWAN_xif metadata tag value as shown in the example below.

#filetype,LoRaWAN_xif

The LoRaWAN driver accepts device type XIF files that use the extension .LoRaWAN, .csv, or .LoRaWAN.csv extension and start with LoRaWAN_xif.

Product Details

The product details identify the product specified by the LoRaWAN XIF file. The product details specification has the following contents:

#program_ID,<Program ID>
#version,<Version>
#product_name,<Product Name>
#manufacturer,<Manufacturer>
#description,<Description>

If you open a CSV file with this line in Excel, it is displayed as two cells, one with #filetype and the other with the LoRaWAN_xif metadata tag value. If you save a LoRaWAN XIF file from Excel, then Excel will append commas to the file type specification. The LoRaWAN driver and the CMS will ignore the commas, if present.

Specify the details as follows:

• <Program ID> – (optional) a 64-bit hexadecimal number used for identifying resource definitions (e.g., 9F:00:96:05:28:04:E1:01) with optional colon and hyphen separators. See Device Type Definition for further information.  Note for LoRaWAN the LoRa Alliance Vendor ID is used for the manufacturer ID. 

• <Version> – (optional) version of the device.

• <Product Name> – (optional) manufacturer's name for the device.

• <Manufacturer> – (optional) device manufacturer.

• <Description> – (optional) comment description of the device.

Following is an example product details specification for a Netvox R712 Wireless Outdoor Temperature Humidity Sensor:

#program_ID,9F:00:96:05:28:04:E1:01
#version,v2.21.019
#product_name,Netvox R712
#manufacturer,Netvox
#description,Netvox R712 Wireless Outdoor Temperature Humidity Sensor

Datapoint List

The datapoint list specifies the datapoints on the device that are to be available to the SmartServer. The first line of the datapoint list is a header with column headings for a datapoint list. The following example shows a datapoint list with a single datapoint defined in the second line:

Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,IAP Field,Write Enable,Downlink Encoder,Downlink Code,Downlink Port,Downlink String Length,Downlink Binary 0 Constant,Downlink Binary 1 Constant,Precision,Description,Native Value 1,Native Value 2,Scaled Value 1,Scaled Value 2,Range Min,Range Max,ASCII Length
Sensors,0,Raw Current,rawcurrentma,,SNVT_amp_f,,-,,,,,,,,,1000,10000,1,10,,,
Sensors,0,Scaled Current,currentma,,SNVT_amp_f,,-,,,,,,,,,1000,10000,1,10,,,
Sensors,0,Current Multiplier,multiplier,,SNVT_count_f,,-,,,,,,,,,,,,,,,

The following table describes the column contents for the datapoint list. You can arrange the columns in any order. The SmartServer uses the name in the heading row entry to identify the contents of the column.  

Example

The example shown below is for the Milesight AM319 indoor air quality sensor.

The filename for the example shown below is Milesight_AM319.lorawan.

#filetype,lorawan_xif,,,,,,,,,,,,,,,,,,,,,
#program_ID,8002590A5A04E100,,,,,,,,,,,,,,,,,,,,,
#version,beta,,,,,,,,,,,,,,,,,,,,,
#product_name,Milesight AM319,,,,,,,,,,,,,,,,,,,,,
#manufacturer,Milesight,,,,,,,,,,,,,,,,,,,,,
#description,xif for Milesight AM319,,,,,,,,,,,,,,,,,,,,,
Block Name,Block Index,Datapoint Name,Address,Native Type,IAP Type,IAP Field,Write Enable,Downlink Encoder,Downlink Code,Downlink Port,Downlink String Length,Downlink Binary 0 Constant,Downlink Binary 1 Constant,Precision,Description,Native Value 1,Native Value 2,Scaled Value 1,Scaled Value 2,Range Min,Range Max,ASCII Length
Sensors,0,PM10,pm10,,SNVT_count_f,,-,,,,,,,,,,,,,,,
Sensors,0,Temperature,temperature,,SNVT_temp_f,,-,,,,,,,,,,,,,,,
Sensors,0,Light Level,light_level,,SNVT_count,,-,,,,,,,,,,,,,,,
Sensors,0,TVOC,tvoc,,SNVT_count_f,,-,,,,,,,,,,,,,,,
Sensors,0,PM2_5,pm2_5,,SNVT_count_f,,-,,,,,,,,,,,,,,,
Sensors,0,Pressure,pressure,,SNVT_count_f,,-,,,,,,,,,,,,,,,
Sensors,0,HCHO,hcho,,SNVT_count_f,,-,,,,,,,,,,,,,,,
Sensors,0,CO2,co2,,SNVT_ppm_f,,-,,,,,,,,,,,,,,,
Sensors,0,PIR,pir,,SNVT_count,,-,,,,,,,,,,,,,,,
Sensors,0,Humidity,humidity,,SNVT_lev_cont_f,,-,,,,,,,,,,,,,,,

LoRaWAN XIF Development Process

The LoRaWAN XIF development process is a multi-step process as outlined and described in more detail below:

1. Create the tenant device profile.
2. Create the device.
3. Examine the uplink data on the application/# MQTT topic.
4. List the datapoints from the device.
5. Create the .lorawan file.
6. Create the .btm file.
7. Create the .dtd file.
8. Create the .dtp.
9. Import the .dtp into the CMS.
10. Validate the uplink data in the Datapoints widget.
11. Validate the uplink data in a BACnet browser.

Step 1: Create the Tenant Device Profile

Create the ChirpStack tenant device profile in one of the following ways:

• Download the ChirpStack device profile template library, which may already have the relevant device profile.
• Obtain the device codec from the manufacturer.

Download the ChirpStack Device Profile Template Library

1. Install git (it may already be installed on your SmartServer). 
   

   To determine whether or not git --version is already installed on your SmartServer, open an SSH session and enter the following command:

   git –version

   If a response similar to the following is returned, then git --version is already installed and you can proceed to the next step.

   git version 2.25.1

   If a response is not returned, then install git --version using the following commands:

   sudo apt update
   sudo apt install git
   get –version

2. Import the library.

   This process will take a few minutes to complete and will consume about 750MB on the SD Card.

   To import the library, from an SSH session, enter the following commands:

   For SmartServer 4.1 (Beta) and higher

   sudo mkdir  -p /media/sdcard/chirpstack/lorawan-devices/
   
   sudo git clone https://github.com/brocaar/lorawan-devices /media/sdcard/chirpstack/lorawan-devices/
   
   sudo find /media/sdcard/chirpstack/lorawan-devices/ -type d -exec chmod 755 {} +
   sudo find /media/sdcard/chirpstack/lorawan-devices/ -type f -exec chmod 644 {} +
   
   sudo podman run --rm -ti --network host \
   --mount type=bind,source=/var/apollo/conf.d/chirpstack/chirpstack/,target=/etc/chirpstack/ \
   --mount type=bind,source=/media/sdcard/chirpstack/lorawan-devices/,target=/opt/lorawan-devices/ \
   docker.io/chirpstack/chirpstack:4.1.1 -c /etc/chirpstack import-legacy-lorawan-devices-repository -d /opt/lorawan-devices
   

   For SmartServer 4.0

   sudo mkdir  -p /media/sdcard/chirpstack/lorawan-devices/
   
   sudo git clone https://github.com/brocaar/lorawan-devices /media/sdcard/chirpstack/lorawan-devices/
   
   sudo find /media/sdcard/chirpstack/lorawan-devices/ -type d -exec chmod 755 {} +
   sudo find /media/sdcard/chirpstack/lorawan-devices/ -type f -exec chmod 644 {} +
   
   sudo docker run --rm -ti --env REDIS_HOST=redis --env POSTGRESQL_HOST=postgres \
   --network lora_gateway_network \
   --mount type=bind,source=/var/apollo/data/lora_gw/configuration/chirpstack/,target=/etc/chirpstack/ \
   --mount type=bind,source=/media/sdcard/chirpstack/lorawan-devices/,target=/opt/lorawan-devices/ \
   docker.io/chirpstack/chirpstack:4.1.1 -c /etc/chirpstack import-legacy-lorawan-devices-repository -d /opt/lorawan-devices
   

Obtain the Device Codec From the Manufacturer

Obtain the javascript device codec from the manufacturer and use it to create the tenant device profile.

For the TTN version, apply the wrapper shown below to match the ChirpStack 4 calling convention:

// ChirpStack 4 wrapper for TTN Codec
}
function decodeUplink(input) {
  return Decoder(input.bytes, input.fPort);
}												

For a ChirpStack 3 codec, use the following wrapper:

// ChirpStack 4 wrapper for ChirpStack 3 Codec
function decodeUplink(input) {
  return Decode(input.fPort, input.bytes);
}

From within ChirpStack, click Device Profiles in the left hand pane, and click Add device profile as shown below. See Discovering, Defining, or Importing Devices for details on how to log into ChirpStack. The device profile name should be the same as the xif file, but without the .lorawan extension. For example: for the xif file Elsys_ERS-Lite.lorawan, the device profile name should be Elsys_ERS-Lite.

If you have imported the library, click Select device profile template and choose the relevant template using the subsequent dialogs as shown below.

If you are using a manufacturer supplied codec, then enter the Name and Description fields and click Codec as shown below. 

If the device supports Class-C communications, then click the Class-C tab and enable the Device supports Class-C option and set the Class-C Confirmed downlink timeout period (seconds) as shown below:

Select Javascript functions from the Payload codec field as shown below. Remove all of the existing code and paste in the manufacturer's codec and click submit.

Step 2: Create the Device

1. Create a device using the device profile and with the Dev EUI and App Key. See the Provisioning LoRaWAN Gateways and Devices section in Discovering, Defining, or Importing Devices.
2. Verify that the join request/join accept phase concludes correctly.

Step 3: Examine Uplink Data

Within an hour, the device should start sending unconfirmed uplink data.

Step 4: List the Datapoints

From an SSH session, subscribe to the application/# topic using the following command (leave the subscription running for at least an hour since data may be supplied over multiple frames):

mosquitto_sub -t application/#

Uplink data will appear similar to the following:

List the data (highlighted in red in the example above) that is returned in the object JSON data.

If there are errors in the codec, they will be highlighted in the uplink data. Debug accordingly.

Step 5: Create the .lorawan File

Create the .lorawan file as described in the LoRaWAN XIF Definition section above using the datapoints list, selecting a suitable IAP Type, and scaling the value as necessary. 

The datapoint JSON key name that is used in the codec is the name that is used in the "Address" field of the .lorawan file, which is the name used by IAP to refer to the datapoint is used in the "Datapoint Name" field.  This, in conjunction with scaling, allows the use of standard manufacturer codec names such as "currentma" or vdd and Current or Battery Voltage subsequently in IAP. 

Choose names and units that will be useful in both IAP and BACnet. The names of the .lorawan and .btm files should match the name of the Device profile in ChirpStack.

Step 6: Create the .btm File

Create the .btm file as described in (Optional) Creating a BACnet Type Map (BTM).

Step 7: Create the .dtd File

Create the .dtd file as described in Defining Device Types.

Step 8: Create the .dtp File

Create the .dtp file (to include the .lorawan, .btm, .dtd, and associated image file in a compressed .zip file with the .dtp extension) as described Defining Device Types.

Step 9: Import the .dtp File into the CMS

Enable BACnet in the Configuration User Interface along with the LoRaWAN Driver. Import the .dtp file using the SmartServer CMS as described in Defining Device Types. See also Discovering, Defining, or Importing Devices.

Step 10: Validate the Uplink Data in the Datapoints Widget

Once the .dtp file has been imported and the device has sent uplink data, it will appear in the CMS. Check the data in the CMS Datapoints widget for the device against the uplink data in the application/# MQTT topic using the last update received. Use a suitable device filter to limit the amount of displayed data.

Step 11: Validate the Uplink Data in a BACnet Browser

Using a BACnet browser such as YABE, check that the present value is correct for each datapoint.