Text Editor

Adafruit recommends using the Mu editor for using your CircuitPython code with Adafruit boards. You can get more info in this guide.

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:

CIRCUITPY
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

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

import time

import adafruit_ble
from 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_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.

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

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.

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.

This guide was first published on Feb 26, 2020. It was last updated on Jul 16, 2024.

This page (Simple Beacon Code in CircuitPython) was last updated on Jul 15, 2024.

Text editor powered by tinymce.