mirror of
https://git.undefined-dev.fr/Blendman974/faceclaw.git
synced 2026-11-19 21:03:09 +00:00
128 lines
7.5 KiB
Markdown
128 lines
7.5 KiB
Markdown
# Faceclaw for Wear OS
|
||
|
||
A watch remote for Faceclaw: everything the Even R1 ring can do, plus the
|
||
things it can't. Runs on a Wear OS 3+ watch (API 30) paired with the phone
|
||
that runs Faceclaw. It is a remote, not a standalone app — without Faceclaw on
|
||
the phone it only tells you to install it.
|
||
|
||
## What it does
|
||
|
||
**The pad** (the home screen; the whole display is the touch surface):
|
||
|
||
| On the watch | On the glasses |
|
||
| --- | --- |
|
||
| tap | select |
|
||
| double-tap, or a two-finger tap | **back**, everywhere: closes menus, leaves a settings column, leaves a folder or the launcher grid, returns to the sidebar (and from the sidebar turns the display off, as the ring does) |
|
||
| press and hold | the system menu: Focus app switcher, Voice input, Close window (a long press, held until you lift your finger; games that use a long press as a move get it instead) |
|
||
| tap, then press and hold | the app's context menu |
|
||
| swipe ↑ ↓ ← → | **spatial navigation, with no mode to enter first**: the launcher highlights one app and the swipe moves it by a row or a column; the settings panel moves between its columns and down its lists; the sidebar moves up and down; Music skips to the previous / next track. Right goes *into* things (sidebar → window, section → items) and left comes back *out* (first column → sidebar). Anywhere without a spatial meaning, up/down scroll, right selects and left goes back. One step per swipe (long swipes used to repeat, which overshot lists whenever the display lagged); use repeated flicks, the crown, or a two-finger page swipe to cover distance. |
|
||
| rotate the crown | previous / next (one step per detent-ish, sensitivity adjustable) — clockwise is previous by default; reverse it in the on-glasses Settings > Watch section |
|
||
| two-finger swipe up / down | scroll a page (3 steps) |
|
||
| **tip taps** — tap your index finger against your thumb | select; two quick taps = back. From the accelerometer; **off by default** (experimental): on a wrist, ordinary hand movement produced phantom selects in testing. Turn on in Watch settings; needs ~¼ s of stillness before a tap counts, and taps are ignored while the watch is off the wrist or buzzing. |
|
||
|
||
The R1 ring's scheme is untouched: the ring only has up/down, tap, double-tap
|
||
and hold, so on the glasses it still works in the stock two-step way (pick a
|
||
launcher row, tap, pick the app). Watch input is tagged as its own source, so
|
||
the same screens give the watch the direct scheme above without the ring
|
||
ever seeing a difference.
|
||
|
||
**Side buttons** (when the app is in front): button 1 tap = select, hold =
|
||
long press; button 2 = back; button 3 = "Hey Even". You can also set
|
||
the watch's button shortcut to open Faceclaw.
|
||
|
||
**Bottom row buttons**: Assistant, Type into app, Apps, Status. They are hidden
|
||
by default; swipe up beginning at the bottom edge to slide them in, then swipe
|
||
down beginning in the button tray to hide them.
|
||
|
||
- **Assistant** — ask the assistant using the *watch's* microphone (system
|
||
speech recognition) or the Wear keyboard, and read the reply on the watch as
|
||
it streams, mirrored from the glasses overlay. The watch buzzes when the
|
||
reply finishes. "Hey Even" instead opens the glasses' own voice dialog, which
|
||
uses the glasses mic.
|
||
- **Type into app** — dictate or type text into the foreground app (the
|
||
terminal, for instance), the same path finalized voice input takes.
|
||
- **Apps** — the sidebar's open windows (tap to switch, × to close) and the
|
||
full launcher, including installed EvenHub apps.
|
||
- **Status** — connection and battery, display on/off, lock/unlock, connect /
|
||
disconnect, and whether Faceclaw is running on the phone; watch settings
|
||
(haptics, keep screen on, tip taps and their sensitivity, crown sensitivity).
|
||
|
||
The pad keeps the watch display awake while it is showing (Watch settings >
|
||
"Keep screen on", default on). Wear OS otherwise dozes within seconds of the
|
||
wrist dropping, so the remote would need a wake-up tap before every gesture.
|
||
|
||
When the watch does doze (wrist down, or "Keep screen on" off), the app stays
|
||
in front as an always-on face: the pad's clock and status line on black,
|
||
redrawn once a minute. Wear OS would otherwise blur a snapshot of the app
|
||
under the system clock and, after its app timeout, drop back to the watch
|
||
face; being ambient-aware avoids both. Motion and crown input pause in ambient.
|
||
|
||
**Waking with a tap.** The system consumes the touch that wakes the watch, so
|
||
the pad treats each wake as a first tap it never saw:
|
||
|
||
- With the Wear OS "Always-on screen" setting on, the dozing pad is the same
|
||
screen, so a tap on it is a tap: one tap wakes the watch and sends *select*
|
||
to the glasses; a double-tap wakes it and sends *back*.
|
||
- With "Always-on screen" off the display was dark, so a lone tap just turns
|
||
it on; a double-tap turns it on and sends *back*.
|
||
- A wrist raise (the wrist-tilt gesture sensor) or a crown turn is not a tap.
|
||
|
||
Phone-side switches live in Faceclaw's Settings > Watch: turn watch control
|
||
off entirely, reverse the crown direction, forbid unlocking from the watch,
|
||
or stop mirroring assistant replies. While the glasses display is off, every
|
||
watch gesture except a double-tap is ignored; double-tap wakes it.
|
||
|
||
The watch buzzes differently when the phone refuses or doesn't answer a
|
||
gesture (glasses disconnected, locked, watch control off); the pill at the
|
||
bottom of the pad says why.
|
||
|
||
## Building and installing
|
||
|
||
The watch app is a separate Gradle project (Kotlin + Compose for Wear OS).
|
||
It needs the same Android SDK the phone build uses and a JDK 17+:
|
||
|
||
```bash
|
||
cd wear && JAVA_HOME=/path/to/jdk ANDROID_HOME=~/Library/Android/sdk ./gradlew :app:assembleDebug
|
||
```
|
||
|
||
The APK lands in `app/build/outputs/apk/debug/`. Install it on the watch over
|
||
adb (enable developer options on the watch, then ADB debugging and, for a
|
||
watch without USB, Wireless debugging / debug over Wi-Fi):
|
||
|
||
```bash
|
||
adb connect <watch-ip>:5555
|
||
adb -s <watch-ip>:5555 install -r app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
Two things must match the phone app or the Data Layer silently won't route:
|
||
|
||
1. **Application id** `com.faceclaw.app` — already set in `app/build.gradle.kts`.
|
||
2. **Signing key.** Debug builds of both apps use the shared Android debug
|
||
keystore (`~/.android/debug.keystore`) on the machine that builds them, so
|
||
building both on the same computer just works. For release builds, sign the
|
||
watch APK with the same keystore as the phone APK.
|
||
|
||
Run `npm run release` from the repository root to build signed phone and Wear
|
||
APKs for sideloading and AABs for Google Play. Both apps use the version in
|
||
`app/version.ts`, with distinct version codes for the phone and Wear tracks;
|
||
see [Android releases](../README.md#android-releases).
|
||
|
||
## Troubleshooting
|
||
|
||
- *"No phone connected"* — the watch has no Bluetooth link to any phone.
|
||
- *"Install Faceclaw on the phone"* — a phone is connected but no app there
|
||
advertises the `faceclaw_phone` capability: the phone build predates the
|
||
watch integration, or the app ids / signing keys differ.
|
||
- *"Open Faceclaw on the phone"* — the phone app is installed but its
|
||
dashboard isn't running (Play services started the process just for our
|
||
message). Open Faceclaw once; it keeps running with its foreground service
|
||
while connected to the glasses.
|
||
- *"The glasses are not connected"* — tap Status > Connect.
|
||
- Nothing happens and no message: check Settings > Watch on the phone.
|
||
|
||
Gestures the watch itself owns — the edge swipe-to-dismiss, the OS-level
|
||
double-pinch / "universal" gestures on some watches — are not available to
|
||
apps and aren't remapped here.
|
||
|
||
Protocol details: [PROTOCOL.md](PROTOCOL.md).
|