Inky Bird Frame

Turn the birds around you, the birds your station hears, and the birds you have seen into reviewed field-journal plates on a color e-paper frame.

Browse the plates · Build the frame · Run with Docker

Eastern Bluebird · Sialia sialis

Northern Cardinal · Cardinalis cardinalis

Inky brings several kinds of bird evidence into one private collection:

• nearby observations from iNaturalist and eBird;
• your own eBird history, including birds recorded on past trips;
• acoustic detections from BirdWeather, self-hosted BirdNET-Go, or BirdNET

• authorized Bird Buddy feeder postcards and optional manual sightings.

Start here

• Build the complete wall frame: choose parts in the

• Run the controller on Docker or a NAS: use the

• Use an existing Mac, Linux host, or Raspberry Pi: use the

• Connect eBird, BirdNET, Bird Buddy, or another source: choose providers in

• Connect a trusted browser application: read the

• Add Inky to a Homepage dashboard: use the

• Request or contribute a bird: start with

How it works

Open the full-size overview on a small screen. The installation guide includes the complete runtime and network diagram.

The project has two installed roles:

• The controller checks configured sources, creates and reviews missing

• The display node downloads approved assets, verifies their checksums, and

A trusted browser application may also read the catalog through a same-origin proxy or an explicitly allowed origin. Inky supplies the data interface and a narrow, script-free plate embed, not a standalone application. The controller has no built-in authentication or TLS and must not be exposed directly to the internet.

The controller and display may run on one capable Raspberry Pi, but the recommended wall build keeps a lightweight Pi behind the frame and runs the controller on an existing Mac, Linux computer, Raspberry Pi 4 or 5, or Docker host. A controller or network outage does not blank the e-paper panel; it keeps showing its last successful image.

A same-origin application proxy is the recommended browser path. It can authenticate users, keeps the controller on the trusted network, and needs no CORS setting. Direct cross-origin access is disabled by default. Browser local network and mixed-content policies vary, so a direct connection may prompt for permission or fail even when its origin is allowed. Browser reads never count as display-node health. Allowing an origin does not add authentication or make the controller safe to expose to the internet. See Browser applications for the API, embed, privacy, and network limits.

Observation sources

• Nearby public sightings: iNaturalist or eBird. These use the configured

• Your sightings and trips: eBird Archive. Inky imports the official

• A live acoustic station: BirdWeather or BirdNET-Go. Inky reads species

• Offline acoustic results: BirdNET Analyzer. Only CSV history you

• A smart feeder: Bird Buddy. This opt-in private-API provider requires

Providers run independently, so one failure does not stop healthy providers. Every result must resolve to the same active iNaturalist bird species before it can enter generation. BirdWeather, BirdNET-Go, and Bird Buddy can also give the newest eligible detection one display turn before normal rotation resumes.

See Discovery sources for credentials, provider limits, privacy, setup, verification, failure handling, recovery, and disabling a provider.

Related project

If you want an end-to-end backyard listening station, AvianVisitors by Teddy Warner is a project I’m happy to point people toward. Built around BirdNET-Pi, it turns local microphone detections into a live illustrated collage and connects with Home Assistant, MQTT, remote access, and eBird regional filtering. Teddy also offers hardware kits for the microphone and frame, and the optional e-ink frame can run from either the local station or BirdWeather data. His detailed AvianVisitors project write-up is a great guide to the full listening-station workflow.

Inky Bird Frame meets that ecosystem at a different point. It can bring in acoustic detections from BirdNET-Go, BirdWeather, and BirdNET Analyzer alongside eBird, iNaturalist, Bird Buddy, and personal eBird history, then turn them into reviewed, reusable field-journal plates. Inky does not record or analyze raw audio, configure microphones, or install and manage a BirdNET detector.

Plates you can trust and reuse

Creating an image does not approve it. A separate Codex run checks every candidate:

1. independently verifies the species profile against at least two authoritative

1. compares anatomy, plumage, proportions, and field marks with every reference

1. checks names, measurements, labels, and location neutrality; and
2. returns structured scores and concrete corrections.

Approved plates and manifests contain no postal code, coordinates, observation dates, local place names, network details, or machine paths. That separation lets every installation reuse the same reviewed plate. Downloaded references, private observations, run logs, rejected work, and display state stay outside the reusable catalog.

Browse the public gallery or read the architecture and privacy model.

Hardware

The reference display uses the 13.3-inch PIM774, a Pi Zero 2 W with a pre-soldered header, and a 12 x 16 inch portrait frame. The supported 7.3-inch PIM773 provides a smaller build; the display node fits the complete canonical plate without cropping or stretching.

