circuitpython ble advertising beacons · listening. this often takes the form of a mobile device...

CircuitPython BLE Advertising BeaconsCreated by John Park

Last updated on 2020-10-26 05:31:44 PM EDT

Overview

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 tousers 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 isdesirable, 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, acustom version for the CLUE board that also shows QR codes and allows you to scroll among multiple beacon URLchoices to advertise!

Parts

All you need to advertise your own BLE beacons is any Adafruit Bluefruit nRF52840 board:

© Adafruit Industries https://learn.adafruit.com/circuitpython-ble-advertising-beacons Page 3 of 27

https://www.adafruit.com/product/4481








Adafruit ItsyBitsy nRF52840 Express - Bluetooth LE

$17.95IN STOCK

Add To Cart

Your browser does not support the video tag. Adafruit CLUE - nRF52840 Express with Bluetooth LE

$39.95IN STOCK

Add To Cart

Adafruit Feather nRF52840 Express

$24.95IN STOCK

Add To Cart

Circuit Playground Bluefruit - Bluetooth Low Energy

OUT OF STOCK

Out Of Stock










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

$2.95IN STOCK

Add To Cart

Lithium Ion Polymer Battery - 3.7v 500mAh

$7.95IN STOCK

Add To Cart

Adafruit Micro Lipo - USB LiIon/LiPoly charger

$5.95IN STOCK

Add To Cart








Additionally, you'll need a mobile device running an Eddystone beacon discovery app, such as Physical Web:

Physical Web for iOS (https://adafru.it/Je7)Physical Web for Android (https://adafru.it/Je8)

Adafruit LiIon/LiPoly Backpack Add-On for ProTrinket/ItsyBitsy

$4.95IN STOCK

Add To Cart




https://apps.apple.com/us/app/physical-web/id927653608

https://play.google.com/store/apps/details?id=com.physicalweb&hl=en_US

Understanding BLE AdvertisingBeacons

Bluetooth LC beacons are low power devices that are used to broadcast a tiny amount of data to any device that'slistening. This often takes the form of a mobile device running an app, such as Physical Web, that can read thebeacon'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 theEddystone 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), andanother 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 ispretty much just always sitting there yelling, "Hey! I'm a beacon! This is my name, and this is a URL I think you shouldvisit!"

Other Uses

This guide focuses solely on using beacons to advertise a URL, however there are a few other common uses forbeacons. These include indoor navigation, tracking (such as lost key finders like Tile), and interaction notifications,such as interactive museum tours.


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 properlibraries and code to use on the Itsy, but you can apply these instructions to the Feather nRF52840, Circuit PlaygroundBluefruit, or CLUE boards as well by downloading the appropriate version of CircuitPython for those boards.


