/RAK4631-Helium-Mapper

Example code for a LPWAN tracker based on the RAK WisBlock products

Primary LanguageC++
RAKstar WisBlock

RAK4631 LoRaWan® Helium Mapper RAKwireless

Based extensively on: beegee-tokyo/RAK4631-LPWAN-Tracker

This module provides data that can be fed into the Helium Cargo app and / or the Helium Coverage Mapper.

It gets location information from an attached uBlox GPS module and sends that data via LoRaWAN to the Helium Console. In addition an acceleration sensor is used to detect if the tracker is moving. If movement of the tracker is detected, location information is sent immediately. If the tracker is stationary, the location data is sent every 1 minute

Solution

This solution shows

  • how to initiate a LoRaWan connection with OTAA network join on the WisCore RAK4631
  • how to initiate BLE with on the WisCore RAK4631
    • BLE UART characteristic for debug output. Requires a BLE-UART app like the Serial Bluetooth Terminal for Android
    • BLE OTA DFU for firmware updates
  • how to use the WisSensor RAK1910 GPS module to aquire location information
  • how to use the WisSensor RAK1904 acceleration sensor to detect movements
  • how to read the battery level from the WisCore RAK5005-O board
  • how to convert the sensor values into a byte array to create the smallest possible LoRa package size

Hardware required

To build this solution the following hardware is required

Total Cost: $96.11

Software required

To build this solution the following is required

Setting Up your WisBlock core on PlatformIO

PlatformIO is a great platform for developing embedded systems. Here are the instructions for getting Rak WisBlocks set up on PlatformIO. Be aware that this project is based on the 2021 firmware (probably newer than what came on your WisBlock Core. To upgrade the firmware, follow the instructions here.

LoRaWan server required

In order to get this code working you need access to the Helium Network. Getting access to Helium is quite simple and there is a good tutorial at Getting WisBlock by RAKwireless Up and Running on The People’s Network.

The region you live in defines the frequency your LoRaWan® gateways will use. So you need to setup your device to work on the correct frequency.

With the new LoRaWAN® library SX126x-Arduino V2.0.0 the region is set as a parameter in lmh_init().

In the call lmh_init() the last parameter defines the LoRaWAN® region.

Short explanation about the new lmh_init() call:

/**@brief Lora Initialisation
 *
 * @param callbacks   Pointer to structure containing the callback functions
 * @param lora_param  Pointer to structure containing the parameters
 * @param otaa        Choose OTAA (true) or ABP (false) activation
 * @param nodeClass   Choose node class CLASS_A, CLASS_B or CLASS_C, default to CLASS_A
 * @param region      Choose LoRaWAN region to set correct region parameters, defaults to EU868
 *
 * @retval error status
 */
	lmh_error_status lmh_init(lmh_callback_t *callbacks, lmh_param_t lora_param, bool otaa, 
	                          eDeviceClass nodeClass = CLASS_A, 
	                          LoRaMacRegion_t region = LORAMAC_REGION_EU868);

The first three parameters are the same as before. Two new parameters have been added.

eDeviceClass nodeClass

Even this parameter was defined in V1.x, the lmh_init() ignored it and initialized the node ALWAYS as a node Class A.
Now you can explicit set your node to CLASS_A or CLASS_C. Please take note that CLASS_B is still not supported by the library.

LoRaMacRegion_t region

This parameter selects the LoRaWAN region for your application. Allowed values for the region are:

  • LORAMAC_REGION_AS923
  • LORAMAC_REGION_AU915
  • LORAMAC_REGION_CN470
  • LORAMAC_REGION_CN779
  • LORAMAC_REGION_EU433
  • LORAMAC_REGION_EU868
  • LORAMAC_REGION_IN865
  • LORAMAC_REGION_KR920
  • LORAMAC_REGION_US915 --Default--
  • LORAMAC_REGION_US915_HYBRID

Some explanation for the code

Due to the complexity of the code, it is split into functional parts.

  • main.h
    • All the includes, global definitions and forward declarations for the app
  • main.cpp
    • Setup function where we initialize all peripherals
    • Main loop
    • Timers callback functions for periodic and delayed sending of packages
  • acc.cpp
    • Accelerometer initialization, interrupt callback function and interrupt clearing functions
  • bat.cpp
    • Battery level functions
  • ble.cpp
    • BLE initialization and BLE UART callback functions
  • display.cpp
    • Display initialization and handling functions
  • gps.cpp
    • GPS initialization and and data poll functions
  • loraHandler.cpp
    • LoRaWan initialization function, LoRaWan handling task and LoRaWan event callbacks
  • include/config.cpp.example
    • This is a sample config file. Copy it to include/config.cpp and configure to match your Helium settings.

How to achieve power saving with nRF52 cores on Arduino IDE

Within the nRF52 Arduino framework is no specific function to send the MCU into sleep mode. The MCU will go into sleep mode when

  • all running tasks are calling delay()
  • the running tasks are waiting for a semaphore

In this example you use the semaphore method.

Two tasks are running independently, the loop() task and the loraTask() task which is started by the SX126x-Arduino library and runs in the background. A semaphores are used to control the activity of the loop() tasks.

/** Semaphore to wake up the main loop */
SemaphoreHandle_t loopEnable;

After setup and starting the LoRaWan join process, the semaphore loopEnable is taken.
This means the loop task will go into waiting mode while the loraTask is handling LoRaWan events in the background. The LoRaWan task is in sleep mode until a LoRa event occurs.
At this point no more task is active and the device will go into sleep mode.

Events to wake up the MCU

  1. Accelerometer detect movement If the ACC sensor detects movement, the MCU receives an interrupt. In the interrupt callback the semaphore loopEnable is given again, which allows the loop task to run.
  2. Timer event If the periodic sending timer is triggered, the MCU will wake up and the callback function of the timer will give the semaphore loopEnable, which allows the loop task to run.

Once the loop task is enabled, it will poll the position from the GPS module and requests sending a data package by calling sendLoRaFrame(). Then it takes the semaphore loopEnable, which puts herself back into waiting mode until the next event.

LoRa® is a registered trademark or service mark of Semtech Corporation or its affiliates. LoRaWAN® is a licensed mark.