Contributing#
Thanks for helping. This page covers how to build, test and send a change.
Build and test#
You need ESP-IDF v6.1 for the firmware and Python 3.12 for the tools.
make -C tests/host # fault engine, custom PIDs, pattern layer, adapter names, input checks
python3 -m unittest discover -s tests -v # report tool
python3 tools/check_docs.py # Markdown links and images
idf.py set-target esp32s3 && idf.py build # firmware
cargo test --manifest-path desktop/app/src-tauri/Cargo.toml # desktop app, needs Rust
The documentation site needs Python 3.13:
pip install --require-hashes -r docs-src/requirements.txt
sphinx-build -W --keep-going -b html docs-src docs-src/_build/html # the site, warnings are errors
python3 docs-src/check_prose.py --all # house style on the hand-written pages
The manuals, the changelog and most of the concept pages come from the Markdown in this repository (docs/manual/*.md, CHANGELOG.md, README.md), so edit those and the site follows. docs-src/README.md explains how.
If you change a file in ml/onboard/, regenerate main/ml_params.h with python3 tools/gen_ml_params.py ml/onboard main/ml_params.h. For ml/onboard/rev/, run python3 tools/gen_ml_params.py ml/onboard/rev main/ml_params_rev.h MLR. CI fails if a header and its files disagree.
Sending a change#
Open an issue first for anything bigger than a fix, so we can agree on the approach.
Keep a pull request to one change. Update the docs in the same pull request.
Wait for CI. It builds the firmware with Wi-Fi clock sync on and off, runs the host tests and the Python tests, and checks the docs. The
desktopworkflow builds the app and runs its tests on Windows, macOS and Linux whendesktop/changes.Say what you tested on a real board, if anything. “Compiles” and “ran on a car” are different claims, and the README keeps them apart.
Style#
Firmware is C11 and C++17 in the existing style: short functions, comments only where the reason is not obvious. Python follows what is in tools/: standard library first, small functions, no comment that repeats the code. Prose in the docs is plain: short sentences, a number or a name instead of an adjective, no hype.
Reporting a security problem#
Use the private route in SECURITY.md, not a public issue.
Repository layout#
Path |
What it holds |
|---|---|
|
firmware source |
|
the shipped models (CarMind E.V, and CarMind R.E.V in |
|
two replay sessions from a public dataset, in the board’s file format |
|
JSON schema of the session files |
|
unit tests that run on a computer, including R.E.V’s learners |
|
|
|
the desktop app (Rust and Tauri) |
|
Docker Compose file and Dashy configuration |
|
configuration, model notes, field checks, screen designs and figures |
|
the user manuals in Markdown, the source of their pages on the documentation site |
|
the documentation site (Sphinx, MyST and pydata-sphinx-theme), built from the Markdown in this repository |