Development environment

We set up a Nix development shell with all the tools needed for the project. We recommend using it because it ensures a consistent environment across all developers and our CI pipeline.

Setup

Note

If you already have Nix installed you can skip this section.

If you’re on Linux or macOS you can install the Nix package manager either via the Determinate Systems installer (recommended) or the official nixos.org installer with experimental-features = nix-command flakes in nix.conf. Optionally you can install direnv so the shell is entered automatically every time you enter the project directory which is quite convenient.

Tip

If you’re on Windows we are currently setting up a devcontainer. We are currently working on it because usb pass-through is not straightforward. For now you could use WSL plus usbipd-win for USB pass-through or have a look at the devcontainer branch.

Common tasks

We use invoke to run common tasks. Run inv --list for the full set (or read their definition in tasks.py). Here are some of the most common ones:

Command	What
inv build	Debug build (bundles the web UI first)
inv flash	Build → merged image → flash via esptool
inv monitor	Open the serial monitor for logs over USB
inv check	Run clippy to check Rust code
inv format	Run all pre-commit hooks on all files
inv docs	Build the documentation (pass -o to open it)
inv docs:dev	Start a local docs server with hot reload
inv web:build	UI production build
inv web:dev	UI dev server with mock API

The API reference is generated by rustdoc and ships with the built site at /api/. inv docs:rustdoc regenerates it on its own.

Pre-commit hooks

We use automated hooks that run before every commit to ensure we catch mistakes early. The hooks are configured in flake.nix via git-hooks.nix (do not edit .pre-commit-config.yaml). They run tasks like rustfmt, taplo, oxlint/oxfmt, alejandra/statix/deadnix, markdownlint + mdformat + cspell, shellcheck/shfmt, ripsecrets, actionlint and convco.

Convco parses your commit message and blocks it if it does not follow the conventional commit specification.

Contributing

We are happy to accept contributions! Feel free to open issues or pull requests. Please make sure your code passes the pre-commit hooks. Fully vibe coded or untested code does not help! You can use AI, but please make sure you fully comprehend the code. Thanks to all the contributors on this project even if they just did little things like fixing typos or improving the documentation. Every contribution is appreciated.