20 August 2020 / Last updated: 25 Jan 2021

Never lose your stuff again: tracking Bluetooth beacons with a Raspberry Pi

Execution time: 1hr - 2hr
Difficulty: Low
Cost: Medium
Never lose something important to you again by using Bluetooth Low Energy (BLE) beacons and Raspberry Pi sensors to track your stuff. Are your keys at home or in the office? By following this guide, you’ll soon know.


Contrary to my family’s opinion, I have a terrific memory. I can remember the words and theme tune to almost every 1980’s UK TV advert ever made, for instance. However, it does let me down in a few ways, such as remembering where I put something. Anything. Barely a day goes by without me losing something important, like my wallet, or my keys, or a child*.
I have apps to remind me about tasks and appointments, but nothing that can tell me where I left my stuff. I’ve tried some other tracker solutions before, but found them expensive, dependent on my smartphone, and limited in use. So, like any hardware hacker worth their salt, I made my own solution.
The idea is to find an inexpensive source of bluetooth beacon tags, attach them to all my stuff (including the children?!?), and detect where they are by using Raspberry Pis as sensors.
Protip: If you already have a Pi, you don’t need to buy anything to test this project, as we’ll show you how to use a smartphone app to create a virtual bluetooth tag!
* I’ve never actually lost a child. For long.

What’s Bluetooth/BLE and what’s a beacon?

Bluetooth has been around for a long time now and most people know it’s a wireless technology for exchanging data between devices over a short range. Bluetooth Low Energy (BLE) came along in about 2011 and differed from Bluetooth “Classic” by providing similar sort of range and throughput, but consuming much less power to do so. It also provided additional capabilities to the traditional model of paired devices initiating data transfers.
One of these capabilities is advertising and discovery, whereby a BLE device can periodically send out a carefully formatted packet to advertise itself and its capabilities. Listening devices can decode these packets and act upon the information to enable novel applications, such as proximity sensing: alerting to the presence or absence of the beacon.

So what’s this project doing?

This guide uses the balenaLocating project to create one or more BLE sensors with Raspberry Pis (either 3B+ or 4) or a balenaFin:
It gives you a dashboard showing you where your beacons are:
By querying cloud-based time-series database:
which is populated by a BLE beacon sensor service running on balenaCloud:
You attach a BLE beacon (we call them tags - see the section on tags below) to anything you don’t want to lose, and give it a representative name, like ‘keys’ or ‘wallet’ or ‘tortoise’.
Then you add a device to your application and name it to the location you’re going to leave it in, like ‘house’ or ‘garage’. Your Raspberry Pis detect the tags, and report them to the database.
The more Raspberry Pis (or other devices) you add to your application, the more locations you can detect your tags in.
So, devices represent locations.Tags attach to, and represent, your important things you don’t want to lose. When a tag is near a device, you know your thing is in a location.
Got it? Great!
Let’s get started!

Hardware required

  • Raspberry Pi (3B+ or 4)
  • A 4GB or greater micro SD Card (we always recommend 16Gb SanDisk Extreme Pro SD cards)
  • Power supply
  • Some BLE beacon tags or a smartphone app to make a virtual beacon for testing.

Software required

  • Software to flash an SD card (we recommend balenaEtcher)
  • A free tier balenaCloud account to setup and manage your fleet of Raspberry Pi sensors
  • A free tier InfluxDB Cloud account (we’ll set this up in a moment)


Create an InfluxDB Cloud Account

We’re going to set up the cloud database first, since we need some information from it later.
InfluxDB Cloud 2.0 (in public beta at the time of writing) is a Time Series-as-a-Platform database technology. It has a free tier offering, with some constraints, but for what we’re building here, the free tier is perfect. We will be storing very small amounts of data (BLE beacons) which we don’t need to persist for longer than a few days at most.

Set up your account

First, create an account on the InfluxDB Cloud 2.0 site, choosing AWS as the cloud provider:
Sign in and copy the URL from your browser. It should look something like this:
Keep this somewhere to hand like in a Notepad file-- we’ll need it later.
Next, go to “Data” and create a bucket. I’ve called mine “balenaLocating” but you can use any name you want, as long as you remember it for later. You can also set the data retention here, to make sure you don’t go over the limit of the free tier plan. I set mine to 48 hours:
Next, we need to make ourselves a token, so that the services on the Raspberry Pi can read and write to the bucket. You can re-use the same token for multiple devices, just make sure it’s configured to read and write to the bucket we just created:
Copy the key value into your Notepad app, and that’s us done with InfluxDB Cloud for now.

Setup the Raspberry Pi