An existing 64-bit Mac or Linux computer can host the controller at no added hardware cost. A dedicated Raspberry Pi 4 is optional. The reference prices checked on July 9, 2026 put the framed PIM774 display at $358.94 and the optional dedicated controller at $173.64, before tax and shipping.

The hardware guide contains the complete bill of materials, panel and mat dimensions, assembly photographs, reuse guidance, and physical safety notes. Verify every measurement against the panel before cutting a mat or backing board.

Install

Choose the path that matches the controller:

• Docker or a NAS: the Docker controller guide downloads a

• macOS, Ubuntu, or Raspberry Pi OS: the

Both paths continue through the same five checkpoints: prepare and diagnose the controller, flash and attach the display Pi, prove the panel with an included plate, prove private-network access, then enable live rotation and automatic generation.

The controller needs Python 3.11 or newer and either a ChatGPT plan that includes Codex or separately billed OpenAI API access. It also needs network access to the observation, geocoder, research, and Codex services you configure. The display needs Pimoroni’s Inky package and private-network access to the controller.

Living with the frame

Normal installations schedule observation refresh, generation, catalog serving, notifications, and display rotation. These commands are the useful first checks on a native installation. They use the default managed runtime; if you chose a different application directory, point IBF at its .venv/bin/inky-bird-frame instead.

IBF="$HOME/Services/inky-bird-frame/.venv/bin/inky-bird-frame"
"$IBF" --version
"$IBF" doctor controller --config /path/to/config.toml
"$IBF" status --config /path/to/config.toml
"$IBF" refresh --config /path/to/config.toml
"$IBF" generate --config /path/to/config.toml

shuffle_bag is the default rotation: it shows every active bird once before a new round and admits newly discovered birds into the current round. The active catalog includes approved species that are currently observed or explicitly kept in the private collection.

See Operations for Docker equivalents, historical seeding, collection management, rotation modes, publication, backups, and failure recovery. Start with Troubleshooting when a doctor check fails.

Notifications

Notifications tell you when something worth seeing happens: a new bird appears, a plate passes review, a failed service recovers, or generation needs help. Routine successes stay quiet. Delivery uses a retry queue, so a notification provider outage does not block discovery or generation.

!Pushover notifications for a recovered generation queue and an approved American Goldfinch plate

Pushover is one option. The same configuration can target Discord, ntfy, Gotify, Slack, email, Home Assistant, and other Apprise-supported services. See Notifications for setup, event controls, retries, and secret handling.

Homepage dashboard

For my fellow homelabbers, I wanted Inky to feel at home beside the rest of your services. The compact card gives you a quick read on catalog readiness, active birds, approved plates, and the controller version. If you have a little more room, the featured-plate card adds an upright bird plate that refreshes every 15 minutes.

Compact status

Status and featured plate

Both versions use Homepage's stock service widgets. There is no custom plugin or JavaScript to install. The screenshots use a deterministic v0.7.0 demo: the 162 public plates published in that release and a fixed Eastern Bluebird. They include no provider, location, observation time, or personal observation data.

Follow the Homepage dashboard recipe for the copy-and-paste configuration and private-network requirements.

Contributing

Code, documentation, hardware compatibility, and new catalog plates are welcome.

• Request a bird
• Report a bug
• Propose a feature
• Report a problem with a published plate
• Read the contribution guide

The project does not offer individual setup support. Start with the doctor commands and troubleshooting guide; open a bug only when you can describe reproducible incorrect behavior.

Thank you to @dwalters0, whose contribution identified and helped close the trusted browser-client gap, and to everyone who shares an issue, plate, fix, or idea.

Documentation

| If you need to… | Read… | | --- | --- | | Choose parts or assemble a frame | Hardware | | Install on macOS, Linux, or Raspberry Pi OS | Native installation | | Run the controller with Docker or on a NAS | Docker controller | | Configure observation and detection sources | Discovery sources | | Operate, seed, recover, update, or roll back | Operations | | Back up or restore private controller state | Backup and restore | | Configure alerts | Notifications | | Add Inky to a Homepage dashboard | Homepage dashboard | | Diagnose a failure | Troubleshooting | | Understand trust, privacy, and data flow | Architecture | | Submit a change or plate | Contributing | | Report a vulnerability privately | Security |

Development

uv sync --extra dev --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv run inky-bird-frame catalog validate --catalog catalog

License

Inky Bird Frame is available under the MIT License. The controller container also includes Codex CLI and GitHub CLI. Their licenses and the exact in-image notice paths are listed in THIRD_PARTY_NOTICES.md.