CircuitPython for ItsyBitsy nRF52840 ExpressCircuitPython (https://adafru.it/tB7) is a derivative of MicroPython (https://adafru.it/BeZ) designed to simplifyexperimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping byrequiring 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 :)

https://adafru.it/Ie7

https://adafru.it/Ie7

Further Information

For more detailed info on installing CircuitPython, check out Installing CircuitPython (https://adafru.it/Amd).

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!


https://github.com/adafruit/circuitpython

https://micropython.org

https://circuitpython.org/board/itsybitsy_nrf52840_express/

https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython

https://learn.adafruit.com//assets/87069


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 Libraries

Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython is so simpleto use is that most of that information is stored in other files and works in the background. These files are calledlibraries. Some of them are built into CircuitPython. Others are stored on your CIRCUITPY drive in a folder called lib.Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storingcode separately from the firmware makes it easier to update both the code you write and the libraries you depend.

Your board may ship with a lib folder already, it's in the base directory of the drive. If not, simply create the folderyourself. When you first install CircuitPython, an empty lib directory will be created for you.

CircuitPython libraries work in the same way as regular Python modules so the Python docs (https://adafru.it/rar) are agreat reference for how it all should work. In Python terms, we can place our library files in the lib directory because itspart of the Python path by default.

One downside of this approach of separate libraries is that they are not built in. To use them, one needs to copy themto the CIRCUITPY drive before they can be used. Fortunately, we provide a bundle full of our libraries.

Our bundle and releases also feature optimized versions of the libraries with the .mpy file extension. These files takeless space on the drive and have a smaller memory footprint as they are loaded.

Installing the CircuitPython Library Bundle

We're constantly updating and improving our libraries, so we don't (at this time) ship our CircuitPython boards with the

As we continue to develop CircuitPython and create new releases, we will stop supporting older releases. Visit https://circuitpython.org/downloads to download the latest version of CircuitPython for your board. You must download the CircuitPython Library Bundle that matches your version of CircuitPython. Please update CircuitPython and then visit https://circuitpython.org/libraries to download the latest Library Bundle.

�


https://circuitpython.org/downloads

https://circuitpython.org/libraries

https://docs.python.org/3/tutorial/modules.html

full library bundle. Instead, you can find example code in the guides for your board that depends on external libraries.Some of these libraries may be available from us at Adafruit, some may be written by community members!

Either way, as you start to explore CircuitPython, you'll want to know how to get libraries on board.

You can grab the latest Adafruit CircuitPython Bundle release by clicking the button below.

Note: Match up the bundle version with the version of CircuitPython you are running - 3.x library for running anyversion of CircuitPython 3, 4.x for running any version of CircuitPython 4, etc. If you mix libraries with majorCircuitPython versions, you will most likely get errors due to changes in library interfaces possible during major versionchanges.

https://adafru.it/ENC

https://adafru.it/ENC

If you need another version, you can also visit the bundle release page (https://adafru.it/Ayy) which will let you selectexactly what version you're looking for, as well as information about changes.

Either way, download the version that matches your CircuitPython firmware version. If you don't know the version,look at the initial prompt in the CircuitPython REPL, which reports the version. For example, if you're running v4.0.1,download the 4.x library bundle. There's also a py bundle which contains the uncompressed python files, you probablydon't want that unless you are doing advanced work on libraries.

After downloading the zip, extract its contents. This is usually done by double clicking on the zip. On Mac OSX, itplaces the file in the same directory as the zip.

Open the bundle folder. Inside you'll find two information files, and two folders. One folder is the lib bundle, and theother folder is the examples bundle.


https://circuitpython.org/libraries

https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest/

Now open the lib folder. When you open the folder, you'll see a large number of mpy files and folders

Example Files

All example files from each library are now included in the bundles, as well as an examples-only bundle. These areincluded for two main reasons:

Allow for quick testing of devices.Provide an example base of code, that is easily built upon for individualized purposes.

Copying Libraries to Your Board

First you'll want to create a lib folder on your CIRCUITPY drive. Open the drive, right click, choose the option to createa new folder, and call it lib. Then, open the lib folder you extracted from the downloaded zip. Inside you'll find anumber of folders and .mpy files. Find the library you'd like to use, and copy it to the lib folder on CIRCUITPY.

This also applies to example files. They are only supplied as raw .py files, so they may need to be converted to .mpyusing the mpy-cross utility if you encounter MemoryErrors . This is discussed in the CircuitPython Essentials

Guide (https://adafru.it/CTw). Usage is the same as described above in the Express Boards section. Note: If you do notplace examples in a separate folder, you would remove the examples from the import statement.

Example: ImportError Due to Missing Library

If a library has multiple .mpy files contained in a folder, be sure to copy the entire folder to CIRCUITPY/lib.�


https://learn.adafruit.com/circuitpython-essentials/circuitpython-expectations#how-can-i-create-my-own-mpy-files-18-6

If you choose to load libraries as you need them, you may write up code that tries to use a library you haven't yetloaded. We're going to demonstrate what happens when you try to utilise a library that you don't have loaded on yourboard, and cover the steps required to resolve the issue.

This demonstration will only return an error if you do not have the required library loaded into the lib folder on yourCIRCUITPY drive.

Let's use a modified version of the blinky example.

import boardimport timeimport simpleio

led = simpleio.DigitalOut(board.D13)

while True: led.value = True time.sleep(0.5) led.value = False time.sleep(0.5)

Save this file. Nothing happens to your board. Let's check the serial console to see what's going on.

We have an ImportError . It says there is no module named 'simpleio' . That's the one we just included in our code!

Click the link above to download the correct bundle. Extract the lib folder from the downloaded bundle file. Scrolldown to find simpleio.mpy. This is the library file we're looking for! Follow the steps above to load an individual libraryfile.

The LED starts blinking again! Let's check the serial console.


No errors! Excellent. You've successfully resolved an ImportError !

If you run into this error in the future, follow along with the steps above and choose the library that matches the oneyou're missing.

Library Install on Non-Express Boards

If you have a Trinket M0 or Gemma M0, you'll want to follow the same steps in the example above to install libraries asyou need them. You don't always need to wait for an ImportError as you probably know what library you added to

your code. Simply open the lib folder you downloaded, find the library you need, and drag it to the lib folder on yourCIRCUITPY drive.

You may end up running out of space on your Trinket M0 or Gemma M0 even if you only load libraries as you needthem. There are a number of steps you can use to try to resolve this issue. You'll find them in the Troubleshootingpage in the Learn guides for your board.

Updating CircuitPython Libraries/Examples

Libraries and examples are updated from time to time, and it's important to update the files you have on yourCIRCUITPY drive.

To update a single library or example, follow the same steps above. When you drag the library file to your lib folder, itwill ask if you want to replace it. Say yes. That's it!

A new library bundle is released every time there's an update to a library. Updates include things like bug fixes andnew features. It's important to check in every so often to see if the libraries you're using have been updated.


Simple Beacon Code in CircuitPython

LibrariesOnce your ItsyBitsy nRF52840 is set up with

CircuitPython, we'll add libraries from the bundle. You

can read up on how to download libraries

here (https://adafru.it/ABU).

From the library bundle, transfer these libraries onto the

Itsy's /lib directory on the CIRCUITPY drive:

adafruit_ble

adafruit_ble_eddystone

Text Editor

Adafruit recommends using the Mu editor for using your CircuitPython code with Adafruit boards. You can get moreinfo in this guide (https://adafru.it/ANO).

Alternatively, you can use any text editor that saves files.

Code.py

Copy the code shown below, paste it into Mu. Plug your ItsyBitsy into your computer via a known good USB cable. Inyour operating system's file explorer/finder, you should see a new flash drive named CIRCUITPY. Save the code fromMu to the Itsy's CIRCUITPY drive as code.py



https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries

https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor

"""This example broadcasts our Mac Address as our Eddystone ID and a link to the Adafruit Discord server."""

import time

import adafruit_blefrom adafruit_ble_eddystone import uid, url

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")

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)

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.

import time import adafruit_blefrom 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 BLEradio.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 shortenerservice, such as bit.ly.


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")

Advertising

With setup complete, the main, ever-repeating loop of the code now takes over. Here, we alternate betweenadvertising the beacon's UID and the beacon's URL, pause for four seconds, and repeat.

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 yourmobile 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.

You may get away with a longer URL than you think you should -- this is because for certain common URL prefixes ('https://www.' for example) and domains ('.com', '.org', etc.) we substitute them for a single non-printing byte.

�


https://www

That's all there is to it! Next we'll create a more sophisticated version on the CLUE.


CLUE Beacon

First, set up CircuitPython on the CLUE following the instructions on this page (https://adafru.it/Jab).

LibrariesNext, install the libraries needed. This guide

page (https://adafru.it/Jb9) 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 moreinfo in this guide (https://adafru.it/ANO).


https://learn.adafruit.com/adafruit-clue/circuitpython


https://learn.adafruit.com/adafruit-clue/clue-circuitpython-libraries

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 embedbelow. 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

"""Eddystone Beacon for CLUEThis example broadcasts our Mac Address as our Eddystone ID and a link to a URL of your choice.Hold the A button to display QR code, use B button to pick URL from the list."""

import timefrom adafruit_pybadger import pybadgerimport adafruit_blefrom adafruit_ble_eddystone import uid, url

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

pybadger.play_tone(1600, 0.25)pybadger.show_business_card(image_name="cluebeacon.bmp")

while True: pybadger.auto_dim_display(delay=3, movement_threshold=4) eddystone_url = url.EddystoneURL(ad_url[pick][0])

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

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)

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")


pybadger.show_business_card(image_name="cluebeacon.bmp") time.sleep(0.1)

# 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)

How It Works

Like the simple example before, we will import libraries for time, ble, and eddystone support. We will also import theadafruit_pybadger library which makes it convenient to use the buttons, speaker, and screen on the CLUE.

import timefrom adafruit_pybadger import pybadgerimport adafruit_blefrom 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.


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.

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 movementthreshold 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.

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.

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 thepybadger.show_business_card() command.

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.

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 theURL is, and this repeats every second.

# 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 UsagePower up the CLUE and you'll see the welcome screen.



Pick Beacon AdvertismentPress 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 CodePress 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.

NOTE: Depending on the beacon app you're running, you may need to refresh or delete the beacon cache in order to see the changed advertisement URL show up.�



circuitpython ble advertising beacons · listening. this often takes the form of a mobile device...

Documents