docs: document usb mavlink and configurator startup

docs/src/architecture.md

@@ -61,11 +61,12 @@ erase sectors, retaining only the old and replacement records across the commit
 boundary. Neither format is exposed as the public KCFG file.
 Motor allocation/mixer topology is immutable compiled vehicle capability data,
 never a scalar field or persistence member. F722 recovers operational settings
-before constructing consumers. Its directly wired local UART accepts only
-exact-target, CRC-valid Kaptan file requests while physical outputs remain
-inhibited. CRC is integrity-only; a shared or remote GCS still needs production
-authentication, source binding, and persistent anti-replay state. Disarmed
-activation and flight-consumer reconstruction remain separate reviewed work.
+before constructing consumers. Its local USB CDC-ACM and directly wired UART
+accept only exact-target, CRC-valid Kaptan file requests while physical outputs
+remain inhibited. CRC is integrity-only; a shared or remote GCS still needs
+production authentication, source binding, and persistent anti-replay state.
+Disarmed activation and flight-consumer reconstruction remain separate reviewed
+work.
 
 The MAVLink dialect root directly includes one-message XML leaves under
 `publish/` and `transfer/`. The `exchange/` contract remains empty until a

docs/src/boards/geprc-f722-v2.md

@@ -1,7 +1,7 @@
 # GEPRC GEP-F722-HD V2
 
 The GEPRC GEP-F722-HD V2 board declaration uses the ICM-42688-P on SPI3 and
-MAVLink telemetry on USART2. It declares no vertical sensor stream. The
+MAVLink telemetry on USB CDC-ACM and USART2. It declares no vertical sensor stream. The
 manufacturer's [GEP-F722-HD V2 manual](https://geprc.com/wp-content/uploads/2025/05/GEP-F722-HD-v2%E9%A3%9E%E6%8E%A7_%E4%BA%A7%E5%93%81%E8%AF%B4%E6%98%8E%E4%B9%A6-.pdf)
 labels the external UART2 pads `T2` and `R2`.
 
@@ -40,7 +40,20 @@ dfu-util --list
 make firmware/boards/geprc-f722-v2 flash
 ```
 
-## Telemetry wiring
+## MAVLink over USB
+
+After flashing, leave ROM DFU mode and reconnect USB. The running application
+enumerates as `Kaptan / GEPRC TAKER F722 V2 (ICM-42688-P)`, normally
+`/dev/ttyACM*` on Linux. Run:
+
+```sh
+make firmware/tools/configurator
+```
+
+Open `http://127.0.0.1:4861` and connect `/dev/serial/by-id/<kaptan-device>` or
+the discovered `/dev/ttyACM*` path from the Connection section.
+
+## UART fallback
 
 Connect a 3.3 V USB-UART adapter with crossed data lines and common ground:
 
@@ -50,12 +63,7 @@ Connect a 3.3 V USB-UART adapter with crossed data lines and common ground:
 | `TX` | `R2` |
 | `GND` | `GND` |
 
-Then run:
-
-```sh
-make firmware/tools/configurator -- \
-    --source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
-```
+Enter `/dev/serial/by-id/<adapter>` in the same configurator's Connection section.
 
 Open `http://127.0.0.1:4861`, Save the discovered fields, and manually
 power-cycle the controller after Save completes. The flash journal is outside
@@ -63,5 +71,5 @@ the application image, so the exact range-limited DFU command above preserves
 it. A mass erase or full-chip erase removes committed settings and restores
 board factory defaults at the next boot. The image remains telemetry-only and
 applies startup motor-pin inhibition. The unsigned local configuration path
-assumes this direct wiring; disconnect every other transmitter from `R2` while
-configuring.
+assumes one directly connected client; disconnect every other transmitter from
+`R2` while configuring over UART.

docs/src/boards/index.md

@@ -3,10 +3,10 @@
 Board pages describe supported hardware topology, build products, and safe
 verification. They do not declare a board flight-ready.
 
-| Board | MCU family | Primary IMU | MAVLink UART |
+| Board | MCU family | Primary IMU | MAVLink links |
 | --- | --- | --- | --- |
-| [Kakute F7 Mini V3](kakute-f7-mini-v3.md) | STM32F722 | MPU-6000 | USART1 |
-| [GEPRC GEP-F722-HD V2](geprc-f722-v2.md) | STM32F722 | ICM-42688-P | USART2 |
+| [Kakute F7 Mini V3](kakute-f7-mini-v3.md) | STM32F722 | MPU-6000 | USB CDC-ACM, USART1 |
+| [GEPRC GEP-F722-HD V2](geprc-f722-v2.md) | STM32F722 | ICM-42688-P | USB CDC-ACM, USART2 |
 
 All board images share the motor-pin inhibit boundary described in
 [Safety boundary](../safety-boundary.md).

