TTGO T-Beam Helium Mapper

Hello!

This is a project that maps hotspot info & sends to the helium server using the TTGO T-Beam rev 1.1. It is delivering data to mappers.helium.com and cargo.helium.com using the Helium API. This project took a lot of playing around and most of the core code was taken from several sources noted below.

Intro

I looked at all the existing mappers out there and what it would take for me to build one with gps and lora. It would have been a good amount of work. So I decided to go with the TTGO T-Beam that has wifi, bluetooth, and a integrated 18650 battery holder. Running a ESP32 (ESP32 DOWD-Q6), it has a ublox Neo 6 GPS module, a SX1276 lora wireless module, and a TP5400 charge controller. Perfect for what I need. The specific version is the rev 1.1 which I believe is the newest.

The main purpose I wanted to make a mapper was to record signal strength and range of my own Helium Hotspot, a Sensecap M1. It helped a lot with my antenna placement. I was able to make a adjustment and actually get data on the change.

I browsed around the internet and found a couple programs that use TTN (The Things Network). I tried these & I couldn't get them to work with the T-Beam rev 1.1. This is a modified version that supports it and I added a option for OTA upgrade, "airplane" mode, & transmit interval. I used the 2.8dbi antenna that I used to had on my Sensecap M1 centered at 915mhz.

There are two parts to the program. The Arduino program runs on the T-Beam and the decoder file gets put in the Helium console to, you guessed it, decode the payload.

Setup - Physical Assembly

Case: The case I printed it using.18 layer height and extra enforcement(in slicing) is recommended for the two screws to attach the front to the back case.

Screws: You need the following:

• 2x 16mm M2 screws (Close case)
• 8x 4mm M2 screws (mount the board)
• 4x 10mm M2 Standoffs (mount the board)

Screen: The screen I used is a 1.3" SH1106 OLED display. That is what the case is designed for. You need to make a "S" shaped pin spacer for the pins to align right. Make sure the pinout for the screen is correct (VCC, GND, SCL, SDA). A lot of SH/SSD screens are GND first, not VCC. I made it using a very small piece of breadboard. Just 2x4 pins. One set of 4 pins goes up to the display, the other goes down into the board headers. See picture. Sorry it is so crude looking; not my best soldering but it works. It is held in place by pressure from the case. I'm working on changing that.

When you plus it in, make sure you get the pins in the right positions. It plugs into the VCC, GND, SDA, SCL pins. Don't worry about SDA/SCL being flipped around. We fix that in our call to Wire.begin() in setup.

Setup - Helium Console

• There is some data we have to enter into the program before we upload. The AppEUI, DeviceEUI, and App Key. These are all pulled form the Helium console.
• Navigate your browser to console.helium.com & Create a login*. When it asks you for a Organization name, just put NA or something you would name your company. I went with KritchCo. You will see this upon successful login:

• We need to add our device to the Helium network. First click Profiles, when that loads, hit the + sign.
• Type in your profile name, I'd recommend something easy with profile at the end. Make sure both options are not enabled. Then hit Create Profile.

• It now brings you back to the profile page. Select Devices on the left.
• On the device page, select the button to add a device. Like like this ((+)) in the window menu.
• Now on the add device page, put in your device name(can be whatever you want), leave the Device EUI and App EUI along. Towards the bottom select your profile you just created under the profile dropdown.
• In the label section, out in a label of your choosing, kit it simple so you know what's a label and what's a profile in the future. I went with HacksterProfile.

• Now hit Save Device. it should look something like the picture below with your device added:

• Notice the arrows, when your device is integrated in the blockchain those labels (Pending) will dissappear.
• Now click on Functions on the left menu. Click the (+) sign in the page that loads.

• Enter in a name for the decoder. Next dropdown select the only option, Decoder. On the last dropdown select Custom Script.
• Now we need to tell it how to decode our payload. Copy & paste the decoder file contents in the Step 2 - Enter Custom Script field.
• Your screen should look like the pic below. Hit Save Function in the lower right.

• It will then bring you to the Functions page with your function there.
• Now lets go to the Integrations menu. On the page that loads, in the top menu select the + sign that looks like a cloud. Then select HTTP under the Add A Custom Integration. End in the following info:
• Endpoint URL:

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

• HTTP Headers:

Content-Type, application/json

• Now name you integration & hit Add Integration. It should look like this:

• On the page that loads it should say "Success" on the top for a moment. Now turn on the Receive Device Joins option and then save changes at the bottom of the page.

• Now the last part. We need to make them talk to one another. We do that in the Flows page. Select it. The page that loads will be blank except for a floating menu the says NODES. Select it.

• A drop down menu appears with our labels, devices, functions, and integrations. Yours won't have the first two entries, just the one you created.

