Building a Helium Mapper / LoRa GPS Tracker

The Mappers Coverage map is a crowd-sourced effort to build a true-signal coverage map of the Helium network across the globe. By mapping real-world coverage, network users can understand where sensor deployments are likely to have success connecting to Helium.

In order to place a mark on the map, the mapper device sends out a signal with a GPS location encoded. If a Helium Hotspot ‘hears’ that signal, data is passed through the internet and recorded in the Mappers database. The Mappers database uses the GPS information from the Mapper to ‘light up’ the hex on the map. Please refer to Helium Mapper Documentation for more information.

This tutorial shows how to DIY a low cost mapper device based on the Cytron Helium Mapper Kit. Basically these are the things that we need to setup:

1. Setup the Helium Console.
2. Wire up the Cytron Helium Mapper Kit.
3. Configure and download the firmware into the Maker Nano RP2040 (The main controller of the mapper device).
4. Start mapping.

1. Setting Up Helium Console

To use the Helium LoRaWAN network, first we need to register a new account at Helium Console. Every new account comes with free 10, 000 Data Credits which is enough to last for some time (The latest Helium Console only give you 250 DC upon signing up. You will need to answer a survey to claim up to 10, 000 DC.)

After you've created your account and logged in, you will see this page. The top right corner shows the Data Credits balance in your account.

There are four things that we need to setup here:
1. Add a new device.
2. Setup the custom function.
3. Setup the integration.
4. Enable multiple packets.
5. Setup the flow.

Add New Device

This is where we add our Helium mapper. If we have multiple mappers or other LoRaWAN sensors, we need to add them here.

1. Click on "Devices" on the left panel to navigate to the devices page. Then, click the "Add New Device" button.

2. Give your device a nice name and click "Save Device". You may leave the other information as it is for now.

3. You will see your newly added device in the list and there will be a "Pending" next to it. Please do not worry as Helium will take up to 20 minutes to add your new device to the block chain. Before that, you will not be able to use your new device yet.

Setup Custom Function

The data received from the Helium Mapper is in binary format and we need to decode it (We need to know which bytes represent latitude, which bytes are longitude, etc) before we send the information to the Mapper server. We need to setup a custom function to do the job.

1. Click on "Functions" on the left panel to navigate to the functions page. Then, click the "Add New Function" button.

2. Give the new function a name, select "Decoder" as the function type and choose "Custom Script" as the format.

3. Copy the java script below and paste it as the custom script. Click "Save Function" button when done.

function Decoder(bytes, port) {
    // Decode an uplink message from a buffer
    // (array) of bytes to an object of fields.
    var latitude = (bytes[0]<<24 | bytes[1]<<16 | bytes[2]<<8 | bytes[3]) / 1E7;
    var longitude = (bytes[4]<<24 | bytes[5]<<16 | bytes[6]<<8 | bytes[7]) / 1E7;
    var altitude = (bytes[8]<<24>>16 | bytes[9]) / 100;
    
    return {
        latitude: latitude,
        longitude: longitude,
        altitude: Math.round(altitude),
        accuracy: 3,
    }
}

Setup Integration

After we've decoded the data from the mapper, we need to send it to the Helium Mapper server to show it on the map. Here we will setup the integration to forward the data to the mapper server. If you have other type of sensor data and you wish to show it on ThingSpeak or adafruit.io, you can set it up here too.

1. Click on "Integrations" on the left panel, then click the "Add New Integration" button and select the "HTTP" Integration.

2. Copy the following URL as the Mappers API Ingest Endpoint URL:

https://mappers.helium.com/api/v1/ingest/uplink

Give it a nice name and click "Add Integration".

3. You can add the "Helium Cargo" integration as well. It allows you to visualize your exact location in real time.

4. Just click "I AGREE", give it a name and then click on "Add Integration".

Enable Multiple Packets

Usually when your mapper device sends out a packet, multiple hotspots might be able to receive your packet. By default, Helium network server will only forward one of the packets to the mapper server and the mapper page will only show that the packet is received by one hotspot.

For this case, we can enable the multiple packets and the Helium network server will forward every single packet received by different hotspots to the mapper server. However, we will need to pay for the extra packets as well in Data Credits.

1. Click on "Multiple Packets" on the left panel and then click the "Add New Multiple Packets Config" button.

2. Enter "All Packets" as the name, slide the slider to the right most (All Available Packets) and click the "Create Multiple Packets Config" button.

Setup Flow

This is where we connected our devices, decoder and integration together.

1. Click on "Flows" on the left panel and then click the "+" button beside the NODES to add a new node.

2. Click on "Devices" and drag your device into the empty flow panel.

3. Click on "Functions" and drag the GPS Decoder function into the flow panel.

