Files
faceclaw/wear/PROTOCOL.md
T

6.6 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.kt (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 except /faceclaw/battery and /faceclaw/press 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, short-then-long-press (tap then hold: the app's context menu; a plain long-press is the glasses' system menu), 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. While the display is off, a double-click wakes the display, a click shows the phone's Glanceboard for a few seconds, and long-press-start/long-press-release hold it up; everything else is ignored.
/faceclaw/press none A finger landed on the pad (each first-finger touch-down, the second tap of a double-tap included) or the stem button went down: delivered on the glasses as a ring-press from source watch, exactly like the R1 ring's touch-down, ahead of whatever gesture the touch becomes (which is still sent on /faceclaw/input). Components that act on touch-down (Flappy, Pinball) then ignore the gesture that follows. Sent only while the mirrored state says the glasses are connected with the display on. Carries no seq and is never acked; the phone drops it silently wherever the following gesture would be refused.
/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.
/faceclaw/battery {battery, charging} The watch's own battery (battery 0–100 or null, charging bool) for the glasses' top-bar and Glanceboard "Watch" indicator. Sent in answer to /faceclaw/battery/request by PhoneListenerService (which Play services starts even while the watch app is closed) and, while the app is open, whenever the level or charging state changes. Carries no seq and is never acked.

All of the above except state/request, battery and press are refused with ok:false when the phone's "Watch remote control" setting is off (a press is just dropped).

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/battery/request (MessageClient, to every reachable watch): {}. Please send /faceclaw/battery now. The phone sends it when a watch becomes reachable, when the glasses connect with the level still unknown, and every 5 minutes after that; the indicator disappears when no watch is reachable.

/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, "silentMode": false,
  "caseBattery": 64, "caseCharging": true,
  "foreground": {"appId": "music", "title": "Music"},
  "windows": [{"windowId": "…", "title": "…", "appId": "…", "focused": true, "closeable": true, "acceptsText": false}],
  "apps": [{"appId": "timer", "title": "Timer"}],
  "remoteEnabled": true, "crownClockwiseNext": false,
  "canUnlock": true, "mirrorAssistant": true,
  "assistantAvailable": true
}

battery is the current or last-known G2 percentage. charging and silentMode identify the two states in which the glasses display is not visible even though the BLE session remains available.

caseBattery is the last-known charging-case percentage, or null until the glasses have reported one; the case only reports while the glasses are docked, so outside charging it can be stale. caseCharging is whether the case is on USB, or null while the glasses are out of the case (they can't see it then). The watch shows the case level under the charging line.

protocol is reserved for incompatible revisions of this format (nothing checks it yet). crownClockwiseNext mirrors the on-glasses Settings > Watch toggle; when false (the default), clockwise crown rotation sends previous/up, and when true it sends next/down.

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