This example is an approach to provide a quick start with RUI3 and WisBlock Sensor modules. With 6 5 simple steps you can build a sensor application and send data packets to a LoRaWAN server or over LoRa P2P.
This code is Work in progress and far from finished. But it can give a first start how to use RUI3.
 |
 |
 |
|---|
This repository has ready to use files for many WisBlock Modules. The main application main.cpp is designed to handle (most) of the different modules automatically. Enabled modules are included in the scheduled sensor readings and their data is added to the uplink payload automatically.
Only a few steps are required to add a module to the application.
The complete LoRaWAN communication is handled by RUI3, setup is done with WisToolBox or AT commands.
This is a generic description for the six steps required to build an application. See below an example for two WisBlock modules.
- Copy the
.cppfile for the required module(s) from the foldermodule-filesto the project folder.
The modules RAK1904, RAK1905, RAK12014, RAK12027 and RAK13011 have different GPIO assigments, depending on the Sensor Slot they are used in.
Please copy for these files in addition the matching xxxxx_S_Y.h files (Y is A to F and is the name of the slot used). Example:
If using RAK13011 in sensor slot C, copy beside of the RAK13011_switch.cpp as well the matching RAK13011_switch_S_C.h file.
-
Compile and flash the application to the WisBlock RAK4631-R, RAK3372 or WisDuo RAK4630, RAK3172
-
Setup the devices LoRa mode (LoRaWAN or LoRa P2P) and the required credentials with [WisToolBox](https://docs.rakwireless.com/Product-Categories/ Software-Tools/WisToolBox/Overview/) or with a terminal application and the RUI3 AT commands
-
In case of LoRaWAN, join the network from WisToolBox or with a terminal application and the RUI3 AT command
AT+JOIN=1:1 -
Check the uplinks on the LoRaWAN server
In this short tutorial an application is created for the WisBlock modules RAK1906 environment sensor and the RAK12019 UV light sensor.
Select the 2 files required in the module-files folder and copy them into the project folder:
The modules RAK1904, RAK1905, RAK12014, RAK12027 and RAK13011 have different GPIO assigments, depending on the Sensor Slot they are used in.
Please copy for these files in addition the matching xxxxx_S_Y.h files (Y is A to F and is the name of the slot used). Example:
If using RAK13011 in sensor slot C, copy beside of the RAK13011_switch.cpp as well the matching RAK13011_switch_S_D.h file.
Select the WisBlock Core or WisDuo module you want to run the application on and the COM port it is connected to. Then compile and upload the code.
 |
 |
 |
|---|
Open a terminal application and connect to the device. Reset the device and you can see the first output of the device with some debug messages. As you can see, it already shows that it found the two WisBlock modules:
To make it easier, the RUI3-Modular has a custom AT command to show some of the settings. Type ATC+STATUS=? (use ATC for custom commands) to see the status:
This device is already setup for LoRaWAN OTAA and has the proper DevEui, AppEUI and AppKey. The LoRaWAN region is as well set correct for my country to AS923-3.
If changes are required, they can be done with the RUI3 AT commands.
I assume here the device is already setup in a LoRaWAN server and a gateway is in range.
To join the LoRaWAN network send AT+JOIN=1 to the device and wait for it to join.
Once the device could successfully join the network, use another custom AT command to setup the automatic send interval for the uplink packets.
The custom AT command ATC+SENDINT=? shows the current interval, which is by default 0 seconds. Use ATC+SENDINT=30 to set the send interval to 30 seconds.
Now the device starts sending an uplink packet every 30 seconds:
In the LoRaWAN server check the incoming uplinks (here Chirpstack is used, but other LNS have similar outputs).
Here we can see the join request/accept and then the incoming uplink packets:
As the uplink packets are encoded in an extended Cayenne-LPP format (see Packet data format), it is easy to see the uplink data with one of the available packet decoders, e.g. the Chirpstack decoder
2-step-firmware-3.mp4
| Module | Function | Supported |
|---|---|---|
| RAK4631-R |
WisBlock Core module with RUI3 | ✔ |
| RAK3372 |
WisBlock Core module with RUI3 | ✔ |
| RAK19007 |
WisBlock Base board | ✔ |
| RAK19003 |
WisBlock Mini Base board | ✔ |
| RAK19001 |
WisBlock Fullsize Base board | ✔ |
| RAK1901 |
WisBlock Temperature and Humidty Sensor | ✔ |
| RAK1902 |
WisBlock Barometer Pressure Sensor | ✔ |
| RAK1903 |
WisBlock Ambient Light Sensor | ✔ |
| RAK1904 |
WisBlock Acceleration Sensor (used for GNSS solutions) | ✔ |
| RAK1905 |
WisBlock 9 DOF sensor | ✔ |
| RAK1906 |
WisBlock Environment Sensor | ✔ |
| WisBlock GNSS Sensor | Work in progress | |
| RAK1921 |
WisBlock OLED display | ✔ |
| RAK12002 |
WisBlock RTC module | ✔ |
| RAK12003 |
WisBlock FIR sensor | ✔ |
| WisBlock MQ2 Gas sensor | Work in progress | |
| WisBlock MG812 CO2 Gas sensor | Work in progress | |
| WisBlock MQ3 Alcohol Gas sensor | Work in progress | |
| RAK12010 |
WisBlock Ambient Light sensor | ✔ |
| RAK12014 |
WisBlock Laser ToF sensor | ✔ |
| RAK12019 |
WisBlock UV Light sensor | ✔ |
| WisBlock Gyroscope sensor | Work in progress | |
| RAK12027 |
WisBlock Seismic sensor | ✔ |
| WisBlock Soil Moisture and Temperature sensor | Work in progress | |
| RAK12037 |
WisBlock CO2 sensor | ✔ |
| RAK12039 |
WisBlock PM sensor | ✔ |
| RAK12040 |
WisBlock AMG8833 temperature array sensor | ✔ |
| RAK12047 |
WisBlock VOC sensor | ✔ |
| RAK12500 |
WisBlock GNSS Sensor | ✔ |
| WisBlock 3 button touch pad | Work in progress | |
| WisBlock LED bar display | Work in progress | |
| WisBlock Gesture sensor | Work in progress |
The modules RAK1904, RAK1905, RAK12014, RAK12027 and RAK13011 have different GPIO assigments, depending on the Sensor Slot they are used in.
Please copy for these files in addition the matching xxxxx_S_Y.h files (Y is A to F and is the name of the slot used). Example:
If using RAK13011 in sensor slot C, copy beside of the RAK13011_switch.cpp as well the matching RAK13011_switch_S_D.h file.
- ArduinoIDE
⤴️ - RAK-STM32-RUI
⤴️ - RAK-nRF52-RUI
⤴️
- CayenneLPP
⤴️ - ArduinoJson
⤴️
- RAKwireless RAK1901 Temperature and Humidity SHTC3 (manual from ZIP)
⤴️ - Adafruit LPS2X
⤴️ - ClosedCube OPT3001
⤴️ - Sparkfun LIS3DH
⤴️ - MPU9250
⤴️ - Adafruit BME680 Library
⤴️ - nRF52_OLED
⤴️ - Melopero RV3028
⤴️ - SparkFun MLX90632 Noncontact Infrared Temperature Sensor
⤴️ - RAKwireless VEML Light Sensor
⤴️ - Pololu VL53L0X
⤴️ - RAK12019_LTR390_UV_Light
⤴️ - RAK12027-D7S
⤴️ - SparkFun SCD30 Arduino Library
⤴️ - RAK12039-PMSA003I
⤴️ - Melopero AMG8833
⤴️ - Sensirion Core
⤴️ - Sensirion Gas Index Algorithm
⤴️ - Sensirion I2C SGP40
⤴️ - SparkFun u-blox GNSS Arduino Library
⤴️
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:
| Data | Channel # | Channel ID | Length | Comment | Required Module | Decoded Field Name |
|---|---|---|---|---|---|---|
| Battery value | 1 | 116 | 2 bytes | 0.01 V Unsigned MSB | RAK4631 | voltage_1 |
| Humidity | 2 | 104 | 1 bytes | in %RH | RAK1901 | humidity_2 |
| Temperature | 3 | 103 | 2 bytes | in °C | RAK1901 | temperature_3 |
| Barometric Pressure | 4 | 115 | 2 bytes | in hPa (mBar) | RAK1902 | barometer_4 |
| Illuminance | 5 | 101 | 2 bytes | 1 lux unsigned | RAK1903 | illuminance_5 |
| Humidity 2 | 6 | 104 | 1 bytes | in %RH | RAK1906 | humidity_6 |
| Temperature 2 | 7 | 103 | 2 bytes | in °C | RAK1906 | temperature_7 |
| Barometric Pressure 2 | 8 | 115 | 2 bytes | in hPa (mBar) | RAK1906 | barometer_8 |
| Gas Resistance 2 | 9 | 2 | 2 bytes | 0.01 signed (kOhm) | RAK1906 | analog_9 |
| GNSS stand. resolution | 10 | 136 | 9 bytes | 3 byte lon/lat 0.0001 °, 3 bytes alt 0.01 meter | RAK12500 | gps_10 |
| GNSS enhanced resolution | 10 | 137 | 11 bytes | 4 byte lon/lat 0.000001 °, 3 bytes alt 0.01 meter | RAK12500 | gps_10 |
| Soil Temperature | 11 | 103 | 2 bytes | in °C | RAK12023/RAK12035 | temperature_11 |
| Soil Humidity | 12 | 104 | 1 bytes | in %RH | RAK12023/RAK12035 | humidity_12 |
| Soil Humidity Raw | 13 | 2 | 2 bytes | 0.01 signed | RAK12023/RAK12035 | analog_in_13 |
| Soil Data Valid | 14 | 102 | 1 bytes | bool | RAK12023/RAK12035 | presence_14 |
| Illuminance 2 | 15 | 101 | 2 bytes | 1 lux unsigned | RAK12010 | illuminance_15 |
| VOC | 16 | 138 | 2 bytes | VOC index | RAK12047 | voc_16 |
| MQ2 Gas | 17 | 2 | 2 bytes | 0.01 signed | RAK12004 | analog_in_17 |
| MQ2 Gas Percentage | 18 | 120 | 1 bytes | 1-100% unsigned | RAK12004 | percentage_18 |
| MG812 Gas | 19 | 2 | 2 bytes | 0.01 signed | RAK12008 | analog_in_19 |
| MG812 Gas Percentage | 20 | 120 | 1 bytes | 1-100% unsigned | RAK12008 | percentage_20 |
| MQ3 Alcohol Gas | 21 | 2 | 2 bytes | 0.01 signed | RAK12009 | analog_in_21 |
| MQ3 Alcohol Gas Perc. | 22 | 120 | 1 bytes | 1-100% unsigned | RAK12009 | percentage_22 |
| ToF distance | 23 | 2 | 2 bytes | 0.01 signed | RAK12014 | analog_in_23 |
| ToF Data Valid | 24 | 102 | 1 bytes | bool | RAK12014 | presence_24 |
| Gyro triggered | 25 | 134 | 6 bytes | 2 bytes per axis, 0.01 °/s | RAK12025 | gyrometer_25 |
| Gesture detected | 26 | 0 | 1 byte | 1 byte with id of gesture | RAK14008 | digital_in_26 |
| LTR390 UVI value | 27 | 2 | 2 byte | 0.01 signed | RAK12019 | analog_in_27 |
| LTR390 UVS value | 28 | 101 | 2 bytes | 1 lux unsigned | RAK12019 | illuminance_28 |
| INA219 Current | 29 | 2 | 2 byte | 0.01 signed | RAK16000 | analog_29 |
| INA219 Voltage | 30 | 2 | 2 byte | 0.01 signed | RAK16000 | analog_30 |
| INA219 Power | 31 | 2 | 2 byte | 0.01 signed | RAK16000 | analog_31 |
| Touchpad left | 32 | 102 | 1 bytes | bool | RAK14002 | presence_32 |
| Touchpad middle | 33 | 102 | 1 bytes | bool | RAK14002 | presence_33 |
| Touchpad right | 34 | 102 | 1 bytes | bool | RAK14002 | presence_34 |
| SCD30 CO2 concentration | 35 | 125 | 2 bytes | 1 ppm unsigned | RAK12037 | concentration_35 |
| SCD30 temperature | 36 | 103 | 2 bytes | in °C | RAK12037 | temperature_36 |
| SCD30 humidity | 37 | 104 | 1 byte | in %RH | RAK12037 | humidity_37 |
| MLX90632 sensor temp | 38 | 103 | 2 bytes | in °C | RAK12003 | temperature_38 |
| MLX90632 object temp | 39 | 103 | 2 bytes | in °C | RAK12003 | temperature_39 |
| PM 1.0 value | 40 | 103 | 2 bytes | in ug/m3 | RAK12003 | voc_40 |
| PM 2.5 value | 41 | 103 | 2 bytes | in ug/m3 | RAK12003 | voc_41 |
| PM 10 value | 42 | 103 | 2 bytes | in ug/m3 | RAK12003 | voc_42 |
| Earthquake event | 43 | 102 | 1 byte | bool | RAK12027 | presence_43 |
| Earthquake SI value | 44 | 2 | 2 bytes | analog 10 * m/s | RAK12027 | analog_44 |
| Earthquake PGA value | 45 | 2 | 2 bytes | analog 10 * m/s2 | RAK12027 | analog_45 |
| Earthquake SHUTOFF alert | 46 | 102 | 1 byte | bool | RAK12027 | presence_46 |
| Earthquake collapse alert | 47 | 102 | 1 byte | bool | RAK12027 | presence_47 |
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 decoders
This list is constantly extended as we add new WisBlock modules. Check out the RAKwireless Standardized Payload repo for the latest status.
The setup of the device (LoRaWAN region, DevEUI, AppEUI, AppKey, ....) can be done with AT commands over the USB port or with WisToolBox
Example AT commands:
AT+NWM=1
AT+NJM=1
AT+BAND=10
AT+DEVEUI=1000000000000001
AT+APPEUI=AB00AB00AB00AB00
AT+APPKEY=AB00AB00AB00AB00AB00AB00AB00AB00
ATC+SENDINT=600
| Command | Explanation |
|---|---|
| AT+NWM=1 | set the node into LoRaWAN mode |
| AT+NJM=1 | set network join method to OTAA |
| AT+BAND=10 | set LPWAN region (here AS923-3) see AT Command Manual |
| AT+DEVEUI=1000000000000001 | set the device EUI, best to use the DevEUI that is printed on the label of your WisBlock Core module |
| AT+APPEUI=AB00AB00AB00AB00 | set the application EUI, required on the LoRaWAN server |
| AT+APPKEY=AB00AB00AB00AB00AB00AB00AB00AB00 | |
| ATC+SENDINT=600 | set the interval the sensor node will send data packets. 600 == 10 x 60 seconds == 10minutes |
The manual for all AT commands can be found here: AT-Command Manual
There are additional custom AT commands implemented:
ATC+STATUS to get the current status of the device.
Example:
atc+status=?
Device Status:
Module: RAK4630
Version: RUI_3.5.2b_175_RAK4631
Send time: 120 s
Network mode LoRaWAN
Network joined
Region: 10
Region: AS923-3
OTAA mode
DevEUI = AC1F09FFFE057110
AppEUI = AC1F09FFFE057110
AppKey = 2B84E0B09B68E5CB42176FE753DCEE79
+EVT:RAK1901 OK
+EVT:RAK1902 OK
+EVT:RAK1903 OK
+EVT:RAK12019 OK
OK
ATC+SENDINT to get and set the automatic send interval
Example:
atc+sendfreq=?
ATC+SENDINT=120s
OK
atc+sendfreq=120
OK
If an RAK12002 RTC module is used, the command ATC+RTC is available to get and set the date time
Example:
atc+rtc=?
ATC+RTC=2000.01.01 0:00:21
atc+rtc=2022:10:21:14:15
OK
atc+rtc=?
ATC+RTC=2022.10.21 14:15:25
If an RAK12500 GNSS module is used, the command ATC+GNSS is available to change GNSS precision and payload format.
It accepts 4 different values:
0 = 4digit prec., 1 = 6digit prec, 2 = Helium Mapper format, 3 = Field Tester format
Example:
atc+gnss=?
GNSS 4 digit Cayenne LPP
atc+gnss=1
OK
```log
atc+gnss=?
GNSS 6 digit extended Cayenne LPP