# CircuitPython BLE Advertising Beacons
## Overview
Danger: This guide has been deprecated. The Google Beacon format was dropped by Google in 2022. This guide is being left for reference only.
Mmmmm, bacon.....
What?
Oh. Beacons? Yes, beacons!
Beacons are low power, low cost Bluetooth LE devices that can be used for a very simple job: to advertise a URL to users running an app on their mobile device within range of the device!
Technically, beacons can also be used for a few different scenarios where a localized, wireless data broadcast is desirable, such as indoor location tracking, point of sales/marketing, and experience personalization.
We'll create two version -- first, a simple beacon that can run on any CircuitPython capable nRF52840 board. Second, a custom version for the CLUE board that also shows QR codes and allows you to scroll among multiple beacon URL choices to advertise!
## Parts
All you need to advertise your own BLE beacons is any Adafruit Bluefruit nRF52840 board:
### Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE
[Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE](https://www.adafruit.com/product/4481)
What's smaller than a Feather but larger than a Trinket? It's an **Adafruit ItsyBitsy nRF52840 Express** featuring the **Nordic nRF52840 Bluetooth® LE** processor! Teensy & powerful, with an fast nRF52840 Cortex M4 processor running at 64 MHz and 1 MB...
In Stock
[Buy Now](https://www.adafruit.com/product/4481)
[Related Guides to the Product](https://learn.adafruit.com/products/4481/guides)
### Adafruit CLUE - nRF52840 Express with Bluetooth® LE
[Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500)
Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made...
In Stock
[Buy Now](https://www.adafruit.com/product/4500)
[Related Guides to the Product](https://learn.adafruit.com/products/4500/guides)
### Adafruit Feather nRF52840 Express
[Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)
The **Adafruit Feather nRF52840 Express** is the new Feather family member with Bluetooth® Low Energy and _native USB support_ featuring the nRF52840! It's our take on an 'all-in-one' Arduino-compatible + Bluetooth® Low Energy with built-in USB...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4062)
[Related Guides to the Product](https://learn.adafruit.com/products/4062/guides)
### Circuit Playground Bluefruit - Bluetooth® Low Energy
[Circuit Playground Bluefruit - Bluetooth® Low Energy](https://www.adafruit.com/product/4333)
**Circuit Playground Bluefruit** is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've taken the popular Circuit Playground Express and made it even better! Now the main chip is an nRF52840...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
You'll also want a USB cable for programming it and power, or you can use a LiPoly battery for remote powering.
### USB cable - USB A to Micro-B
[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller
Approximately 3 feet / 1 meter long
In Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Adafruit Micro Lipo - USB LiIon/LiPoly charger
[Adafruit Micro Lipo - USB LiIon/LiPoly charger](https://www.adafruit.com/product/1304)
Oh so adorable, this is the tiniest little lipo charger, so handy you can keep it any project box! Its also easy to use. Simply plug in the gold plated contacts into any USB port and a 3.7V/4.2V lithium polymer or lithium ion rechargeable battery into the JST plug on the other end. There are...
In Stock
[Buy Now](https://www.adafruit.com/product/1304)
[Related Guides to the Product](https://learn.adafruit.com/products/1304/guides)
### Adafruit LiIon/LiPoly Backpack Add-On for Pro Trinket/ItsyBitsy
[Adafruit LiIon/LiPoly Backpack Add-On for Pro Trinket/ItsyBitsy](https://www.adafruit.com/product/2124)
If you have an ItsyBitsy or Pro Trinket you probably know it's the perfect little size for a portable project. This LiPoly backpack makes it really easy to do! Instead of wiring 2 or 3 boards together to make a charging system, this little PCB sits on top of the PCB and allows a...
In Stock
[Buy Now](https://www.adafruit.com/product/2124)
[Related Guides to the Product](https://learn.adafruit.com/products/2124/guides)
Additionally, you'll need a mobile device running an Eddystone beacon discovery app, such as Physical Web:
- [Physical Web for iOS](https://apps.apple.com/us/app/physical-web/id927653608)
- [Physical Web for Android](https://play.google.com/store/apps/details?id=com.physicalweb&hl=en_US)
# CircuitPython BLE Advertising Beacons
## Understanding BLE Advertising Beacons
Bluetooth LC beacons are low power devices that are used to broadcast a tiny amount of data to any device that's listening. This often takes the form of a mobile device running an app, such as Physical Web, that can read the beacon's advertising broadcast and display a URL the user can then visit.
There are two primary BLE beacon standards: Apple's iBeacon, and Google's Eddystone. In this guide, we'll use the Eddystone standard to create a beacon that advertises a website URL (which you can customize to any URL you like).
## Advertising
When an Eddystone beacon is running, it transmits a packet of information that includes a Unique Identifier (UID), and another packet of information that includes a website URL.
Note, this data is transmitted with no need for connecting, pairing, or bonding with a mobile device. The beacon is pretty much just always sitting there yelling, "Hey! I'm a beacon! This is my name, and this is a URL I think you should visit!"
## Other Uses
This guide focuses solely on using beacons to advertise a URL, however there are a few other common uses for beacons. These include indoor navigation, tracking (such as lost key finders like Tile), and interaction notifications, such as interactive museum tours.
# CircuitPython BLE Advertising Beacons
## Simple Advertising Beacons
## CircuitPython Setup
For our simple beacon example, we'll use the ItsyBitsy nRF52840. We'll show you how to set it up with the proper libraries and code to use on the Itsy, but you can apply these instructions to the Feather nRF52840, Circuit Playground Bluefruit, or CLUE boards as well by downloading the appropriate version of CircuitPython for those boards.
# CircuitPython BLE Advertising Beacons
## CircuitPython for ItsyBitsy nRF52840 Express
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## Set up CircuitPython Quick Start!
Follow this quick step-by-step for super-fast Python power :)
[Download the latest version of CircuitPython for this board via CircuitPython.org](https://circuitpython.org/board/itsybitsy_nrf52840_express/)
## Further Information
For more detailed info on installing CircuitPython, check out [Installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython).
**Click the link above and download the latest UF2 file.**
Download and save it to your desktop (or wherever is handy).
Plug your Itsy nRF52840 into your computer using a known-good USB cable.
**A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.**
In the image, the **Reset** button is indicated by the magenta arrow, and the **BTLE** **status LED** is indicated by the green arrow.
Double-click the **Reset** button on your board (magenta arrow), and you will see the **BTLE LED** (green arrow) will pulse quickly then slowly blue. If the DotStar LED turns red, check the USB cable, try another USB port, etc.
If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!
You will see a new disk drive appear called **ITSY840BOOT**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **ITSY840BOOT.**
The LED will flash. Then, the **ITSY840BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it, you're done! :)
# CircuitPython BLE Advertising Beacons
## Simple Beacon Code in CircuitPython
## Text Editor
Adafruit recommends using the Mu editor for using your CircuitPython code with Adafruit boards. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor).
Alternatively, you can use any text editor that saves files.
## CircuitPython Libraries & Code.py
To use with CircuitPython, you need to first install a few libraries, into the lib folder on your **CIRCUITPY** drive. Then you need to update **code.py** with the example script.
Thankfully, we can do this in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries and the **code.py** file in a zip file. Extract the contents of the zip file, open the directory **examples/** and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your **CIRCUITPY** drive.
Your **CIRCUITPY** drive should now look similar to the following image:
https://github.com/adafruit/Adafruit_CircuitPython_BLE_Eddystone/blob/main/examples/ble_eddystone_simpletest.py
## Code Explainer
### Libraries
Here's how this code works. First we import the `time` and `adafruit_ble` libraries.
Then, we import `uid` and `url` from the `adafruit_ble_eddystone` library. These two give us the capability to advertise a unique identifier (UID) and a website URL.
```python
import time
import adafruit_ble
from adafruit_ble_eddystone import uid, url
```
### Radio & Eddystone Setup
Next we'll create an instance of the `BLERadio()` and then create a variable for the `eddystone_uid`. This is the unique ID that is used to differentiate beacons when multiple of them are present. We can re-use the BLE `radio.address_bytes` as our UID.
We'll also create a variable for the website URL we want to be advertised from our beacon, **eddystone\_url.**
In this case, we are using **https://adafru.it/discord** as the beacon URL, but you can swap in a URL of your choosing. Just be careful it isn't too long -- anything under 18 characters will work, otherwise you can use a URL shortener service, such as bit.ly.
```python
radio = adafruit_ble.BLERadio()
# Reuse the BLE address as our Eddystone instance id.
eddystone_uid = uid.EddystoneUID(radio.address_bytes)
eddystone_url = url.EddystoneURL("https://adafru.it/discord")
```
Info:
## Advertising
With setup complete, the main, ever-repeating loop of the code now takes over. Here, we alternate between advertising the beacon's UID and the beacon's URL, pause for four seconds, and repeat.
```python
while True:
# Alternate between advertising our ID and our URL.
radio.start_advertising(eddystone_uid)
time.sleep(0.5)
radio.stop_advertising()
radio.start_advertising(eddystone_url)
time.sleep(0.5)
radio.stop_advertising()
time.sleep(4)
```
## Usage
To use it, simply power up the beacon and then launch your Physical Web app (or other beacon-aware app) on your mobile device. You'll see the app scan for beacons.
When the beacon is found, you will see some info about it, including a clickable link to take you to the advertised URL.
Any icons and descriptive text are scraped from the website itself, and not part of the data delivered by the beacon.
That's all there is to it! Next we'll create a more sophisticated version on the CLUE.
# CircuitPython BLE Advertising Beacons
## CLUE Beacon
First, set up CircuitPython on the CLUE following the [instructions on this page](https://learn.adafruit.com/adafruit-clue/circuitpython).
## Libraries
Next, install the libraries needed. [This guide page](https://learn.adafruit.com/adafruit-clue/clue-circuitpython-libraries) will show you where to download them.
You'll need the following libraries for this project:
- adafruit\_bitmap\_font
- adafruit\_ble
- adafruit\_ble\_eddystone
- adafruit\_bus\_device
- adafruit\_display\_shapes
- adafruit\_display\_text
- adafruit\_pybadger
- adafruit\_register
- adafruit\_lis3mdl.mpy
- adafruit\_lsm6ds.mpy
- adafruit\_miniqr.mpy
- neopixel.mpy
## Text Editor
Adafruit recommends using the Mu editor for using your CircuitPython code with the Feather boards. You can get more info in [this guide](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor).
Alternatively, you can use any text editor that saves files.
## Image Files and Code.py
This project uses a couple of .bmp image files -- you can get them by downloading the Project Zip link in the embed below. Unzip the downloaded zip archive and then drag the two image files to your CLUE board's **CIRCIUTPY** drive.
Copy the code shown below, paste it into Mu. Save the code from Mu to the CLUE's **CIRCUITPY** drive as **code.py**
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE/CLUE_Beacon/code.py
## How It Works
Like the simple example before, we will import libraries for time, ble, and eddystone support. We will also import the `adafruit_pybadger` library which makes it convenient to use the buttons, speaker, and screen on the CLUE.
```python
import time
from adafruit_pybadger import pybadger
import adafruit_ble
from adafruit_ble_eddystone import uid, url
```
## Setup
We'll set up the `radio` and `eddystone_uid` as before, but this time instead of a single URL, we'll create a list of few to pick through.
This is a list of tuples, which each entry containing both a URL and a "nice name".
The `pick` variable will be used to select a URL from the list when the B button is pressed.
```python
radio = adafruit_ble.BLERadio()
# Reuse the BLE address as our Eddystone instance id.
eddystone_uid = uid.EddystoneUID(radio.address_bytes)
# List of URLs to broadcast here:
ad_url = [("https://circuitpython.org", "CirPy"),
("https://adafru.it/discord","DISCORD"),
("https://forums.adafruit.com", "Forums"),
("https://learn.adafruit.com", "Learn")
]
pick = 0 # use to increment url choices
```
We'll use the `pybadger.play_tone()` command to beep the on-board speaker, and the `pybadger.show_business_card()` command to display a .bmp image.
```python
pybadger.play_tone(1600, 0.25)
pybadger.show_business_card(image_name="cluebeacon.bmp")
```
## Main Loop
In the main loop of the program we will set the display to auto dim after three seconds, and set the movement threshold so you can shake it a little to wake up the CLUE and undim it.
The `eddystone_url` is set to the first one in the list.
```python
pybadger.auto_dim_display(delay=3, movement_threshold=4)
eddystone_url = url.EddystoneURL(ad_url[pick][0])
```
## Buttons
When the A button is pressed by itself, the `pybadger.show_qr_code()` command is run, displaying the automatically generated QR code image for the currently selected URL.
```python
if pybadger.button.a and not pybadger.button.b: # Press button A to show QR code
pybadger.play_tone(1200, 0.1)
pybadger.brightness = 1
pybadger.show_qr_code(data=ad_url[pick][0]) # Tests QR code
time.sleep(0.1) # Debounce
```
When the B button is pressed, the next URL in the list is selected, and this info is displayed on the screen using the `pybadger.show_business_card()` command.
```python
elif pybadger.button.b and not pybadger.button.a: # iterate through urls to broadcast
pybadger.play_tone(1600, 0.2)
pick = (pick + 1) % len(ad_url)
pybadger.brightness = 1
pybadger.show_business_card(image_name="bg.bmp", name_string=ad_url[pick][1], name_scale=5,
email_string_one="", email_string_two=ad_url[pick][0])
time.sleep(0.1)
```
When both A and B buttons are pressed at the same time, the display returns to the initial screen image.
```python
elif pybadger.button.a and pybadger.button.b:
pybadger.play_tone(1000, 0.2)
pybadger.brightness = 1
pybadger.show_business_card(image_name="cluebeacon.bmp")
time.sleep(0.1)
```
## Beacon Advertising
Finally, we have the beacon advertising code, just as with the simple example. The beacon UID is advertised, then the URL is, and this repeats every second.
```python
# Alternate between advertising our ID and our URL.
radio.start_advertising(eddystone_uid)
time.sleep(0.5)
radio.stop_advertising()
radio.start_advertising(eddystone_url)
time.sleep(0.5)
radio.stop_advertising()
time.sleep(1)
```
## CLUE Beacon Usage
Power up the CLUE and you'll see the welcome screen.
## Pick Beacon Advertisment
Press the B button to pick a URL from your list. There is a small beep when the button press is recognized -- you may need to hold it for a second first.
The current beacon name and URL will be displayed.
## QR Code
Press the A button to go to QR code mode. This is great for any users without a BLE beacon app who want to use their camera to scan the URL instead.
Here is the auto-generated QR code. All made in CircuitPython!
You can press the B button to switch to the other URLs which will change the beacon advertisements almost instantly.
Warning:
## Featured Products
### Adafruit CLUE - nRF52840 Express with Bluetooth® LE
[Adafruit CLUE - nRF52840 Express with Bluetooth® LE](https://www.adafruit.com/product/4500)
Do you feel like you just don't have a CLUE? Well, we can help with that - get a CLUE here at Adafruit by picking up this sensor-packed development board. We wanted to build some projects that have a small screen and a lot of sensors. To make it compatible with existing projects, we made...
In Stock
[Buy Now](https://www.adafruit.com/product/4500)
[Related Guides to the Product](https://learn.adafruit.com/products/4500/guides)
### Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE
[Adafruit ItsyBitsy nRF52840 Express - Bluetooth® LE](https://www.adafruit.com/product/4481)
What's smaller than a Feather but larger than a Trinket? It's an **Adafruit ItsyBitsy nRF52840 Express** featuring the **Nordic nRF52840 Bluetooth® LE** processor! Teensy & powerful, with an fast nRF52840 Cortex M4 processor running at 64 MHz and 1 MB...
In Stock
[Buy Now](https://www.adafruit.com/product/4481)
[Related Guides to the Product](https://learn.adafruit.com/products/4481/guides)
### Circuit Playground Bluefruit - Bluetooth® Low Energy
[Circuit Playground Bluefruit - Bluetooth® Low Energy](https://www.adafruit.com/product/4333)
**Circuit Playground Bluefruit** is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've taken the popular Circuit Playground Express and made it even better! Now the main chip is an nRF52840...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
### Adafruit Feather nRF52840 Express
[Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)
The **Adafruit Feather nRF52840 Express** is the new Feather family member with Bluetooth® Low Energy and _native USB support_ featuring the nRF52840! It's our take on an 'all-in-one' Arduino-compatible + Bluetooth® Low Energy with built-in USB...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4062)
[Related Guides to the Product](https://learn.adafruit.com/products/4062/guides)
### Adafruit Feather nRF52840 Sense
[Adafruit Feather nRF52840 Sense](https://www.adafruit.com/product/4516)
The **Adafruit Feather Bluefruit Sense** takes our popular [Feather nRF52840 Express](https://www.adafruit.com/product/4062) and adds a smorgasbord of sensors to make a great wireless sensor platform. This Feather microcontroller comes with Bluetooth® Low Energy and...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4516)
[Related Guides to the Product](https://learn.adafruit.com/products/4516/guides)
### USB cable - USB A to Micro-B
[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller
Approximately 3 feet / 1 meter long
In Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Adafruit Micro Lipo - USB LiIon/LiPoly charger
[Adafruit Micro Lipo - USB LiIon/LiPoly charger](https://www.adafruit.com/product/1304)
Oh so adorable, this is the tiniest little lipo charger, so handy you can keep it any project box! Its also easy to use. Simply plug in the gold plated contacts into any USB port and a 3.7V/4.2V lithium polymer or lithium ion rechargeable battery into the JST plug on the other end. There are...
In Stock
[Buy Now](https://www.adafruit.com/product/1304)
[Related Guides to the Product](https://learn.adafruit.com/products/1304/guides)
## Related Guides
- [Introducing the Adafruit nRF52840 Feather](https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather.md)
- [Adafruit Circuit Playground Bluefruit](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit.md)
- [Adafruit ItsyBitsy nRF52840 Express](https://learn.adafruit.com/adafruit-itsybitsy-nrf52840-express.md)
- [Introducing Adafruit CLUE](https://learn.adafruit.com/adafruit-clue.md)
- [Adafruit Feather nRF52840 Sense](https://learn.adafruit.com/adafruit-feather-sense.md)
- [MIDI for Makers](https://learn.adafruit.com/midi-for-makers.md)
- [Chameleon Scarf](https://learn.adafruit.com/chameleon-scarf.md)
- [Cyberpunk Santa Eye](https://learn.adafruit.com/cyberpunk-santa-eye.md)
- [Glowing Beehive Hairdo Wig](https://learn.adafruit.com/glowing-beehive-hairdo-wig.md)
- [CircuitPython BLE Heart Rate Zone Trainer Display](https://learn.adafruit.com/circuitpython-ble-heart-rate-monitor-gizmo.md)
- [NeoPixel Spats with Gemma and MakeCode](https://learn.adafruit.com/neopixel-spats.md)
- [Clue And MagTag Pep Talk Generator](https://learn.adafruit.com/clue-and-magtag-pep-talk-generator.md)
- [Zelda: Breath of the Wild – 3D Printed Guardian Sword with NeoPixel LEDs](https://learn.adafruit.com/breath-of-the-wild-guardian-sword-led-3d-printed.md)
- [Zelda Guardian Robot Terrako Companion](https://learn.adafruit.com/terrako.md)
- [Kaleidoscope Eyes (Trinket-Powered NeoPixel LED Ring Goggles)](https://learn.adafruit.com/kaleidoscope-eyes-neopixel-led-goggles-trinket-gemma.md)
- [Wireless Control Button for WLED Projects](https://learn.adafruit.com/wireless-control-button-for-wled-projects.md)
- [NeoPixel LED Heart Necklace](https://learn.adafruit.com/neopixel-led-heart-necklace.md)
- [CircusPython: Jump through Hoops with CircuitPython Bluetooth LE](https://learn.adafruit.com/circuspython-jump-through-hoops-with-bluetooth-le.md)
- [NeoPixel Infinity Mirror Coaster](https://learn.adafruit.com/infinity-mirror-coaster.md)