Skip to content

Commit 1300c05

Browse files
jburo1jburo1
committed
docs(software): document the sim/real boundary and expanded CI flow.
1 parent b87318c commit 1300c05

3 files changed

Lines changed: 787 additions & 37 deletions

File tree

‎docs/software/build_pipeline.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,17 @@ change.
2626
## Shared Validation Flow
2727

2828
After code is pushed or opened in a pull request, GitHub Actions runs the
29-
repository's CI workflow to validate the main supported package set.
29+
repository's CI workflow in several focused lanes:
30+
31+
- `lint`
32+
- `ros-core`
33+
- `bringup-smoke`
34+
- `vision-host`
35+
- `firmware-build`
36+
- `docs-build`
37+
38+
This keeps the default PR gate broad enough to catch interface drift while
39+
keeping the slower checks isolated instead of hiding inside one large job.
3040

3141
See [CI/CD Overview](ci_cd.md) for:
3242

‎docs/software/ci_cd.md‎

Lines changed: 120 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ repository and how it affects day-to-day development.
77

88
There are currently two GitHub Actions workflows:
99

10-
- `ci`: continuous integration for build, lint, and test validation
10+
- `ci`: continuous integration for lint, build, unit/package tests, launch
11+
smoke, firmware compile, and docs validation
1112
- `docs`: continuous deployment for the MkDocs documentation site
1213

1314
At the moment, Omniseer does **not** have a release pipeline for firmware,
@@ -37,39 +38,78 @@ This means CI acts as a gate for the default branch and for incoming PRs.
3738

3839
### What it does
3940

40-
The CI job currently performs the following checks:
41-
42-
1. Installs the ROS 2 `kilted` build and test dependencies needed by the
43-
selected package set
44-
2. Runs Ruff against the Python packages in `ros_ws/src/analysis` and
45-
`ros_ws/src/bringup`
46-
3. Builds the main validated ROS package subset:
47-
- `omniseer_msgs`
48-
- `yolo_msgs`
49-
- `omniseer_description`
50-
- `analysis`
51-
- `bringup`
52-
4. Builds `omniseer_vision_bridge` only when the RKNN and RGA SDKs are
53-
available in the runner environment
54-
5. Runs the current ROS test subset:
55-
- `omniseer_description`
56-
- `analysis`
57-
- `bringup`
58-
6. Builds and runs the portable native vision tests:
59-
- `image_buffer_pool_test`
60-
- `jsonl_telemetry_test`
61-
- `rolling_telemetry_test`
41+
The workflow is split into focused jobs:
42+
43+
| Job | Purpose |
44+
| --- | --- |
45+
| `lint` | Run Ruff against the Python helper/operator packages |
46+
| `ros-core` | Install ROS workspace deps, build the validated package set, run unit/package tests, and conditionally build `omniseer_vision_bridge` when the RKNN/RGA SDKs are available |
47+
| `bringup-smoke` | Launch headless simulation and verify the core sim/hardware boundary topics and type contracts |
48+
| `vision-host` | Build and run the portable native vision tests |
49+
| `firmware-build` | Run a compile-only PlatformIO build for the Teensy firmware target |
50+
| `docs-build` | Build the MkDocs site in strict mode on every PR/push |
51+
52+
The validated ROS package set in `ros-core` now includes:
53+
54+
- `omniseer_gz_assets`
55+
- `omniseer_msgs`
56+
- `yolo_msgs`
57+
- `omniseer_description`
58+
- `analysis`
59+
- `bringup`
60+
- `robot_io_adapters`
61+
- `robot_diag_control`
62+
- `robot_diag_control_cpp`
63+
64+
The ROS test subset now includes:
65+
66+
- `omniseer_description`
67+
- `analysis`
68+
- `bringup`
69+
- `robot_io_adapters`
70+
- `robot_diag_control`
71+
- `robot_diag_control_cpp`
72+
73+
The `bringup-smoke` job intentionally checks a narrow, stable contract instead
74+
of trying to prove the full robot stack. It uses a dedicated minimal world and
75+
CI-safe geometry path so the check does not depend on optional Gazebo models or
76+
STL-heavy collision geometry. Today it verifies that headless sim bringup
77+
publishes:
78+
79+
- `/clock`
80+
- `/imu`
81+
- `/scan`
82+
- `/range`
83+
- `/mecanum_drive_controller/odometry`
84+
85+
It also checks the expected message types on that boundary and fails if the
86+
headless sim graph exits before those topics come up.
87+
88+
### Workflow hygiene
89+
90+
The CI workflow now includes a few guardrails that matter once hardware work
91+
starts:
92+
93+
- `concurrency` cancels superseded runs on the same branch or PR
94+
- each job has an explicit timeout
95+
- ROS, vision, firmware, and smoke-test logs are uploaded as artifacts
96+
- ROS dependency installation is driven from package manifests through
97+
`scripts/ci/install_ros_workspace_deps.sh`
6298

6399
### Why this helps
64100

65101
This workflow gives quick feedback when a change breaks:
66102

