Server control protocol and device actions
Overview
The Android server control path is the bidirectional control socket handled by server/…/ControlChannel.java. It wraps a LocalSocket with a ControlMessageReader for client-to-device messages and a DeviceMessageWriter for device-to-client responses. server/…/Controller.java owns the receive loop: start() launches a control-recv thread that repeatedly calls controlChannel.recv(), decodes one ControlMessage, and dispatches it to Android wrapper calls through server/…/Device.java, capture controls, camera controls, or the UHID manager.
server/…/ControlMessageReader.java defines the wire framing for incoming commands. Every message starts with a one-byte type from ControlMessage.java; payloads are then read in big-endian DataInputStream order. Text and byte-array fields are length-prefixed: most strings use a 4-byte length, UHID names and START_APP use a 1-byte length, and UHID report/input arrays use a 2-byte length. Positional events carry x, y, and the client video size; scroll values are signed fixed-point shorts expanded to a [-16, 16] range, while touch pressure is an unsigned fixed-point short. Unknown message types throw ControlProtocolException, which makes Controller.handleEvent() log a protocol error and stop the receive loop.
Controller.handleEvent() separates universal capture messages, display/device messages, and camera-source messages. TYPE_RESET_VIDEO resets surfaceCapture.getCaptureControl() for both display and camera sources. In normal display mode, key, text, touch, scroll, back/screen-on, display power, rotation, panels, clipboard, UHID, hard-keyboard settings, app start, display resize, and file-scan messages are handled. In camera mode, input/device actions are disabled and only camera torch/zoom messages plus reset-video are accepted. Input injection is gated by Device.supportsInputEvents(displayId), which allows the main display on all supported Android versions and secondary displays only from Android 10 onward.
server/…/Device.java is the bridge from decoded control actions to Android services. It injects KeyEvent and MotionEvent objects via ServiceManager.getInputManager().injectInputEvent(), setting a non-main display id on the event before injection. It also wraps power/display state (PowerManager, SurfaceControl, DisplayControl), status-bar panels, clipboard access, rotation through WindowManager, app discovery and launch through PackageManager/ActivityManager, and broadcasts such as media scans. Display power is especially device-version-specific: Device.setDisplayPower() deliberately avoids Android 15's newer request-display-power path, applies power mode to all physical displays on Android 10+, and has an Honor Android 14 workaround that falls back to the built-in display path.
For text input, Controller.injectText() iterates characters and maps each through server/…/KeyComposition.java before asking KeyCharacterMap for key events. The composition table decomposes accented characters into Android dead-key sequences because KeyCharacterMap.getEvents() may return null for precomposed characters. Each generated KeyEvent is injected asynchronously to the current action display.
Pointer and coordinate handling is split across Controller.java, PositionMapper.java, PointersState.java, and Pointer.java. A video capture notifies Controller.onNewVirtualDisplay() with the target display id and a PositionMapper; the controller stores them atomically and wakes waiters that need a virtual-display id. PositionMapper.map() rejects positional events whose embedded client video size no longer matches the current video size, which prevents stale clicks after rotation or resize, and applies the capture transform from video pixels to device pixels when needed. Controller.getEventPointAndDisplayId() uses mapped coordinates and the virtual display id when display data exists; without display data it accepts raw coordinates only for a real displayId.
Touch injection keeps multi-pointer state in PointersState. Client pointer ids are mapped to compact Android local ids with a maximum of ten active pointers, and pointers marked up are removed after their current event is materialized into MotionEvent.PointerProperties and PointerCoords. The special client pointer id -1 is treated as the mouse when it is a hover event or any non-primary mouse button is active; otherwise the controller emits touchscreen events and clears buttons. Multi-touch down/up actions are rewritten to ACTION_POINTER_DOWN/ACTION_POINTER_UP with the pointer index. On Android 6+, mouse button transitions are expanded into Android's required sequence: first button ACTION_DOWN, every press ACTION_BUTTON_PRESS, every release ACTION_BUTTON_RELEASE, and final release ACTION_UP, with InputManager.setActionButton() setting the changed button.
Non-positional actions use Controller.getActionDisplayId(): a real mirrored display uses the configured displayId, while --new-display waits for capture to report the virtual display id and otherwise returns DISPLAY_ID_NONE. This display-id distinction is important because Controller.java intentionally injects coordinate-relative events to the virtual display id but injects other key/action events to the configured display id unless the configured id is Device.DISPLAY_ID_NONE. BACK_OR_SCREEN_ON checks screen state before choosing BACK versus POWER, and SET_DISPLAY_POWER targets the main display when mirroring a virtual display so a virtual display's power shortcut can still wake the physical device.
Clipboard responses are device-to-client messages. Controller creates a DeviceMessageSender unless the video source is camera. If clipboard autosync is enabled, the controller registers a ClipboardManager primary-clip listener; changes not caused by the controller itself are sent as DeviceMessage.TYPE_CLIPBOARD. An explicit GET_CLIPBOARD may first inject COPY or CUT with wait-for-finish on Android 7+, then sends a clipboard message only when autosync is disabled to avoid duplicate synchronization. SET_CLIPBOARD sets Android clipboard text, optionally injects PASTE on Android 7+, and sends TYPE_ACK_CLIPBOARD when the client supplied a nonzero sequence.
Outgoing messages are asynchronous. server/…/DeviceMessageSender.java owns a control-send thread and a bounded queue of 16 messages; producers call send() from the receive thread, clipboard listener, or UHID file-descriptor callback. If the queue is full, the message is dropped with a warning rather than blocking the producer. server/…/DeviceMessageWriter.java serializes the response type and payload, truncates clipboard UTF-8 safely to fit a 256 KiB message, writes UHID output as id plus 2-byte length plus data, and flushes after each message.
UHID support is lazy. Controller.getUhidManager() creates server/…/UhidManager.java on the first UHID control message. On Android 15+ with --new-display, it may wait up to one second for a virtual display id, then looks up that display's unique id so UHID devices can be associated to the display through InputManager.addUniqueIdAssociationByPort(). UhidManager.open() opens /dev/uhid, replaces any duplicate id, writes a UHID_CREATE2 request using the client-provided vendor id, product id, name, and HID report descriptor, and registers a file-descriptor listener on a HandlerThread for Android 6+. UHID_INPUT messages write UHID_INPUT2 requests to the stored fd, and UHID_DESTROY closes and unregisters the fd; closing the last device removes the display association. UHID output reports read from /dev/uhid are converted into DeviceMessage.TYPE_UHID_OUTPUT and sent back through the same asynchronous sender.
Concurrency is intentionally narrow. The receive loop executes most device actions serially on control-recv, but long app lookup/start work is offloaded to a single-thread executor in Controller.startAppAsync() so control reception is not blocked while installed apps are scanned. --keep-active starts a daemon keep-active thread that periodically calls Device.keepActive() for the current action display. displayData is an AtomicReference because capture callbacks, the receive thread, the keep-active thread, UHID creation, and start-app logic may all observe it; first availability is additionally signaled through displayDataAvailable. On shutdown, Controller.stop() interrupts keep-active, receive, and sender threads, while the receive thread's finally closes all UHID fds before notifying termination.
Coupling
- If a control message type is added or its payload changes, update ControlMessage.java, ControlMessageReader.java, and
Controller.handleEvent()together; the reader throwsControlProtocolExceptionfor unknown types and the controller throws an assertion for decoded-but-unhandled types. - If a device-to-client response changes, update DeviceMessage.java, DeviceMessageWriter.java, and every producer in Controller.java or UhidManager.java; the writer is the only place that defines the outgoing byte layout and it flushes per message.
- If video sizing, transforms, capture orientation, virtual display creation, or display resize behavior changes outside this package, verify
PositionMapper.map()andController.getEventPointAndDisplayId()still receive the same video size/transform contract; stale size mismatches are intentionally dropped instead of remapped. - If display-id semantics change, check both positional and non-positional paths in Controller.java: touch/scroll use the virtual display id from
DisplayData, while key/back/rotation/start-app/keep-active usegetActionDisplayId()orgetStartAppDisplayId(). - If clipboard behavior changes, keep
Controller.isSettingClipboardaligned withDevice.setClipboardText()and the autosync listener; otherwise setting clipboard from the client may echo back as a device clipboard update or duplicate COPY/CUT results. - If UHID protocol fields or Android display association behavior changes, update both
ControlMessageReader.parseUhidCreate()andUhidManager.buildUhidCreate2Req()/buildUhidInput2Req(); the reader's 1-byte name and 2-byte descriptor/input lengths must match the native UHID request builder.
Risks
Controller.getEventPointAndDisplayId()andPositionMapper.map()drop positional events when the client-reported video size differs from the current mapper size. This protects against stale clicks after rotation, but if capture code reports the wrong size or missesonNewVirtualDisplay(), touch and scroll silently stop taking effect; history aroundPositionMapperincludes several transform/crop/orientation rewrites and event-size logging changes.Device.setDisplayPower()is fragile across Android versions and vendors. It deliberately disables the Android 15 display-power API because of a linked issue, applies multi-physical-display logic on Android 10+, and special-cases Honor Android 14; changing this path can break turn-screen-off/on shortcuts or cleanup restore behavior inController.setDisplayPower().UhidManageruses one sharedByteBufferfor all UHID fd callbacks on its handler thread and sends output through a bounded queue. If future UHID reads are moved off that single looper or produce bursts larger thanDeviceMessageSender's 16-message queue, HID output reports can be corrupted or dropped.Controller.startAppAsync()creates a single-thread executor butController.stop()does not shut it down. App lookup is intentionally off the receive loop, but long-running package scans can outlive control shutdown and still callDevice.startApp()if not guarded by future lifecycle changes.