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 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.

...

• 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

...

If you open a CSV file with this line in Excel, then 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.

...

• <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 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.

...

...

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.

...

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

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

   Code Block
   git –version

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

   Code Block
   git version 2.25.1

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

   Code Block
   sudo apt update sudo apt install git get –version

   
   

2. Import the library.

   NoteThis

    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:

   Code Block
   title 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

   
   

   Code Block
   title 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

1. Obtain the ChirpStack 4 javascript device codec from the manufacturer and use

...

1. the contents when creating the tenant device profile as shown in section 8 below.
   

...

1. 
   

2. If only the TTN

...

1. codec is available, apply the wrapper shown below to match the ChirpStack 4 calling convention:

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

...

1. 
   

2. If only a ChirpStack 3 codec is available, use the following wrapper:
   

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

...

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

   Code Block
   title Example
   http://10.0.1.21:8080

   The ChirpStack administration login page appears.
   

   
   Image Added
   
   
2. Enter the login username / email and password (default is admin / admin), and click Submit.
   
   
3. 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.
   
   Image Modified
   
   
4. If you have imported the library, click Select device profile template and choose the relevant template using the subsequent dialogs as shown below.
   
   Image Modified
   
   
5. If you are using a manufacturer supplied codec, then enter the Name and Description fields and click Codec as shown below.

...

1. 
   
   Image Modified
   
   
2. 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:
   
   Image Modified
   
   
3. Select Javascript functions from the Payload codec field as shown below. Remove all of the existing code and paste in the manufacturer's codec

...

1. .
   
   Image Modified
   
   
2. Click Submit.

Step 2: Create the Device

...

Perform the following steps to 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 4: List the Datapoints

Perform the following steps to list the datapoints:

1. 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):
   

   Code Block
   mosquitto_sub -t application/#

   Uplink data will appear similar to the following:
   

   Code Block
   apollo@smartserver-17qampp:~$ mosquitto_sub -v -t application/#

...