Once you’ve found all the hardware and prepared all the software, we’re going to start setting up the Raspberry Pi.

Click this button

Tip: If you don’t already have a balenaCloud account, clicking the deploy button will take you to the signup page, where you can make a free one. If you have a Google or Github account, you can sign in with one of those. Alternatively, if you’re already familiar with balenaCloud you can also deploy the code with the CLI.
When you reach 'Create and deploy to application', toggle the “Advanced” switch, which will show you a series of Application Configuration Variables, some of which we can plug our InfluxDB information into:
Now, find that URL you saved from earlier, as you’ll need to update the following settings:
  • INFLUX_BUCKET - this is the bucket name we set above
  • INFLUX_HOST - this is the host URL we copied into a notepad, the blue bit from above
  • INFLUX_KEY - this is the key we created as Read/Write for our bucket
  • INFLUX_ORG - this is the org ID we copied, the green bit from above
Now you can click Create and Deploy.
This will create an application with all of the code already deployed and all of the device variables created and set!

Add a device and download the balenaOS disk image from the dashboard

Add a device within that application by clicking the 'Add Device' button. If you are connecting to a wireless network, you can set your WiFI SSID and passphrase here too. Otherwise, a wired connection will suffice.
This process creates a customized image configured for your application and device type, and includes your network settings if you specified them.
When you're first getting started, a development image will be most useful, as it permits a number of testing and troubleshooting features. More details on the differences between development and production images can be found here.

Flash your SD card with the balenaOS disk image and boot the device

Once the OS image has been downloaded, it’s time to flash your SD card. balenaEtcher is perfect for this.
Insert the SD card and power on your device. If everything worked correctly, after a few minutes your device information screen in the dashboard should look something like this, showing two services: beaconService and dashboard.

View the Dashboard

The dashboard is a simple web app which queries the cloud database to find the last time a beacon was detected, and which sensor detected it. To view it, turn on your device’s Public URL:
And click the link to open it in your browser:
On this screen, you’ll see three tabs in the left-hand menu: “Home”, “Devices” and “Tags”.
The Home tab shows you where your Tags are. As you won’t have named your tags yet (that bit is coming), you’ll need to click the “Show Un-Named Tags” button. Here’s my dashboard with that button clicked:
The long ID FDA50693-A4E2-4FB1-AFCF-C6EB07647825-10011-10011 is a tag sitting on my desk, which I haven’t named yet. You’ll also notice that the page tells you the last time it was seen, the location and the strength of the signal received. Underneath the table is the countdown until the table updates, so you don’t have to keep refreshing the browser to see the latest data.
The ‘Location (UUID)’ column is showing you the mapping of the device in your balenaCloud application (each has a Universally Unique ID) and the location it represents. This location value is actually just the name of the device, and I’ll show you how to rename a device in just a moment. For now your device(s) will have balena-generated names like ‘thoughtful-doughnut’ or ‘pensive-tortoise’.
If no device receives a beacon from a tag previously seen for 10 minutes or more, its row will have a pink background to help you see any missing tags:


In the “Devices” area of the dashboard you get a card for each device you have added to the application, when it was last seen, if it’s online or not, and a list of the tags it has seen:
This view is useful when you are trying to configure the system using the RSSI_THRESHOLD, which we’ll look into later.

“So what’s in the Tag area?”

...I heard you all ask. Here’s what you’ll find:
At least, that’s what’s in mine. Let’s get some data into your app, and then we can talk about populating the Tag screen.

Do some testing

The quickest (and cheapest) way to test that your application is working, is to make your smartphone pretend it is a tag, by generating a beacon. There are quite a number of apps on the stores that can do this, we have tested the following options for Android and IOS:


Beacon Simulator (Google Play Store) by Vincent Hiribarren
Open the app:
Click the ‘+’ button and select ‘iBeacon’ from the list of templates that appears:
In these options, you can set the name, and the major and minor values to whatever you like. I recommend leaving the UUID as the default, and just adding a major and minor value:
Now flick the switch and turn your virtual tag on:


BLE Scanner 4.0 (Apple App Store) by BluePixel Technologies
  1. Open the app:
  1. Go to the iBroadcast tab (bottom navbar)
  1. Click on the cog icon in the top right corner
  2. Click the plus sign in the top right corner to add a beacon, and choose “iBeacon”:
  3. In these options, you can set the name, and the major and minor values to whatever you like. You will need to provide a UUID. A service like Online UUID Generator or UUIDTools.com can be used to generate custom UUIDs.
  1. Once created, select the iBeacon so that it can be broadcasted
  1. Go back to the Beacon Broadcast screen. It should now be broadcasting the iBeacon we created