docs/src/boards/kakute-f7-mini-v3.md

@@ -1,7 +1,8 @@
 # Kakute F7 Mini V3
 
 The Holybro Kakute F7 Mini V3 board declaration uses the MPU-6000 on SPI1,
-MAVLink telemetry on USART1, and the MTF01 range/optical-flow route on UART4.
+MAVLink telemetry on USB CDC-ACM and USART1, and the MTF01 range/optical-flow
+route on UART4.
 The checked-in manufacturer datasheet is
 `firmware/boards/kakute-f7-mini-v3/datasheet.pdf`.
 
@@ -45,7 +46,20 @@ dfu-util --list
 make firmware/boards/kakute-f7-mini-v3 flash
 ```
 
-## Telemetry wiring
+## MAVLink over USB
+
+After flashing, release `Boot` and reconnect USB so the application starts and
+enumerates as `Kaptan / Kakute F7 Mini V3`, normally `/dev/ttyACM*` on Linux.
+Then launch the target-described web UI:
+
+```sh
+make firmware/tools/configurator
+```
+
+Open `http://127.0.0.1:4861` and connect `/dev/serial/by-id/<kaptan-device>` or
+the discovered `/dev/ttyACM*` path from the Connection section.
+
+## UART fallback
 
 Use a 3.3 V USB-to-UART adapter with crossed data lines and common ground:
 
@@ -55,12 +69,7 @@ Use a 3.3 V USB-to-UART adapter with crossed data lines and common ground:
 | `TX` | `R1` |
 | `GND` | `G` |
 
-Launch the target-described web UI:
-
-```sh
-make firmware/tools/configurator -- \
-    --source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
-```
+Enter `/dev/serial/by-id/<adapter>` in the same configurator's Connection section.
 
 Open `http://127.0.0.1:4861`, edit the discovered fields, press Save, and
 manually power-cycle the controller after Save completes. The flash journal is
@@ -68,5 +77,5 @@ outside the application image, so the exact range-limited DFU command above
 preserves it. A mass erase or full-chip erase removes committed settings and
 restores board factory defaults at the next boot. The image remains
 telemetry-only and does not enable motor control. The unsigned local
-configuration path assumes this direct wiring; disconnect every other
-transmitter from `R1` while configuring.
+configuration path assumes one directly connected client; disconnect every
+other transmitter from `R1` while configuring over UART.

docs/src/configuration.md

@@ -12,19 +12,25 @@ parameter catalog.
 | --- | --- | --- |
 | `kaptan-sitl serve --config FILE.cbor` | One validated Quad-X configuration at process construction. | No live file endpoint is attached yet. |
 | `kaptan-sitl serve` | The validated factory Quad-X configuration. | No persistent store. |
-| STM32F722 image | Board factory settings, or the newest valid flash-journal snapshot. | `/config/user.kcfg` on the directly wired local UART while motor pins remain inhibited. |
+| STM32F722 image | Board factory settings, or the newest valid flash-journal snapshot. | `/config/user.kcfg` over local USB CDC-ACM or the directly wired UART while motor pins remain inhibited. |
 
 ## Web configurator
 
-Build and flash the board image, connect its MAVLink UART directly to a 3.3 V
-USB-UART adapter, then run from the repository root:
+Build and flash the board image, boot normally, connect the board's USB port,
+and run from the repository root:
 
 ```sh
-make firmware/tools/configurator -- \
-    --source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
+make firmware/tools/configurator
 ```
 
-`--source-system` is the configurator's exact MAVLink source identity. Every
+Open `http://127.0.0.1:4861`, enter the device path in the Connection section,
+and select **Connect serial**. On Linux the application device normally appears
+as `/dev/serial/by-id/<kaptan-device>` or `/dev/ttyACM0`. For UART, connect a
+3.3 V USB-UART adapter to the board-specific RX/TX pads and enter its device
+path instead.
+
+The web tool defaults to MAVLink source system `255` and baud `115200`.
+`--source-system` and `--baud` remain optional command-line overrides. Every
 simultaneously connected GCS must use a different nonzero system ID so transfer
 ownership and retries cannot alias another client.
 
@@ -71,7 +77,8 @@ cannot safely be edited as scalar configuration:
 
 - output-inhibit and status-LED routes;
 - IMU model, bus, interrupt route, mount, and driver setup;
-- MAVLink and optional vertical-sensor routes and bootstrap baud rates;
+- MAVLink UART and optional vertical-sensor routes and bootstrap baud rates;
+- the fixed F722 USB CDC-ACM transport;
 - service-timer frequency; and
 - compiled image role.
 
@@ -155,9 +162,10 @@ UTF-8 detail. The configurator rejects a successful close with a missing,
 malformed, or failure-bearing prefix. The file layer passes these bytes through
 without interpreting them.
 
