Files
faceclaw/wear/PROTOCOL.md
T
Kalani Helekunihi 8fa04d1b46 Add Wear OS companion app and remote controls
Add a Wearable Data Layer bridge for syncing dashboard state and commands.

Introduce a standalone watch app with assistant, app launcher, touchpad remote, settings, and connectivity UI.
2026-08-23 15:02:35 -05:00

4.0 KiB
Raw Blame History

Watch ⇄ phone protocol

Transport: the Wearable Data Layer (Google Play services). Both apps share the com.faceclaw.app application id and, for release builds, the signing key — the Data Layer routes only between matching apps. Payloads are UTF-8 JSON objects. Phone side: App_Resources/.../FaceclawWearBridge.java (transport), app/native/wear-bridge.ts (JS wrapper), app/g2/wear-remote.ts (meaning). Watch side: app/src/main/kotlin/com/faceclaw/wear/Protocol.kt, PhoneLink.kt.

Capabilities (res/values/wear.xml on each side): the phone advertises faceclaw_phone, the watch faceclaw_watch. Each side finds the other with CapabilityClient.getCapability(…, FILTER_REACHABLE).

Every watch → phone message carries seq (monotonic per watch process) and is answered on /faceclaw/ack.

Watch → phone (MessageClient)

Path Payload Effect
/faceclaw/input {gesture, steps?} A ring gesture through the same path as the phone UI's test buttons. gesture ∈ click, double-click, scroll-up, scroll-down, long-press (complete short hold), long-press-start, long-press-release, wakeword ("Hey Even"), swipe-up, swipe-down, swipe-left, swipe-right (spatial input only a watch can produce: delivered to the glasses UI as swipe-* events for components that navigate spatially — launcher grid, settings columns, sidebar, Music — with a scroll / click / double-click fallback elsewhere). steps (1–12) repeats a scroll. Refused while the glasses are disconnected. The lock screen is honoured exactly as for the ring (only a double-click reaches it, toggling the locked display).
/faceclaw/command {command, …} launch-app {appId}, focus-window {windowId}, close-window {windowId}, sidebar, wake, sleep, lock, unlock, connect, disconnect, close-assistant. Everything but connect/disconnect needs a connection; everything but lock/unlock is refused while locked; unlock also needs the phone's "Watch can unlock glasses" setting.
/faceclaw/assistant {text} Send a query to the assistant (shell.sendToAssistant) — the reply shows on the glasses and streams back to the watch as events.
/faceclaw/text {text} Type text into the foreground window (receiveTextInput, e.g. the terminal). Refused when the window doesn't take text.
/faceclaw/state/request {} Re-publish the state item even if unchanged.

All of the above except state/request are refused with ok:false when the phone's "Watch remote control" setting is off.

Phone → watch

/faceclaw/ack (MessageClient, to the sender): {seq, ok, jsReady, message}. jsReady:false means Play services started the app process for the message but the JS dashboard isn't up (the user has not opened Faceclaw since boot); the watch shows "Open Faceclaw on the phone".

/faceclaw/event (MessageClient, to every reachable watch):

  • {type:"assistant", phase, text} — phase ∈ thinking, streaming (text so far, replace semantics, ≤ 4/s), done (final text), error (message), closed (overlay dismissed).
  • {type:"alert", text} — a glasses.show_alert popup. Both are gated by the phone's "Mirror assistant to watch" setting.

/faceclaw/state (DataClient item, keys json and updatedAt): the mirrored dashboard state, re-sent whenever it changes (and at least every 30 s):

{
  "protocol": 1, "version": "…",
  "phase": "connected", "status": "…", "connected": true,
  "screenOn": true, "locked": false, "worn": true, "listening": false,
  "battery": 78, "charging": false,
  "foreground": {"appId": "music", "title": "Music"},
  "windows": [{"windowId": "…", "title": "…", "appId": "…", "focused": true, "closeable": true, "acceptsText": false}],
  "apps": [{"appId": "timer", "title": "Timer"}],
  "remoteEnabled": true, "canUnlock": true, "mirrorAssistant": true,
  "assistantAvailable": true
}

apps is the launcher grid plus installed EvenHub packages, i.e. exactly what the assistant's apps.launch tool accepts.