4. Click on "Integrations" and drag the Cargo and Mappers integrations into the flow panel.

5. Connect the nodes together as follow.

6. Click on the device node, then click the "Packets" tab under the settings panel and enable multiple packets for this device.

2. Wire Up the Cytron Helium Mapper Kit

The Cytron Helium Mapper Kit consists of the following components:1. Maker Nano RP20402. Grove Shield for Arduino Nano3. Grove E5 LoRaWAN Module4. GY-NEO6MV2 GPS Module5. Grove to Female Headers Extension Cable6. Grove to Grove Extension Cable7. Male Pin Headers

You might also need a USB Micro B Cable to power up the mapper or modify the settings.

1. Make sure the VCC switch on the Grove Shield for Arduino Nano is at 3V3 position. Then stack the Maker Nano RP2040 onto the shield.

2. Use the Grove to Grove extension cable to connect the E5 LoRaWAN module to port "UART" on the Grove shield.

3. The pin headers on the GPS module doesn't come pre-soldered. We will need to solder it first.

4. Connect the GPS antenna. It's quite tight and you might need to push harder until it snaps in.

5. Connect the Grove to female headers extension cable to the GPS module. Make sure the sequence is correct:
VCC - Red
RX - Yellow
TX - White
GND - Black

* If you are not using the Arduino Nano Grove Shield, please check the connection is correct (GPS TX connect to Host Rx and vice versa).
* You need to swap the yellow and white cable if you are using Maker Pi RP2040 or Maker Pi Pico.

6. Connect the GPS module to port "D4" on the Grove Shield.

7. Connect the Micro USB cable to the Maker Nano RP2040 to power it up.

3. Setting Up the Firmware

We use CircuitPython in this example of Helium Mapper. The first thing we need to do is to make sure the Maker Nano RP2040 is running the latest version of CircuitPython Firmware.

1. Download the latest stable release of CircuitPython firmware from here.

2. While pressing the BOOT button, connect the USB cable from the computer to the Maker Nano RP2040. Alternatively, you may press and release the RESET button while holding down the BOOT button. A new drive named "RPI-RP2" should appear on your computer.

3. Copy the CircuitPython firmware you just downloaded into this drive.

4. After finish copying, the board should reboot with a new drive "CIRCUITPY". Now you have updated the CircuitPython firmware successfully.

5. Download the examples from:
https://github.com/CytronTechnologies/MAKER-NANO-RP2040
Then, copy all the files in folder "Examples/CircuitPython/HeliumMapper/" to the root directory of "CIRCUITPY" drive (code.py already exists there. We need to overwrite it).

6. Edit the "helium_config.py" file with any text editor (eg: notepad). Make sure the region is set according to your LoRaWAN region.

# Helium Configuration

helium_config = {
    "region" : "AS923", # EU868, US915, AU915, AS923, KR920, IN865...etc
    "deveui" : "XXXXXXXXXXXXXXXX",
    "appeui" : "XXXXXXXXXXXXXXXX",
    "appkey" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

7. Login to the Helium Console again. Click "Devices" on the left panel and then click on the device you have just added before this.

8. Copy the Device EUI, APP EUI and App Key and replace the value in "helium_config.py". If the App Key is hidden, you can click the eye icon beside it to unhide.

# Helium Configuration

helium_config = {
    "region" : "AS923", # EU868, US915, AU915, AS923, KR920, IN865...etc
    "deveui" : "D09BD9C058CF3171",
    "appeui" : "5A5611A2E5B8C51F",
    "appkey" : "0B85DB4F2A5EBFFCE1642CF811CB14AF"
}

9. Save the "helium_config.py", reset the board and start mapping.

4. Start Mapping

We can start mapping by powering up the mapper and put it into your car. Basically the program flow of the mapper is as follow.

The RGB LEDs (Neopixels) on the Maker Nano RP2040 represents the state of the GPS and the LoRaWAN E5 module.

RGB LED 0 - GPS

Blinking Blue - No GPS Fix.Blinking Green - GPS Fix obtained.

RGB LED 1 - LoRaWAN E5 Module

White - Initializing E5 module.
Red - Initialization failed.
Yellow - Joining Helium Network.
Blue - Sending data.

The mapper is programmed to be sending its coordinate at certain interval which is dependent on the travelling speed of the mapper.

Below 30km/h : Transmit every 60 seconds
30km/h - 60km/h : Transmit every 20 seconds
Above 60km/h : Transmit every 10 seconds

To be sure the data is received, you can login to the console again and go to the device page. You can check the activities under your device page.

And finally, you may enjoy seeing the HEX on the Helium Mappers page turning green one by one. You can click on each HEX to see which hotspots actually received the signal from the mapper.

You may also go to the Helium Cargo page, search for your mapper name and check out your mapper location in real time.