1. application/4d2b4765-ff93-49c3-93d8-86edcf864bf5/device/24e124710c143951/event/up {"deduplicationId":"8c89914a-04f5-455f-96b5-35d78682c693","time":"2023-06-09T11:51:31.858367905+00:00","deviceInfo":{"tenantId":"52f14cd4-c6f1-4fbd-8f87-4025e1d49242","tenantName":"ChirpStack","applicationId":"4d2b4765-ff93-49c3-93d8-86edcf864bf5","applicationName":"Sensors","deviceProfileId":"9cf4283c-3595-4bf0-98a5-c6e5b3c10db2","deviceProfileName":"Milesight_AM319","deviceName":"AM319","devEui":"24e124710c143951","tags":{}},"devAddr":"005f42c9","adr":true,"dr":5,"fCnt":31,"fPort":85,"confirmed":false,"data":"A2fPAARoYwUAAAbLAgd9gQIIfScACXMYJwp9BAALfQoADH0PAA==","object":{"hcho":0.04,"temperature":20.7,"pressure":1000.8,"pm2_5":10.0,"pm10":15.0,"co2":641.0,"light_level":2.0,"pir":0.0,"tvoc":39.0,"humidity":49.5},"rxInfo":[{"gatewayId":"ac1f09fffe06047c","uplinkId":50882,"rssi":-62,"snr":14.0,"rfChain":1,"location":{},"context":"0BrjFQ==","metadata":{"region_common_name

...

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.

Image Removed

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.

...

1. ":"EU868","region_name":"eu868"}}],"txInfo":{"frequency":868100000,"modulation":{"lora":{"bandwidth":125000,"spreadingFactor":7,"codeRate":"CR_4_5"}}}}

   
   

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

3. 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.

Image Added

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.

Image Added

LoRaWAN Driver External Downlink Encoder

Overview  

When complex downlink hex strings need to be created once a given datapoint is updated by IAP (either via the REST or MQTT APIs, from the CMS, the scheduler or BACnet), an external encoder can be used to achieve do this.

The optional “Downlink Encoder”  field in a .lorawan XIF may contain a command that is executed by the LoRaWAN driver in a child process.

The standard input of the child process is always supplied with a JSON object that contains the following key value pairs:

• devEUI (the LoRaWAN devEUI)
• devName (the device name in ChirpStack)
• datapointName (the name of the datapoint that was updated by IAP or an external protocol such as BACnet, as defined in the XIF file)
• inputValue (the current value of the datapoint “datapointName”, that will be used to derive the downlink data to ChirpStack
• datapoint (the current value of all datapoints associated with the device in question)

An example of the JSON object is shown below. For this example, “Light Level” is the current value that IAP has for the datapoint, and “inputValue” is the new requested value for the datapoint.

{
    "devEUI": "2c1165fffe7aea35",
    "devName": "ISDE_ISNN_100L_EU",
    "datapointName": "Light Level",
    "inputValue": "42",
    "datapoint": {
        "Burn Hours": "194",
        "Energy": "16",
        "Light Level": "88",
        "Voltage": "240.30000000000001",
        "fPort": "2"
    }
}

The command can also accept arguments, such as one of the datapoint’s XIF field wrapped in curly brackets for example: {Datapoint Name}. The referenced fields are resolved into their respective values when the command is executed. 

The Downlink Encoder Command

The command should always start with an executable (e.g., bash / python), followed by a script name and any other arguments. The encoder is not executed in a shell, so any script’s interpreter must be explicitly used.

The executable, which is always the first word in the command, will be searched for in the actual PATH environment variable of the local machine. Commas cannot be used in the command.

An example XIF field containing a valid downlink encoder command is shown below.

python /var/apollo/data/lwd/res/encoder.py {Block Name} {Block Index}

Downlink Encoder Output

The only accepted output on the STDOUT of the encoder process either a hexadecimal string such as “0x102fa8” or a decimal string such as “100200”. Only one line is expected, without whitespace padding. The new line character at the end is ignored. The output of the encoder will be base64 encoded by the LoRaWAN driver and then passed to the MQTT application topic which is being monitored by ChirpStack. ChirpStack will send the update to the device using confirmed service.

Activity Logging

Normal and erroneous activity is logged, and the log can be accessed using the following command:

journalctl -f -u smartserver-lorawan

In case the call was successful (exit code 0), the log will contain an entry with the sent downlink data.

If the encoder process ends with an exit code other than 0, then the downlink message processing is interrupted, and the encoder process’ STDERR (if any) is printed in the log accordingly.

Example of a successful call is shown below.

Image Added

Example of an unsuccessful call is shown below.

Image Added

 Worked Example for ISDE ISNN-100L Outdoor Luminaire Controller (OLC)

An example of a working downlink encoder for the ISDE ISNN-100L Outdoor Luminaire Controller can be found here.

In the case of the ISNN-100L, it requires a scalar with a value between 0₁₀ and 254₁₀ which represents 0% (off) to 100% (full on).  However, in the case of the example, the datapoint uses SNVT_lev_cont_f so that the light level can be controlled using 0-100% with IAP ensuring data input validation.  The encoder will therefore scale up the value to between 0₁₀ and 254₁₀. The output of the encoder is a hex string where the scaled “Input Value” is encapsulated within product-specific pre-fix and post-fix data.

For example, the output hex string from the encoder can be 0x0203027e2aff, where the data format is as follows:

The output string is subsequently encoded by the LoRaWAN driver into Base64 and sent as a confirmed downlink update to the MQTT application/ topic as shown below.

 Image Added

Debugging the Encoder 

Debugging can be performed in one of the ways listed below. These methods are described in the sections that follow.

1. Writing output to a local file
2. Using the cat command with a JSON file
3. Using Visual Studio Code

Writing Output to a Local File

You can write output to a local file from the encoder, this method is used in the example. At a minimum, this allows you to inspect the data received from the LoRaWAN driver. This mechanism can be used to derive the JSON file for the next two debugging options.

Using the cat command with a JSON file

You can debug the encoder by executing it on a development machine with an example set of data using a command as shown in the example below.

cat input.json | python encoder.py

The JSON file must contain a valid JSON object, with inputValue being a mandatory key/value pair.

An example of a valid input.json file is shown below.

{
     "devEUI": "70b3d52dd3003b86",
     "devName": "MClimateVicki",
     "datapointName": "childLock",
     "inputValue": "32",
     "datapoint": {
           "batteryVoltage": "2.8999999999999999",
           "brokenSensor": "0",
           "childLock": "0",      
           "relativeHumidity": "58.979999999999997",
           "sensorTemperature": "22.710000000000001",
           "targetTemperature": "21"
     }
}

Using Visual Studio Code

To debug in Visual Studio Code, the launch.json file needs to be modified to pass the contents of a valid JSON file to the command line. An example of a valid launch.json is shown below.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Current File with Arguments",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/encoder.py",
            "console": "integratedTerminal",
            "args": [
                "${workspaceFolder}/input.json"
            ]
        },
    ]
}