Heltec Lora CubeCell Fun – Part 2

In Part-1 of this post I explored my attempt to get a LoRa gateway (RAK Wireless 2247) and end node (Heltec LoRa CubeCell) connected to TheThingsNetwork (TTN). After two days of deep  ‘funstration’ , I was about to give up. But ‘Ole Sopwith NEVER gives up. Up, over, or around – this experiment was going to work.

Many Makers at this point would strongly believe they were sold bum hardware. You know the drill, “When in doubt – blame the hardware.”  I do not subscribe to this theory. In all my years of Making, I cannot recall the last time I was shipped a Maker device that was DOA. Yes, it happens, but it is very, very, very rare. The QC in modern factories is excellent, and if something does not work out of the box, I blame the hardware last.

My problem was how to tell if the CubeCell connection problem was the CubeCell or the gateway – or both.

I spent a lot of time messing around with the devEui, appEui, and appKey arrays. Lots of documentation and videos suggest if your device does not connect, you should reverse the array entries to account for endian differences in the transport layer.

In fact, the TTN configuration page has a handy reversing capability that makes copying the entries in either order. Changing the endian order did not fix the issue.

As i continued to review the source code of the Heltec SendReceive.ino example app, I saw this code in the Setup() function:

Hmmm, I wonder what that does? I am in the US, not AU, but both countries use sub-bands of the 915 MHz LoRa band. Digging deeper in the source code files, I found the setSubBand2 function.

Now this was really interesting. All the function does is change the first element in the userChannelsMask array.  I was wondering what that array was for…

You can see in the above code snippet, the first element in the userChannelsMask is set to 0x00FF. The setSubBand2 function changes the first entry to 0xFF00 if the active region is AU.

Just for fun, I changed the first element in the array to 0xFF00 and uploaded the change to the device. Within 1 second, the CubeCell connected and joined to the TNN network. Whoah!

I guess at this point, most folks would jump up and do a victory dance and move on in their project. Not me!. I had to know all the gory details of why this small change in the code made everything start working.

In digging deeper, I came across this hard-to-find Heltec doc. After reading this, I began to understand what is going on here.

When I configured the gateway on TTN, I had to choose a LoRa sub-band:

I did not know which band to choose. And as you can see from the highlighted item above, FSB-2 is used by TTN. Ummm… Ok… Does that mean I should select it because my gateway will be using TTN? Or.. Does that mean I should NOT select it because it is already used by TTN?

And what is this sub-band stuff anyway? Heltec provides a nice list of the LoRa band plans used around the world. In the US and AU, the LoRa band is broken out into sub-bands. In the US, the LoRa frequencies vary between 902 and 915 MHz.

This fine web page charts the below list of the US sub-bands:

Ok- now I get it. TTN has decided to use the US Sub-Band-2 for all US devices. This requires your gateway AND device to use frequencies 903.9 – 905.3 MHz.

Configuring my RAK 2247 gateway was done by the RAK install scripts. When I selected the US region, it configures the system for Sub-Band 2. The only thing I had to do was select FSB-2 on the TTN gateway configuration page and it all worked.

Configuring the CubeCell sub-band is tricky. In the source code, it uses the six-element uint16_t array as a mask.

uint16_t userChannelsMask[6]={0x00FF,0x0000,0x0000,0x0000,0x0000,0x0000 };

The default setting of the array is shown above. Each element in the array represents 2 sub-bands. That means the first element (0x00FF) mask tells the code to use sub-band  1.

Why 1 and not 2? Because of little endian format. When I changed the first element to 0xFF00, it tells the code to use Sub-band 2, which is the only way the end node will work.

If you are not a programmer, and lots of Makers are not, you do not, and should not,  have to understand how a mask works in C code.  What you do need to know is that you must change the mask in the example code to get your device to work in the US.

The whole painful takeaway here is pretty simple

Lessons Learned

  1.  If you build a LoRa gateway for use in the US and you want it to connect to TTN, you MUST select Sub-Band 2 or your system will not work.
  2. If you build a Lora end device (node) for use in the US and you want it to connect to TTN, you MUST use Sub-Band 2 frequencies or your system will not work.

This was a very painful lesson for me to learn. I do not get easily frustrated, but this problem tested my patience. I do not blame Heltec or anyone else for this new knowledge I had to learn the hard way.

TTN and most of its users are in Europe. The EU does not use sub-bands, so their devices just work. This was painfully obvious when I watched YouTube videos. In fact, in one video posted by my FAV YouTuber Andreas Speiss, he says, “It all just works!”

Cheers Andreas – mine now works too!

I hope these two blog posts helps out a fellow Maker. If you would like me to write-up more detailed “How-To’s” around LoRa fun in the US, leave a comment below.

Sopwith

4 thoughts on “Heltec Lora CubeCell Fun – Part 2

  1. OMG you are the BEST! I’ve been stuck trying to figure out how to connect my Heltec hardware to TTN using a Raspberry PI in the US as well. I agree, the documentation for the US settings is quite incomplete.

    Man you are a lifesaver

  2. Pingback: Heltec Lora CubeCell Fun – Part 1 | Electronic Adventures with Sopwith

Leave a Reply

Your email address will not be published. Required fields are marked *