WisBlock Sensor Solution for LoRaWAN

Content

• Hardware supported
• Software used
• How to use it
• Packet data format
• Setup Weather Kits
• Setup GNSS Kits
• Setup Air Quality Kits

This is a new approach for WisBlock. It scans the I2C bus and Serial to detect which WisBlock modules are attached to the WisBlock base and creates an LoRaWAN payload in Cayenne LPP with the data of the found modules.

REMARK

This firmware is using the WisBlock API V2 ⤴️ which helps to create low power consumption application and taking the load to handle communications from your shoulder. WisBlock-API-V2 is a new version of the WisBlock API that has an AT command interface that is compatible with RAK's RUI3 AT command interface.

Hardware supported

LIMITATIONS

• The RAK1904 module MUST be installed in
  • Slot C of RAK5005-O, RAK19007 or RAK19001
  • Slot A of RAK19003
• The RAK1905 module MUST be installed in
  • Slot C of RAK5005-O, RAK19007 or RAK19001
  • Slot A of RAK19003
• RAK1910 and RAK12500 cannot be used together (both are GNSS location trackers)

Power consumption

The MCU and LoRa transceiver go into sleep mode between measurement cycles to save power. I could measure a sleep current of 40uA of the whole system for a solution that enables sleep. Some solutions, like GNSS trackers or the RAK12047 VOC sensor, that require longer wake times or more frequent wake-ups, have a higher power consumption.
In addition, sensors like the MQ gas sensors that are using a heating element will consume more power as well.

Software used

IDE

• PlatformIO ⤴️
• alternative ArduinoIDE ⤴️ (Not compatible atm)
• Adafruit nRF52 BSP ⤴️
• Raspberry Pi RP2040 BSP ⤴️
• Patch to use RAK4631 & RAK11310 with PlatformIO ⤴️

  LoRaWAN and BLE communication

• WisBlock-API-V2 ⤴️
• SX126x-Arduino LoRaWAN library ⤴️
• CayenneLPP ⤴️
• ArduinoJson ⤴️

  Sensor libraries

• Adafruit BME680 Library ⤴️
• Adafruit FRAM I2C ⤴️
• Adafruit LIS3DH ⤴️
• Adafruit LPS2X ⤴️
• Adafruit MCP23017 Arduino Library ⤴️
• Adafruit Unified Sensor ⤴️
• Adafruit Unified Sensor ⤴️
• Adafruit EPD ⤴️
• ClosedCube OPT3001 ⤴️
• Coulomb Counter ⤴️
• D7S ⤴️
• INA219_WE ⤴️
• LPS35HW ⤴️
• Melopero RV3028 ⤴️
• MPU9250 ⤴️
• nRF52_OLED ⤴️
• Pololu VL53L0X ⤴️
• RAK12019_LTR390_UV_Light ⤴️
• RAK12035_SoilMoisture ⤴️
• RAKwireless RAK12034 ⤴️
• RAKwireless CAP1293 Touch Pad library ⤴️
• RAK I3G4250D Gyroscope ⤴️
• RAKwireless MQx library ⤴️
• RAKwireless VEML Light Sensor ⤴️
• RAKwireless Storage ⤴️
• RevEng PAJ7620 ⤴️
• Sensirion Core ⤴️
• Sensirion Gas Index Algorithm ⤴️
• Sensirion I2C SGP40 ⤴️
• SparkFun SHTC3 Humidity and Temperature Sensor Library ⤴️
• SparkFun u-blox GNSS Arduino Library ⤴️
• SparkFun SCD30 Arduino Library ⤴️
• SparkFun STC3x Arduino Library ⤴️
• SparkFun MLX90632 Noncontact Infrared Temperature Sensor ⤴️
• SparkFun ADXL313 Arduino Library ⤴️
• SparkFun GridEYE AMG88 ⤴️
• TinyGPSPlus ⤴️

... to be updated, check platformio.ini for a list of all libraries used

REMARK

The project was developed using Platform IO. But for the users that still stick to Arduino IDE, an Arduino IDE compatible copy of the sources is in the ArduinoIDE folder. The code is not compiling on Arduino IDE atm.
The complete project for PIO is in the PlatformIO folder.

REMARK

When using PlatformIO, the libraries are all listed in the platformio.ini and are automatically installed when the project is compiled.
When using Arduino IDE all libraries need to be installed manually using the Arduino Library Manager.

How to use it

Compile the firmware and flash it on a WisBlock with all required modules installed.

Setup the LPWAN credentials with one of the options:

Over USB

Connect over USB to setup the LPWAN credentials. Use the DevEUI printed on the RAK4631, use the AppEUI and AppKey from your LPWAN server. Do NOT activate automatic join yet. As weather sensor levels are not changing very fast, it might be sufficient to set the send frequency to every 10 minutes. The send frequency is set in seconds, so the value would be 10 * 60 ==> 600

Example AT commands:

AT+NWM=1
AT+NJM=1
AT+BAND=10
AT+DEVEUI=1000000000000001
AT+APPEUI=AB00AB00AB00AB00
AT+APPKEY=AB00AB00AB00AB00AB00AB00AB00AB00
AT+SENDINT=600

REMARK

The manual for all AT commands can be found here: AT-Commands.md ⤴️. WisBlock API V2 does not support all RUI3 AT commands. You can check available AT commands with the command AT?

Over BLE

Use the WisBlock Toolbox ⤴️, connect over Bluetooth with the Soil Sensor and setup the credentials. Do NOT activate automatic join yet.

Packet data format

The packet data is made compatible with the extended Cayenne LPP encoding from ElectronicCats/CayenneLPP ⤴️.
The content of the packet depends on the modules installed on the WisBlock Base Board:

