mirror of
https://git.undefined-dev.fr/Blendman974/faceclaw.git
synced 2026-11-19 21:03:09 +00:00
136 lines
10 KiB
Markdown
136 lines
10 KiB
Markdown
# Watch ⇄ phone protocol
|
||
|
||
The Wear OS and Apple Watch apps speak the same messages over different
|
||
transports, and `app/g2/wear-remote.ts` gives them their meaning on both phones.
|
||
This document describes the messages and the Wear OS transport; see "Apple Watch
|
||
transport" at the end for what differs there.
|
||
|
||
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):
|
||
|
||
```json
|
||
{
|
||
"protocol": 1, "version": "…",
|
||
"phase": "connected", "status": "…", "connected": true, "preview": false,
|
||
"screenOn": true, "locked": false, "worn": true, "listening": false,
|
||
"battery": 78, "glassesModel": "G2", "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,
|
||
"vibrateOnInput": true, "soundEffects": false,
|
||
"canUnlock": true, "mirrorAssistant": true,
|
||
"assistantAvailable": true
|
||
}
|
||
```
|
||
|
||
`battery` is the glasses' current or last-known percentage, and `glassesModel`
|
||
is what the charging line calls them: `G2`, `G1` or `iO` (a watch treats a
|
||
missing one, from an older phone app, as `G2`). `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. Only Wear OS reads
|
||
it, and the toggle only appears on Android; on Apple Watch, clockwise is always
|
||
previous/up.
|
||
|
||
`vibrateOnInput` and `soundEffects` mirror the Settings > Watch toggles that appear
|
||
on iOS, and only the Apple Watch app reads them. Wear OS keeps its vibration setting
|
||
on the watch and has no sounds.
|
||
|
||
`apps` is the launcher grid plus installed EvenHub packages, i.e. exactly what
|
||
the assistant's `apps.launch` tool accepts.
|
||
|
||
`preview` says gestures are landing on the phone's own display preview, with no
|
||
glasses involved: `connected` stays false, but input isn't refused. Only the iOS
|
||
app sets it for now.
|
||
|
||
## Apple Watch transport
|
||
|
||
Transport: WatchConnectivity. Phone side:
|
||
`App_Resources/iOS/src/FaceclawWatchBridge.m` (transport),
|
||
`app/native/wear-bridge.ios.ts` (JS wrapper). Watch side:
|
||
`apple-watch/Faceclaw/PhoneLink.swift`, `Protocol.swift`.
|
||
|
||
The system only links the two apps when the watch app's
|
||
`WKCompanionAppBundleIdentifier` names the phone app, its bundle ID begins with
|
||
the phone app's, **and the phone app's bundle embeds it in `Watch/`**; installing
|
||
each app separately leaves both sides reporting the other as not installed. See
|
||
`apple-watch/README.md`.
|
||
|
||
A message is a dictionary `{path, json}`, where `json` is the JSON payload above;
|
||
every path and payload is unchanged. `sendMessage` is used with no reply handler,
|
||
and acks are ordinary `/faceclaw/ack` messages. What differs follows from one fact:
|
||
**the phone can't wake the watch app, and the app is suspended whenever the wrist
|
||
drops.** The watch can wake the phone app, and does so with any message.
|
||
|
||
| Wear OS | Apple Watch |
|
||
| --- | --- |
|
||
| `/faceclaw/state` is a Data Layer item | The application context, `{json, updatedAt}`, for the app's next wake. While the app is in front it's also sent live as `{path: "/faceclaw/state", json, updatedAt}`, since context delivery can lag. Whichever `updatedAt` is newer wins. |
|
||
| `/faceclaw/event` is lost if the app is closed | Also sent live, with `at`. All but `streaming` snapshots also stay in the context as `{event, eventAt}`, so a reply that finished with the wrist down is there on the next raise. The watch drops anything not newer than the last `at`, and ignores a stale context event (assistant after 10 minutes, alert after 1). |
|
||
| `/faceclaw/battery/request` wakes a listener service | Only reaches an app in front. The app reports on open, every minute while open, and when the system grants it background time (asked for every 30 minutes), leaving `{battery: <json>}` in its own context for the phone to find. The payload adds `at` (ms), and the phone treats a level over 4 hours old as unknown. |
|
||
| "Reachable" is a capability query | `isPaired && isWatchAppInstalled`, whether or not the app is running. Live reachability changes also fire the connection callback, which is what pushes fresh state to an app coming to the front. |
|
||
| `nodeId` routes acks | Unused: a session has one counterpart. |
|
||
|
||
`isReachable` lags a moment behind a wrist raise, so the watch holds gestures for up
|
||
to 1.5 s rather than failing them. Touch-downs (`/faceclaw/press`) are never held.
|