elizaos--eliza/plugins/plugin-facewear/native/android/even-realities

Eliza Facewear — Even Realities G1/G2 Companion App

Android companion app that bridges the Even Realities G1 (and G2) glasses to an elizaOS agent via BLE.

Architecture

elizaOS Agent (WebSocket)
        ↕  WebSocket (OkHttp)
AgentBridgeService (Android)
        ↕  Android Binder IPC
G1BleService (Android)
        ↕  BLE GATT / Nordic UART Service
Even Realities G1 glasses

The G1 runs its own ARM firmware and communicates over BLE. This app uses the Nordic UART Service (NUS) BLE profile (UUID 6e400001-b5a3-f393-e0a9-e50e24dcca9e) exposed by both lenses and does not consider pairing ready until the left and right lens are connected.

BLE Protocol

The G1 implements the same core command framing used by plugin-facewear:

Command byte	Payload	Action
0x4E	display sequence/chunk header + UTF-8 text	Display text on both lenses
0xF5 0x18	stop subcommand	Clear display
0x01	level + auto flag	Set display brightness
0x0E	0x01 / 0x00	Enable / disable the right-lens mic
0x25	heartbeat sequence	Keep connection alive
0x2C 0x01	none	Request battery status
0x4D 0x01 / 0xF4 0x01	none	Left/right connection-ready init

Incoming 0xF1 mic frames are forwarded to the agent as mic_lc3 JSON events with sampleRate: 16000, encoding: "lc3", byte-array payloads, and base64 payloads. Other RX packets are forwarded as g1_raw events so the agent can parse taps, serial responses, battery status, and display acknowledgements.

Prerequisites

Tool	Version
Android Studio	Hedgehog 2023.1+
JDK	17
Android SDK API	35
Android device	API 29+ with Bluetooth LE

Building

./gradlew assembleDebug
# Output: app/build/outputs/apk/debug/app-debug.apk

Installing

adb install -r app/build/outputs/apk/debug/app-debug.apk

Usage

1. Enable Bluetooth on your Android phone
2. Turn on your G1 glasses
3. Open the app → tap Scan for G1
4. The app will find _L_ and _R_ G1 lenses via BLE and connect both
5. Enter your elizaOS agent WebSocket URL (e.g. ws://192.168.1.100:31337/smartglasses-ws)
6. Tap Connect to Agent
7. Agent responses will appear on the G1 HUD display

How the Agent Integration Works

• AgentBridgeService connects to the elizaOS WebSocket and sends a hello frame with deviceType: "even-realities"
• The agent (plugin-facewear) should detect this device type and skip TTS audio (G1 has no speaker)
• agent_text frames are forwarded to G1BleService.displayText() → BLE → both G1 HUD lenses
• transcript frames (final=true) show "You: ..." on the HUD
• clear_display, mic_control, brightness, battery_status, heartbeat, and g1_write agent frames are forwarded to the BLE service
• G1 RX packets are forwarded back to the agent as g1_raw; 0xF1 microphone chunks are additionally forwarded as mic_lc3

Troubleshooting

Problem	Fix
Scan finds nothing	G1 not powered on, or pairing mode not active
GATT_ERROR 133	Common on first connect — retry once or power-cycle G1
NUS service not found	Wrong device or firmware too old
Text not showing on G1	Confirm both lenses report ready and the agent is sending agent_text frames
WebSocket refused	Check agent is running; use LAN IP, not localhost
Permission denied on BLE scan	Grant Location + Bluetooth permissions in Settings