Nip back to your application Dashboard and you should find your virtual tag in the list of Un-Named tags found. Here’s mine from the Android example above:

Name your Tags

Now we have some tags appearing in the Dashboard, it’s time to give them a name. Remember, when these are real tags, the idea is to put them in your bags, attach them to your keys and glue one to your tortoise. So, we need to name them to the thing they are stopping you losing.
To do this, we set some more environment variables in balenaCloud. Each one must start with the name ‘TAG_’ followed by the name of the thing:
The value is the ID of the tag. You can copy this out of the “Home” screen, once you’ve clicked the “Show Unnamed Tags” button.
All of this looks a bit like this in balenaCloud:
With that set (and the services back running) your dashboard will look more like mine with tags named!

Map your devices to locations

At last-- the final piece of the puzzle: naming your devices so that they represent a location. The idea here is that you can have as many devices acting as sensors as you like.
Tip: Don’t forget you can use our device multi-tool post to add this code to any other balena devices you have running, such as balenaSound or balenaSense.
You may want one at home, at your place of work, in the garage, or the shed. The more devices you have acting as a sensor, the more chances you have of knowing where your stuff is!
Another scenario worth considering is multiple devices in the same location, to try and get a more accurate location than just “home” or “office”. You could, for instance, put a device downstairs and another upstairs (if you have stairs, obviously), to be told which floor of a building a tag is on. You may need to “trim” the reception coverage of each device, so that they don’t both see a tag (otherwise the dashboard will just show you which device saw it last) - which is covered in the next section: ‘Configure your system’.
So that the devices relate to their location, simply rename the device in balenaCloud:
Once the device has restarted, you’ll find it’s changed in the dashboard:
And here’s what it looks like in balenaCloud when you have several devices all named to the location they represent:

Configure your system

  • Debug
  • RSSI threshold
  • Separation period
There are a couple more environment variable options available to set, should you want to. These can be set at the application level, and so apply to the whole fleet, or at the device level to be device specific.
The first one is DEBUG and should be self-explanatory. Set it to true if you need more output from the services, mainly to find out why/if a tag is being found and ignored, or just not found at all.
Next is RSSI_THRESHOLD. This can be set to a number between -100 and 0. The default is -75. It’s the threshold for the strength of signal received from a tag, filtering out weak signals. What this allows you to do is trim each sensor, so that their coverage plots don’t overlap.
As an example, you may have a sensor in the house and the shed, but you only want things in the shed to be found by that sensor, so that they are not reported as being in the house. To do this, put a tag in your shed, and look at the logging output of the house sensor in balenaCloud with the RSSI_THRESHOLD for that sensor set to -100. If you can see the tag in the shed with that sensor, increase the threshold setting (try -80 next) and watch again. Keep doing this until you find the largest threshold number that DOES NOT find the tag in the shed.
NOTE: Whenever you change a device variable within balenaCloud, you’ll force a restart of the services running on the device.. Don’t be alarmed if this happens.
Lastly you can set SEP_PERIOD to the number of seconds between reporting each tag beacon. The frequency between beacon broadcasts varies between tags, but is normally one every few seconds. There’s no point sending each one of these to our cloud database, unless you want to know the exact second something was last seen. So this is set to only report on each tag every 30 seconds. Change this to fit your own needs.

Getting Tags

Tags vary enormously in cost but can be found cheaply if you search around. What you’re looking for is a tag which uses the iBeacon standard and can be programmed. I found these on AliExpress:
The listing includes details for how to program them. What this means is changing the ID that the tag is broadcasting. Normally when you buy multiple tags from a supplier, they all turn up with the same ID programmed into them. If you don’t change this, the above system will think they are all the same thing you don’t want to lose. This tag I got from AliExpress included instructions about how to use another smartphone app to change the ID of the tag. But a word of warning: it can be tricky to program them yourself. A more reliable way would be to buy tags from a company that will give you support programming them (some companies do the programming for you), such as here: https://www.beaconzone.co.uk/ibeacon


Now you can attach tags to all your favourite things, put a device wherever you might leave them, and always know where they are. Maybe you have commercial use cases for such a system? How about knowing which warehouse stock is in? What about knowing if important equipment is at work or out on site? What about tracking the movement of items through a factory? The fleet management aspect of balenaCloud allows you to keep all your devices up to date and under control without having to look after each one individually. The possible applications are endless.
Let us know on Twitter if you try the project, and drop us a line on the balena Forums if you have any problems.
by Phil WilsonCTO and co-CEO