Build Pinna
Build the boot image and the signed root filesystem image that you install on your device.
This page shows how to build the two files you install on an Echo (2nd gen) or an Echo Dot (2nd gen): the boot image and the root filesystem image. Releases carry prebuilt ones; build your own to develop Pinna or to sign with a key of your own.
Before you begin
- Use an x86_64 Linux computer. Nix with
flakes enabled is the easiest way to get the tools; without it, install the
tools that
flake.nixlists yourself. The build needs network access to download the toolchain, the Debian packages and the kernel source.
Get the source and the tools
-
Clone the repository:
git clone https://github.com/elsbrock/pinna.git cd pinna -
Start the development shell. It provides the Rust toolchain, the ARM cross compilers, mkosi, QEMU and fastboot:
nix developThe first time, it downloads the tools and takes a few minutes. Without Nix, skip this step and install the tools that
flake.nixlists from your distribution.
Run all of the following commands with the development shell’s tools, or your own equivalents.
Create a signing key
Pinna installs and boots only root filesystem images that are signed with the
release key. Releases are signed with the project key in keys/release.pub.
To sign your own images with your own key, run once:
just keygen
The command writes two files:
secrets/release.key: the private key. Git ignores it. Keep it safe and make a backup: you need the same key to build updates for devices that run your images.secrets/release.pub: the public key. The build compiles it in instead of the project keykeys/release.pubwhen it exists, so a device accepts only images signed with your private key. Such a build starts with Updates off, because the project’s releases don’t install on it. See Offer your own builds as updates.
If secrets/release.key already exists, just keygen keeps it and only
writes the public key again.
Installing your own build on a device that runs a release is a key change:
flash the root filesystem and the boot image together. pinnactl update
cannot cross a key change.
If you lose the private key, devices that run your images can’t accept updates any more. To recover, build with a new key and install both the boot image and the root filesystem again from fastboot.
Add your own files
-
Put your own files into
secrets/. Git ignores the folder, so they never end up in the repository.File What it’s for How to create it secrets/release.keySigns your own root filesystem images. Only to sign your own builds just keygen(writessecrets/release.pubtoo; the build compiles it in)secrets/machine-idNot needed: each device derives its machine id from its serial number — secrets/authorized_keysYour SSH public key. Without it, you can’t log in over SSH Copy your public key, for example ~/.ssh/id_ed25519.pubsecrets/wifi/wpa_supplicant-wlan0.confYour Wi-Fi network, so the device connects on first boot. Optional: you can also set it up on the dashboard over USB See Connect to Wi-Fi secrets/device/pinnad.tomlDeveloper settings for this device. Optional: owners set the device up on the dashboard See Developer settings secrets/device/esphome-keyA fixed encryption key for the Home Assistant connection. Optional: Home Assistant sets a key itself See Developer settings -
Download the wake word models:
just modelsThis puts the openWakeWord models into
blobs/models/.
The build stops if the signing key is missing. For the other files, it
prints a warning and continues. Read the warnings: without authorized_keys
you can’t log in over SSH.
Wake word models
Pinna ships the openWakeWord models for Alexa, Hey Jarvis, Hey
Mycroft and Hey Rhasspy (v0.5.1), and Okay Nabu from
rhasspy/pyopen-wakeword, pinned
to a commit. just models downloads them during the build; they aren’t part of
the repository. Release images include them with a NOTICE next to them that
names their sources and licenses. The openWakeWord models are licensed under
CC BY-NC-SA 4.0, which doesn’t allow commercial use. Okay Nabu comes from a
repository under Apache-2.0; the model itself carries no licence of its own.
Amazon’s firmware
The device needs Amazon’s Wi-Fi and Bluetooth firmware and the bitstream for
its microphone FPGA. They aren’t part of the repository. just kernel and
just image run just firmware, which downloads them into blobs/firmware/
and checks their sha256. Pinna doesn’t modify them, and its license doesn’t cover them.
It also downloads the Wi-Fi firmware of the Echo Dot (3rd gen), and
linux-firmware’s patch for its Wi-Fi and Bluetooth chip, and the image
installs both, for the Dot’s planned port.
Build the images
To build everything that you need to install Pinna, run:
just all
just all builds the kernel, the root filesystem and the boot image, and then
lists the two files:
| File | Contents |
|---|---|
build/pinna-boot.img |
The kernel, the device tree, and a small initramfs that checks and mounts the root filesystem |
build/pinna.root.img |
The root filesystem: Debian with Pinna, read-only and signed, so that the device can detect any change to it |
The first build takes longest, because it downloads and compiles the kernel.
Rebuild one part
You don’t need to rebuild everything after each change:
| Command | Builds | Output |
|---|---|---|
just kernel |
The kernel, as a Debian package | build/debs/linux-image-*.deb |
just image |
The root filesystem, with Pinna’s programs | build/pinna.root.img |
just bootimg |
The boot image | build/pinna-boot.img |
just bootimg uses the kernel from the last just kernel. After you change
the kernel, run just kernel before just bootimg.
Check the build (optional)
To check that the image boots before you install it, boot it in a virtual machine. This needs a kernel built for QEMU:
just kernel-qemu
just vm-test
The test boots the root image you built, then checks that the system services, SSH and the Home Assistant API come up. It takes a few minutes. For the other tests, see Contribute.
What’s next
Install Pinna. Later, to build an update for a device that already runs Pinna, see Update Pinna.