Libraries

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

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 more info in this guide.

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. In your operating system's file explorer/finder, you should see a new flash drive named CIRCUITPY. Save the code from Mu to the Itsy's CIRCUITPY drive as code.py

# 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 Feb 26, 2020.

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

Text editor powered by tinymce.