Documentation: https://docs.lhre.org
Longhorn Racing Electric's monorepo: firmware for every ECU on the car, the hardware abstraction layer it's built on, and the tooling to build, test, and flash it all with Bazel.
-
:material-swap-horizontal:{ .lg .middle } CAN Matrix & Signals
Full CAN ID allocation, message timings, signal bit layouts, and telemetry bindings generated from spec.
:octicons-arrow-right-24: Open CAN Matrix{ .md-button .md-button--primary }
-
:material-chip:{ .lg .middle } Boards & Firmware
Per-ECU firmware layout, the VCU reference board, pinouts, and the new-board scaffolder.
:octicons-arrow-right-24: Explore Boards{ .md-button }
-
:material-layers-outline:{ .lg .middle } LHAL & Drivers
Platform-independent hardware abstraction layer enabling 100% host-testable embedded code.
:octicons-arrow-right-24: Read LHAL Guide{ .md-button }
-
:material-bug-outline:{ .lg .middle } Hardware Debugging
Zero-setup VS Code debugging with ST-Link, hermetic gdb, OpenOCD, and SVD peripheral viewer.
:octicons-arrow-right-24: Debugging Guide{ .md-button }
| Directory | What lives there |
|---|---|
drivers/ |
Hardware. LHAL (our platform-independent HAL) and vendor HAL packages. |
lib/ |
Platform-agnostic C++ that builds on host and target (ring buffers, CRC, CAN pack/unpack, …), with colocated tests. |
apps/ |
Host-side software: telemetry, dashboards, gateways. |
boards/ |
Per-ECU firmware projects (boards/VCU is the reference layout). |
tools/ |
Build and dev tooling: firmware_project, flashing, VS Code debugging, formatting. |
autonomy/ |
The driverless stack: ROS 2 Jazzy + Gazebo, built with colcon rather than Bazel (ADR-009). |
simulation/ |
Vehicle dynamics studies on BobSim, run with Make and Docker rather than Bazel (ADR-012). |
vehicle/ |
The current car's parameters (vehicle.yml, tire models). One source for simulation and any Bazel target. |
There are no per-year directories: main is always the current car, and past
seasons live in tags and maintenance branches (see
CONTRIBUTING.md).
The decisions that shape the repo — monorepo, Bazel, LHAL, docs conventions — are recorded as ADRs in docs/architecture. The build system gets its own long-form record — why Bazel, and the whys behind its forks, pins, and patches — in docs/build-system.md.
- Bazelisk (installs the pinned
Bazel from
.bazelversionautomatically) - Git
That's it — compilers (ARM GCC for firmware, LLVM for host code) are hermetic and downloaded by Bazel. No Xcode, MSVC, or system GCC needed for C++, and no MSYS2 or Git Bash on Windows: builds there are shell-free (ADR-018). STM32CubeMX is only needed when changing a board's peripheral configuration.
On Windows, builds run locally instead of on remote executors; for full remote
execution use WSL2 (see the comments in .bazelrc).
Windows also needs the startup --output_user_root=C:/_bzl line uncommented
in .bazelrc.user (copied from
.bazelrc.user.example) —
without it, Python codegen tools blow Windows' 260-char path limit and die
with an ImportError in the protobuf runtime.
Everything goes through Bazel, and the surface is small enough to memorize.
Shown for the VCU; swap VCU/vcu for any board — the targets are uniform
because firmware_project generates them.
| To… | Run |
|---|---|
| Build one board's firmware | bazel build //boards/VCU:vcu |
| Build + test everything | bazel test //... |
| Test host C++ under UBSan | bazel test --config=ubsan //boards/... //drivers/... (more) |
| Run a board's simulator | bazel run --config=local //boards/VCU:vcu_sim |
| Flash over ST-Link | bazel run //boards/VCU:openocd |
| Flash over USB (DFU) | bazel run //boards/VCU:dfu |
| Format all C/C++ | bazel run //tools/format |
| Fix IDE red squiggles | bazel run //:refresh_ide |
bazel test //... runs on the BuildBuddy Linux executors by default (see
below); add --config=local to any command to stay entirely on your
machine. Green bazel test //... on a fresh clone means you're set up —
there is nothing else to install.
When the convention doesn't cover you — a file the build won't pick up, a new dependency, vendoring a library, a test target that isn't found — see the cookbook.
Debug on hardware: open the repo in VS Code, install the recommended Cortex-Debug extension, plug in the ST-Link, and hit F5 — breakpoints, FreeRTOS thread views, and peripheral registers, with nothing else to install on any OS (see CONTRIBUTING.md).
Builds stream to and cache on lhre.buildbuddy.io.
To authenticate, copy .bazelrc.user.example to
.bazelrc.user (gitignored) and paste your API key from BuildBuddy →
Settings → API keys — ask a software lead for an invite to the org.
No key, or no internet? --config=local builds entirely on your machine.
MIT, see LICENSE.