• Now, drag your label we created to the workspace toward the left side. Like in this video:

• Next click on the Functions tab. Drag you function after your label you just dragged so its on the right, Then again under the Integrations tab with you integration to the right of your function. (see below video)
• Now you need to connect them so they communicate. Starting on the left with your label you created, click and drag from the little dot on the right hand side of the label. Drag it to the left dot on the function so it connects. Do that again with the right dot on the function and connect to your last rectangle, you integration. See video:

• The lines are solid right now between the rectangles. They will change to moving lines once our device is online.

Setup - Arduino Sketch

• Plug in your T-Beam to a USB port on the computer.
• Update Arduino IDE (1.8.16) to the newest if you are not running it already.
• Open your Arduino IDE & open the downloaded sketch titled main.ino along with the other files. Keep them together. Available thru GitHub also.
• Make sure you have the ESP32 platform installed. If you don't have the ESP32 boards installed, here is a great guide on how to do that: How to install ESP32 Boards
• Now under the tools menu, for board, select under the ESP32 Arduino submenu, the T-Beam. Tools -> Board -> ESP32 Arduino -> T-Beam
• Under tools again, Set upload speed to 921600(If you have problems uploading, try lowering this), Flash Frequency set to 80mhz, Core Debug set to none, PSRAM set to enabled, and lastly select your port your board is plugged into. I'm on a Mac so its a gibberish linux style name. On PC it will be COM13 or a similar number.

Setup - Add Helium Keys

• Open the main.ino sketch you downloaded. It will open several other tabs/files with the main.ino file. Click on the configuration.h tab and scroll down to the OTAA keys section. This is where we put in our keys.
• While still in the console, select Devices on the left. Now select your device by clicking on the name.
• That will pull up a page similar to this one:

• The info we need is under device details. The DevEUI & AppEUI needs to be in little-endian format (lsb first). Click on the arrows to the right of the Device EUI. That gets us its hexadecimal value which is what the Arduino program needs. Its still not right though. Click on the opposing arrow icon to the right of what you just pressed to expand the EUI. That switches it to lsb format.
• Copy the Device EUI and past it in the Arduino program in the DEVEUI line between the brackets. Follow the same process for APP EUI.
• For the App Key, you want it in big-endian format (msb first). Click on the privacy (eye) icon to the right of App Key. Then follow the process we just did for the DevEUI and APPEUI but make sure this key is in msb format, not lsb. Paste it in our sketch in the APPKEY brackets.
• Now compile & upload your program. It will take 20-30 seconds to compile and upload roughly for most.

To change screen types, uncomment #define SHLCD in configuration.h for a SH 1.3" type which is what the case uses. Important note: For the display to fit the case, you need to make a kinda "s"

Upon a successful upload, your T-Beam will restart and you should see the Helium logo briefly and then it will begin searching for Satellites. If it errors out when compiling, check to make sure your keys are within the brackets and that you have the right board/options selected.

Once the board is running and getting the GPS lock, initialize the device keys by pressing the Action button (see below) 10 times. It will then say "Initialized keys" and reboot.

Thats It! Have fun mapping!

Checkout your mapping efforts at: mappers.helium.com

Using the Mapper

Here is the button mapping from left to right from a front view:

1: Power On/Off - hold 8 seconds to toggle

2: Action - press number of times within 5 seconds:

• 1 press - Low Power mode (useful for charging)
• 2 presses - Polling Speed (cycles between 15, 30, 60 seconds)
• 3 presses - Enable OTA mode
• 10 presses - Erase Keys

3: Reset

OTA mode is used for wireless uploads. It will create a hotspot named helium with password open4meplease. Connect to it and the IP address is 192.168.4.1 to upload to.

Using Helium Console

To see if your device is successfully integrated and sending valid data, navigate in your browser to : console.helium.com & login.

On the left side menu, select devices and then the name of your device you created earlier. You will see your devices listed. Check on the right hand side under "Last Connected" and see if you have a date/time:

*** It might take up to 20min to integrate so be patient and don't reset your keys!

On the page scrolling down, look at your event log at the bottom. It should look similar to this & be reporting events on every transmit:

The blue dot on the graph is showing the rssi of the hotspot that accepted the info. If it is yellow, that means your transmission is being received but for some reason it wasn't able to integrate into mappers.helium.com. Check that you copied your decoder and keys correctly and in flows you are connected. If red, check your flows.

If you expand on the of the uplink messages it will give you the hotspot or hotspots info.

If you notice inconsistent data, like dots missing or long durations between received transmissions, remember, your data only gets to the server if the hotspot receiving the data is setup correctly which isn't always the case I've noticed.

*When creating a login, I'm not sure if you are able to without being a hotspot owner. I think you can but you just won't get the 10k data credits for free. You will have to buy some. They are super cheap.