Amy's Heart User Guide

LED Light Controller with Bluetooth App

Contents

1. Getting Started
2. Button Controls
3. Connecting via Bluetooth
4. The Web App
5. Directional Spotlight (Joystick)
6. Piano Keyboard
7. Colors & Light Sequences
8. Sound Themes & Volume
9. Bluetooth Troubleshooting
10. Tips & Notes

1. Getting Started

Amy's Heart is an LED light controller with 22 individually addressable RGB LEDs. It can be controlled with two physical buttons on the device, or wirelessly through a Bluetooth web app on your phone or computer.

The device has a small OLED display that shows the current settings (color, sequence, brightness, sound theme, volume, and Bluetooth status). When you press Button 1, a dog appears on screen. When you press Button 2, a cat appears.

Tip: All your settings are automatically saved to the SD card. When you turn the device off and back on, it will remember exactly how you left it.

2. Button Controls

Both buttons respond differently depending on how long you hold them.

Button 1 — Lights

Press	Hold Time	Action
Quick tap	< 0.25s	Cycle light sequence (Candle → Comet → Breathe → Solid)
Medium hold	0.25 – 1s	Cycle color (Red → Green → Blue → Purple → Pink → Cyan → Orange → Yellow → White)
Long hold	> 1s	Start Bluetooth pairing (LEDs breathe blue)

Button 2 — Sound & Brightness

Press	Hold Time	Action
Quick tap	< 0.25s	Cycle brightness (5 levels: 10% → 30% → 50% → 75% → 100%)
Medium hold	0.25 – 1s	Cycle volume (Low → High → Off)
Long hold	> 1s	Cycle sound theme (Cricket → Sci-Fi → Robot)

3. Connecting via Bluetooth

Open the web app (index.html) in Chrome on your phone or computer.
On the device, long-press Button 1 (hold for more than 1 second). The LEDs will start breathing blue — this means the device is broadcasting and ready to pair.
In the app, tap "Connect via Bluetooth". A list of nearby devices will appear.
Select "Amy's Heart" from the list.
The LEDs will flash green twice to confirm a successful connection. The app will show your current device settings.

Tip: The device broadcasts for 30 seconds. If you don't connect in time, the LEDs will flash red and return to normal. Just long-press Button 1 again to retry.

Note: Bluetooth Web API requires Chrome or a Chromium-based browser (Edge, Brave, Opera). Safari and Firefox do not currently support Web Bluetooth.

4. The Web App

Once connected, the app gives you full control over the device. Here's what each section does:

Power Toggle

The Lights ON / Lights OFF button turns the LED strip on and off. When you turn it back on, it restores your exact previous settings — color, sequence, brightness, and even the directional spotlight position.

Color

Choose from 9 preset colors by tapping the colored circles:

Red Green Blue Purple Pink Cyan Orange Yellow White

Or pick any color you like using the Custom Color picker (hue and saturation gradients).

Special Color Modes

The dropdown below the color buttons offers three animated color modes:

Rotating Rainbow — Continuously shifting rainbow across the strip
Random on Change — Random colors that change with the animation
Color Shimmer — Smooth, organic color waves

Brightness

Drag the slider from 0% to 100%. The brightness changes smoothly in real time as you drag.

Light Sequence

The dropdown lets you choose from 7 light patterns:

Sequence	Description
Candle	Realistic flickering — each LED flickers independently
Comet	A glowing tail that bounces back and forth along the strip
Breathe	Smooth pulsing — fades in and out gently
Solid	Steady, constant light (flashlight mode)
Double Comet	Two comet tails moving in opposite directions from center
Split Breathe	Left and right halves breathe in opposite phases
Wave	Three rotating bright points with smooth gradients between them

Tip: The buttons on the device cycle through the first 4 sequences. The last 3 (Double Comet, Split Breathe, Wave) are only available through the app.

Sound Theme & Volume

Choose a sound theme (Cricket, Sci-Fi, or Robot) and set the volume (Off, Low, or High). Each theme changes the chirps and beeps the device makes when you press buttons or change settings.

