TASK 62 — full USB KVM: the phone becomes the glass and the hands

Status: built on ArchDev, not installed on the phone. Opened 2026-08-07. This task owns the one-cable composite from mode request through rollback and the first hardware acceptance. It does not own phone-as-host power; TASK-58 does.

Contract

The attached computer is the host. It sends a GUD display into the Pixel 3. The phone draws that display in a Wayland surface and returns keyboard, pointer and touch through boot-protocol HID. NCM keeps a control lane and smoo offers host-backed storage through FunctionFS/ublk.

One mode change owns all four functions:

kvm_mode = ffs.gud + ffs.smoo + ncm.usb0 + hid.keyboard + hid.pointer

usb-signaller prepares both FunctionFS mounts, starts both responders, waits for both readiness signals, then binds the UDC. Any failure tears the partial mode down and restores the previously working USB posture. The shell never writes configfs: it asks sessiond, which records an Action::UsbMode and calls the system D-Bus mechanism.

Where the work lives

Layer	Canonical path	State
Receiver + display + HID	`souveraine/src/bin/souveraine-usb-kvm.rs`	built ARM64
Session authority	`souveraine/src/sessiond/{protocol,device_state,server}.rs`	`usb` + `set_usb_mode`, including `kvm`
Human surface	`souveraine/surfaces/quickshell/`	nested Power Options; HID and KVM are live leaves when advertised
Souveraine package	`souveraine/packaging/arch/PKGBUILD.prebuilt`	receiver included on aarch64
Gadget mechanism	`usb-signaller/`	full composite, readiness gates, rollback, user-owned HID/GUD lane
Device packages	`Pixel3Arch/pkgs/{usb-signaller,smoo}`	recipes written; not published/installed

The separate local souveraine-usb repo is a safety copy from the first layout attempt, not a source of record. Do not build another package from it.

Verification already earned

Receiver unit tests: RGB565 dirty-rect conversion and HID usage mapping.
Receiver strict Clippy: clean.
ArchDev full release build: ARM64 PIE, 3,893,576 bytes, SHA-256 1fb58409cb1923599bcbcf229d1d2c1a61d4d7b2143387f21e7c6043ec44622d.
ArchDev sessiond build: ARM64 PIE, SHA-256 46046a53231b4f838fb47d8a8e75a51c6c8471ea3ccd2bc43bbf7ced2e38841a.
Mode scripts parse, the source/package copies match, and the Casey-owned runtime directory, environment file and /dev/hidg* nodes are reachable by the unprivileged receiver.

gud-gadget has no declared licence. Casey explicitly accepted that risk for this private build. Do not publish its binary into a public archive until that is resolved.

Phone truth before landing

Measured at 10.10.30.213 on 2026-08-07:

usb-signaller 0.3.1-3, souveraine r379, no smoo package;
live mode charging_only;
advertised modes: developer, tethering, charging-only, MTP and host;
data role device, charger online;
charge_control_end_threshold=99; no start-threshold attribute.

So a KVM button in a newly deployed shell must remain unavailable until the new usb-signaller package advertises kvm_mode. That is deliberate feature discovery, not a version guess.

Landing order

Publish/install the new souveraine, smoo, and usb-signaller packages. Keep Wi-Fi SSH alive; do not make a USB mode change the only recovery path.
Verify get_modes includes hid_mode,kvm_mode before opening the power sheet. Verify all installed files are package-owned.
Enter HID mode first. Confirm keyboard and pointer enumerate on the host, reports arrive, and developer mode restores cleanly.
Enter KVM mode. Confirm host enumeration for GUD, both HIDs, NCM and smoo; then confirm a host frame reaches the phone and touch returns to the host.
Pull the cable and force one responder failure. In both cases the daemon must stop services, release FunctionFS, and leave or restore a usable mode.
Only after those checks make KVM a normal daily-driver choice.

No phone mutation or flash belongs before step 1's packages exist.

Acceptance

A host frame is visible on the phone; resize redraws without a blank buffer.
Physical keyboard, mouse and touch in that surface control the attached host.
NCM remains usable and smoo reaches its ready endpoint.
Closing the surface, unplugging, or a failed responder leaves no stuck UDC, root-only endpoint or dead management port.
The held-power sheet reports the actual mode and returns to developer USB.

Connects to

USB/README.md (exploration and host-mode record), TASK-30 (verb tables), TASK-33 (adjacent charging policy), TASK-50 (the inverse hand-on-glass path), TASK-57 (phone-as-gadget dock), TASK-58 (host-role VBUS), SAF federation (attached identity and probe ownership).

4.7 KiB Raw Blame History