[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93332":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":14,"starSnapshotCount":14,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},93332,"inky-bird-frame","veteranbv\u002Finky-bird-frame","veteranbv","Location-neutral bird field-journal plates for Pimoroni Inky displays",null,"Python",111,9,1,0,7,47.2,"MIT License",false,"main",true,[],"2026-07-22 04:02:08","# Inky Bird Frame\n\nShow birds recently observed or detected near you as illustrated field-journal\nplates on a color e-paper display.\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd width=\"50%\" align=\"center\">\n      \u003Cimg src=\"catalog\u002Fspecies\u002F12942-eastern-bluebird\u002Fportrait.png\" alt=\"Eastern Bluebird scientific field-journal plate\" width=\"100%\">\n      \u003Cbr>\u003Cstrong>Eastern Bluebird\u003C\u002Fstrong> · \u003Cem>Sialia sialis\u003C\u002Fem>\n    \u003C\u002Ftd>\n    \u003Ctd width=\"50%\" align=\"center\">\n      \u003Cimg src=\"catalog\u002Fspecies\u002F9083-northern-cardinal\u002Fportrait.png\" alt=\"Northern Cardinal scientific field-journal plate\" width=\"100%\">\n      \u003Cbr>\u003Cstrong>Northern Cardinal\u003C\u002Fstrong> · \u003Cem>Cardinalis cardinalis\u003C\u002Fem>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fimages\u002Fframed-installation.jpg\" alt=\"Inky Bird Frame displaying an Eastern Bluebird field-journal plate in a bronze portrait frame\" width=\"560\">\n  \u003Cbr>\u003Cem>A finished portrait installation using the recommended 12 x 16 inch frame with a panel-fitted mat opening.\u003C\u002Fem>\n\u003C\u002Fp>\n\nThe controller checks the observation sources you configure. iNaturalist and\neBird use your distance and time window; BirdWeather uses recent detections from\nyour station. If a matching plate already exists, the controller uses it. If\nnot, it gathers licensed reference photos, researches the species, creates a\nplate with Codex, and reviews the result before it can appear on the frame.\nApproved plates are cached and reused.\n\n## How it works\n\n\u003Cp align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs\u002Fimages\u002Finstallation-architecture-dark.png\">\n    \u003Cimg src=\"docs\u002Fimages\u002Finstallation-architecture.png\" alt=\"Inky Bird Frame runtime architecture showing Internet services, the controller, its private HTTP connection with the Raspberry Pi display node, and the Inky Impression panel\" width=\"760\">\n  \u003C\u002Fpicture>\n\u003C\u002Fp>\n\nThe project has two jobs:\n\n- The **controller** checks observations, creates and reviews missing plates,\n  and serves approved images on the private network.\n- The **display node** downloads approved assets, verifies their checksums, and\n  rotates them on the Inky panel. It never runs discovery or Codex.\n\nThe roles may run on one capable Raspberry Pi, but the recommended wall build\nkeeps the lightweight display node behind the frame and runs the controller on\nan existing Mac, Linux computer, Raspberry Pi 4 or 5, or Docker host. A Pi Zero\n2 W is a good display node, but it is not recommended for Codex generation.\n\nDiscovery location is private controller configuration. Approved plates and\nmanifests contain no ZIP code, coordinates, observation dates, local place\nnames, network details, or machine paths. A plate generated for one installation\ncan therefore be reused by every installation.\n\n## How plates are approved\n\nCreating an image does not approve it. A separate Codex run checks every\ncandidate:\n\n1. independently verifies the profile against at least two authoritative\n   sources;\n2. compares anatomy, plumage, proportions, and field marks with every reference\n   photograph;\n3. checks scientific and common names, measurements, labels, and location\n   neutrality; and\n4. returns structured scores and concrete findings.\n\nA failed review becomes corrective input for the next attempt. Attempts are\nbounded by configuration, and exhausted work stops for inspection rather than\npublishing. Once a taxon passes, it is never regenerated implicitly.\n\nRegular application code handles selection, licensing rules, checksums, image\ndimensions, rotation, publishing, downloads, and display state. Codex handles\nsourced species research, illustration, and review.\n\n## Hardware\n\nThe reference build uses two computers with distinct jobs. A Raspberry Pi Zero\n2 W lives behind the frame and only displays approved images. A Raspberry Pi 4\nor an existing macOS\u002FLinux computer runs discovery, Codex generation and\nreview, catalog publication, and the HTTP service.\n\n### Framed display\n\nThis is everything required to build the part that hangs on the wall.\n\n| Part | Qty | Unit price | Extended | Purpose |\n| --- | ---: | ---: | ---: | --- |\n| [Pimoroni Inky Impression 13.3 inch (PIM774)](https:\u002F\u002Fwww.adafruit.com\u002Fproduct\u002F6472) | 1 | $275.00 | $275.00 | Six-color, 1600x1200 e-paper display; mounting hardware and GPIO extension header are included |\n| [Raspberry Pi Zero 2 W with pre-soldered header](https:\u002F\u002Fwww.pishop.us\u002Fproduct\u002Fraspberry-pi-zero-2w-with-headers\u002F) | 1 | $20.75 | $20.75 | Compact Wi-Fi display node; no soldering required |\n| [5V 2.5A Micro-USB power supply](https:\u002F\u002Fwww.adafruit.com\u002Fproduct\u002F1995) | 1 | $8.25 | $8.25 | Powers the display node with a standard straight cable |\n| [Official Raspberry Pi 64GB A2 microSD card](https:\u002F\u002Fwww.pishop.us\u002Fproduct\u002Fraspberry-pi-sd-card-64gb\u002F) | 1 | $29.95 | $29.95 | Operating system and local image cache |\n| [Golden State Art 12 x 16 inch bronze frame](https:\u002F\u002Fwww.amazon.com\u002Fgp\u002Faw\u002Fd\u002FB0C1Q5MYG9) | 1 | $24.99 | $24.99 | Portrait frame; the included 8 x 10.5 inch mat must be enlarged or replaced |\n| **Framed display subtotal** |  |  | **$358.94** | Before tax and shipping |\n\nThe display's active area is approximately 7.98 x 10.65 inches. The included\n8 x 10.5 inch mat masks part of that area and must not be used unchanged. Enlarge\nit or order a custom mat with an opening of at least 8.1 x 10.75 inches, then\nverify the opening against the physical panel before cutting. Test-fit the\ndisplay and Pi, trace their position on the supplied rear backing board, and cut\nan opening that leaves the Pi, microSD card, and power connector accessible. The\nPi connects directly to the display and does not need a separate case. A\nright-angle power cable is not required.\n\n### A reuse-first build\n\nThe frame pictured below was built from parts already on hand: an Inky\nImpression display, a Compute Module 4, and a Waveshare carrier board. The CM4\nis larger and more powerful than the display role requires, but reusing it made\nthis build practical without buying another computer. This is one working\nlayout, not required hardware; the smaller Pi Zero 2 W above remains the\nrecommended display node for a new build.\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd width=\"50%\" align=\"center\">\n\u003Cimg src=\"docs\u002Fimages\u002Freference-build-open-back.jpg\" alt=\"Open back of the framed display during assembly, with the panel and CM4 carrier visible\" width=\"100%\">\n\u003Cbr>\u003Cstrong>Before the backing board.\u003C\u002Fstrong> Heavy-duty duct tape holds the panel securely while the display node remains accessible.\n\u003C\u002Ftd>\n\u003Ctd width=\"50%\" align=\"center\">\n\u003Cimg src=\"docs\u002Fimages\u002Freference-build-backing-cutout.jpg\" alt=\"Rear backing board cut around the CM4 carrier in the assembled frame\" width=\"100%\">\n\u003Cbr>\u003Cstrong>With the backing fitted.\u003C\u002Fstrong> The supplied board was cut around the carrier so power, storage, and service access remain available.\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\nWhatever hardware you reuse, test-fit every layer before cutting the backing.\nAvoid pressure on the e-paper panel, keep the display cable relaxed, and leave\nconnectors and ventilation unobstructed.\n\n### Dedicated controller\n\nAn existing 64-bit macOS or Linux computer can run the controller at no\nadditional hardware cost. For a self-contained installation, the reference\ncontroller is a Raspberry Pi 4 running 64-bit Ubuntu Server:\n\n| Part | Qty | Unit price | Extended | Purpose |\n| --- | ---: | ---: | ---: | --- |\n| [Raspberry Pi 4 Model B, 4GB](https:\u002F\u002Fwww.adafruit.com\u002Fproduct\u002F4296) | 1 | $120.00 | $120.00 | Runs discovery, Codex, review, catalog, and HTTP services |\n| [Official Raspberry Pi 5.1V 3A USB-C power supply](https:\u002F\u002Fwww.adafruit.com\u002Fproduct\u002F4298) | 1 | $8.74 | $8.74 | Controller power |\n| [Flirc passive aluminum Raspberry Pi 4 case](https:\u002F\u002Fwww.adafruit.com\u002Fproduct\u002F4553) | 1 | $14.95 | $14.95 | Silent enclosure and passive cooling |\n| [Official Raspberry Pi 64GB A2 microSD card](https:\u002F\u002Fwww.pishop.us\u002Fproduct\u002Fraspberry-pi-sd-card-64gb\u002F) | 1 | $29.95 | $29.95 | 64-bit OS, application, references, and generated assets |\n| **Dedicated controller subtotal** |  |  | **$173.64** | Before tax and shipping |\n| **Complete dedicated build** |  |  | **$532.58** | Framed display plus dedicated controller |\n\nReference prices were checked on July 9, 2026. Retail prices and availability\nchange; the totals exclude tax and shipping. A computer with a microSD reader\nis needed to flash the two cards. No HDMI cable, keyboard, mouse, right-angle\ncable, or display-node enclosure is required for normal operation.\n\nThe controller requires Python 3.11 or newer, Codex CLI authenticated with a\nChatGPT subscription, and network access to Codex, iNaturalist, optional eBird,\nZippopotam.us, and configured research sources. The display node requires\nPython 3.11 or newer with Pimoroni's Inky package and network access to the\ncontroller HTTP service.\n\nThe panel reports a `1600x1200` landscape canvas. Plates are authored at\n`1200x1600` and rotated left for a portrait-mounted frame.\n\n## Install\n\nStart with the path that matches your controller:\n\n- **Docker or a NAS:** use the [Docker controller guide](docs\u002Fdocker.md). It\n  downloads a small deployment bundle and pulls the published AMD64 or ARM64\n  [GHCR image](https:\u002F\u002Fgithub.com\u002Fveteranbv\u002Finky-bird-frame\u002Fpkgs\u002Fcontainer\u002Finky-bird-frame).\n  It does not build the project from source.\n- **macOS, Ubuntu, or Raspberry Pi OS:** use the\n  [native installation guide](docs\u002Finstallation.md).\n\nBoth guides take you through the display Pi after the controller is healthy.\nInstallation follows five checkpoints:\n\n1. prepare and diagnose the controller;\n2. flash the display Pi and attach PIM774;\n3. show the included Eastern Bluebird without Codex or a controller;\n4. prove the Pi can reach the controller; and\n5. enable live rotation and automatic generation.\n\nNative setup previews its changes first. Repeat the command with `--yes` to\napply them, then run the matching doctor:\n\n```bash\ninky-bird-frame setup controller --config \u002Fpath\u002Fto\u002Fconfig.toml\ninky-bird-frame setup controller --config \u002Fpath\u002Fto\u002Fconfig.toml --yes\ninky-bird-frame doctor controller --config \u002Fpath\u002Fto\u002Fconfig.toml\n\ninky-bird-frame setup display --config \u002Fpath\u002Fto\u002Fconfig.toml \\\n  --source-dir \u002Fpath\u002Fto\u002Finky-bird-frame \\\n  --venv \"$HOME\u002F.virtualenvs\u002Fpimoroni\"\ninky-bird-frame setup display --config \u002Fpath\u002Fto\u002Fconfig.toml \\\n  --source-dir \u002Fpath\u002Fto\u002Finky-bird-frame \\\n  --venv \"$HOME\u002F.virtualenvs\u002Fpimoroni\" --yes\ninky-bird-frame doctor display --config \u002Fpath\u002Fto\u002Fconfig.toml\n```\n\n## Operate\n\n```bash\n# Refresh observations and the private active catalog without invoking Codex.\nuv run inky-bird-frame refresh --config config.toml\n\n# Generate and review missing plates from the latest refresh.\nuv run inky-bird-frame generate --config config.toml\n\n# Queue a broader one-time set without changing the active display window.\nuv run inky-bird-frame seed --config config.toml --source inaturalist \\\n  --window last-year --species-limit 500\n\n# Inspect approved, pending, and failed work.\nuv run inky-bird-frame status --config config.toml\n\n# Serve the catalog and rotate the next approved plate.\nuv run inky-bird-frame serve --config config.toml\nuv run inky-bird-frame display-cycle --config config.toml\n\n# Preview or run owner-only publication into this repository's catalog.\nuv run inky-bird-frame catalog-publish --config config.toml --dry-run\nuv run inky-bird-frame catalog-publish --config config.toml\n```\n\nChoose any combination of `inaturalist`, `ebird`, and `birdweather` in\n`discovery.sources`. BirdWeather reads detection summaries from one station; it\ndoes not receive recordings or manage microphones. Every provider result is\nmatched to the same iNaturalist species identity before it enters the catalog.\n\nChoose `last-day`, `last-week`, `last-30-days`, `last-year`, or `all-time` for\nthe observation window. Provider limits still apply. The\n[discovery guide](docs\u002Fdiscovery.md) explains credentials, merging, privacy,\nand those limits.\n\nRotation modes are `sequential`, `shuffle`, `shuffle_bag`, and `weighted`.\n`shuffle_bag` is the default: it shows every active bird once before starting a\nnew round, while adding newly discovered birds to the current round. See\n[Operations](docs\u002Foperations.md) for every option and the recovery commands.\n\n## Related project\n\nLooking for a project that listens through a local microphone?\n[AvianVisitors](https:\u002F\u002Fgithub.com\u002FTwarner491\u002FAvianVisitors) by Teddy Warner\nuses BirdNET-Pi and presents detected birds in a live illustrated collage. It\nalso supports Home Assistant, MQTT, remote access, eBird regional filtering,\noptional e-ink hardware, BirdWeather, and complete kits. Inky Bird Frame focuses\non reusable field-journal plates and does not manage audio. Teddy's detailed\n[AvianVisitors project write-up](https:\u002F\u002Ftheodore.net\u002Fprojects\u002FAvianVisitors\u002F)\nshows the complete listening-station workflow.\n\n## Notifications\n\nNotifications tell you when something worth seeing happens: a new bird appears,\na plate passes review, a failed service recovers, or a generation needs help.\nRoutine successes stay quiet. Delivery uses a retry queue, so a notification\nprovider outage does not block discovery or generation.\n\n![Pushover notifications for a recovered generation queue and an approved American Goldfinch plate](docs\u002Fimages\u002Fpushover-notifications.png)\n\nThis example uses Pushover, but it is not required. The same configuration can\ntarget Discord, ntfy, Gotify, Slack, email, Home Assistant, and other\nApprise-supported services. See [`docs\u002Fnotifications.md`](docs\u002Fnotifications.md)\nfor setup examples, event controls, retry behavior, and secret handling.\n\n## Reusable catalog\n\nEvery approved species lives under `catalog\u002Fspecies\u002F\u003Ctaxon-id>-\u003Cslug>\u002F`:\n\n- `portrait.png`: location-neutral `1200x1600` source plate\n- `display.png`: hardware-ready `1600x1200` image\n- `manifest.json`: facts, research and review sources, reference provenance,\n  quality scores, generation metadata, and SHA-256 checksums\n- `profile.json`: factual species profile matching the manifest, when produced\n  by the current pipeline\n- `quality-review.json`: sourced review matching the manifest, when produced by\n  the current pipeline\n\nDownloaded source photographs, run logs, pending work, rejected work, and\ndisplay state stay under ignored runtime storage. Reference licenses and source\nURLs remain recorded without redistributing the source bitmaps.\n\nPublishing to the shared catalog is optional and separate from the live frame.\nThe publisher accepts only new species that pass the catalog checks, opens a\ncatalog-only pull request, and verifies the exact files before merging it.\nExternal pull requests and GitHub-hosted workflows never receive the private\ncontroller's publication credentials.\n\n## Contributing\n\nCode, documentation, hardware support, and new catalog plates are welcome. The\nrepository includes structured templates for bug reports, feature proposals,\nbird requests, and pull requests.\n\nTo contribute a plate generated by your own controller, prepare one approved\ntaxon and validate the resulting catalog:\n\n```bash\nuv run inky-bird-frame catalog prepare \u003Ctaxon-id> \\\n  --source-catalog \u003Capproved-catalog> \\\n  --catalog catalog\nuv run inky-bird-frame catalog validate --catalog catalog\n```\n\nPublic CI verifies privacy, provenance, checksums, image structure, and that\ncatalog pull requests only add new immutable taxa. It does not receive Codex,\ndeployment, notification, or publisher credentials. See\n[`CONTRIBUTING.md`](CONTRIBUTING.md) for the complete workflow and engineering\nexpectations, and [`SECURITY.md`](SECURITY.md) for private vulnerability\nreporting.\n\n## Development\n\n```bash\nuv sync --extra dev --locked\nuv run ruff format --check .\nuv run ruff check .\nuv run mypy\nuv run pytest\n```\n\nSee [`docs\u002Finstallation.md`](docs\u002Finstallation.md),\n[`docs\u002Ftroubleshooting.md`](docs\u002Ftroubleshooting.md),\n[`docs\u002Farchitecture.md`](docs\u002Farchitecture.md),\n[`docs\u002Foperations.md`](docs\u002Foperations.md),\n[`docs\u002Fnotifications.md`](docs\u002Fnotifications.md), and\n[`CONTRIBUTING.md`](CONTRIBUTING.md) for design, deployment, and contribution\ndetails.\n","这是一个为Pimoroni Inky彩色电子墨水屏设计的鸟类观鸟记录展示系统，可自动获取本地观测数据（如eBird、iNaturalist、BirdWeather），生成标准化的科学风格鸟类图鉴卡片并轮播显示。项目采用分离式架构：控制器负责数据拉取、图像生成（调用Codex辅助）与审核，显示节点仅安全下载并渲染已批准的卡片，确保隐私与低功耗。所有生成的图鉴卡片不包含地理位置、时间等敏感信息，支持跨设备复用。适用于自然教育展示、家庭观鸟墙、生态监测站点等需长期静音展示本地鸟类信息的物理空间场景。",2,"2026-07-16 02:30:09","CREATED_QUERY"]