A Rough Guide to Chirpstack on Helium

At the begin­ning of Heli­um’s LoRaWAN, the abil­i­ty to route a pack­et from a device through the Hotspot net­work to wher­ev­er you want­ed it to go was a ser­vice pro­vid­ed either Heli­um Inc or even­tu­al­ly, the Heli­um Foun­da­tion. That rout­ing hap­pened through the Heli­um Con­sole, which was a cus­tom built LNS (LoRaWAN Net­work Serv­er). An LNS is the thing that man­ages all the pack­ets of data on a LoRaWAN. 

Devices sense the data and trans­mit it, Hotspots receive the data and pass it to an LNS, the LNS routes the data to the enti­ty who pays for it and keeps track of who sent what where and when. That’s a lot of w’s.

Heli­um Con­sole had a few lim­i­ta­tions. First, for a nor­mal user you could only have 10 devices on it. It was always only ever meant to be a demon­stra­tion or “intro to Heli­um” tool. 

Sec­ond, it was very expen­sive for the Heli­um Foun­da­tion to run. This was fine to cov­er in the ear­ly days, but in order for the net­work and mar­ket to ful­ly mature, solu­tions pro­vid­ed by the mar­ket need to evolve. In order for those to evolve, there can’t be a “free” com­peti­tor. That explains why the Heli­um Con­sole is being phased out a long while from now (my guess is end of 2024) to make room for any­one to run an LNS to run their sov­er­eign LoRaWAN appli­ca­tions. (Thanks to Abhay for the improve­ment on that statement!)

Short ver­sion? The Heli­um ecosys­tem is ready for busi­ness­es to be built.

So, as a net­work user, where does that leave you? 

The first option is Chirp­stack, and using Paul Pin­ault’s (disk91 on Dis­cord) tech­ni­cal exper­tise, I’m run­ning one that you can try. The LNS is being run under the Meteo­Sci­en­tif­ic name as part of my “how to run a Heli­um busi­ness” series.

It’s free to cre­ate an account, and you get a few hun­dred data cred­its for free when you sign up so you can test dri­ve it. After that, data cred­its cost $.0001 each. If you had a device that sent 3 para­me­ters (say, tem­per­a­ture, humid­i­ty, and air pres­sure) once an hour, that would cost you [.0001 x 3 x 24 x 365] about $2.63/year.

Want to try it out? Let’s get start­ed. First, go to console.meteoscientific.com and cre­ate an account. Once you’ve signed up and you’re in, look to the left, where you’ll see the basic menu.

This is a lit­tle dif­fer­ent than the old Heli­um Con­sole, but don’t pan­ic, I’ll walk ya through it. For now you should see a cou­ple hun­dred cred­its up in the top right of your screen, that’s plen­ty to get a device on and get started. 

The first thing you’ll want to do is decide what device you’re going to onboard. In my case, I’ll be using the Mak­er­Fabs LoRaWAN Soil Mois­ture Sen­sor, which you can buy here. I’ve writ­ten about how I’m using it, how to print a 3D enclo­sure for it, and it’s pre­de­ces­sor all on this blog, feel free to review any of those links if you need to. It looks like this:

Pret­ty sim­ple, right? Now, if you’ve got­ten a sen­sor on Heli­um before you may be tempt­ed to skip ahead and “just fig­ure it out”, which you can do if you know 2 things. First, Chirp­stack does­n’t use AppEUIs. Sec­ond, Chirp­stack does­n’t have a menu item for Devices; those are found in Appli­ca­tions. You can mud­dle through it from there if you’d like, or you can con­tin­ue fol­low­ing along step by step.

Step 1: Cre­ate a “Device Pro­file”. Chirp­stack (and I) make this super easy in this case by already hav­ing a tem­plate in the MetSci (short for Meteo­Sci­en­tif­ic) LNS. You can find it by going to “Device pro­file” in the menu and hit­ting the “Add Device pro­file” but­ton on the top right. 

When you hit that “Add device pro­file” but­ton you’ll see a page with a ton of choic­es, includ­ing the “Select device-pro­file tem­plate” blue but­ton. More on that lat­er. Most choic­es are self-explana­to­ry, some of ’em are new to many of us. If you’re onboard­ing some­thing oth­er than the soil mois­ture sen­sor I’m using in my exam­ple, I’d sug­gest leav­ing the defaults as they are and chang­ing just the Name, Descrip­tion, and Region to match what you’ve got:

If you’re using the soil mois­ture sen­sor (and you’re in the US915 region), I’ve made this wicked easy; just hit the “Select device-pro­file tem­plate” but­ton, and look for “Mak­er­Fabs”, then keep click­ing all the obvi­ous choic­es. That will load up the tem­plate for you with a US915 region. Even if you don’t have this sen­sor, feel free to use this as a lit­tle ref­er­ence point on your new Con­sole journey!

Now, there’s an impor­tant step if you’re using a dif­fer­ent device: You’ll need to add in the “codec”, which we used to call a “decoder”. For the SMS (Soil Mois­ture Sen­sor) tem­plate, it’s already loaded in. If you’re using some­thing else, make sure you look for the Codec tab and add in a decoder (usu­al­ly you can find it on the inter­we­bz and copy/paste it in. Remem­ber to “Sub­mit” when you’re done mak­ing all your edits to the Gen­er­al tab and the Codec. Here’s where to find the Codec tab:

Cool, so now we have a “Device pro­file” and we’ve added the codec. What’s next? In Heli­um, we’d add a Device. In Chirp­stack, we add an Application.

Head down to Appli­ca­tions, and (obvi­ous­ly?) hit the Add appli­ca­tion button.

This’ll bring up some­thing that seems blind­ing­ly obvi­ous and redun­dant: The “Name” and “Descrip­tion” of the Appli­ca­tion. We’re almost there, so bear with this; it’ll make more sense when we fin­ish the next step of adding a Device. I know, I know, it’s con­fus­ing. Just keep going.

Now, one way to use an Appli­ca­tion is that you’re using 2 sen­sors that are the same sen­sor but in dif­fer­ent regions (US915 and EU868, one for me, one for my aun­tie in Eng­land’s gar­den), or you might be using them for dif­fer­ent prop­er­ties and so they have dif­fer­ent send­ing require­ments (every hour vs once per day). They could pull from the same or dif­fer­ent tem­plates, depend­ing on how you want to set them up. For one device it won’t make much sense, but Heli­um ain’t about run­ning just one device…

Woohoo, let’s add a device! Now that we have an Appli­ca­tion, from the Appli­ca­tions tab in the main menu, choose the appli­ca­tion you just made:

Then hit the blue “Add device” button.

That’ll bring you to the device page. I like to fill out the descrip­tion ful­ly, with a reminder to myself of the nam­ing con­ven­tion I’m using, although that may only be on the 001 of each device. On the Device EUI you can fill in what you have or have Chirp­stack gen­er­ate a DevEUI for you by hit­ting the lit­tle circle/arrow but­ton. For Device Pro­file, choose the (only) option

Once you’ve filled all that in, hit Sub­mit at the bot­tom, which will take you to the “Appli­ca­tion key” tab up in OTAA keys on the Appli­ca­tion menu. You can use the same circle/arrow but­ton to gen­er­ate an App Key (if you’re going to load that onto your device), or you can type in the App­Key if one came with the sensor.

There is no APPEUI in Chirp­stack! This can be a bit jar­ring to you, and in some cas­es you’ll have to enter in all zeros for your AppEUI if you’re pro­gram­ming your device (which is what I do for this device in Platformio).

Whew, we’ve done all the Chirp­stack work we need to do! If your device came with pre-pro­grammed keys you’ll use, you should add bat­ter­ies and it *should* fire right up. You’ll see that in Appli­ca­tions / [your appli­ca­tion] / Devices / [your device].

In that case I did­n’t have any bat­ter­ies in it, I just used the Upload and Mon­i­tor and pow­er from the USB on Plat­formio. Looks like it’s report­ing correctly! 

Very cool, right? Feel free to try it out, and let us know if you find any bugs; this is still pret­ty new, so we haven’t worked out all the kinks yet. If you want a head start on this rad new world we’re head­ing into with Heli­um, this is your chance. Rock on!