glasses-eyes

Glasses Eyes

Custom controller for the Shining Glasses LED glasses (the ones sold with the “Shining Glasses” Android/iOS app). It draws Vector-robot-style eyes on the glasses’ 36 × 12 RGB LED matrix and lets you steer where they look, make them blink, and switch emotions. You control it from a web page, on a laptop or directly from an Android phone.

Phone controller (no install): open https://aks3310.github.io/glasses-eyes/phone/ in Chrome on Android, then tap Connect.

This is an unofficial, personal interoperability project. It isn’t affiliated with the glasses’ maker or the app’s developer.

How it works

The glasses are a Bluetooth Low Energy device. The official app was reverse-engineered (see shining-glass-protocol-report.md). The relevant parts:

• Commands (brightness, mode changes) are 16-byte AES-128-ECB encrypted packets on characteristic …9600.
• Live paint (DIY mode) accepts plain 20-byte packets on characteristic …960b: up to 8 pixel coordinates plus one RGB colour per packet. The pixels change immediately.

The controller renders each animation frame, compares it with what it believes is on the glasses, and sends only the changed pixels as live-paint packets. When idle, it slowly repaints the whole screen so a dropped packet never leaves a stray pixel for long.

There are two ways to run it:

	Laptop version	Phone version
Files	server.py + link.py + renderer.py + protocol.py + web/index.html	phone/index.html (single self-contained page)
Bluetooth	Python (bleak) on the laptop	Web Bluetooth in Chrome (Android, or desktop Chrome/Edge)
Control	Browser page served by the Python server	The same page that talks to the glasses
Extras	Blink-curve graph editor, live stats	Wake lock keeps the screen on while connected

Both versions render identically. The JavaScript port was checked against the Python renderer and packet planner on 77 test cases.

Laptop version

Requires Python 3.11+.

python -m venv ~/.venvs/glasses-eyes
~/.venvs/glasses-eyes/Scripts/python -m pip install -r requirements.txt   # Windows; use bin/python on macOS/Linux
~/.venvs/glasses-eyes/Scripts/python server.py

Then open http://127.0.0.1:8765. The server scans for the glasses and connects automatically.

• --address 00:41:20:03:81:9C connects to a known address without scanning.
• --no-ble runs the page without the glasses (preview only; also serves the phone page for testing).
• --host 0.0.0.0 lets another device on your Wi-Fi open the page.

Windows tip: keep the virtual environment at a short path (like ~/.venvs/...). Inside very long folder paths, Windows fails to load the Bluetooth DLLs (DLL load failed … The filename or extension is too long).

Phone version (no laptop)

phone/index.html is a complete standalone app using Web Bluetooth. It’s hosted on GitHub Pages at https://aks3310.github.io/glasses-eyes/phone/. Requirements:

• Chrome on Android (or Chrome/Edge on a computer). Firefox and iOS browsers don’t support Web Bluetooth.
• The page must be served over HTTPS (for example GitHub Pages) or from localhost.
• Tap Connect and pick the glasses in Chrome’s device chooser (required every time; a page can’t connect silently).
• Keep the page in the foreground. The page keeps the screen awake while connected, but the animation pauses if you switch apps.

To test on a computer first: run python server.py --no-ble and open http://localhost:8765/phone in Chrome.

Settings are stored in the browser (localStorage) on each device.

Controls

• Gaze pad: drag to look around; it snaps back to centre on release (optional). Arrow keys/WASD on the laptop version.
• Blink: the Blink button or Space. Auto blink fires every N seconds (±35% random).
• Emotions (keys 1–8): neutral, happy, sad, angry, surprised, sleepy, suspicious, wink. Switching either morphs the eye shape with easing or blinks and swaps it while the eyes are shut.
• Blink curve: separate easing for closing and opening, plus close/hold timing and presets. The laptop version adds a drag-the-handles graph editor. An overshooting curve makes the eyes “pop” wider.

Link settings (tuning speed vs. reliability)

Setting	What it does
Frame rate	Most frames sent to the glasses per second. The animation itself always runs at 30 fps.
Packet gap	Pause after each 8-pixel packet. Raise it if pixels go missing.
Reliable writes	Each packet waits for an acknowledgement. No radio drops, but much slower.
Paint order	Order of pixels within a frame: light new first (original; can smear on fast moves), slide (keeps the eye’s shape), erase old first.
Speed cap	Limits how far the eyes move per glasses frame, spreading fast glances over several small frames.
Refresh screen	Redraws all 432 pixels (also done automatically after connecting).

Known limitations

• The glasses accept one connection at a time. Close the official app, and don’t run the laptop and phone versions together.
• After a Bluetooth disconnect, the glasses often stop advertising. Switch them off and on before reconnecting.
• Throughput is limited: each packet carries at most 8 pixels, so big, fast movements take several packets per frame.
• Calibrate orientation with Test pattern: someone facing you should see red top-left, green top-right, blue bottom-left and white bottom-right. Use Mirror or Flip if not.

Other files

File	Purpose
shining-glass-protocol-report.md	Full reverse-engineering report: GATT map, command table, upload and live-paint formats, app flows, hardware test results
light_test.py	Minimal smoke test: connects and steps the brightness (also has an offline --selftest of the encryption)
tools/decrypt_firmware.py	Decrypts the firmware images bundled in the official APK (assets/TR1906R04-*_OTA.bin) for analysis. No firmware is included in this repository.
requirements.txt	Python dependencies: bleak, cryptography, aiohttp