Operations Manual for the Whistling Birds Prop
This page covers normal operational uses, configuration settings, what normal behavior looks and sounds like, and what to check when something seems off.
This is the owner’s manual for the Whistling Birds prop. It covers daily use, configuration, troubleshooting, and safety.
Quick Start
The daily use flow in six steps. Practice this sequence on a table before wearing the gauntlet.
- Power on. Connect battery or USB-C. If the prop has a power switch, flip it ON. The dart-tip LEDs will fade in and out once and you’ll hear a boot sound — that means the firmware is running.
- Arm. Pass the hand-plate magnet over the reed switch. Darts extend row by row.
- Choose salvo size. Tilt the front / nozzle end up or down to cycle through the configured salvo sizes.
- Fire. Roll the gauntlet sideways to fire the current salvo.
- Disarm. Trigger the magnet again. Darts retract in reverse order.
- Power off. Flip the switch OFF or disconnect USB-C.
Before First Use
Run through these checks once before the first power-on. Most issues trace back to a loose connection.
Normal Operation
Power and Charging
The prop runs from a supported Adafruit LiPo battery or from USB-C power.
- LiPo battery: Best for untethered wear and demos. Expect 4–6 hours of runtime depending on LED brightness and activation frequency.
- USB-C power: Use any standard USB-C power pack or wall outlet.
- Power switch: Toggles the unit on and off.
- Charging: Plug the prop into USB-C to charge the LiPo (if installed). The battery charges whether the prop is on or off.
Charging Overlay
When you plug in USB-C while the prop is on, a charging animation takes over the LEDs. A comet pattern lights up a number of LEDs proportional to the current charge level, and the color shifts from red to yellow to green as the battery fills.
- Unplug USB to dismiss the animation and return to the previous power state.
- Trigger the magnet during the animation to exit charging view and disarm.
- If the prop was off before you plugged in, it stays off when you unplug — it does not auto-arm.
Arm and Disarm
The magnetic sensor is the only arm and disarm trigger. Arming extends the dart rows in sequence; disarming retracts them in reverse.
| Action | How | What happens |
|---|---|---|
| Arm | Pass the magnet over the reed switch | Outer row extends, then middle, then center |
| Disarm | Trigger the magnet again while armed | Center retracts, then middle, then outer |
| Enter config | Hold magnet ~2 seconds while disarmed | Darts extend and menu navigation begins |
Salvo Selection and Firing
Firing and salvo control use tilt gestures while the prop is armed.
| Gesture | Behavior |
|---|---|
| Roll the gauntlet sideways | Fire the current salvo |
| Tilt the front / nozzle end upward | Increase salvo size |
| Tilt the front / nozzle end downward | Decrease salvo size |
Salvo sizes come from the SALVO_SIZES list in config.py on the CIRCUITPY drive. The prop cycles through that list in the exact order you write it, so you can add or remove values, put them in any order, and even repeat a value if you want it to come up more than once while cycling. A value of 0 means row mode (fires one full row per trigger). Other values fire that number of individual darts per trigger.
After a salvo fires
Each fired dart flashes white with a missile sound, then the servo retracts the spent row. After the salvo completes, the fired LEDs pulse with a dim afterburner glow (the color is configurable in the settings menu) before switching off.
All darts depleted
When every dart has been fired, the system logs the depletion internally and powers down automatically. This is intentional, not a malfunction. To reset: trigger the magnet once. The magnetic reset clears the depleted flag so you can arm and fire again normally.
Firing modes
The prop now stores firing behavior as a Firing Mode selection in the config menu:
| Mode | How it behaves while armed |
|---|---|
| Off | Firing gestures are disabled. The prop stays armed but will not fire until you pick tilt or shake again. |
| Tilt | Tilt left or right fires. Tilt up increases salvo size. Tilt down decreases salvo size. |
| Shake | Shake fires. Tilt left increases salvo size. Tilt right decreases salvo size. |
The selected firing mode persists when storage is writable, so the prop comes back in the same mode on the next startup.
Configuration Mode
Configuration mode lets you change settings without editing files. With the prop disarmed, hold the magnetic trigger for about 2 seconds to enter it. The menu always opens on Battery Level first, so the first LED behavior you see is the battery preview. The menu exits automatically after 15 seconds of inactivity — any gesture resets the timer.
| Gesture | Behavior |
|---|---|
| Tilt left | Previous menu item |
| Tilt right | Next menu item |
| Tilt up | Select / confirm |
| Tilt down | Exit configuration mode |
What you will see and hear
The menu gives both LED and speaker feedback, so you do not have to guess whether the prop registered your input.
- On entry: Battery Level opens first. The LEDs immediately show the live battery preview instead of a numbered menu flash.
- When you tilt left or right: The prop plays the navigation click, flashes the selected item’s color twice, then returns to the numbered idle menu view.
- When you tilt up: The prop plays the menu-select tone, then opens that item or starts the selected action.
- Inside a selector: Every option change updates the LEDs live. Saving plays the confirmation tone. Cancelling with tilt down returns to the previous menu without changing the saved value.
- If you stop moving: The prop stays in the current menu view for about 15 seconds, then exits configuration mode automatically.
Menu items and feedback details
The dart-tip LEDs tell you where you are in the menu before you select anything. After the initial battery preview, the menu uses the afterburner color to count out the menu number with highlighted LEDs. If you lose track of where you are, stop moving and watch the LEDs before selecting.
Submenu interaction
When you navigate to a menu item and tilt up, you enter that item’s submenu. Inside a submenu, the prop shows the option live instead of the numbered menu view:
| Gesture | Behavior |
|---|---|
| Tilt left / right | Cycle through options (e.g., colors) |
| Tilt up | Confirm and save the current selection |
| Tilt down | Cancel and return to the menu (no change) |
| Item | # | What it does and what the LEDs show |
|---|---|---|
| Battery Level | 1 | This is always the first item on entry. The LEDs immediately show the battery or USB-only preview. On battery power the color is red below 30%, yellow from 30–70%, and green above 70%, with more LEDs lit as charge rises. USB-only shows blue. |
| Firing Mode | 2 | Choose between Off, Tilt, and Shake. Off blocks firing while leaving the prop armed. Tilt and Shake remap the active firing gestures. The selector shows solid red for Off, blue for Tilt, and green for Shake while you cycle. |
| Idle Animation | 3 | Preview the available armed idle animations live on the LEDs, then save the one you want running while armed. Cycling plays the navigation click; saving plays the confirmation tone. |
| Dart Tip Color | 4 | Cycle through available dart-tip colors. The LEDs hold the currently previewed color while you browse; saving blinks the selected color three times and plays the confirmation tone. |
| Afterburner Color | 5 | Same interaction as Dart Tip Color, applied to the post-fire afterburner glow. The LEDs stay on the candidate color while you cycle so you can judge it before saving. |
| Volume | 6 | Cycle through 13 audio levels from mute to full. The LEDs act as a level meter — the count of lit LEDs rises with the volume — and the color shifts from red at mute, through orange, yellow, and green, finishing white at maximum. The navigation tone plays at the previewed level on every cycle so you can judge it by ear. Saving plays the confirmation tone; cancelling restores the previous level. |
| Demo Mode | 7 | Starts the automated showcase sequence immediately (see below). The menu preview flashes the Demo Mode color first, then the prop transitions into the demo loop. |
Idle animation options
The Idle Animation menu offers seven looping patterns that play on the dart-tip LEDs while the prop is armed. Most patterns adapt to your saved Dart Tip Color as the primary tone and the Afterburner Color as the accent — change those colors and every animation reskins automatically. Rainbow is the exception and always runs the full spectrum.
| Animation | What you see on the LEDs |
|---|---|
| Solid Primary | Every active LED holds the dart-tip color steady — no motion. This is the lowest-power option; the prop drops into adaptive sleep between updates while it is selected. Default on a fresh install. |
| Breathing | All LEDs inhale and exhale together in the dart-tip color over roughly a one-second cycle, fading between dim and full brightness. |
| Scanner | A bright head in the afterburner color sweeps back and forth across the strip, leaving a soft trail. The dart-tip color sits behind it as a dim background. |
| Orbit | An accent-colored dot rotates around the ring while a half-blended counter-dot tracks the opposite side. Travels at about four LEDs per second over a soft primary glow. |
| Heat Pulse | A travelling shimmer blends the primary and accent colors in a phase-shifted wave across each LED — reads like rippling heat or a slow plasma roll. |
| Sparkle | A dim primary base with bright white pops appearing on random LEDs many times per second. Subtle at low brightness, festive when cranked up. |
| Rainbow | The full color wheel spread evenly across the LEDs, scrolling continuously around the ring. Ignores the dart-tip and afterburner color settings. |
config.py File Settings
Settings not reachable through the on-device menu are configured by editing config.py at the root of the CIRCUITPY drive in any text editor. Changes take effect on the next power cycle.
| Setting | Default | What it controls |
|---|---|---|
| Visual effects | ||
DART_TIP_COLOR |
“blue” |
LED color on the dart tips when armed and extended. Valid names are listed in lib/neopixel_control.py. |
AFTERBURNER_COLOR |
“red” |
Post-fire afterburner glow color. Valid names are listed in lib/neopixel_control.py. |
DART_COLOR_CYCLE |
[“red”, “orange”, …] |
Color list available in the on-device color selector menus. Add, remove, or reorder names to customize the cycle. |
SELECTED_ANIMATION |
“solid_primary” |
Default idle LED animation while armed. |
| Firing configuration | ||
SALVO_SIZES |
[0, 1, 4, 12] |
Ordered darts-per-trigger list. The prop cycles through entries exactly as written, so you can use values from 0–12 in any order and repeat values if you want. 0 fires one full row; other values fire that number of individual darts. |
DARTS_PER_SALVO |
0 |
Startup salvo size. Must match a value present in SALVO_SIZES. 0 starts in row-firing mode. |
| Gesture sensitivity | ||
TILT_THRESHOLD |
5.0 |
Angle in degrees needed to register a tilt gesture. Lower = more sensitive. Range: 1.0–10.0. |
SHAKE_THRESHOLD |
15 |
Sensitivity for shake detection. Lower = more sensitive. Range: 5–50. |
TAP_THRESHOLD |
127 |
Sensitivity for tap detection. Lower = more sensitive. Range: 20–127. |
FIRE_WITH_SHAKE |
False |
Initial firing gesture on startup. True fires with shake; False fires with tilt. Also changeable in the on-device menu. |
| Demo mode | ||
DEMO_MODE_TIMEOUT |
0 |
Seconds before demo mode auto-exits. 0 disables the timeout. Range: 0–3600. |
DEMO_BRIGHTNESS |
0.5 |
LED brightness during demo mode. Range: 0.0–1.0. |
| Advanced | ||
_SERVO_ANGLES |
[0, 50, 100, 150] |
Servo positions for Off, Outer row, Middle row, and Inner row. Some v2 builds need [0, 70, 120, 180] instead, depending on how the timing gear seats during assembly — see the v2 changelog for context. |
AUDIO_LEVEL |
1 |
Sound effect volume. Range: 0.0 (muted) to 1.0 (maximum). Also adjustable on-device through the Volume menu item. |
DEBUG_MODE |
False |
Enables serial console debug output. Set True only when diagnosing firmware issues. |
Demo Mode
Demo mode is for conventions, display tables, and photos. It cycles through features automatically so you do not have to fire each sequence manually.
- The demo loop cycles through salvo sizes with randomized colors, firing and retracting automatically.
- LED brightness drops to 50% during the demo to conserve battery.
- Stop it early by triggering the magnetic sensor at any time. Your saved dart color, afterburner color, and salvo size are fully restored on exit.
What Normal Behavior Looks Like
These are not problems. If you see any of the following, the prop is working as designed.
- Boot LED fade and sound. On power-up the dart-tip LEDs fade in and out once and you hear a short power-up tone. This confirms the firmware is running.
- Click and whir sounds during arm, disarm, and fire. The servo energizes only while a move is in progress, then powers down. A short whir on arm, disarm, or fire is expected. You’ll also hear click sounds as each row extends or retracts.
- Slight delay between gesture and response. The firmware debounces tilt input to prevent accidental firing. A deliberate motion works better than a subtle flick.
- Battery level reads “full” on USB. USB power bypasses the battery measurement path. The reading is only accurate on LiPo with the voltage divider installed.
- Colors reset after a firmware update. Color preferences persist to flash storage. A firmware reflash overwrites storage, so colors return to defaults until you set them again.
- Config menu exits on its own. The menu times out after 15 seconds of no interaction. This is intentional — re-enter from the disarmed state to continue.
Troubleshooting
Start with the symptom that matches. If none of these resolve the issue, see Stage 05: Support.
| Symptom | Likely cause | What to check |
|---|---|---|
| No response at all | Power not reaching the board | Battery connected and charged? Switch ON? USB cable is data-capable? You should hear a boot sound and see an LED fade on power-up. |
| Powers on but does not arm | Magnet alignment or reed switch wiring | Pass the magnet slowly across the reed switch area. Confirm the connector for the sensor is fully seated. |
| Arms but darts do not move | Servo disconnected or linkage binding | Verify the servo header connection and check that the gear train moves freely by hand. |
| Darts move but LEDs stay dark | LED data or power wiring | Check data-line continuity to the first LED in the strip. Confirm 5V and GND reach the strip. |
| Fires on its own or triggers accidentally | Magnet too close in resting position | Reposition the activation magnet so it only triggers during a deliberate wrist motion. |
| Tilt gestures feel inconsistent | Mounting angle or motion too subtle | Use a deliberate, larger tilt. The accelerometer debounce requires intentional motion. |
| Servo keeps buzzing after movement | Mechanical binding or travel too aggressive | Check for obstructions in the gear train, or along the fiber optics, wires, or nozzle — those areas can cause friction if misaligned. Reduce the configured max servo angle if needed. |
| Battery check shows “unavailable” | Voltage divider not installed | The BAT-to-A3 divider is required for battery percentage. USB-only always reports unavailable. |
| Worked on bench, fails in gauntlet | Wire pinch or fiber drag from installation | Remove the module and retest on a table. Compare behavior outside vs. inside the gauntlet. |
| Prop powered down on its own after firing | All darts were depleted | This is expected. Trigger the magnet once to clear the depleted state, then arm normally. See All darts depleted. |
| Tilt gesture doesn’t re-fire | Still holding the tilt | Return your wrist to neutral before tilting again. Each gesture requires a return to center. See Salvo Selection and Firing. |
| Config changes looked correct but reverted later | CIRCUITPY was mounted read-only over USB | Disconnect USB-C, power from battery, then save the setting again. Preview works over USB, but persistence can fail while the filesystem is read-only. |
| Magnet trigger became too sensitive after wearing it awhile | Magnet shifted on the hand plate or moved closer during wear | Check the magnet mount and resting gap to the reed switch. Reposition or shim it so it only triggers during a deliberate wrist motion. |
| Servo starts a move but does not finish after the gauntlet warms up | Linkage drag from heat, wiring, or fiber routing | Power off, let it cool, then inspect the gearbox path, fiber bundle, and wire routing for added drag. Test outside the gauntlet if needed. |
| Battery drains quickly on a display table | Long armed time or repeated demo loops | Use USB-C for table display, shorten demo sessions, or disarm between interactions. Continuous LEDs and repeated motion use more power than photo-call use. |
Safety & Handling
- This module is intended for cosplay and prop use only.
- Do not leave the prop powered and unattended.
- Disconnect power if the system becomes unusually hot or behaves erratically.
- Avoid moisture, excessive heat, and direct impact on the electronics.
- Do not force the dart rows by hand while the servo is powered — this can strip gears or damage the linkage.
- Do not modify wiring or solder joints unless you understand the circuit design.