-The directly wired local UART is the initial transport. CRC validates framing
-integrity, not peer authenticity. Disconnect other transmitters from the board
-RX line. A shared or remote GCS still requires signing, source/key binding,
+Local USB CDC-ACM and the directly wired UART are the F722 transports. CRC
+validates framing integrity, not peer authenticity. Use one directly connected
+client and disconnect other transmitters from the board RX line while using the
+UART. A shared or remote GCS still requires signing, source/key binding,
 persistent anti-replay state, and provisioning before this inbound service can
 be exposed safely.
 

docs/src/logs.md

@@ -83,6 +83,6 @@ The log ingress is transport-neutral and unfiltered. The tested
 fanning an event into that sink and proves `kaptan_log::info!` reaches a
 generated `LOG` payload.
 `kaptan-sitl serve` does not yet attach a file/diagnostic MAVLink link. F722
-images accept only the unsigned Kaptan file service on their directly wired
-local UART; that direct-wire assumption does not extend to a shared or remote
-MAVLink network.
+images accept the unsigned Kaptan file service on local USB CDC-ACM and their
+directly wired UART; that physical-link assumption does not extend to a shared
+or remote MAVLink network.

docs/src/mavlink.md

@@ -17,10 +17,21 @@ requires verified MAVLink 2 signing, configured source/target binding,
 persistent anti-replay state, and a provisioning/key-rotation policy as one
 reviewed feature.
 
-The local UART is Kaptan's initial operational file transport, not an
-authenticated remote-control channel. Any transmitter electrically connected
-to that RX line can issue file requests, so connect the USB-UART
-adapter directly and disconnect other transmitters. The platform retains its
+Each F722 image exposes MAVLink on its board-selected UART and as a USB CDC-ACM
+serial device. Linux normally names the application USB link `/dev/ttyACM*`;
+this is distinct from the STM32 ROM DFU device used while the Boot pin is
+asserted. UART and USB have independent receive framers. A host that opens the
+CDC port and asserts DTR becomes the publication and diagnostic link; UART is
+used while USB is closed. A file response is always returned on the link that
+carried its request, so connecting USB cannot redirect a UART transaction.
+The current descriptor uses the pid.codes shared development identity
+`1209:0001` plus the STM32 factory device ID as its serial number. Obtain and
+substitute a project-specific PID before distributing hardware as a product.
+
+These local links are operational file transports, not authenticated
+remote-control channels. Any transmitter physically connected to either link
+can issue file requests, so use a direct USB cable or USB-UART adapter and
+disconnect other transmitters while configuring. The platform retains its
 startup-configured low motor-output state throughout this workflow; no marker
 type is treated as GPIO ownership or command authority. A networked GCS must
 add verified signing, source binding, and durable replay protection before it
@@ -33,9 +44,13 @@ close response does not repeat a flash operation. This serialization does not
 authenticate its peer.
 
 Telemetry transmission uses bounded frame classes. A critical frame may
-replace pending best-effort traffic, but never the DMA-owned active buffer.
-Completion retries preserve ordering and retain a transiently busy frame for a
-later service turn.
+replace pending best-effort traffic, but never a UART-DMA-owned or active USB
+frame. UART completion retries preserve ordering, while USB advances a retained
+frame across bounded CDC endpoint writes. DTR close, suspend, and
+deconfiguration pause USB transmission and return publications to UART. Only a
+bus reset discards USB transmission state. Closing DTR also discards partial
+input. File-transfer and response-replay state expire under the protocol lease,
+not on transport disconnect.
 
 The local web configurator exposes a bounded live view of CRC-valid inbound
 frames. It groups packets by source and message ID and measures receive

docs/src/reference.md

@@ -10,7 +10,7 @@ This page collects stable limits and points to the detailed contracts.
 | File transfer | Custom `FILE_CONTROL` (51025) and `FILE_DATA` (51026), one owner-bound stop-and-wait transfer, 246-byte data chunks, CRC-32C. |
 | Diagnostics | `LOG` (51020) for macro-produced level/text; `ERROR` (51021) for a bounded reportable `{ error_id, raised_at[96] }` firmware error. |
 | Publications | Kaptan-native `HEARTBEAT` (51027), `IMU` (51028), `RANGE` (51029), and `OPTICAL_FLOW` (51030); exact integer units and monotonic `u64` microseconds. |
-| F722 configuration | `/config/user.kcfg`; target-described fields and board factory values over a directly wired unsigned UART with motor outputs physically inhibited. |
+| F722 configuration | `/config/user.kcfg`; target-described fields and board factory values over local USB CDC-ACM or a directly wired unsigned UART with motor outputs physically inhibited. |
 
 Read [Configuration](configuration.md) for configuration ownership, artifact,
 and file contracts, [Logs](logs.md) for receiver decoding and filtering, and