elizaos--eliza/plugins/plugin-facewear/docs/smartglasses-upstream-audit.md

Smartglasses Upstream Audit

This plugin was built from the gitignored research checkouts under research/even-realities/. The repository root .gitignore ignores that checkout folder, so these upstream repos remain local evidence and are not part of the committed package.

Repository Coverage

Requested source	Local checkout	Primary files reviewed	Capability carried into @elizaos/plugin-facewear
fabioglimb/even-toolkit	research/even-realities/even-toolkit	glasses/bridge.ts, glasses/glass-format.ts, glasses/paginate-text.ts, glasses/gestures.ts, stt/sources/glass-bridge.ts, stt/audio/pcm-utils.ts	G2/EvenHub bridge display, event, and PCM audio assumptions; text pagination and gesture normalization informed src/transport/even-bridge.ts and src/protocol/smartglasses.ts.
BxNxM/even-dev	research/even-realities/even-dev	apps/_shared/even-events.ts, apps/_shared/autoconnect.ts, apps/base_app/src/base-template.ts, README.md	Simulator bridge lifecycle, sendStartUpPage, app bridge readiness, and click/double-click input expectations used by packages/examples/smartglasses/evenhub-smoke.ts and simulator-automation-smoke.ts.
emingenc/even_glasses	research/even-realities/even_glasses	even_glasses/models.py, even_glasses/utils.py, even_glasses/commands.py, even_glasses/notification_handlers.py, even_glasses/bluetooth_manager.py, even_glasses/README.md	G1 command constants, display packet framing, RSVP, mic control, mic response parsing, LC3 notification parsing, heartbeat, dashboard/settings, BMP, and notification handling in src/protocol/smartglasses.ts and src/services/smartglasses-service.ts.
binarythinktank/eveng1_python_sdk	research/even-realities/eveng1_python_sdk	connector/bluetooth_manager.py, services/commands.py, services/notification_handlers.py, utils/message_utils.py, examples/*.py	Nordic UART UUIDs, broad scan plus _L_/_R_ lens matching, heartbeat bytes, LC3 mic chunks, and display packet shape used by src/transport/noble.ts, src/transport/web-bluetooth.ts, and protocol tests.
meyskens/fahrplan	research/even-realities/fahrplan	lib/bluetooth_manager.dart, lib/services/*, lib/features/*, README.md	Practical G1 app coverage for dashboard/checklist display, notification mirroring, navigation, translation, QuickNote/voice-note list/fetch/delete/delete-all packets, and live transcription expectations reflected in src/actions/facewear-control.ts, src/protocol/smartglasses.ts, and package smoke coverage.
nickustinov/weather-even-g2	research/even-realities/weather-even-g2	g2/index.ts, g2/events.ts, g2/ui.tsx, _shared/*, README.md	G2 captured-event behavior, list/text/system event handling, and zero-value index edge cases used by EvenHub event normalization.
jappyjan/even-realities	research/even-realities/even-realities	packages/*, apps/*, SDK/app examples	EvenHub SDK wrapper patterns for page startup, rebuild, and listener registration used by EvenBridgeTransport.
emingenc/g1_flutter_blue_plus	research/even-realities/g1_flutter_blue_plus	lib/services/commands.dart, lib/services/reciever.dart, lib/services/bluetooth_manager.dart, lib/main.dart	Flutter BLE discovery and direct G1 receiver behavior cross-checked command constants, _L_/_R_ pairing, 0xF5 taps, 0x0E mic responses, and 0xF1 voice data.
nickustinov/tesla-even-g2	research/even-realities/tesla-even-g2	g2/events.ts, g2/renderer.ts, g2/navigation.ts, g2/ui.tsx, README.md	G2 bridge event normalization for nested event keys, click/double-click/scroll fallback, and dashboard/menu rendering expectations used by src/transport/even-bridge.ts and simulator smoke.
galfaroth/awesome-even-realities-g1	research/even-realities/awesome-even-realities-g1	README.md	Ecosystem cross-check for the G1 SDK/demo sources and command families.
even-realities/EvenDemoApp	research/even-realities/EvenDemoApp	lib/ble_manager.dart, lib/services/ble.dart, lib/services/evenai.dart, lib/services/features_services.dart, lib/controllers/bmp_update_manager.dart, ios/Runner/BluetoothManager.swift, android/app/src/main/kotlin/com/example/demo_ai_even/bluetooth/BleManager.kt	Official demo behavior for right-lens mic, LC3 audio, text streaming, native exit, serial request, app whitelist, iOS same-init (0x4D 0x01 to both lenses), Android same-init (0xF4 0x01 to both lenses), notification flows, and BMP transfer.
Mentra-Community/MentraOS	research/even-realities/MentraOS	cloud/docs/sdk/display-layouts.mdx, cloud/docs/cloud-architecture/managers/audio-manager.mdx, cloud/docs/cloud-architecture/managers/microphone-manager.mdx, cloud/docs/cloud-architecture/managers/transcription-manager.mdx, sdk/*, mobile/*	Bridge/native display APIs, setMicState, mic_pcm/mic_lc3, local transcription streams, display width/glyph constraints, G1 dashboard height/depth position packets, 0x2C 0x01 battery status request/response parsing, and hardware validation requirements used by src/transport/even-bridge.ts, display wrapping, transcript events, dashboard position controls, battery status, and hardware smoke evidence.

Implemented Surface

The upstream review maps to the following local implementation:

• Direct G1 BLE packet protocol and parsing: src/protocol/smartglasses.ts
• Eliza service lifecycle, display streaming, mic control, tap handling, audio/transcript events, heartbeat, and settings: src/services/smartglasses-service.ts
• Eliza actions/providers: src/actions/*.ts, src/providers/smartglasses-status.ts
• Direct BLE transports: src/transport/web-bluetooth.ts, src/transport/noble.ts
• EvenHub/G2/Mentra bridge transport: src/transport/even-bridge.ts
• Mock transport for deterministic Eliza tests: src/transport/mock.ts
• Physical validation harnesses:
  • packages/examples/smartglasses/hardware-smoke.ts
  • packages/examples/smartglasses/noble-hardware-smoke.ts
  • packages/examples/smartglasses/hardware-evidence.ts
• Simulator validation harness:
  • packages/examples/smartglasses/evenhub-smoke.ts
  • packages/examples/smartglasses/simulator-automation-smoke.ts

Test Coverage

The implementation is covered by:

• src/__tests__/protocol-smartglasses.test.ts: packet encoding, pixel-aware display wrapping, display chunking, mic commands, tap/audio/serial parsing, settings, dashboard position/content, navigation, translation, notifications, notes, voice-note list/fetch/delete/delete-all, BMP, heartbeat, init modes, and app whitelist/setup.
• src/__tests__/facewear-service.test.ts: Eliza service display streaming, RSVP, sequence counters, mic toggle state, side tap behavior, long press/stop recording, raw and decoded audio paths, transcript events, startup auto-init, heartbeat loop, pre-connected transport listener attachment, and transport preference.
• src/__tests__/functional-parity.test.ts: exported action/provider/service wiring.
• src/__tests__/even-bridge.test.ts: G2/EvenHub/Mentra bridge rendering, audio, transcription, and input normalization.
• src/__tests__/web-bluetooth.test.ts and src/__tests__/noble.test.ts: direct BLE lens pairing, UART subscription/write behavior, and notification parsing.
• packages/examples/smartglasses/smartglasses.test.ts: package example packet path plus physical evidence helper requirements.
• packages/examples/smartglasses/package-smoke.ts: public package export, Eliza event emission, status provider, and action path.

Remaining Physical Gate

The code includes physical G1 validation paths and direct BLE smoke coverage. An earlier report from 2026-05-20T06:38:56Z reached both lenses on the plugged-in headset and proved whole-headset direct BLE connectivity, serial response, init/display/settings responses, heartbeats, and right-lens mic-disable response for serial S110LABC040019. It did not complete the physical gate because that run did not observe a physical-state packet with wearing, so tap and microphone audio evidence could not be observed. The freshest short Bleak attempt from 2026-05-20T07:42:31Z did not discover either lens. CoreBluetooth did discover 36 BLE devices, but zero matched Even/G1 names and zero advertised the G1 UART service UUID. Both status and validator output report physicalBlocker: "headset_not_found" for that case, which means the next Bleak attempt needs both lenses out of the charging base, nearby, advertising, and worn before the tap/audio validation window. The Bleak raw report also records status.connected: false, service UUID/manufacturer scan inventory, and the same blocker-aware setup hint when no lenses are found. A Noble attempt from 2026-05-20T07:26:42Z failed before scanning because the native Noble BLE binding is unavailable for the current macOS ARM64 Node/Bun ABI; that path now writes a report and reports physicalBlocker: "transport_unavailable" instead of silently leaving an older hardware report in place.

Use the root helpers for the next hardware proof attempt:

bun run --cwd packages/examples/smartglasses hardware:prove:bleak:watch
bun run --cwd packages/examples/smartglasses hardware:status-latest
bun run --cwd packages/examples/smartglasses hardware:validate-latest

The lower-level package commands remain available when debugging inside the example:

bun run --cwd packages/examples/smartglasses hardware:prove:bleak
bun run --cwd packages/examples/smartglasses hardware:status-latest
bun run --cwd packages/examples/smartglasses hardware:validate-latest

The Noble/Web Bluetooth paths are still available for adapter/browser-specific checks:

bun run --cwd packages/examples/smartglasses hardware:prove:noble
bun run --cwd packages/examples/smartglasses dev:hardware

The required evidence checklist is enforced by packages/examples/smartglasses/hardware-evidence.ts: connected lenses, connection-ready/init writes, display packets, serial request and response, settings writes, wearing physical state, single-tap mic enable, right-lens mic-enable write, microphone audio, double-tap mic disable, and right-lens mic-disable write.

The Bleak/CoreBluetooth proof report also captures macOS Bluetooth preflight metadata (bluetoothAdapter and pairedG1Devices) before scanning. That keeps the latest JSON artifact self-contained when diagnosing the paired-but-not- advertising state that blocks the physical tap/audio gate.