Riding The Downlink — A Rough Guide To Browan Tabs

What is a down­link, why would you want one, and how can you use ’em? With Heli­um being a per­mis­sion­less net­work, we’re going to have a ton of peo­ple who are not LoRa wiz­ards try­ing to use a LoRaWAN, includ­ing down­links. I thought I’d write up a few arti­cles on how to solve some of the frus­trat­ing obsta­cles you might find as you con­tin­ue your Heli­um jour­ney. This should help the aver­age user get a hold of one lever in this high tech­nol­o­gy world called “the down­link”. We’ll start off with some back­ground, explain a lit­tle about how it works and give some exam­ples of how you might use it. 

LoRaWAN is not some­thing the aver­age per­son is famil­iar with, and almost all man­u­als avail­able are writ­ten for peo­ple who already under­stand what’s going on. That’s fan­tas­tic if you got a EE degree and then a Mas­ters in wire­less com­mu­ni­ca­tion. It’s less use­ful if you’re a plumber who wants to lev­el up their game and is curi­ous about tech­nol­o­gy (i.e. an excel­lent can­di­date to use the Heli­um network).

Let’s start with a few sen­sors from Browan, a com­pa­ny that’s been in the LoRaWAN busi­ness since 2016, and the wire­less busi­ness since 2002. Browan was kind enough to send me sam­ples so I could share them with you. 

Browan famous­ly makes the Object Loca­tor Tabs, which were some of the first devices ever on Heli­um, and make up many of the devices BFGNeil uses over at Track­pac. While most of us know Tabs as track­ers, the Tab form fac­tor (the lit­tle hexag­o­nal shape) is used to house a num­ber of sen­sors, 3 of which I’ll talk about here. Browan also makes the Mer­ryIoT line, which pro­duced a Heli­um Hotspot for a while and con­tin­ues to sell LoRaWAN sensors.

Here are a few exam­ples of dif­fer­ent Tabs. You can find all of ’em over on Browan’s web­site.

• Tab TBWL100 — Water Leak Sensor
• Tab TBHV110 — Healthy Home (IAQ) Sensor
• Tab TBMS100 — Motion Sen­sor

Onboard­ing these sen­sors will give you a good idea of the poten­tial and the lim­i­ta­tions that they come with. The poten­tial is the big­ger of the two; by com­bin­ing these you can fig­ure out an awful lot about a space; from whether the cat came in (motion sen­sor in a cat tun­nel) knocked over the water bowl and then left, all the way out to deter­min­ing whether or not you should open the win­dows when you’re weld­ing in your garage workshop.

I’ll leave the imag­i­na­tion part up to you and dig into some of the prac­ti­cal­i­ties you might run up against if you’re still new to the whole LoRaWAN & Heli­um thing. 

We’ll start at the basic lev­el: Every sen­sor has 3 “keys” to it: The DevEUI, the AppEUI, and the App­Key. There are oth­ers, but as a basic Heli­um user, those are the three you need.

In many sen­sors you can change those keys to suit you. That might be impor­tant if you’re secu­ri­ty mind­ed, or if you have an inter­nal iden­ti­fi­ca­tion scheme for the sen­sors in your business. 

With Browan Tabs, you don’t have to wor­ry about chang­ing keys. You can’t repro­gram the DevEUI, AppEUI, or App­Key. It’s sim­ple: What they ship with is what you’ve got. You’ll either receive the key-set in an email, or they may be print­ed on a slip of paper or stick­er in the box. Don’t lose ’em, as you won’t have an easy way to retrieve them. I know of one case where the keys for over 300 Tabs were lost and they got thrown out. Don’t let that be you!

Now, every device on a LoRaWAN has a “decoder”, also called a “codec”. This is a set of instruc­tions that deci­phers the data the sen­sor sends out (in an uplink) and turns it into some­thing we can read and use, like a tem­per­a­ture or air qual­i­ty read­ing. Decoders are vital to actu­al­ly using the net­work, but they’re not always easy to find or to write for a spe­cif­ic device.

