Build And Tool Commands¶

Run commands from the repository root unless a section says otherwise.

cd /path/to/Veloxity

Prerequisites¶

Rust¶

Install Rust with rustup, then add the embedded targets used by the board crates:

rustup target add thumbv8m.main-none-eabihf
rustup target add thumbv7em-none-eabihf

Without the correct targets installed, you will not be able to run cargo xtasks associated with the associated board.

probe-rs¶

Install probe-rs for hardware flashing and debug-probe access:

cargo install probe-rs-tools

ROSflight Simulation¶

For the ROSflight simulator path, source ROS 2 and the ROSflight workspace before running Veloxity "shim" commands.

Example:

source /opt/ros/jazzy/setup.zsh
source /path/to/rosflight/workspace/install/setup.zsh

The tested Veloxity integration does not require edits to rosflight_io or generated ROSflight install files.

xtask¶

xtask is the repository command wrapper. It keeps common commands discoverable and avoids long target/package invocations.

cargo xtask <command>

Supported board names:

pico2w
nucleo
pixracerpro

Host Checks¶

cargo xtask check-host
cargo xtask test-host

Host checks build or test code (unit tests) for the computer running Cargo, rather than for an embedded flight-controller target. Run these commands from the repository root:

check-host runs cargo check for the workspace's default members:

comms/veloxity_mavlink crates/veloxity_core sim/firmware xtask

check-host does not produce firmware binaries or check the embedded board targets. test-host runs unit tests for veloxity-core and sim

Direct equivalents:

cargo check
cargo test -p veloxity_core
cargo test -p sim --lib

for building the ROS2 shim, testing physical hardware, or checking embedded board crates read on.

Board Checks¶

Board checks verify that the embedded veloxity firmware compiles for each flight-controller architecture. Run them from the repository root. Each command runs cargo check for the board's veloxity firmware binary using the appropriate embedded target.

cargo xtask check-board pico2w
cargo xtask check-board nucleo
cargo xtask check-board pixracerpro

Direct equivalents:

cargo check -p pico2w --target thumbv8m.main-none-eabihf --bin veloxity
cargo check -p nucleo --target thumbv7em-none-eabihf --bin veloxity
cargo check -p pixracerpro --target thumbv7em-none-eabihf --bin veloxity

These board checks certify that the rust code and dependencies compile for the selected microcontroller architecture. They do not produce flashable release builds.

Board Builds And Flashing¶

Run these commands from the repository root. These commands will produce a firmware file under target/. build-board uses Cargo's development profile and does not connect to or modify physical board memory.

Build:

cargo xtask build-board pico2w
cargo xtask build-board nucleo
cargo xtask build-board pixracerpro

Flashing builds the firmware and uploads it through the connected debug probe (assumed to already be installed per previous installation instruction)

After confirming the intended board is attached, the boards with verified runner configurations can be flashed through Cargo:

cargo xtask flash-board pico2w
cargo xtask flash-board pixracerpro

Pixracer Pro flashing always uses --release --no-default-features. The command above therefore uses the companion-computer UART transport and excludes diagnostic features. Select USB VCP or diagnostic instrumentation explicitly when needed:

cargo xtask flash-board pixracerpro --vcp
cargo xtask flash-board pixracerpro --scope-timing-pins
cargo xtask flash-board pixracerpro --sensor-poll-diagnostics

The opt-in flags may be combined.

STM32 Targets¶

Nucleo-H753ZI firmware is maintained and compiles, but has not been tested on physical hardware recently.

Pixracer Pro is the active STM32 validation target. The current high-rate timing build is (explicitly):

cargo build -p pixracerpro --target thumbv7em-none-eabihf --bin veloxity --release \
  --features 'scope-timing-pins'

By default, the xtask associated with the pixeracer is set for release mode as explained previously.

The current Pixracer Pro hardware baseline is a fixed 400 Hz control loop with board-specific continuous service polling. A 10-second UART MAVLink acceptance run at 921600 baud passed with zero CRC errors, zero MAVLink sequence gaps, and 399.5 Hz host / 399.4 Hz board-timestamp IMU telemetry while injected heartbeat, TIMESYNC, version, and parameter request traffic was present. Scope captures showed clean 400 Hz BMI08x production and foreground IMU consumption with producer-to-consumer latency below 100 us. Follow STM32 boards for further information.

ROS 2 Shim Build¶

The ROS2 shim must be built before Veloxity can be used with the ROSflight simulator. This build combines * sim/firmware * The C++ ROS2 node from sim/ros2/veloxity_sil_board_shim

Assuming the ROS2 installation and ROSflight workspace have already been sourced, run the build/source helper:

source scripts/build_and_source_ros2_shim.zsh

This helper compiles the sim package as a static library that the C++ ROS2 node links into it's executable. The helper below builds only the veloxity shim package with colcon. It uses the repository's workspace/ directory for the ROS2 build rather than placing generated files beside the source package.

It runs:

cargo xtask build-sim-lib
colcon build --base-paths sim/ros2/veloxity_sil_board_shim ...
source workspace/install/setup.zsh

All the above commands also add the newly built veloxity_sil_board_shim package, executable, config files, and launch files to the current ROS2 environment.

Generated outputs:

target/debug/libsim.a
workspace/build/
workspace/install/
workspace/log/

After the build finishes, verify that the ROS2 package has been identified by ROS2:

ros2 pkg prefix veloxity_sil_board_shim

Run the full tested simulator workflow from:

Veloxity ROScopter sim end-to-end

Generated Cleanup¶

Remove local generated artifacts:

cargo xtask clean-generated

This removes:

target/
workspace/
rosflight_memory/
tools/__pycache__/
tools/espnow_uart_bridge/build*/
tools/espnow_uart_bridge/sdkconfig
tools/espnow_uart_bridge/dependencies.lock

After cleanup, rebuild the ROS 2 shim with:

source scripts/build_and_source_ros2_shim.zsh