67103
- ROS package metadata or dependency declarations
68104
- message generation for the selected interface packages
69-
- Python linting in the helper packages
70-
- the frontier-selection and `omniseer_description` C++ tests
71-
- the package-level XML and test wiring in `analysis` and `bringup`
105+
- Python linting in the helper and operator packages
106+
- the C++ adapter and gateway test suites
107+
- the package-level XML and test wiring in `analysis`, `bringup`, and the
108+
operator tooling
109+
- the core sim/hardware boundary wiring before real hardware is in the loop
110+
- compile-time firmware regressions on the main MCU target
72111
- the portable part of the native vision runtime
112+
- docs regressions that would otherwise only show up at deploy time
73113

74114
In practice, this reduces the chance that a broken branch reaches `master`
75115
without anyone noticing.
@@ -84,7 +124,7 @@ It does **not** currently guarantee:
84124
- camera or sensor availability
85125
- RKNN/RGA-backed execution inside the default GitHub runner image
86126
- firmware flashing or micro-ROS deployment
87-
- Gazebo or robot end-to-end runtime validation
127+
- long-duration Gazebo or robot end-to-end runtime validation
88128
- release packaging or artifact publishing
89129

90130
Those would require additional jobs, richer runners, or hardware-aware test
@@ -108,7 +148,7 @@ The job:
108148

109149
1. Checks out the repository with full history
110150
2. Installs MkDocs and the Material theme
111-
3. Builds the site
151+
3. Builds the site in strict mode
112152
4. Deploys the generated documentation to the `gh-pages` branch
113153

114154
This is the current "CD" piece of the repository.
@@ -121,24 +161,56 @@ benefits:
121161
- PRs get an automatic build/test signal without requiring every reviewer to
122162
reproduce the same checks locally
123163
- dependency drift in ROS packages is more likely to fail early
124-
- lightweight regressions in Python helpers and portable vision utilities are
125-
caught before merge
164+
- lightweight regressions in Python helpers, operator tools, and portable
165+
vision utilities are caught before merge
166+
- the sim/hardware boundary gets a fast smoke signal before hardware
167+
integration starts absorbing debugging time
168+
- firmware compile breaks show up before anyone plugs in a board
126169
- docs changes can be published without a manual deployment step
127170

128171
The local equivalents of the current CI checks are:
129172

130173
```bash
131-
ruff check ros_ws/src/analysis ros_ws/src/bringup
174+
ruff check ros_ws/src/analysis ros_ws/src/bringup ros_ws/src/robot_diag_control
132175

133176
source /opt/ros/kilted/setup.bash
134177
cd ros_ws
135178
colcon build --merge-install \
136-
--packages-select omniseer_msgs yolo_msgs omniseer_description analysis bringup
179+
--packages-select \
180+
omniseer_gz_assets \
181+
omniseer_msgs \
182+
yolo_msgs \
183+
omniseer_description \
184+
analysis \
185+
bringup \
186+
robot_io_adapters \
187+
robot_diag_control \
188+
robot_diag_control_cpp
137189
colcon test --merge-install \
138-
--packages-select omniseer_description analysis bringup
190+
--packages-select \
191+
omniseer_description \
192+
analysis \
193+
bringup \
194+
robot_io_adapters \
195+
robot_diag_control \
196+
robot_diag_control_cpp
139197
colcon test-result --all --verbose
198+
```
199+
200+
For the headless bringup smoke check:
201+
202+
```bash
203+
source /opt/ros/kilted/setup.bash
204+
cd ros_ws
205+
colcon build --merge-install \
206+
--packages-select omniseer_gz_assets omniseer_msgs omniseer_description bringup robot_io_adapters
207+
source install/setup.bash
208+
OMNISEER_RUN_SIM_SMOKE=1 python3 -m pytest -vv -s src/bringup/test/test_sim_launch_smoke.py
209+
```
210+
211+
For the portable host vision tests:
140212

141-
cd /path/to/omniseer
213+
```bash
142214
cmake -S vision -B vision/build-verify -DVISION_BUILD_HARNESS=OFF
143215
cmake --build vision/build-verify \
144216
--target image_buffer_pool_test jsonl_telemetry_test rolling_telemetry_test
@@ -147,6 +219,18 @@ ctest --test-dir vision/build-verify \
147219
--output-on-failure
148220
```
149221

222+
For the compile-only firmware check:
223+
224+
```bash
225+
platformio run -d firmware -e teensy41
226+
```
227+
228+
For docs validation:
229+
230+
```bash
231+
mkdocs build --strict
232+
```
233+
150234
If the RKNN and RGA SDKs are installed locally, you can also build:
151235

152236
```bash
@@ -164,7 +248,7 @@ Likely future additions:
164248

165249
- a release workflow for tagged versions
166250
- hardware-in-the-loop jobs on a self-hosted runner
167-
- integration tests for launch flows and ROS graphs
251+
- longer-running integration tests for launch flows and ROS graphs
168252
- container image builds
169-
- firmware build and test automation
253+
- firmware flash/test automation
170254
- artifact retention for logs, test reports, and generated packages

0 commit comments

Comments
 (0)