The Tabs all share one decoder, which is kind of cool. This means that in Chirp­stack (which you can try here), you just set up a Device Pro­file and then cre­ate mul­ti­ple Appli­ca­tions for it. In the Heli­um Con­sole, you’d just set up one Func­tion, then run all the Devices through that Function.

Ok, so that’s all the basic stuff. What hap­pens if you want to change some­thing on the device? There isn’t a way to con­nect a pro­gram­ming cable to Tabs, so you have to do it wire­less­ly, through some­thing called a down­link.

A down­link is a com­mand you send over the air once the sen­sor is acti­vat­ed and has joined the net­work. A down­link is received by the sen­sor AFTER the sen­sor uplinks. If your uplink inter­val (the inter­val at which your sen­sor sends data) is only once a day, you’ll only have one shot per day to send back a downlink. 

A down­link might tell the sen­sor to send out pack­ets on a dif­fer­ent inter­val (every 5 min­utes vs every hour), or it might tell the sen­sor when to actu­al­ly report some­thing. For exam­ple on the Indoor Air Qual­i­ty sen­sor, you might only want to pay atten­tion to tem­per­a­ture changes of over 5 degrees; you don’t need to know if the room went from 72F to 73F.

Down­links are tricky for new users. Con­cep­tu­al­ly easy, they are finicky in prac­tice. If you don’t get every detail cor­rect, they don’t work. Let’s go through a few exam­ples of com­mon pit­falls that you can avoid.

Let’s start by check­ing out the Browan man­u­al for the IAQ Sen­sor, you can find it here. On page 14, you’ll see the the Appen­dix for Con­fig­u­ra­tion of Down­link Commands. 

The first thing to look for is what port to send the down­link on. In this case, it’s 204.

Next, fig­ure out what para­me­ter you want to change. If you want to change mul­ti­ple para­me­ters and see what hap­pens after each change, con­sid­er chang­ing your uplink inter­vals to be fre­quent so you have mul­ti­ple fast options for send­ing back down­links, then set­ting the uplink inter­val back to what­ev­er you’ll use long term. 

So, how do we write an down­link and then send it? Every device is slight­ly dif­fer­ent, and read­ing the man­u­al helps. In gen­er­al, you’ll have to do some trans­la­tion between what you want to say (Hey, only tell me if the temp changes 10 degrees) and what you send (0x10 in the case of a Browan IAQ tab). Usu­al­ly you can find exam­ple pay­loads that’ll guide you, like this:

I’ve found that most of the time, the exam­ples seem sim­ple but can be real­ly con­fus­ing. Are you sup­posed to send 01 02 or 0x02? Or some­thing else? 

Usu­al­ly, the engi­neer who wrote the firmware on the device has done some lit­tle tweak that total­ly makes sense to her, but can catch ya out if you’re not pay­ing atten­tion. In the exam­ple image above, note that the “Unit” of time is 5 min­utes. They also don’t refer to a “uplink inter­val”, they call it a “Keep alive value”.

Final­ly, you may notice that they use a for­mat called hexa­dec­i­mal, which you’ll need to trans­late to. In the IAQ index delta exam­ple above, 50 is the num­ber you as a human would read, but you’ll need to send 32. You can con­vert Dec­i­mal to Hexa­dec­i­mal here.

The eas­i­est way to get the right com­mand is to use Browan’s Down­link Trans­la­tor, which I’ve made avail­able in a Google sheet you can view and copy by hit­ting the but­ton below.

Here’s what it looks like; use the tabs on the bot­tom to find the sen­sor you’re using, then choose the Con­fig val­ue you want and then copy/paste the Down­link Com­mand Pay­load. You can choose to con­fig­ure all of ’em at once as well (as you can see in the screen­shot below.)

Oh, and one more thing. There’s a trick to pop­ping off the shell so you can replace the bat­tery; here’s how to do it: