glow 💡

CLI controller for ELK-BLEDOM / MELK Bluetooth LED strips — color, moods, music-reactive, screen sync, game profiles, and a time-aware schedule daemon. All from your terminal.

---

✨ What it does

glow turns your cheap Amazon BLE LED strip into a smart ambient light that actually knows what you're doing:

• 🎨 Full color control — named colors, hex codes, RGB values, smooth fades
• 🌅 Moods — 14 presets (relax, focus, gaming, sleep, study…) with smart time-of-day brightness
• 🎵 Music reactive — your Mac mic feeds into FFT; bass → 🔴, mids → 🟢, treble → 🔵 in real time
• 🖥️ Screen sync — captures dominant screen color every N seconds and fades the strip to match
• 🎮 Game mode — combines screen color + audio analysis to detect shots, footsteps, running, and intense moments; ships with profiles for CoD, The Last of Us, Cyberpunk 2077, RDR2, Minecraft, Horror (and a generic fallback)
• ⏰ Scheduler — cron-like schedule daemon that installs as a macOS login item via launchd
• 🔦 Hardware effects — rainbow, breathe, blink, jump, and ~20 more (baked into the strip's firmware)

---

🔧 Hardware

Detail	Value
Chip	Telink TLSR8253 / TLSR8258 BLE SoC
Device name	ELK-BLEDOM, MELK-OA10, ELK-BLE
Protocol	Proprietary 10-byte BLE frame
Service UUID	0000fff0-0000-1000-8000-00805f9b34fb
Write UUID	0000fff3-0000-1000-8000-00805f9b34fb

These strips are sold under many brand names on Amazon/AliExpress but all share the same Telink SoC and the same undocumented BLE protocol — reverse-engineered and documented in elk_bledom_protocol.py.

---

📦 Install

git clone https://github.com/kshivam654/glow.git
cd glow
python -m venv venv
source venv/bin/activate
pip install -e .

First run — scan for your device and save its address:

glow scan

The address is stored in ~/.glow.json and reused automatically on every subsequent command.

macOS permissions

Feature	Permission needed
All BLE commands	Bluetooth — System Settings → Privacy & Security → Bluetooth
glow music	Microphone
glow screen / glow game	Screen Recording

---

🚀 Commands

Power

glow on
glow off

White modes

glow warm           # warm white, auto brightness
glow warm 60        # warm white at 60%
glow cool           # cool/daylight white
glow cool 80

Color

glow color red
glow color ff0066
glow color red --fade 1.5      # smooth transition
glow rgb 255 0 100
glow rgb 255 0 100 --fade 2

Named colors: red green blue white yellow cyan magenta orange pink purple

Fade

glow fade red
glow fade ff0066 --duration 3

Brightness

glow brightness 80    # 0–100

Moods

glow mood relax
glow mood gaming
glow mood sleep
glow mood movie --brightness 60
glow moods            # list all

Mood	Color	Default Brightness
relax	warm orange	60%
focus	blue	90%
gaming	red-pink	100%
movie	deep purple	40%
sunset	orange	80%
forest	green	70%
sleep	dim red	15%
party	magenta	100%
ocean	deep blue	70%
warm	soft white	80%
cool	cool white	80%
romantic	rose	35%
study	bright warm white	95%
midnight	deep purple	20%

Smart brightness (auto)

When brightness is omitted, glow picks a level based on time of day:

Time	Brightness
06:00 – 12:00	80%
12:00 – 18:00	100%
18:00 – 20:00	90%
20:00 – 22:00	75%
22:00 – 00:00	60%
00:00 – 02:00	45%
02:00 – 04:00	30%
04:00 – 06:00	20%

Hardware effects

glow effect rainbow
glow effect breathe
glow effect jump
glow effect purple-fade --speed 20    # 0=fast, 100=slow
glow effects                           # list all

Mic mode (strip's built-in hardware mic)

glow mic                        # energetic (default)
glow mic spectrum
glow mic rolling
glow mic rhythm
glow mic energetic --sensitivity 80

Most MELK strips have no physical mic chip — use glow music instead.

🎵 Music mode (Mac mic → real-time FFT → BLE)

glow music                         # default
glow music --sensitivity 4.0       # louder response for quiet rooms
glow music --speed 0.06            # dreamy slow transitions
glow music --mode beat --color purple
glow music --mode pulse --color cyan
glow music --bg                    # run in background

Mode	What it does
freq (default)	bass → 🔴 mids → 🟢 treble → 🔵
beat	flashes on kick, exponential decay between beats
pulse	brightness pulses with volume, color stays fixed

Press Ctrl+C or run glow stop to end.

🖥️ Screen sync

glow screen                           # defaults
glow screen --interval 0.3            # faster updates
glow screen --saturation 2.5          # more vivid colors
glow screen --fade-speed 0.8          # slower transitions
glow screen --monitor 2               # second display
glow screen --bg                      # run in background

🎮 Game mode

Combines screen color + microphone audio to run a state machine:

State	Trigger	Effect
idle	near silence	dim ambient glow in game's palette
walking	low audio	subtle brightness pulse
running	mid audio	brighter + warmer
combat	sharp bass spike = gunshot	muzzle flash color, fades back
intense	sustained loud audio	full brightness, high saturation

glow game                              # auto-detects frontmost app
glow game --profile tlou
glow game --profile cod --interval 0.08
glow game --bg

Game profiles: cod · tlou · cyberpunk · rdr2 · minecraft · horror · generic

Auto-detection reads the frontmost macOS app name and matches against each profile's keyword list.

⏰ Schedule

glow schedule add 07:00 on
glow schedule add 07:00 warm 70
glow schedule add 09:00 mood focus
glow schedule add 18:00 mood relax
glow schedule add 23:30 off

glow schedule list
glow schedule remove 3

glow schedule daemon        # run manually
glow schedule install       # install as macOS login item (launchd)

Schedules are stored in ~/.glow.json. Daemon logs go to ~/.glow.log.

Uninstall the daemon:

launchctl unload ~/Library/LaunchAgents/com.glow.scheduler.plist
rm ~/Library/LaunchAgents/com.glow.scheduler.plist

Background processes

glow music --bg
glow screen --bg
glow game --bg
glow stop          # kill whatever is running in background

Shell completion

glow completion zsh     # prints eval line to add to ~/.zshrc
glow completion bash
glow completion fish

---

📅 Example daily routine

glow schedule add 07:00 warm 70        # gentle wake-up
glow schedule add 09:00 mood study     # work mode
glow schedule add 13:00 mood focus     # afternoon focus
glow schedule add 18:00 mood sunset    # evening wind-down
glow schedule add 21:00 mood relax     # chill
glow schedule add 23:00 mood sleep     # sleep prep
glow schedule add 23:30 off            # lights out
glow schedule install                  # activate

---

🗂️ Project structure

glow/
├── glow.py                 # CLI — all commands (Click)
├── led_controller.py       # ELKBledomController class
├── elk_bledom_protocol.py  # Raw byte protocol reference / reverse-engineering notes
├── pyproject.toml          # Package config (pip install -e .)
└── venv/                   # Python virtual environment (gitignored)

Config: ~/.glow.json — device address + schedules
Logs: ~/.glow.log — schedule daemon output

---

🔍 Troubleshooting

❌ ELK-BLEDOM not found

• Make sure the strip is powered on
• Close any phone app (Magic Lantern / ELK Lantern) — BLE only allows one connection at a time
• Run glow scan to re-discover

Light doesn't react to commands

• Re-run the command; the strip occasionally needs a moment
• If colors look wrong (red shows as green, etc.) check _wire() in led_controller.py

glow music / glow screen / glow game stop immediately

• Grant the required permissions in System Settings → Privacy & Security

Schedule not firing

• Check the daemon: launchctl list | grep glow
• Check logs: tail -f ~/.glow.log
• Times must be exact HH:MM format

---

🤝 Contributing

PRs welcome! Some ideas:

• Windows / Linux BLE backend
• More game profiles
• Web UI / menubar app
• Zigbee / WLED support

---

📄 License

MIT — do whatever you want with it.