Quick start

Start with a firmware image that is ready to flash.

1. Install the CLI

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/onmcu/onmcu-rs/releases/latest/download/onmcu-installer.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://github.com/onmcu/onmcu-rs/releases/latest/download/onmcu-installer.ps1 | iex"

cargo install onmcu --locked

cargo binstall onmcu

Verify the executable is in the path:

onmcu --version

See Installation for pre-built archives and platform details.

2. Create and store an API key

Open app.onmcu.com/settings, create an API key, and then run:

onmcu login

Paste the key at the prompt. The CLI saves it in the OS keyring.

3. Find a board

onmcu list-boards

Choose a value from the Board MPN column. The board part number must match the firmware target.

4. Build firmware

OnMCU receives a firmware file; it does not run your compiler. Build locally with the target, chip features, linker script, and memory layout for the selected MCU.

For Rust, the linked ELF usually appears below the target triple:

cargo build --release --target thumbv7em-none-eabihf

For C, build with the appropriate Arm toolchain and linker script:

make

Board and firmware must match

A binary linked for one MCU or memory map is not portable to a different board. Select the OnMCU board for which the firmware was built.

5. Run it

onmcu run \
  --board NUCLEO-H743ZI \
  --file target/thumbv7em-none-eabihf/release/my-firmware

The CLI uploads the file, waits for a device, and streams RTT logs by default. To capture a UART instead:

onmcu run \
  --board NUCLEO-F401RE \
  --logging serial \
  --baud 115200 \
  --file build/serial-firmware.elf

6. End the run cleanly

When the firmware passes or fails, report the result with a semihosting exit. OnMCU will stop the run instead of holding the board until --timeout.

For a working project with logging and a clean exit, clone an example:

git clone https://github.com/onmcu/rust-examples.git
cd rust-examples/nucleo-h743zi
cargo run

git clone https://github.com/onmcu/c-examples.git
cd c-examples/nucleo-h743zi
make run

Both examples use OnMCU as the project runner, log a short counter, and exit with success from the device.