5. Directional Spotlight (Joystick)

The circular joystick control lets you focus the light on specific LEDs — like aiming a spotlight along the strip.

Center position — All LEDs at even brightness (no spotlight effect).
Drag outward — The further from center, the tighter the focus. At full distance, only about 3 LEDs are brightly lit with a smooth gradient falloff on either side.
Rotate around — Aim the spotlight at any position along the strip.

The small dots around the ring show you which LEDs are lit and how bright they are — a live preview of the spotlight shape.

Joystick Behavior

The thumb stays where you leave it when you release — it doesn't snap back.
To reset, drag close to the center. It will snap to center automatically when you're within the deadzone.
The spotlight works on top of your current brightness — it's a multiplier, not a replacement.

Flip Controls

If the device is mounted upside down, tap Flip Controls so the joystick directions still make visual sense. This reverses the mapping so left/right and up/down match what you see.

Tip: The directional spotlight position is saved and will persist when you restart the device.

6. Piano Keyboard

Tap "Open Piano" to open a full-screen piano. You can play tones through the device's buzzer! The piano has 4 octaves (C3 through B6) spread across two rows. The sound style depends on your current sound theme.

Tip: Turn your phone sideways for the best piano experience. Some very low notes may be greyed out if the buzzer can't play them clearly.

7. Colors & Light Sequences — Quick Reference

Colors (Button)

Red
Green
Blue
Purple
Pink
Cyan
Orange
Yellow
White

Colors (App Only)

Rotating Rainbow
Random on Change
Color Shimmer
Any custom RGB color

Sequences (App Only)

Double Comet
Split Breathe
Wave

8. Sound Themes & Volume

Theme	Style
Cricket	Natural chirping — quick, organic bursts
Sci-Fi	Futuristic sweeps and alien-sounding tones
Robot	Mechanical beeps — clean, digital sounds

Volume	Description
Off	Completely silent — no button sounds
Low	Quiet — subtle feedback
High	Full volume

9. Bluetooth Troubleshooting

If the app won't connect or the connection is unstable:

Reset Steps — Follow these in order:

Power off the device completely.
Close the app's browser tab (don't just switch away — fully close it).
Power the device back on and wait a moment for it to start up.
Open a new browser tab and load the app (index.html).
On the device, long-press Button 1 to start Bluetooth broadcasting (LEDs breathe blue).
In the app, tap "Connect via Bluetooth" and select "Amy's Heart".

Common Issues

Problem	Solution
"Amy's Heart" doesn't appear in the device list	Make sure the LEDs are breathing blue — this means the device is broadcasting. If not, long-press Button 1 again. The device only broadcasts for 30 seconds.
Connection drops randomly	Move your phone/computer closer to the device. Bluetooth range is typically 5–10 meters. Walls and other electronics can reduce range.
App shows "Connected" but controls don't respond	Disconnect from the app, close the tab, power cycle the device, and reconnect from a fresh tab.
Browser says "Bluetooth not supported"	Use Google Chrome, Microsoft Edge, Brave, or Opera. Web Bluetooth does not work in Safari or Firefox.
Can't connect on iPhone	Web Bluetooth has limited support on iOS. Try using the Bluefy app (a Bluetooth-enabled browser) or use a computer with Chrome instead.
Device settings look wrong after connecting	The app reads settings from the device on connect. If values look off, try changing a setting back and forth to re-sync.

10. Tips & Notes

Settings are saved to the SD card automatically, a couple of seconds after your last change. If you unplug the device immediately after making changes, the very last adjustment might not be saved.
The directional spotlight works with every color and every light sequence — including animated ones like Candle and Comet.
When the device disconnects from Bluetooth (e.g. you close the app), it keeps running with whatever settings were active. Nothing resets.
The 3 app-only sequences (Double Comet, Split Breathe, Wave) are remembered even after a restart. They'll keep running without the app connected.
The brightness slider in the app gives you finer control than the physical button (continuous 0–100% vs. 5 fixed levels).