public/kaptan
1
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity

build: add directory-oriented make workflows
Host SITL smoke / Deterministic Gazebo command path (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Onur Özkan committed 2026-08-30 07:05:01 +03:00
1 parent 4bc98adbc6
commit 7dc3ccb619
40 files changed
+1367 -278
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/Makefile
+34 -8
View File
@@ -1,12 +1,38 @@
MDBOOK ?= mdbook
override SHELL := /bin/sh
override MAKEFLAGS += --no-print-directory
.PHONY: build serve test
.DEFAULT_GOAL := help
.DELETE_ON_ERROR:
build:
override MDBOOK := mdbook
override PRIMARY_GOAL := $(firstword $(MAKECMDGOALS))
ifeq ($(PRIMARY_GOAL),run)
.PHONY: run
# Application arguments may also look like Make goals. The run recipe recovers
# their exact boundaries from the original invocation.
.DEFAULT:
@:
else
.PHONY: help run check
help:
@printf '%s\n' 'Usage: make docs -- <mdbook arguments...>' '' \
'With no arguments, mdbook test and mdbook build are run.' \
'Example: make docs -- build' '' \
'Project target:' \
' check Run mdbook test and mdbook build'
endif
check:
$(MDBOOK) test
$(MDBOOK) build
serve:
$(MDBOOK) serve --open
test:
$(MDBOOK) test
run:
@exec python3 ../scripts/make-argv.py exec run $(MDBOOK)
docs/src/boards/geprc-f722-v2.md
+5 -10
View File
@@ -17,13 +17,10 @@ the board's immutable typestate literal.
## Build and package
From the firmware workspace:
From the repository root:
```sh
cd firmware
cargo build --release --locked -p kaptan-geprc-f722-v2 \
--target thumbv7em-none-eabihf
./scripts/create-dfu-image.sh target/thumbv7em-none-eabihf/release/kaptan-geprc-f722-v2
make firmware/boards/geprc-f722-v2
```
The packaging script validates the ELF against the shared F722 linker layout
@@ -40,9 +37,7 @@ listed `0483:df11` target before flashing:
```sh
dfu-util --list
dfu-util --device 0483:df11 --alt 0 \
--dfuse-address 0x08000000:leave \
--download target/thumbv7em-none-eabihf/release/kaptan-geprc-f722-v2.bin
make firmware/boards/geprc-f722-v2 flash
```
## Telemetry wiring
@@ -58,8 +53,8 @@ Connect a 3.3 V USB-UART adapter with crossed data lines and common ground:
Then run:
```sh
cargo run --locked -p kaptan-configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
make firmware/tools/configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
```
Open `http://127.0.0.1:4861`, Save the discovered fields, and manually
docs/src/boards/kakute-f7-mini-v3.md
+5 -10
View File
@@ -17,13 +17,10 @@ typestate literal.
## Build and package
From the firmware workspace:
From the repository root:
```sh
cd firmware
cargo build --release --locked -p kaptan-kakute-f7-mini-v3 \
--target thumbv7em-none-eabihf
./scripts/create-dfu-image.sh target/thumbv7em-none-eabihf/release/kaptan-kakute-f7-mini-v3
make firmware/boards/kakute-f7-mini-v3
```
The packaging script uses the shared F722 linker layout and prints the flash
@@ -45,9 +42,7 @@ application offset.
```sh
dfu-util --list
dfu-util --device 0483:df11 --alt 0 \
--dfuse-address 0x08000000:leave \
--download target/thumbv7em-none-eabihf/release/kaptan-kakute-f7-mini-v3.bin
make firmware/boards/kakute-f7-mini-v3 flash
```
## Telemetry wiring
@@ -63,8 +58,8 @@ Use a 3.3 V USB-to-UART adapter with crossed data lines and common ground:
Launch the target-described web UI:
```sh
cargo run --locked -p kaptan-configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
make firmware/tools/configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
```
Open `http://127.0.0.1:4861`, edit the discovered fields, press Save, and
docs/src/configuration.md
+3 -3
View File
@@ -17,11 +17,11 @@ parameter catalog.
## Web configurator
Build and flash the board image, connect its MAVLink UART directly to a 3.3 V
USB-UART adapter, then run from `firmware`:
USB-UART adapter, then run from the repository root:
```sh
cargo run --locked -p kaptan-configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
make firmware/tools/configurator -- \
--source-system 255 --serial /dev/serial/by-id/<adapter> --baud 115200
```
`--source-system` is the configurator's exact MAVLink source identity. Every
docs/src/development.md
+34 -15
View File
@@ -1,27 +1,46 @@
# Development and verification
## Command layout
Each component owns its Makefile: the Cargo workspace, all-board workflows,
individual boards, tools, and documentation each define commands in their own
directory. The root Makefile contains repository-wide workflows and routes a
directory path to that directory's Makefile.
The standard `--` ends Make's own options. Every following argument uses the
selected application's native command line. For example,
`make firmware -- test --workspace --locked --offline` runs `cargo test
--workspace --locked --offline` from `firmware`, while
`make firmware/tools/sitl -- ready` runs `kaptan-sim ready`. Board paths are
the complete build-and-package command, so they need no invented operation
name.
## Fast host checks
```sh
cd firmware
cargo test --workspace --offline
cargo clippy --workspace --all-targets --offline --exclude kaptan-geprc-f722-v2 --exclude kaptan-kakute-f7-mini-v3 -- -D warnings
cargo clippy -p platform-stm32f7 --all-targets --offline -- -D warnings
cargo fmt --all --check
git diff --check
make firmware -- fmt --all --check
make firmware -- test --workspace --locked --offline
make firmware -- clippy --workspace --all-targets \
--exclude kaptan-geprc-f722-v2 \
--exclude kaptan-kakute-f7-mini-v3 --locked --offline -- -D warnings
```
## Target checks
```sh
cd firmware
cargo clippy -p kaptan-geprc-f722-v2 -p kaptan-kakute-f7-mini-v3 \
--target thumbv7em-none-eabihf --offline -- -D warnings
cargo build --release --locked \
make firmware/boards
make firmware -- clippy \
-p kaptan-geprc-f722-v2 -p kaptan-kakute-f7-mini-v3 \
--target thumbv7em-none-eabihf --offline
--target thumbv7em-none-eabihf --locked --offline -- -D warnings
```
`make firmware docs` builds Rust API documentation with warnings denied.
`make docs` checks and builds the separate mdBook project. `make pre-commit`
runs both documentation checks along with repository formatting, host and
embedded Clippy, Rust and script tests, and SITL structure tests. `make check`
adds a whitespace check. `make build` builds and packages release firmware and
builds the mdBook project.
## Strict core coverage
```sh
@@ -38,10 +57,10 @@ the gate.
## Simulation acceptance
```sh
cd firmware
python3 tools/sitl/world-structure-test.py
python3 -m unittest tools/sitl/test_kaptan_sim.py
tools/sitl/e2e-smoke.sh
cd firmware/tools/sitl
python3 world-structure-test.py
python3 -m unittest test_kaptan_sim.py
./e2e-smoke.sh
```
The Docker smoke is intentionally separate from host unit tests because it
docs/src/errors.md
+1 -1
View File
@@ -2,7 +2,7 @@
Public reportable Kaptan error enums derive `KaptanError`:
```rust
```rust,ignore
#[derive(Debug, kaptan_err_reportable::KaptanError)]
enum SensorError {
#[kaptan_error(id = 12345)]
docs/src/getting-started.md
+9 -5
View File
@@ -11,12 +11,16 @@ The repository development shell also supplies `dfu-util` and the checked
nix develop
```
For host development, run:
From the repository root, discover the developer commands with:
```sh
cd firmware
cargo test --workspace --offline
cargo clippy --workspace --all-targets --offline --exclude kaptan-geprc-f722-v2 --exclude kaptan-kakute-f7-mini-v3 -- -D warnings
make help
```
Run the repository checks with:
```sh
make pre-commit
```
Bare-metal board packages are not host-test targets. Check them with the
@@ -42,7 +46,7 @@ The manual is an [mdBook](https://rust-lang.github.io/mdBook/) project. The
repository's Nix development shell provides the checked tool version:
```sh
nix develop -c make -C docs build
nix develop -c make docs -- build
```
The generated static site is written to `target/docs/`.
docs/src/logs.md
+1 -1
View File
@@ -2,7 +2,7 @@
Kaptan code uses the familiar logging macros on both host and flight targets:
```rust
```rust,ignore
kaptan_log::debug!("estimator waiting for IMU");
kaptan_log::info!("configuration loaded");
kaptan_log::warn!("range aid stale");
docs/src/reference.md
+2 -18
View File
@@ -21,24 +21,8 @@ and file contracts, [Logs](logs.md) for receiver decoding and filtering, and
Before review, run:
```sh
cd firmware
cargo fmt --all --check
cargo test --workspace --locked --offline
cargo clippy --workspace --all-targets \
--exclude kaptan-kakute-f7-mini-v3 \
--exclude kaptan-geprc-f722-v2 --locked --offline -- -D warnings
cargo clippy -p kaptan-kakute-f7-mini-v3 -p kaptan-geprc-f722-v2 \
--target thumbv7em-none-eabihf --locked --offline -- -D warnings
cargo build --release --locked --offline \
-p kaptan-kakute-f7-mini-v3 -p kaptan-geprc-f722-v2 \
--target thumbv7em-none-eabihf
python3 -m unittest scripts/test-analyze-fw.py
scripts/analyze-fw.py \
target/thumbv7em-none-eabihf/release/kaptan-kakute-f7-mini-v3 \
platforms/stm32f7/link/f722/memory.x
scripts/analyze-fw.py \
target/thumbv7em-none-eabihf/release/kaptan-geprc-f722-v2 \
platforms/stm32f7/link/f722/memory.x
make pre-commit
make build
```
The target-specific lint verifies the local configuration receiver and journal
docs/src/safety-boundary.md
+2 -2
View File
@@ -26,8 +26,8 @@ authority.
Run the structural guard after any platform or board change:
```sh
cd firmware
cargo test -p platform-stm32f7 --test platform_safety_boundary --offline
make firmware -- test -p platform-stm32f7 \
--test platform_safety_boundary --locked --offline
```
This boundary is deliberately stronger than an application-level disarm flag:
docs/src/sitl.md
+6 -8
View File
@@ -11,19 +11,17 @@ It is a pre-bench software gate, not a physical-flight validation.
## Run the closed loop
```sh
cd firmware
docker compose -f tools/sitl/compose.yaml up -d --build
tools/sitl/kaptan-sim ready
tools/sitl/kaptan-sim move 5 3 1 --wait
tools/sitl/kaptan-sim land 0 0 --wait
docker compose -f tools/sitl/compose.yaml down
docker compose -f firmware/tools/sitl/compose.yaml up -d --build
make firmware/tools/sitl -- ready
make firmware/tools/sitl -- move 5 3 1 --wait
make firmware/tools/sitl -- land 0 0 --wait
docker compose -f firmware/tools/sitl/compose.yaml down
```
For the reproducible command-path gate, use:
```sh
cd firmware
tools/sitl/e2e-smoke.sh
firmware/tools/sitl/e2e-smoke.sh
```
The smoke scenario verifies ascent, translation, descent, landing, flat-plane