26 January 2022 / Last updated: 26 Jan 2022

Create a fleet of centrally-managed Bluetooth low-energy(ble) beacons with ble-lighthouse and balena

Execution time: 30 mins to 1 hour
Difficulty: Easy
Cost: Low
Low-energy Bluetooth beacons bridge the physical and the digital world. Whether it’s navigating indoor devices or broadcasting sensor information in a connectionless state, beacons have efficiently enabled the Internet of Things(IoT) to be part of many use cases.
Introducing ble-lighthouse, the best way to build fleets of Bluetooth low-energy beacons
As a part of my balenaLabs Residency, I decided to make a project which enables anyone to create a centrally managed fleet of BLE beacons using cheap single board computers.
For instance, a device like the Raspberry Pi Zero W can broadcast:
  • URLs
  • UIDs
  • Sensor data (work in progress)
And since the balena architecture allows one to run multiple containers on the same device, the possibilities to use these beacons are truly endless.
Some real-world applications include:
  • Using BLE beacons in a Museum to broadcast webpages or links to Augmented Reality apps to deliver educational content
  • Broadcasting your business profile in a conference event
  • Navigating indoor environments based on sensor locations
  • Temperature and Humidity sensor beacon updating every x seconds
  • Beacons at a retail store broadcasting a discount coupon
  • BLE beacons to help identify trees and plants in a garden
  • … and more
Before we dive in, you can review a bit of background first, or, get right to the build steps.


BLE beacons are traditionally created using microcontroller platforms which are really low powered and can run off a coin cell for an year or so, but creating them on single board computer with balena stack enables a great deal of workflow for ex: Hosting a web page from a container and displaying it’s public URL from the beacon container. The webpage can be updated automatically using a Continuous Integration Pipeline.
The other feature is centrally managing all the beacons and changing what sort of things they broadcast - Updating URLs, disabling broadcasts, changing sensor update rate all from a single dashboard, you can also rename the device, so for ex: A librarian can rename a beacon as fiction section, biographies and self-help books from balena dashboard and know which beacon they’re updating from balenaCloud. I’d say it is a fair trade-off for giving up on low power aspects of microcontroller based beacons where it’s hard to update and manage them with this sort of ease.

What’s a balenaLabs Residency?

My prototype is part of the balenaLabs residency program, where balenistas take on a physical computing project to learn more about balena and various hobbyist or industrial use cases. It’s also a way to better understand how and why other people use balena. You can check out all kinds of build logs and notes on our Forums.
Also, this program isn’t just for balena’s teammates - any community member can join in on the fun. Share your project on the Forums to let us know what you’re working on. We’re here to help!

Inspired by our users

For balenaLabs Residency projects, it’s been always advised to work on something which you truly care about. From my experience with balena before and after joining the company, I’ve also observed a number of usability issues. Here are some of my motivations for picking up this project :

Creating a project that needs No (very few) external hardware

Let’s be honest, the global supply chain shortages haven't been pretty cruel and as a Developer Advocate I wanted to create a project which requires no or very little hardware to build so that I can easily showcase it in community events, conferences etc . No one likes to debug wire connections live, hence I thought of this project as something which can be made by just using a Pi 0 and if you wanna broadcast sensor data maybe an additional DHT11 sensor, and that’s all.

Learning more about the Bluetooth wireless protocol

I was always fascinated with Bluetooth wireless radios and how one protocol can be used for so many things from A2DP profile allowing audio playback on bt speakers and headphones to heart rate monitor profile, bt serial profile and now these beacons. You can check out some of my previous work on ble.

Digging into the use cases surrounding Bluetooth low-energy

I still think we haven't leveraged the full potential of beacons yet, there can be tons of applications and some companies are already out there that make ble beacons to advertise telemetry data and other things but they're mostly around microcontrollers and maybe closed implementations. I'll take any excuse to learn more about how ble beacons work in general.


Hardware required

  • A Raspberry Pi (Zero W or W 2 , 3B+, and 4 are supported)
  • A 32GB MicroSD card (like a SanDisk Pro)
  • A supported power supply for your device
  • (optional) Sensor ex DHT22 (implementation is WIP)

Software required

  • A free balenaCloud account (your first ten devices are free and fully featured, no credit card required to start)
  • balenaEtcher to flash your OS image to your SD card
  • balenaCLI if you want to learn more advanced balena usage and manage a fleet of devices
  • The project code on GitHub if you’re setting this up with balenaCLI
  • A beacon scanner app for your mobile device (e.g. eBeacon for iOS, beacon Scanner for Android, or something similar)

Let’s build

Deploy with balena

To use this method, you’ll want to start a free balenaCloud account, and then click the button below to add this Fleet to your account. You can also find some high-level instructions on my Project page on balenaHub.
balena deploy button
If you use Deploy with balena, you’re basically skipping the need to download a copy of the software and use balenaCLI to push it to your account. Instead, you’ll log into balenaCloud and you’ll be prompted to “Create and deploy” a new Fleet (this project).
Create and deploy this Fleet to your balenaCloud account
If you do this route, skip onto the paragraph below about adding a device to your Fleet.

Add this Fleet to your account using balenaCLI

This is the advanced route to start using this project. You’ll need to install balenaCLI and fork a copy of the project from GitHub. Add a new Fleet on your balenaCloud account. From the CLI, navigate into the code folder, log into your account from the command line, and use balena push <fleet-name> to push the code into your Fleet.
You’ve successfully pushed your code if you see this message:
When you see Charlie the Unicorn, you've successfully pushed your Fleet code to balenaCloud
Go to balenaCloud -> your fleet -> Devices, and choose the Add Devices option to add a device to the fleet.
Add your device(s) to your Fleet
Choose the right device type from the dropdown and determine whether you’re using Ethernet or Wi-Fi (if Wi-Fi, you’ll need to include Wi-Fi credentials, which are not stored anywhere except for securely on your particular OS image for your device). Download the OS image and use balenaEtcher to flash the image onto your SD card.
Insert the SD card into your device and power it on. You should see the device appear once it boots, connects to your network, and ultimately connects to the balenaCloud VPN.

Follow along with my build log

You can learn about the project and how it’s created by checking the build logs on the balenaForums.


Once your device has downloaded the latest release, you should see these services up and running. Your screen should look like this:
You're on the right track once your balena device downloads the latest release and you see these services
Now, depending on the type of mobile device you have, you can scan for this beacon. By default the beacon transmits the balena website URL for you to visit. You can customize this and many other parameters of this project.
Here’s the iOS beacon app finding the freshly-created ble-lighthouse device:


Your entire fleet of beacons can be all managed centrally via balenaCloud and its device variable management. Try any of the environment variables below to add some customization.
URL (works if BEACON_TYPE is set to URL)https://hub.balena.ioAny URL that includes https://
UID(works if BEACON_TYPE is set to UID)01234567890123456789012345678901any 16 bytes unique ID
If you have some experience with app development you can also create custom apps specifically for your use case and business and use beacons to make a better in-store experience for your customers (for example).

What’s next?

The project is hosted on the github here, While I continue to work on improving this project, contributions are always welcome. The next goal is to add support for sensors and come up with a uniform packet structure so it’s easy to recognise the type of sensor such as we do with our connector blog. Product Builder/Hardware Hacker Phil has also created a ble beacon gateway which can take data from ble beacon and send it on the internet. I will be trying to make my beacons compatible with it.
Thanks for checking out my project, let me know how you used it and as always if you have any questions, comments, feedback, or suggestions don’t hesitate to reach out to us.
by Ayan PahwaProduct builder and developer advocate at balena