diff --git a/docs/src/architecture.md b/docs/src/architecture.md index b064813..9d0bc74 100644 --- a/docs/src/architecture.md +++ b/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 diff --git a/docs/src/boards/geprc-f722-v2.md b/docs/src/boards/geprc-f722-v2.md index cdeb878..5df814b 100644 --- a/docs/src/boards/geprc-f722-v2.md +++ b/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/` 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/ --baud 115200 -``` +Enter `/dev/serial/by-id/` 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. diff --git a/docs/src/boards/index.md b/docs/src/boards/index.md index e73c4b3..116de2d 100644 --- a/docs/src/boards/index.md +++ b/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). diff --git a/docs/src/boards/kakute-f7-mini-v3.md b/docs/src/boards/kakute-f7-mini-v3.md index 6e8a848..b2056f8 100644 --- a/docs/src/boards/kakute-f7-mini-v3.md +++ b/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/` 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/ --baud 115200 -``` +Enter `/dev/serial/by-id/` 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. diff --git a/docs/src/configuration.md b/docs/src/configuration.md index 6a0fc1d..7352d6d 100644 --- a/docs/src/configuration.md +++ b/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/ --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/` 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. diff --git a/docs/src/logs.md b/docs/src/logs.md index c4871cd..1a335a0 100644 --- a/docs/src/logs.md +++ b/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. diff --git a/docs/src/mavlink.md b/docs/src/mavlink.md index 2392bcd..bb9dfa1 100644 --- a/docs/src/mavlink.md +++ b/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 diff --git a/docs/src/reference.md b/docs/src/reference.md index 64fa469..78e19ff 100644 --- a/docs/src/reference.md +++ b/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