# BLE Beacon NeoPixels
## Overview
https://youtu.be/OveiOuSnRPM
We were inspired by the Disney MagicBand+ to build a pair of wearable mouse ears that light up in response to the same Bluetooth Low Energy broadcasts that drive the bands at the parks.
The ears listen for Disney's manufacturer advertisements and react in real time. When a MagicBand+ light command is sent, a Starlight Bubble Wand cast, or a Fab 50 statue beacon is detected nearby, the ears animate to match what's happening around them - including the fireworks at Magic Kingdom and Epcot.
This means you can use Disney products like the bubble wands to cast colors to our custom NeoPixel projects.
The wearable headbands are powered by a QT Py ESP32-S3 and a Lipo BFF, while a remote runs on the Adafruit CLUE.
We think this project could be adapted for accessibility projects like mobile scooters, wheelchairs or even strollers. We have a special "Find Me" beacon mode that could help you spot your accessible vehicles in dark and crowded areas.
There are two separate projects that run CircuitPython code. The Adafruit CLUE acts as a BLE remote that pulls from a list of commands that was captured from the Disney theme parks and ties them to LED animations. The TFT display on the CLUE shows a menu of animations to choose from and can send BLE commands to trigger the LEDs on Disney MagicBands and accessories.
## Parts
### Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT
[Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5426)
The ESP32-S3 has arrived in QT Py format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this QT Py is great for powering your IoT projects.
The ESP32-S3 is a highly-integrated,...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5426)
[Related Guides to the Product](https://learn.adafruit.com/products/5426/guides)
### Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py
[Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py](https://www.adafruit.com/product/5397)
[Is your QT Py all alone](https://www.adafruit.com/?q=qt+py&sort=BestMatch), lacking a friend to travel the wide world with? When you were a kid you may have learned about the "buddy" system, well this product is kinda like that! A board that will watch your QT...
In Stock
[Buy Now](https://www.adafruit.com/product/5397)
[Related Guides to the Product](https://learn.adafruit.com/products/5397/guides)
### NeoPixel Jewel - 7 x 5050 RGB LED with Integrated Drivers
[NeoPixel Jewel - 7 x 5050 RGB LED with Integrated Drivers](https://www.adafruit.com/product/2226)
Be the belle of the ball with the NeoPixel Jewel! We fit seven of our tiny 5050 (5mm x 5mm) smart RGB LEDs onto a beautiful, round PCB with mounting holes and a chainable design to create what we think is our most elegant (and evening-wear appropriate) NeoPixel board...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2226)
[Related Guides to the Product](https://learn.adafruit.com/products/2226/guides)
### Short Headers Kit for Feather - 12-pin + 16-pin Female Headers
[Short Headers Kit for Feather - 12-pin + 16-pin Female Headers](https://www.adafruit.com/product/2940)
These two **Short** **Female Headers** alone are, well, lonely. But pair them with any of our [Feather](https://www.adafruit.com/categories/777) boards and you're in business!
These headers are particularly cute and...
In Stock
[Buy Now](https://www.adafruit.com/product/2940)
[Related Guides to the Product](https://learn.adafruit.com/products/2940/guides)
### Short Feather Male Headers - 12-pin and 16-pin Male Header Set
[Short Feather Male Headers - 12-pin and 16-pin Male Header Set](https://www.adafruit.com/product/3002)
These two **Short** **Male Headers** alone are, well, lonely. But pair them with any of our [Feather](https://www.adafruit.com/categories/777) boards and you're in business!
In Stock
[Buy Now](https://www.adafruit.com/product/3002)
[Related Guides to the Product](https://learn.adafruit.com/products/3002/guides)
### Lithium Ion Polymer Battery - 3.7v 1200mAh
[Lithium Ion Polymer Battery - 3.7v 1200mAh](https://www.adafruit.com/product/258)
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 1200mAh for a total of about 4.5 Wh. If you need a larger battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/258)
[Related Guides to the Product](https://learn.adafruit.com/products/258/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...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4500)
[Related Guides to the Product](https://learn.adafruit.com/products/4500/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,
In Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long
[Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long](https://www.adafruit.com/product/3891)
For those who are fans of our silicone-covered wires, but are always looking to _up their wiring game_. We now have **Silicone Cover Ribbon cables!** These may look _a lot_ like
Out of Stock
[Buy Now](https://www.adafruit.com/product/3891)
[Related Guides to the Product](https://learn.adafruit.com/products/3891/guides)
# BLE Beacon NeoPixels
## Circuit Diagram
This provides a visual reference for wiring of the components. This diagram was created using [Fritzing software](http://fritzing.org/download/).
Some of the wiring can be reduced by sharing power and ground connections across the two NeoPixel Jewels with a ribbon cable.
Mickey Ear Wires Lengths:
Left ear: **24.5 cm**
Right ear (QT Py Case Side): **18.5 cm**
# BLE Beacon NeoPixels
## CircuitPython on CLUE
[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** flash drive to iterate.
The following instructions will show you how to install CircuitPython. If you've already installed CircuitPython but are looking to update it or reinstall it, the same steps work for that as well!
## Set up CircuitPython Quick Start!
Follow this quick step-by-step for super-fast Python power :)
[Download the latest version of CircuitPython for CLUE from circuitpython.org](https://circuitpython.org/board/clue_nrf52840_express/)
**Click the link above to download the latest version of CircuitPython for the CLUE.**
Download and save it to your desktop (or wherever is handy).
Plug your CLUE 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.**
Double-click the **Reset** button on the top (magenta arrow) on your board, and you will see the NeoPixel RGB LED (green arrow) turn green. If it turns red, check the USB cable, try another USB port, etc. **Note:** The little red LED next to the USB connector will pulse red. That's ok!
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 **CLUEBOOT**.
Drag the **adafruit-circuitpython-clue-etc.uf2** file to **CLUE**** BOOT.**
The LED will flash. Then, the **CLUEBOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
If this is the first time you're installing CircuitPython or you're doing a completely fresh install after erasing the filesystem, you will have two files - **boot\_out.txt** , and **code.py** , and one folder - **lib** on your **CIRCUITPY** drive.
If CircuitPython was already installed, the files present before reloading CircuitPython should still be present on your **CIRCUITPY** drive. Loading CircuitPython will not create new files if there was already a CircuitPython filesystem present.
That's it, you're done! :)
# BLE Beacon NeoPixels
## CLUE Code
This is the firmware that runs on the Adafruit CLUE - the BLE remote you carry to fire commands at the Beacon Ears or test new park signatures. It draws a category grid on the TFT, broadcasts BLE adverts when you select a command, and has a Listen Mode that captures unique Disney packets to a CSV file for reverse-engineering new park show codes.
To program your CLUE remote, click on the **Download Project Bundle** button in the window below. It will download to your computer as a zipped folder.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/code.py
The remote is split across six files. **code.py** drives the menu state machine and main loop. **command\_library.py** is the named catalog of all MagicBand+, wand, and ears-only commands. **magicband\_protocol.py** is shared with the receiver and provides the `build_*` helpers that turn palette indices and timing values into raw byte payloads. **ble\_transmitter.py** wraps `_bleio` to broadcast a payload as a BLE advert with the Disney CID. **ui.py** defines the four display views: a category grid, a scrollable command list, a confirm modal, and a listen capture view. **boot.py** handles the read-write filesystem flag for Listen Mode saves.
Plug your CLUE into your computer with a known-good USB cable. The **CIRCUITPY** drive should show up. Copy **code.py** , **boot.py** , **command\_library.py** , **magicband\_protocol.py** , **ble\_transmitter.py** , and **ui.py** to the root of the **CIRCUITPY** drive. Then copy the contents of the bundle's **lib** folder to the **lib** folder on your **CIRCUITPY** drive.
The required libraries are **adafruit\_debouncer.mpy** , **adafruit\_display\_shapes** , **adafruit\_display\_text** , and **adafruit\_lsm6ds** (for shake detection).
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/ui.py
### Three-View State Machine
The CLUE has a 240x240 TFT display. We use three view states swapped via `display.root_group`: a 4-tile category grid, a scrollable list of commands inside one category, and a confirm modal for shake-fired random commands. Each view is its own class in **ui.py** with its own `group` and `set_status()` method.
```
_STATE_GRID = 0
_STATE_LIST = 1
_STATE_CONFIRM = 2
```
The main loop calls one of three handler functions depending on the current state. Each handler reads button events, shake input, and returns the next state plus any pending command. The shape is `(next_state, last_shake_time, pending_command, return_state)`. This lets the confirm modal know which view to return to after a yes/no decision.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/command_library.py
### The Command Library
Every command the remote can broadcast lives as a tuple in **command\_library.py**. The shape is `(name, payload, needs_ping)` where `needs_ping` tells the transmitter whether to send a 0.5-second wake-ping before the real command to prime the band's receiver.
```
SHOW_FX = (
("Taste the Rainbow",
bytes.fromhex("e100e90c000f0f5d465bf005323748b0"), False),
("DCL Rainbow *",
bytes.fromhex("e100e90c000f0fa3afb5a3af307b7db7"), False),
("Ears Battery",
bytes.fromhex("aa4201"), False),
("Ears Brightness",
bytes.fromhex("aa4203"), False),
("Ears Statue",
bytes.fromhex("aa4205"), False),
("Listen Mode",
b"LISTEN", False),
)
```
Commands are grouped into four `CATEGORIES`: Colors, Show FX, Fades, and Animate. The grid view shows the category names. The list view shows the commands inside a category. To add a new captured packet to the menu, append a tuple to one of the category lists. The asterisk suffix on a command name marks ones that trigger the band's vibration motor - useful prep cue for the wearer.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/magicband_protocol.py
### Building a Color Command
Most commands are constructed at module load time using helper functions from **magicband\_protocol.py**. The single-color and dual-color builders take palette indices and produce the raw bytes the band's firmware expects.
```
DUAL_COLOR = (
("Red & Blue", build_dual_color(0x15, 0x02), True),
("Orange & Cyan", build_dual_color(0x13, 0x16), False),
("Pink & Lime", build_dual_color(0x08, 0x12), True),
("Purple & Yellow", build_dual_color(0x01, 0x0F), True),
...
)
```
Compare this with the firmware-baked `SHOW_FX` entries: those use raw `bytes.fromhex()` hex strings instead of helper builders, because their payloads are program IDs to specific firmware animations rather than synthesizable from palette indices.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/ble_transmitter.py
### Broadcasting a BLE Advert
The **ble\_transmitter.py** module wraps `_bleio.adapter` directly to send raw 31-byte BLE adverts. We don't go through `adafruit_ble`'s Advertisement classes because we need full control over the manufacturer-data bytes.
```
def broadcast(payload, duration=_BROADCAST_SECONDS):
packet = _build_advertisement(payload)
adapter = _bleio.adapter
if not adapter.enabled:
adapter.enabled = True
if adapter.advertising:
adapter.stop_advertising()
adapter.start_advertising(packet, connectable=False, interval=_AD_INTERVAL)
time.sleep(duration)
adapter.stop_advertising()
```
The default broadcast duration is 3 seconds. MagicBands latch a command within the first second, but the timing byte in the payload controls the actual fade so we can stop advertising well before the animation finishes. The ad interval is 25 milliseconds, the closest valid value to the BLE minimum that doesn't trip a CircuitPython float-precision edge case.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/CLUE_BLE_Beacon_Remote/boot.py
### Listen Mode
Holding A and B together for 0.8 seconds enters Listen Mode. The remote stops broadcasting, starts BLE scanning, and dedupes incoming Disney-CID packets into a dictionary keyed by raw payload bytes. When the user long-presses B to stop, the captures are written to **/captures/listen\_NNN.txt** on the **CIRCUITPY** drive.
```
def _listen_capture_loop(seen):
...
while True:
button_b.update()
if button_b.long_press:
break
try:
for entry in adapter.start_scan(
interval=0.04, window=0.04,
minimum_rssi=-100, timeout=0.2):
payload = _extract_disney_payload(entry.advertisement_bytes)
if payload is None:
continue
key = bytes(payload)
if key in seen:
seen[key][1] += 1
else:
seen[key] = [time.monotonic() - start_time, 1, entry.rssi]
finally:
adapter.stop_scan()
...
```
Filesystem writes from Python only work if **boot.py** remounted the **CIRCUITPY** drive as Python-writable. To switch into capture mode, drop a file named **capture\_mode.txt** on the drive and reset the CLUE - or let Listen Mode itself set the NVM flag and ask you to reset. To switch back to dev mode, delete the marker file via the REPL and reset.
### Shake-to-Fire
The CLUE's onboard LSM6DS33 accelerometer enables a fun shake-fire-random feature. The handler reads acceleration on every loop and triggers a confirm modal with a random command if the magnitude exceeds a threshold and a cooldown has elapsed.
```
def shake_magnitude():
x, y, z = accel.acceleration
return math.sqrt(x * x + y * y + z * z) - 9.81 # subtract gravity
if shake_magnitude() > _SHAKE_THRESHOLD and now - last_shake_time > _SHAKE_COOLDOWN:
_cat_idx, command = pick_random_command()
enter_confirm(command[0])
```
The threshold is in meters per second squared after subtracting earth's gravity. Adjust `_SHAKE_THRESHOLD` down if you want a softer shake to trigger, or up if you keep getting accidental fires while walking.
# BLE Beacon NeoPixels
## CircuitPython
[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.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
There are two versions of this board: one with 8MB Flash/No PSRAM and one with 4MB Flash/2MB PSRAM. Each version has their own UF2 build for CircuitPython. There isn't an easy way to identify which version of the board you have by looking at the board silk. If you aren't sure which version you have, try either build to see which one works.
Warning:
[Download the latest version of CircuitPython for the 8MB/No PSRAM version of this board via circuitpython.org](https://circuitpython.org/board/adafruit_qtpy_esp32s3_nopsram/)
[Download the latest version of CircuitPython for the 4MB/2MB PSRAM version of this board via circuitpython.org](https://circuitpython.org/board/adafruit_qtpy_esp32s3_4mbflash_2mbpsram/)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
Plug your board into your computer, using a known-good data-sync cable, directly, or via an adapter if needed.
Click the **reset** button once (highlighted in red above), and then click it again when you see the **RGB status LED(s)** (highlighted in green above) turn purple (approximately half a second later). Sometimes it helps to think of it as a "slow double-click" of the reset button.
If you do not see the LED turning purple, you will need to reinstall the UF2 bootloader. See the **Factory Reset** page in this guide for details.
On some very old versions of the UF2 bootloader, the status LED turns red instead of purple.
For this board, tap reset and wait for the LED to turn purple, and as soon as it turns purple, tap reset again. The second tap needs to happen while the LED is still purple.
Once successful, you will see the **RGB status LED(s)** turn green (highlighted in green above), and a disk drive ending in " **...BOOT**" should appear on your host computer. If you see red, try another port, or if you're using an adapter or hub, try without the hub, or different adapter or hub.
If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
Info:
You will see a new disk drive appear called **QTPYS3**** BOOT**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **QTPYS3BOOT**.
Copy or drag the UF2 file you downloaded to the **BOOT** drive.
The **BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it!
# BLE Beacon NeoPixels
## QT Py Code
This is the firmware that runs on the QT Py ESP32-S3 inside the ear headband. It scans for Disney BLE adverts, decodes them with a shared protocol module, and renders matching animations on the two NeoPixel Jewels.
To program your QT Py for the Beacon Ears, click on the **Download Project Bundle** button in the window below. It will download to your computer as a zipped folder.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/BLE_Beacon_Ears/code.py
Plug your QT Py ESP32-S3 into your computer with a known-good USB-C cable. The **CIRCUITPY** drive should show up as a USB drive. Copy **code.py** , **renderer.py** , **magicband\_protocol.py** , **pixel\_zones.py** , and **battery.py** to the root of the **CIRCUITPY** drive. Then copy the contents of the bundle's **lib** folder to the **lib** folder on your **CIRCUITPY** drive.
The required libraries are **adafruit\_debouncer.mpy** and **neopixel.mpy**.
### How It Works
The firmware is split across five files. **code.py** is the main scan-and-render loop. **magicband\_protocol.py** decodes Disney BLE packet bytes into structured command dicts. **renderer.py** turns those command dicts into per-frame animation states. **pixel\_zones.py** abstracts the two NeoPixel Jewels as left and right ear zones. **battery.py** reads the LiPo voltage divider so the on-demand battery animation knows what to show.
### Disney's BLE Manufacturer Adverts
Every MagicBand+, Starlight Bubble Wand, and Fab 50 statue at the parks broadcasts standard Bluetooth Low Energy advertisements with Disney's manufacturer company identifier (CID) `0x0183`. Any phone with a BLE scanner app can see these. The receiver listens for that CID and pulls out the manufacturer-data payload.
```
DISNEY_CID = 0x0183
```
Most of the original codes were documented at the [emcot.world](https://emcot.world/Disney_MagicBand%2B_Bluetooth_Codes) wiki. We extended the catalog with new captures from Magic Kingdom and Epcot using the CLUE remote's Listen Mode.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/BLE_Beacon_Ears/magicband_protocol.py
### The 32-Color Palette
MagicBand+ commands reference a fixed 5-bit palette built into the band's firmware. Most commands send palette indices rather than raw RGB values. We mirror the same palette in **magicband\_protocol.py** with calibrated RGB values that look right on a NeoPixel Jewel at low brightness.
```
PALETTE_RGB = (
(80, 255, 255), # 0x00 cyan (red boost so it's not pure teal)
(180, 0, 255), # 0x01 purple
(0, 0, 255), # 0x02 blue
(0, 20, 120), # 0x03 midnight blue
...
(0, 255, 0), # 0x19 green
(80, 255, 40), # 0x1A lime green
(255, 200, 180), # 0x1B white (warm white)
...
(255, 0, 255), # 0x1F random / magenta
)
```
Green and blue channels look brighter per unit input than red on WS2812B LEDs, so cyan values have their red channel boosted to compensate. White is biased warm to avoid a blue cast at low brightness levels. Edit `PALETTE_RGB` if you want to retune any colors for your specific Jewels.
### Decoding a Packet
The `parse()` function in **magicband\_protocol.py** takes a manufacturer-data payload and returns a dict describing what kind of command it is. The first byte of the payload selects the family. `0xCF` is a Starlight Bubble Wand cast. `0xC4` is a Fab 50 statue beacon. `0xCC` is the wake-ping that park beacons broadcast continuously. `0xE9` and `0xEA` are park show packets like Epcot's stage lighting. `0xE1` and `0xE2` wrap the most common guest-facing animation commands with a function code in bytes 2 and 3.
```
def parse(payload):
if not payload:
return None
wand = parse_wand(payload)
if wand is not None:
return wand
if _is_statue_beacon(payload):
return _parse_statue_beacon(payload)
return _parse_by_head(payload)
```
Each branch returns a dict like `{"kind": "single_color", "palette_idx": 0x15, "mask": 0, "timing": ..., "vibration": 0}`. The renderer never touches raw bytes - it dispatches on the `kind` field.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/BLE_Beacon_Ears/pixel_zones.py
### Stereo Ear Zones
The **pixel\_zones.py** module wraps the two NeoPixel Jewels as separate "zones" with the same minimal API.
```
zone.fill(rgb) # solid color across all pixels
zone.set_led(idx, rgb) # write a specific pixel
zone.count # number of pixels in the zone
zone.show() # flush to hardware
```
The renderer writes to both zones each frame and calls `show()` once at the end. Animations apply a stereo phase offset between the two zones so static colors get a gentle out-of-phase breathing animation and rotations get a left-leads-right sweep.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/BLE_Beacon_Ears/renderer.py
### Animation State Pattern
Every command renders through the same pattern in **renderer.py**. `for_command()` takes a parsed command dict and returns an animation state with three fields: a `duration_s`, a `render(zones, t)` function, and a `label` string for the serial log.
```
def _state_dual_color(command):
inner_rgb = magicband_protocol.PALETTE_RGB[command["inner_idx"]]
outer_rgb = magicband_protocol.PALETTE_RGB[command["outer_idx"]]
duration_s = command["timing"]["seconds"]
def render(zones, t):
for zone_idx, zone in enumerate(zones):
zone.set_led(0, inner_rgb)
phase_offset = 0.5 if zone_idx == 1 else 0.0
...
return {"duration_s": duration_s, "render": render, "label": "DUAL ..."}
```
The main loop calls `render(zones, t)` every frame, where `t` is seconds since the animation started. When `t` exceeds `duration_s`, the animation expires and the ears go idle until the next packet arrives.
### The Remote Command Sub-Protocol
The CLUE remote can fire four "ears-only" commands that don't render anything on real bands or wands - they only the ears recognize. The packet format uses the Disney CID with a custom `0xAA 0x42` prefix, followed by one byte that selects the command. Real bands and wands ignore packets they don't recognize, so this is safe to broadcast alongside MagicBand+ traffic.
```
REMOTE_COMMANDS = {
bytes.fromhex("aa4201"): "battery",
bytes.fromhex("aa4203"): "brightness",
bytes.fromhex("aa4204"): "find",
bytes.fromhex("aa4205"): "statue",
}
def remote_command(payload):
return REMOTE_COMMANDS.get(bytes(payload[:3]))
```
Add another command by appending an entry to the dict and a matching branch in the `if/elif` handler in **code.py**.
### Render Priority Chain
Each frame, the loop picks one source to render from a priority chain. Find Me beats everything because it's the most user-critical animation. Solo enter/exit indicators beat brightness flashes, which beat the battery-unavailable yellow pulse, which beats the battery display, which beats the active animation, which beats Solo Mode cycling, which beats idle. A real BLE packet can preempt Solo Mode mid-showpiece for park interaction without the user juggling modes.
```
if frame_t < find_mode_until:
...
elif frame_t < solo_indicator_until:
...
elif frame_t < brightness_flash_until:
...
elif frame_t < battery_display_until:
...
elif active_state is not None:
...
elif solo_mode:
...
else:
renderer.render_idle(zones)
```
# BLE Beacon NeoPixels
## 3D Printing
3MF files for 3D printing are oriented and ready to print on FDM machines using PLA filament. Original design source files may be downloaded using the links below.
[QT Py Case for Ears](https://a360.co/3R4A1L9)
[CLUE Remote Case](https://a360.co/3PBhiGv)
[BLE-Ears-STLs.zip](https://cdn-learn.adafruit.com/assets/assets/000/144/167/original/ble-ears-STL.zip?1779128725)
[CLUE +QT Py / Lipo BFF Cases 3MF](https://cdn-learn.adafruit.com/assets/assets/000/144/125/original/clue-qtpy-lipo-cases.3mf?1778598445)
Info: The dropdown on the Fusion 360 site allows you to pick your preferred 3D file format like STEP, STL, etc.
### Slice with settings for PLA material
The parts were sliced using BambuStudio using the slice settings below.
- PLA filament 220c extruder
- 0.2 layer height
- 10% gyroid infill
- 200mm/s print speed
- Tree Supports
- 60 C heated bed
The QT Py band is printed in TPU filament.
## Design Source Files
The project assembly was designed in Fusion 360. Once opened in Fusion 360, It can be exported in different formats like STEP, STL and more.
Electronic components like Adafruit's boards, displays, connectors and more can be downloaded from the [Adafruit CAD parts GitHub Repo](https://github.com/adafruit/Adafruit_CAD_Parts/).
# BLE Beacon NeoPixels
## Assemble QT Py + NeoPixels
## Short Headers and Sockets
We used short strips of socket headers on the QT Py to keep the circuit low-profile and project compact.
Yellow: When cutting headers to fit the QT Py boards, be sure to use eye protection. See the guide below about soldering headers.
### How To Solder Headers - Overview
[How To Solder Headers](https://learn.adafruit.com/how-to-solder-headers)
[Overview](https://learn.adafruit.com/how-to-solder-headers/overview)
## Plan Wires
You'll want to measure out your wire connections depending on where you want to install the NeoPixel LEDs and the QT Py. You can cut down on some of the wiring by sharing power and ground connections across the two NeoPixel Jewels with a ribbon silicone cable.
Mickey Ear Wires Lengths:
Left ear: **24.5 cm**
Right ear (QT Py Case Side): **18.5 cm**
## Solder Connections
The wired connections are soldered to the top of the QT Py with them running underneath the PCB.
## Sew Neopixels
The two mounting holes on the NeoPixel Jewels are then sewn to the fabric with a needle and thread.
Yellow: Be careful using hobby knives to avoid cuts. Younger makers should ask older folks to assist.
## Lipo Pocket
You can create a pocket for the Lipo battery by measuring and cutting a small slit on the side of the headbands with a hobby knife. These were big enough to fit a 1200mAh lipo battery.
## Lipo JST
You can route the battery cable in between the QTPy and LiPo BFF before plugging it into the JST port.
## Assemble QT Py case
The QT Py case snap fits together and features a cutout for connecting a flexible TPU band into the side of the case. The TPU band can be wrapped around the headband to attach them together.
## Place Slide Switch
A slide switch add-on piece lets you easily turn the circuit on and off.
## Press fit case
Align the wires to the cutouts on the case and press fit the two side together.
A piece of twisty tie wire can help to keep the cable taught to the headband.
# BLE Beacon NeoPixels
## Assemble Remote
The case for the CLUE features cutouts for the on-board buttons and display.
Plug the lipo battery JST into the port on the Clue.
## Place Lipo in Case
Align the lipo cable to the cutout inside the case.
## Lipo Battery Retainer
The retainer keeps the lipo battery mounted in place. Align the corner cutouts to the cable and carefully press into the walls in the case.
## Place CLUE
Gently guide the lipo cable to the left side of the case, avoiding the button presser on the case.
## Attach Cover
Peel the protective film off of the display.
Align the button cutout to the cover to press fit to the case.
# BLE Beacon NeoPixels
## Usage
# Using the Beacon Ears
The Beacon Ears system is two boards working together. The headband ears listen passively for Disney BLE adverts at home or in the parks. The CLUE remote sends commands to the ears and to nearby MagicBands, wands, and Fab 50 statues - or scoops up packets in Listen Mode for reverse-engineering new park show codes.
### Quick Reference - Beacon Ears (QT Py)
- **BOOT** single-press: cycle brightness (3 levels)
- **BOOT** double-press (Solo Mode only): skip to next showpiece
- **BOOT** triple-press: toggle Solo Mode on or off
- **BOOT** long-press (0.5s): show battery level
### Boot Up
Plug a LiPo battery into the JST connector on each board, or run them off USB. The Beacon Ears blink briefly through their idle frame and start listening immediately.
### Brightness Levels
Short-press the BOOT button on the QT Py to cycle through three brightness presets: dim, medium, bright. Each press shows a quick confirmation flash on the outer rings - one lit pixel for dim, two for medium, three for bright. The current preset persists until you press again or until the next reset.
### Battery Level
Long-press the BOOT button on the QT Py for half a second to show the current battery level. On USB power, both Jewels animate a swirling fill: a leading-edge pixel sweeps around the outer ring, leaving lit pixels behind it equal to the battery level. Five lit pixels means full, one means nearly empty. The animation holds with a gentle pulse, then fades to black.
On battery power, the same long-press shows a brief yellow center pulse instead. WS2812 LED timing is unreliable when the battery is sagging under animation current draw - the yellow pulse signals "plug in to USB to check level reliably" and saves the user from misreading a corrupted color.
### Solo Mode
Triple-press the BOOT button to enter Solo Mode. The ears flash a brief white burst, then start cycling through a curated reel of showpiece animations. The reel mixes synthesized highlights with real packets captured from Epcot's stage lighting - five-color rainbow rotations, dual-color combos, deep "Disney blue" 6-bit RGB, plus a handful of decoded park show captures.
Double-press BOOT during Solo Mode to skip the current showpiece and pick a new random one. Triple-press again to exit Solo Mode - the ears flash a cool blue pulse and return to listening.
A real Disney BLE packet preempts Solo Mode cleanly. If you walk past a Fab 50 statue or another guest's MagicBand fires while you're in Solo Mode, the ears interrupt the showpiece, render the park animation, then resume Solo cycling on the next pick. You don't have to manage modes manually for park interaction to work.
### Quick Reference - CLUE Remote
- **A** single-press: scroll up in list view
- **A** double-press: select / fire
- **A** triple-press: toggle silent mode
- **B** single-press: scroll down in list view
- **B** double-press: open category / back to grid
- **B** long-press (0.6s): cancel / send Off command
- **A and B** held together (0.8s): light sleep
- **Shake** : fire a random command (with confirm prompt)
### Boot Up
The CLUE shows the four-tile category grid: Colors, Show FX, Fades, Animate. The grid is the home view - everything starts here.
### The CLUE Display Grid
The grid view is the home screen. Four tiles - Colors, Show FX, Fades, Animate - cover the catalog of every command the remote can broadcast. The currently selected tile pulses magenta. Press A once to move the highlight forward, B once to move backward.
Double-press A to open the highlighted category. The display switches to a scrollable list view of every command in that category. Double-press B to go back to the grid.
### The CLUE Display List
The list view shows commands one per row at scale 2 if they fit, scale 1 if longer. The selected row is highlighted with a leading caret and magenta text. Press A or B once to scroll up or down. Press A twice to fire the selected command.
Some command names end with an asterisk - these trigger the band's haptic vibration motor and announce a brief buzz on the wearer's wrist. The asterisk is a heads-up to the remote operator that the command will physically vibrate any band that latches it.
Long-press B to broadcast the Off command and cancel any latched animation. Off has no pre-ping so the cancellation is immediate.
### Shake to Fire
The CLUE's onboard accelerometer detects a sharp shake and pops up a confirmation modal with a random command picked from the catalog. Double-press A to fire, B to cancel and return to the previous view. The shake threshold is calibrated for a deliberate motion - a normal walking pace won't trigger it, but a sharp wrist flick will.
### Find Me
Send the Find Me command from the CLUE to start a 30-second high-visibility beacon animation on the ears. The phases are a strobe at 5 Hz alternating white with rainbow colors, a rainbow chase rotating around each Jewel, and a slow rainbow breathing pulse. Brightness is forced to maximum for the duration regardless of the current preset, then restored when the animation ends. We think this works well for spotting a stroller, scooter, or wheelchair across a crowded parking lot.
### Display Sleep
The CLUE's TFT backlight auto-sleeps after 30 seconds of no button activity. Any button press wakes it instantly. The display sleep is the largest power saver on the CLUE - the backlight pulls 25 to 35 mA when on, dropping to near-zero when off.
### Light Sleep
Hold A and B together on the CLUE for 0.8 seconds to enter light sleep. The TFT backlight turns off, the speaker silences, and the BLE radio shuts down. Press either button to wake. Light sleep preserves Python state, so the selected category, silent mode, and any other settings persist through the sleep cycle.
### Statue Preview
Send the Statue command from the CLUE to fire the same golden swirl animation the ears play when they detect a real Fab 50 statue beacon. This is a four-second swirl with two breathing pulse beats and white sparkles tinted gold. Useful for video shoots, demos, or just enjoying the surprise without hunting down a statue.
### Silent Mode
Triple-press the A button on the CLUE to toggle silent mode. With silent mode on, the chime that plays after every command fire is suppressed - the ears still react to broadcasts, just without the audible feedback from the remote. Useful in quiet spaces or when filming.
### Listen Mode
Listen Mode is a sentinel command in the Show FX category. Selecting it switches the CLUE from broadcasting to BLE scanning. The capture view shows the elapsed seconds, the count of unique payloads seen, and the total payload count. Every unique Disney-CID packet within the receive window gets logged with a first-seen timestamp, count, and last RSSI.
Long-press B to stop the capture. If the **CIRCUITPY** drive is mounted Python-writable, the captures save to **/captures/listen\_NNN.txt** - tap B once more to dismiss the save confirmation. If the drive is host-mounted (the default when USB is connected), the CLUE sets a flag in non-volatile memory and asks for a reset to switch into capture mode for the next boot.
To switch back to dev mode after capturing, open the serial REPL and run `import os; os.remove("/capture_mode.txt")`, then reset the CLUE. The drive returns to host-writable so you can drag-drop new code onto it.
## Featured Products
### Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT
[Adafruit QT Py ESP32-S3 WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5426)
The ESP32-S3 has arrived in QT Py format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this QT Py is great for powering your IoT projects.
The ESP32-S3 is a highly-integrated,...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5426)
[Related Guides to the Product](https://learn.adafruit.com/products/5426/guides)
### Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py
[Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py](https://www.adafruit.com/product/5397)
[Is your QT Py all alone](https://www.adafruit.com/?q=qt+py&sort=BestMatch), lacking a friend to travel the wide world with? When you were a kid you may have learned about the "buddy" system, well this product is kinda like that! A board that will watch your QT...
In Stock
[Buy Now](https://www.adafruit.com/product/5397)
[Related Guides to the Product](https://learn.adafruit.com/products/5397/guides)
### NeoPixel Jewel - 7 x 5050 RGB LED with Integrated Drivers
[NeoPixel Jewel - 7 x 5050 RGB LED with Integrated Drivers](https://www.adafruit.com/product/2226)
Be the belle of the ball with the NeoPixel Jewel! We fit seven of our tiny 5050 (5mm x 5mm) smart RGB LEDs onto a beautiful, round PCB with mounting holes and a chainable design to create what we think is our most elegant (and evening-wear appropriate) NeoPixel board...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2226)
[Related Guides to the Product](https://learn.adafruit.com/products/2226/guides)
### Lithium Ion Polymer Battery - 3.7v 1200mAh
[Lithium Ion Polymer Battery - 3.7v 1200mAh](https://www.adafruit.com/product/258)
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 1200mAh for a total of about 4.5 Wh. If you need a larger battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/258)
[Related Guides to the Product](https://learn.adafruit.com/products/258/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...
Out of Stock
[Buy Now](https://www.adafruit.com/product/4500)
[Related Guides to the Product](https://learn.adafruit.com/products/4500/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,
In Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long
[Silicone Cover Stranded-Core Ribbon Cable - 4 Wires 1 Meter Long](https://www.adafruit.com/product/3891)
For those who are fans of our silicone-covered wires, but are always looking to _up their wiring game_. We now have **Silicone Cover Ribbon cables!** These may look _a lot_ like
Out of Stock
[Buy Now](https://www.adafruit.com/product/3891)
[Related Guides to the Product](https://learn.adafruit.com/products/3891/guides)
### Short Feather Male Headers - 12-pin and 16-pin Male Header Set
[Short Feather Male Headers - 12-pin and 16-pin Male Header Set](https://www.adafruit.com/product/3002)
These two **Short** **Male Headers** alone are, well, lonely. But pair them with any of our [Feather](https://www.adafruit.com/categories/777) boards and you're in business!
In Stock
[Buy Now](https://www.adafruit.com/product/3002)
[Related Guides to the Product](https://learn.adafruit.com/products/3002/guides)
## Related Guides
- [Introducing Adafruit CLUE](https://learn.adafruit.com/adafruit-clue.md)
- [Adafruit LiIon or LiPoly Charger BFF Add-On for QT Py](https://learn.adafruit.com/adafruit-qt-py-charger-bff.md)
- [Adafruit QT Py ESP32-S3](https://learn.adafruit.com/adafruit-qt-py-esp32-s3.md)
- [3D Scans for Low Poly Statues](https://learn.adafruit.com/low-poly-3d-scans-for-3d-printing.md)
- [CircuitPython CLUE I Ching Caster](https://learn.adafruit.com/clue-i-ching-caster.md)
- [AdaBox 015](https://learn.adafruit.com/adabox015.md)
- [Overwatch Prop Gun: Lucio's Blaster Pt. 3](https://learn.adafruit.com/overwatch-prop-gun-lucios-blaster-pt-3.md)
- [Digital Nose Milk Freshness Checker](https://learn.adafruit.com/digital-nose-gas-sensor-milk-freshness-checker.md)
- [NeoPixel LED Necklace Insert with USB Charging](https://learn.adafruit.com/neopixel-led-necklace-insert-with-usb-charging.md)
- [PyLeap BLE Controlled NeoPixels with CLUE](https://learn.adafruit.com/pyleap-ble-controlled-neopixels-with-clue.md)
- [Adafruit IO Home: Lights and Temperature ](https://learn.adafruit.com/adafruit-io-house-lights-and-temperature.md)
- [CLUE Custom CircuitPython Badge](https://learn.adafruit.com/clue-custom-circuit-python-badge.md)
- [PyLeap CLUE Custom Conference Badge](https://learn.adafruit.com/pyleap-clue-custom-conference-badge.md)
- [ulab: Crunch Numbers fast in CircuitPython](https://learn.adafruit.com/ulab-crunch-numbers-fast-with-circuitpython.md)
- [¡Bienvenido a CircuitPython!](https://learn.adafruit.com/bienvenido-a-circuitpython-2.md)
- [CLUE Altimeter](https://learn.adafruit.com/clue-altimeter.md)
- [Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge](https://learn.adafruit.com/bluetooth-le-broadcastnet-sensor-node-raspberry-pi-wifi-bridge.md)
- [Karel The Robot In CircuitPython](https://learn.adafruit.com/karel-the-robot-in-circuitpython.md)