Mappers Quickstart

This guide will show you step by step how to contribute data to the Mappers project with an off-the-shelf tracker. This guide will use the Dragino LGT92, but any LoRaWAN compatible tracker will work.

Steps

  1. Add device to Console.
  2. Create new Label and HTTP integration with Mappers API ingest endpoint.
  3. Create Function Decoder to decode device payload and attach to Label created in first step.
  4. Attach Label to tracking device and verify data is being sent successfully.

1. Add Device to Console

To start, you'll need to add your device to Console. You should have been provided with a DevEUI, AppEUI, and AppKey from the seller of the device. Follow our quickstart for instructions on how to add a new device to Console.

2. Create HTTP Integration

To start, we'll create a new HTTP integration in Console. Navigate to the Integrations page using the left navigation and then select the HTTP integration.

Next we'll fill in the details, see instructions and image below.

  1. Enter the Mappers API Ingest endpoint https://mappers.helium.wtf/api/v1/ingest
  2. Enter the name for this Integration: Mappers Integration
  3. Create and apply a Label for this Integration, we've used the same name as the integration.
  4. Finally, click Create Integration to complete.

3. Create Function Decoder

Next, we'll be creating a Function decoder to decode the payload from the device and properly format it for the API endpoint. The decoder is specific to the encoding scheme used to encode the data before the device transmits it. For off-the-shelf devices this is usually manufacturer specific. For development devices, CayenneLPP if often used. For this guide we'll be using a decoder specifically made for this tracking device and slightly modifying it by adding two additional required fields. The original decoder can be found from the manufacturer's website here.

To start, navigate to the Functions page using the left navigation and then click Create New Function.

  1. Enter a name for the decoder (below we've used Dragino LGT92 Decoder), select the type of Function, Decoder in this case, and finally select Custom Script from the drop down.

  2. Copy and paste the complete decoder function provided by the manufacturer found here or below.

    function Decoder(bytes, port) {
     return {
       // GPS coordinates; signed 32 bits integer, MSB; unit: °
       // When power is low (<2.84v), GPS won’t be able to get location
       // info and GPS feature will be disabled and the location field
       // will be filled with 0x0FFFFFFF, 0x0FFFFFFF. 
     
       Latitude: 
         (bytes[0]<<24 | bytes[1]<<16 | bytes[2]<<8 | bytes[3]) / 1000000,
       
       Longitude:
         (bytes[4]<<24 | bytes[5]<<16 | bytes[6]<<8 | bytes[7]) / 1000000,
    
       // Alarm status: boolean
       ALARM_status: (bytes[8] & 0x40) > 0,
    
       // Battery; 14 bits; unit: V
       BatV: ((bytes[8] & 0x3f)<<8 | bytes[9]) / 1000,
    
       // Motion detection mode; 2 bits
       MD: {
         "0": "Disable",
         "1": "Move",
         "2": "Collide",
         "3": "Custom"
       }[bytes[10]>>6],
    
       // LED status for position, uplink and downlink; 1 bit
       LON: (bytes[10] & 0x20) ? "ON" : "OFF",
    
       // Firmware version; 5 bits 
       FW:150+(bytes[10] & 0x1f),
    
       // Roll; signed 16 bits integer, MSB; unit: °
    
       // Sign-extend to 32 bits to support negative values: shift 16 bytes
    
       // too far to the left, followed by sign-propagating right shift
    
       Roll: (bytes[11]<<24>>16 | bytes[12]) / 100,
    
       // Pitch: signed 16 bits integer, MSB, unit: °
    
       Pitch: (bytes[13]<<24>>16 | bytes[14]) / 100,
     };
    }
    

    Next we need to add two more fields that are required by the Mappers API but missing from the function. You'll see these at the bottom of the editor window in the screen shot below. Altitude is permanently set to zero because this device does not output altitude and we will assume that the tracker will be used at ground level. Accuracy is set to three meters since this device does not output a measure of accuracy and this is a reasonable measure of precision to be expected for this device. Find more details on the API specification here.

  3. Next search for and add the Mappers Integration label we created with the integration.

  4. Finally save your function.

4. Attach Label to Device

Next we'll attach the Mappers Integration label to the device. Navigate to your device page and click the Add Label button shown below.

Search for the Mappers Integration label and click Add Label as shown below.

You are now ready to power on your device and verify that data is being sent correctly to the Mapper API. To do this just expand an uplink event in the event log and verify that you are getting a "Success" message for the integration as shown below.

That's all! You can now expect to see your data show up on mappers.helium.com in eight hours or less. The map data is updated every six hours starting at 04:20 UTC.