REMARK

Channel ID's in cursive are extended format and not supported by standard Cayenne LPP data decoders.

Example decoders for TTN, Chirpstack, Helium and Datacake can be found in the folder RAKwireless_Standardized_Payload repo ⤴️

Compiled output

The compiled files are located in the ./Generated folder. Each successful compiled version is named as
WisBlock_SENS_Vx.y.z_YYYY.MM.dd.hh.mm.ss
x.y.z is the version number. The version number is setup in the ./platformio.ini file.
YYYY.MM.dd.hh.mm.ss is the timestamp of the compilation.

The generated .zip file can be used as well to update the device over BLE using either WisBlock Toolbox ⤴️ or Nordic nRF Toolbox ⤴️ or nRF Connect ⤴️

When using PlatformIO in addition a UF2 file for the RAK4631 is generated. You can force the RAK4631 into bootloader mode by double-pushing the reset button. A new USB drive will be installed. Pull the UF2 file into the new drive to flash the device.

Debug options

Debug output can be controlled by defines in the platformio.ini
_LIB_DEBUG_ controls debug output of the SX126x-Arduino LoRaWAN library

• 0 -> No debug outpuy
• 1 -> Library debug output (not recommended, can have influence on timing)

_API_DEBUG_ controls debug output of the WisBlock-API library

• 0 -> No debug outpuy
• 1 -> Library debug output

_MY_DEBUG_ controls debug output of the application itself

• 0 -> No debug outpuy
• 1 -> Application debug output

_CFG_DEBUG_ controls the debug output of the nRF52 BSP. It is recommended to keep it off

Example for no debug output and maximum power savings:

[env:wiscore_rak4631]
platform = nordicnrf52
board = wiscore_rak4631
framework = arduino
build_flags = 
    ; -DCFG_DEBUG=2
    -DSW_VERSION_1=1 ; major version increase on API change / not backwards compatible
    -DSW_VERSION_2=0 ; minor version increase on API change / backward compatible
    -DSW_VERSION_3=0 ; patch version increase on bugfix, no affect on API
    -DLIB_DEBUG=0    ; 0 Disable LoRaWAN debug output
    -DAPI_DEBUG=0    ; 0 Disable WisBlock API debug output
    -DMY_DEBUG=0     ; 0 Disable application debug output
    -DNO_BLE_LED=1   ; 1 Disable blue LED as BLE notificator
lib_deps = 
    beegee-tokyo/SX126x-Arduino
    beegee-tokyo/WisBlock-API-V2
    sparkfun/SparkFun SHTC3 Humidity and Temperature Sensor Library
    adafruit/Adafruit LPS2X
    closedcube/ClosedCube OPT3001
    sabas1080/CayenneLPP
extra_scripts = pre:rename.py

Setup Weather

This guide can be used for WisBlock Kit 1 and RAK Developer Kit 2

Used Hardware

• WisBlock Core RAK4631
• WisBlock Base RAK5005-O, RAK19007 or RAK19001
• RAK1901
• RAK1902
• RAK1903

Installing the modules

Install the modules in any matching slot, following the Quick Start Guides in the RAKwireless Documentation Center

Firmware setup

Setup the device using the AT command interface or the BLE application

Setup GNSS

This guide can be used for WisBlock Kit 2, WisBlock Kit 3, WisBlock GNSS Tracker for LoRaWAN and RAK Developer Kit 3

Used Hardware

• WisBlock Core RAK4631
• WisBlock Base RAK5005-O, RAK19007, RAK19003 or RAK19001
• RAK1910 or RAK12500
• RAK1904
• RAK1906

Installing the modules

The RAK1904 module MUST be installed in
Slot C of RAK5005-O, RAK19007, RAK19003 or RAK19001

If using the RAK1910, it MUST be installed in
Slot A of RAK5005-O
any matching slot of RAK19007 or RAK19001

If using the RAK12500, it can be installed in any matching slot of the Base Boards.

The RAK1906 can be installed in any matching slot of the Base Board.

For installation guides, following the Quick Start Guides in the RAKwireless Documentation Center

Firmware setup

Setup the device using the AT command interface or the BLE application

RAK11700 GNSS Tracker for LoRaWAN is the default start mode for this setup.
If building the Helium Mapper Kit, the mode MUST be changed with the below AT command:

The solution can be set to 3 different working modes using the AT command AT+GNSS:

Using standard Cayenne LPP location resolution

The Cayenne LPP standard format uses only 4 digit for the location precision. This default location format is automatically supported by most LoRaWAN servers and Visualization platforms like MyDevices.
It is the default and is set with the AT command AT+GNSS=0.

Using improved location resolution

Setting this option, the data is still sent in Cayenne LPP format, but uses a custom data identifier and 6 digits for a higher latitude and longitude resolution. To decode this format a custom data encoder is required. Data encoders for TTN, Chirpstack and Datacake can be found in the Custom Data Decoder folder.
The enhanced location resolution is set with the AT command AT+GNSS=1.

Using the Helium Mapper data format.

This option sends the data in the Helium Mapper format, as explained in Make a Helium Mapper with the WisBlock.
Packet decoders for this format are provided in the above article.
The Helium Mapper functionality is set with the AT command AT+GNSS=2.

Setup Air Quality

This guide can be used for WisBlock Kit 4 and RAK Developer Kit 4

Used Hardware

• WisBlock Core RAK4631
• WisBlock Base RAK5005-O, RAK19007, RAK19003 or RAK19001
• RAK1906

Installing the modules

Install the modules in any matching slot, following the Quick Start Guides in the RAKwireless Documentation Center

Firmware setup

Setup the device using the AT command interface or the BLE application