Pi Hero makes your Raspberry Pi discoverable, reachable, and pleasant to use.
Every feature is a Debian package from a signed apt repository. One cloud-init file on the boot partition describes a device: flash a card, boot, and the Pi installs its packages and shows up in your network. No control machine, no playbook.
| Package | What it does |
|---|---|
pihero |
The MOTD lists installed features, failed units, pending reboots, and the USB address; bootconfig edits the boot files safely |
pihero-avahi |
The Pi appears in Finder's network browser with an icon and its device information, announced as an SMB server because that is what Finder lists; SSH is advertised too |
pihero-usb-gadget |
Ethernet over USB on top of Raspberry Pi's rpi-usb-gadget: a Mac on the cable gets an address from the Pi and lists the interface under the board's name |
pihero-kiosk |
One web page full screen on the display: cog (WPE WebKit) straight on the DRM device, no X server and no compositor; the page is URL in /etc/pihero/kiosk.conf |
cog |
Debian's cog 0.18.4 rebuilt with the fix for software-rendered frames, arm64 only; the kiosk's browser from this repository until Debian carries the fix |
kaomoji |
The Pi Hero cast: kaomoji hero, wizard, and visitor print one animated kaomoji each on the terminal, from one static binary that a curl line runs anywhere; pihero depends on it and shows the hero in its MOTD |
 Pis in the network browser |
 device information |
 device information with a custom model |
|---|
Planned: Bluetooth PAN as pihero-bt-pan. Pi Hero 1, the Ansible playbook, is frozen at tag
pihero-ansible; docs/pihero-1.md says what
became of each of its features.
You need a Mac with Homebrew, a Raspberry Pi (Zero W and up), and an SD card.
- Describe the device. Copy the sample and edit it: hostname, your SSH public key, the pretty name, the Finder icon, the
USB gadget's name, and your Wi-Fi in
network-config; a Zero W or another ARMv6 board takes# image: raspios_lite_armhfin the header. The sample installspihero,pihero-avahi, andpihero-usb-gadget; device directories other thansample/are gitignored.mkdir devices/mypi && cp devices/sample/user-data devices/sample/network-config devices/mypi/ - Flash. Find the card with
diskutil list external, then:Two minutes: the image is written, verified, and completed with your files. Raspberry Pi Imager works as well.brew bundle make flash DEVICE=mypi DISK=disk9
- Boot. Six minutes and two reboots later
ssh pi@mypi.localgreets you with the MOTD, the Pi is in Finder, and a Mac on the USB cable gets an address from the gadgetpihero-usb-gadgetbrought up, listed under the name you gave it.
MODEL in the device file picks the Finder icon; AirPort4 is the default. Some popular choices:
| Model identifier | AirPort4 |
AirPort7,120 |
MacPro7,1@ECOLOR=226,226,224 |
|---|---|---|---|
| Type identifier | com.apple.airport-express |
com.apple.airport-extreme-tower |
com.apple.macpro-2019-rackmount |
| Kind | Mac | AirPort Extreme | Mac |
| Icon |  |
 |
 |
| Sidebar icon |  |
 |
 |
All eleven choices are pictured in devices/README.md, along with every key of the device
file and what to do if the Pi does not show up. Updating a device is sudo apt upgrade on the Pi; changing it is a reflash.
Releases are published to bkahlert.github.io/pihero, a flat repository signed with the
key in docs/pihero-apt.asc (fingerprint DE60 9D7F F5BE 430D AC8C C807 081F 70E6 A077 DF7A). The
device file embeds that key, so a device trusts nothing else.
Everything runs on the Mac; a Raspberry Pi is optional.
brew bundle # qemu, podman, uv
podman machine init && podman machine start
make doctor # lists what is missing| Directory | Contents |
|---|---|
| packages/ | One directory per Debian package: what it installs under root/, its nfpm.yaml manifest, its tests; kaomoji/ is the cast; cog/ rebuilds Debian's cog |
| testkit/ | The test harness: the pytest plugin and the commands behind make; builds the packages and tests them in podman containers, a QEMU VM, or on a Pi over SSH |
| devices/ | Device files, one directory per device, documented in devices/README.md; only sample/ is committed, and a gitignored .env names a directory of device directories kept elsewhere |
| docs/ | Design, testing, and platform notes |
make build # every package into dist/
make test-tier0 # unit tests and static checks
make test-tier1 # install, remove, purge in a systemd container
make test-tier2 [VM_DISPLAY=480x320] # boot a QEMU VM from a device file, with a virtual display
make test # tiers 0 and 1, what CI runs on every push
make test-all # tiers 0 to 2, what make release runs
make test-preview # the kiosk preview's VM session on this Mac (QEMU, a window server)
make deploy TARGET=pi@mypi.local # the packages a real device has, freshly built
make checkpoint # the ssh tier on the checkpoints, the real boards .env names
make docs-models # docs/models and the model tables from this Mac's iconsWhat each tier proves and how to write a test is in docs/testing.md. The model icons pictured in the
READMEs come from make docs-models, which runs device-icons on this Mac;
device-icons icons preview <model identifier> shows a candidate in Finder before it goes into a device file.
make release VERSION=2.1.0 # clean tree required; runs tiers 0 to 2, then tags v2.1.0
git push origin v2.1.0 # CI builds, signs, and publishes
make checkpoint # after reflashing the two real boards; docs/testing.md "Release" has the steps- docs/design.md: the decisions and their reasons
- docs/raspberry-pi-os.md: Raspberry Pi OS and cloud-init quirks the device file works around
- docs/app-conventions.md: conventions for applications built on top of Pi Hero
Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by making a PayPal donation to ensure this journey continues indefinitely!
Thanks again for your support, it is much appreciated! 🙏
MIT. See LICENSE for more details.