Contribute
Set up a development environment, run the tests, try changes on a device, and send them upstream.
This page explains how to work on Pinna: how to set up the tools, which tests
exist and what each one needs, and how to log in to a device and try a change on
it. Owners set up and use a satellite on its dashboard;
the developer pages cover the rest: this page, Build Pinna,
the developer settings in pinnad.toml,
pinnactl and the control API, and
Releases and updates.
Pinna is a small project in early development. Before you start on something larger than a fix, open an issue so that the work isn’t duplicated.
Set up the tools
Pinna builds on an x86_64 Linux computer. Nix
with flakes enabled is the easiest way to get the tools, but Nix is not
required: without it, install the same tools yourself (flake.nix is the
list). The repository’s development shell provides the Rust toolchain, the
ARM cross compilers, mkosi, QEMU, fastboot,
uv for the Python-based tests, and Node for the
dashboard (just web, just image and just web-check).
-
Clone the repository:
git clone https://github.com/elsbrock/pinna.git cd pinna -
Start the development shell, or skip this step and use the tools you installed yourself:
nix develop -
List the available tasks:
just
Building images also needs a signing key and the files described in Build Pinna. The tests in this section don’t, unless the table says so.
Run the checks
Run the host checks on every change. They format-check the code, run Clippy with warnings as errors, and run the unit tests of every crate:
just check
To run everything, including the virtual machine tests, run:
just test
just test takes a while, and some of its parts need files that you build
first. The repository has no CI that runs these tests, so run them yourself
before you send a change that affects the image or the device.
Tests and what they need
| Task | What it checks | What it needs |
|---|---|---|
just check |
Formatting, Clippy and the unit tests of every crate | Nothing else |
just esphome-conformance |
Home Assistant’s own client library (aioesphomeapi 46.2.0) talks to Pinna’s ESPHome API server: the entity set, encryption, key rotation and error cases |
Network access the first time, to download the Python packages |
just sendspin-conformance |
Music Assistant’s own Sendspin server library (aiosendspin 10.2.0 and 10.3.0, as Music Assistant 2.10.7 and 2.11.0b9 pin it) plays to a pinnad on your computer: the handshake, PCM and FLAC at 48 and 44.1 kHz played on the server’s timeline, a new track and a format change mid-stream, volume and mute both ways, track details, pause, play and stop through the group, leaving the group, reconnecting, a second server, a new name and switching off |
uv, and network access the first time, to download the Python packages. It builds pinnad and gives it free ports, so a development pinnad can keep running |
just wakeword-parity |
Pinna’s wake word scores match the reference implementation (onnxruntime) on test recordings | The wake word models (just models); skips without them |
just e2e |
A complete voice request: pinnad with the real wake word and a recording, with a simulated Home Assistant |
The wake word models (just models); skips without them |
just web-check |
The dashboard: design tokens, generated API code, unit tests and svelte-check. just test runs it |
Network access the first time, to download the npm packages |
just kernel-config |
The kernel configurations contain every option Pinna needs: the MT8163 device, the MT8516 Echos (planned), and QEMU on ARM, arm64 and x86_64 | Network access the first time, to download the kernel source |
just bootimg-roundtrip |
The boot image unpacks and repacks byte for byte | build/pinna-boot.img from just bootimg |
just vm-test |
The real ARM root image boots in QEMU, and SSH and the Home Assistant API come up | just kernel-qemu image first. Takes a few minutes, because QEMU emulates the CPU |
just vm-test-arm64 |
The same ARM root image boots on the arm64 kernel, as 32-bit programs: the way the MT8516 Echos will run it (planned) | just kernel-qemu-arm64 image first. Slower than just vm-test, because QEMU emulates a 64-bit CPU. just test doesn’t run it |
just vm-test-x86 |
The same checks with the x86_64 image, and the virtual Echo Dot: its buttons, microphone button, speaker, and the wake word through its microphone | just kernel-x86 image-x86 first. Faster with KVM. The wake word check needs the models (just models); skips without them |
just vm-hotspot-test |
The setup hotspot, with four simulated Wi-Fi radios in the x86_64 virtual machine: a phone in a network namespace joins it, is sent to the dashboard and scans there; a wrong password tried from the phone stops the hotspot, brings it back and shows why; a simulated home network kept from its new address keeps it off; forgetting it brings the hotspot back | SSH_KEY=~/.ssh/key just vm-hotspot-test, after just kernel-x86 image-x86 with that key’s public half in secrets/authorized_keys. just test doesn’t run it |
just vm-rescue-test |
The initramfs stays in rescue mode, without restarting, on a disk without a root filesystem image and on one without slot partitions | just kernel-qemu first. just vm-rescue-test-x86 runs the same on x86_64 and needs just kernel-x86. just test doesn’t run either |
just vm-update-test |
An update installs into the other slot, the trial boot succeeds, and a broken update rolls back | just kernel-qemu image and the signing key. Builds two more images, so it takes longer |
just updates-test |
The release service (services/updates/): its channels, file downloads, cache and withdrawn releases, against recorded GitHub answers |
Node 24 or later; no Cloudflare or GitHub account |
just test-device |
Speaker, microphones, LED ring and the Home Assistant API on a real device | A running device reachable over SSH |
just wakeword-parity and just e2e pass without running anything if the
wake word models are missing. Run just models before you rely on their
result.
Log in to a device
Owners never need to log in: the dashboard has every setting. To debug or develop, log in on your computer in one of these ways:
-
Over SSH, with the key from
secrets/authorized_keysthat the image was built with. Pinna accepts only keys, no passwords. A release image has no key: add yours over the serial console first. Over the USB cable the device is at10.42.0.1, and your computer gets an address between10.42.0.10and10.42.0.29:ssh [email protected]Over Wi-Fi, use the device’s IP address or its
.localname, such aspinna-2a914e.local. -
Over the USB serial console, which needs no key. It also has a root shell in rescue mode, where SSH doesn’t run:
picocom -b 115200 /dev/ttyACM0
After a reinstall the device has a new SSH host key, and ssh refuses to
connect. Remove the old key, on your computer:
ssh-keygen -R 10.42.0.1
ssh-keygen -R pinna-2a914e.local # your device's name
These commands, on the satellite, show what the dashboard shows and more:
pinnactl status # the state, as in pinnactl and the control API
systemctl --failed # services that failed
journalctl -b -u pinnad # the log of pinnad since this start
pinna-bootctl slot-status # the slots, their versions and states
Include their output when you report a problem.
When pinnad doesn’t start
pinnad refuses to start if pinnad.toml contains a setting it doesn’t know,
a value of the wrong type, or an invalid encryption key file. Then the health
check fails, and the device restarts into fastboot (see
The fastboot guard). To find the cause:
-
Start Pinna again, on your computer:
fastboot reboot -
Log in over the USB serial console right away: the health check restarts the device about 40 seconds after Pinna’s services start. The serial console doesn’t need an SSH key.
-
Read the log of the previous start, and fix the cause:
journalctl -b -1 -u pinnad
If you can’t fix it in time, install the root filesystem again from fastboot, as described in Recover a device. This erases the settings, which also removes a broken configuration.
Try a change on a device
To test new versions of Pinna’s programs on a running device without
reinstalling it, use just push:
just push
just push cross-compiles pinnad, pinnactl, pinna-bootctl and
pinna-bootstages, copies them to the device over SSH as a system extension
in /var/lib/extensions/pinna-dev, and restarts pinnad. The root filesystem
stays read-only and unchanged.
By default it connects to [email protected], over USB. To use another address, set
PINNA_HOST:
PINNA_HOST=[email protected] just push
To remove the extension and go back to the installed programs, run:
scripts/push-dev.sh --remove
While the extension is there, the satellite doesn’t install updates: after the restart, the extension’s programs would hide the new release’s. Remove it first.
Try a change without a device
just dev-vm runs the x86_64 image in a virtual machine as a virtual Echo
Dot. Your browser stands in for its hardware: its microphone, its speaker
and its four buttons. The image, pinnad, the wake word and Home Assistant’s
voice pipeline are the same as on a Dot. The beamformer and the Dot’s echo
canceller are not part of it.
You need:
- KVM: write access to
/dev/kvm, usually by being in thekvmgroup. Without it the CPU is emulated, and the satellite takes many minutes to start. - Podman or Docker, installed on your computer. The development shell doesn’t include them.
- The signing key and
secrets/authorized_keys, as for any image (see Build Pinna). Withoutauthorized_keys, SSH andjust push-vmcan’t log in.
just models # once: the wake word models
just kernel-x86 image-x86 # once, and again after changes to the image
just dev-vm # keeps running; stop it with Ctrl-C
just dev-ha # in a second terminal
Without just models the image has no wake word, and saying it does
nothing.
just dev-ha runs a Home Assistant for the satellite on your computer, in
containers: Home Assistant, Whisper for speech to text and
Piper for text to speech. It sets them up once, with an Assist pipeline and
the virtual Echo Dot added. The first start downloads the images and the
speech models, a few gigabytes. Open it at http://localhost:8123; from this
computer it needs no login. just dev-ha stop removes the containers, and
build/dev-ha/ keeps their state.
Then:
- Open the dashboard at
http://127.0.0.1:18090, on the same computer. Browsers share the microphone only withlocalhostor127.0.0.1. From another computer, forward the port withssh -L 18090:127.0.0.1:18090 <this computer>and open the same address there. - On the Overview, under Virtual Echo Dot, select Connect and allow the browser to use the microphone.
- Say “Alexa, what time is it?” The ring on the Overview is the satellite’s
own: it shows what
pinnadlights.
Hold the round buttons the way you would on the Dot: a short press, a long press, or + held down to repeat. The microphone button turns the microphones off and on, like the Dot’s.
Audio file as the microphone (Choose…, once connected) plays a
recording into the satellite instead of your voice. That gives the same input every time, for example
crates/pinna-wakeword/tests/fixtures/alexa-twice.wav.
The virtual machine keeps its disk in build/dev-vm/, so Home Assistant
keeps knowing it after a restart. Each start installs the newest
build/pinna-x86.root.img. FRESH=1 just dev-vm starts with an empty
/var. The virtual satellite has its own identity. It never joins Home
Assistant as your Echo Dot.
To try a new pinnad without building the image again, run just push-vm
while the virtual machine is running. It works like just push, but the
programs it puts on the satellite last only until the virtual machine
restarts. Then the image’s own are back.
To work on the dashboard with live reloading, point Vite at the virtual machine:
cd dashboard && PINNA_URL=http://127.0.0.1:18090 npm run dev
Open the localhost address Vite prints. The virtual Echo Dot works there too.
To use your own Home Assistant instead of just dev-ha, start the virtual
machine with ESPHOME_BIND=0.0.0.0 just dev-vm. Then add the satellite under
Settings › Devices & services › Add integration › ESPHome, with this
computer’s address and port 6053. Your computer’s firewall and your network
must let Home Assistant reach that port. Discovery doesn’t work from inside
the virtual machine.
To run a second virtual machine, for example from another worktree, give it
other ports: WEB_PORT=18190 SSH_PORT=2323 ESPHOME_PORT=6153 just dev-vm, and
SSH_PORT=2323 just push-vm to update it. There is one just dev-ha per
computer: running it from another worktree replaces the containers. Images
built from the same checkout are the same device to Home Assistant, so
connect only one of them to it at a time.
Work on one part
Most work happens in one crate. Some useful commands:
cargo test -p pinna-wakeword # tests of one crate
cargo run -p pinna-bootimg -- info build/pinna-boot.img
To find your way around the code, see Repository layout.
Send a change
- Open an issue that describes the problem or the feature.
- Make the change on a branch. Write commit messages in the
Conventional Commits style that the
history uses, for example
fix(pinnad): …orfeat(image): …. - Run
just check, and the tests from the table that cover what you changed. - Open a pull request on GitHub and say which tests you ran.
Licences
Pinna’s own code is under the MIT licence. The Linux kernel is under the GNU
GPL version 2. The wake word models that just models downloads are under
CC BY-NC-SA 4.0, which doesn’t allow commercial use. They are never committed
to the repository. If you build an image with them, the image contains them,
so keep that licence in mind before you share it.
What’s next
- Build Pinna to get images you can install.
- Offer your own builds as updates, or publish a release: Releases and updates.
- Read about the architecture.