veteranbv/inky-bird-frame

# Inky Bird Frame 将您附近最近观察到或探测到的鸟类，以彩色电子纸显示屏上的插图野外日志画板（plates）形式展示出来。

Eastern Bluebird · Sialia sialis

Northern Cardinal · Cardinalis cardinalis

控制器会检查您配置的观察数据源。iNaturalist 和 eBird 会根据您的距离和时间窗口进行筛选；BirdWeather 则使用来自您站点的最近探测记录。如果匹配的画板已经存在，控制器会直接使用它。如果不存在，它会收集已获得授权的参考照片，研究该物种，使用 Codex 创建画板，并在其于相框上展示之前对结果进行审查。已批准的画板会被缓存并重复使用。 ## 工作原理

该项目有两个主要任务： - **控制器（controller）** 负责检查观察记录，创建并审查缺失的画板，并在私有网络上提供已批准的图像。 - **显示节点（display node）** 负责下载已批准的资源，验证其校验和（checksums），并在 Inky 面板上轮换显示它们。它绝不运行发现（discovery）流程或 Codex。 这两个角色可以运行在同一台性能足够的 Raspberry Pi 上，但对于推荐的壁挂式构建方案，建议将轻量级的显示节点保留在相框背后，而将控制器运行在现有的 Mac、Linux 计算机、Raspberry Pi 4 或 5，或是 Docker 宿主机上。Pi Zero 2 W 是一个很好的显示节点，但不建议用于 Codex 生成。 发现地点（Discovery location）属于控制器的私有配置。已批准的画板和清单（manifests）中不包含任何邮政编码、坐标、观察日期、当地地名、网络详情或机器路径。因此，为某个装置生成的画板可以被所有装置重复使用。 ## 画板是如何获批的 创建图像并不意味着它已获批。会由一次单独的 Codex 运行来检查每个候选图像： 1. 独立对照至少两个权威来源验证物种特征信息； 2. 将解剖结构、羽毛、比例和野外标志与每一张参考照片进行比对； 3. 检查学名和俗名、尺寸、标签以及地理位置的中立性；以及 4. 返回结构化的评分和具体的审查结果。 审查失败的产物会成为下一次尝试的纠正性输入。尝试次数受配置限制，耗尽限度的工作会停止以供检查，而不会被直接发布。一旦某个分类群（taxon）通过审查，就不会再被隐式重新生成。 常规的应用程序代码负责处理选择、许可规则、校验和、图像尺寸、轮换、发布、下载和显示状态。Codex 则负责处理带来源的物种研究、插图绘制以及审查。 ## 硬件 参考构建使用了两台分工不同的计算机。一台 Raspberry Pi Zero 2 W 放置在相框背后，仅用于显示已批准的图像。一台 Raspberry Pi 4 或现有的 macOS/Linux 计算机则用于运行发现流程、Codex 生成与审查、目录发布以及 HTTP 服务。 ### 带框显示屏 这是构建挂在墙上的显示部分所需的全部材料。 | 部件 | 数量 | 单价 | 总价 | 用途 | | --- | ---: | ---: | ---: | --- | | [Pimoroni Inky Impression 13.3 英寸 (PIM774)](https://www.adafruit.com/product/6472) | 1 | $275.00 | $275.00 | 六色 1600x1200 电子纸显示屏；包含安装硬件和 GPIO 扩展排针 | | [带预焊接排针的 Raspberry Pi Zero 2 W](https://www.pishop.us/product/raspberry-pi-zero-2w-with-headers/) | 1 | $20.75 | $20.75 | 紧凑型 Wi-Fi 显示节点；无需额外焊接 | | [5V 2.5A Micro-USB 电源](https://www.adafruit.com/product/1995) | 1 | $8.25 | $8.25 | 使用标准直缆线为显示节点供电 | | [官方 Raspberry Pi 64GB A2 microSD 卡](https://www.pishop.us/product/raspberry-pi-sd-card-64gb/) | 1 | $29.95 | $29.95 | 用于操作系统和本地图像缓存 | | [Golden State Art 12 x 16 英寸铜制画框](https://www.amazon.com/gp/aw/d/B0C1Q5MYG9) | 1 | $24.99 | $24.99 | 竖向画框；自带的 8 x 10.5 英寸卡纸窗必须扩大或替换 | | **带框显示屏小计** | | | **$358.94** | 不含税费和运费 | 显示屏的有效显示区域约为 7.98 x 10.65 英寸。自带的 8 x 10.5 英寸卡纸窗会遮挡部分区域，因此不能不加修改地直接使用。请将其扩大，或者定制一个开孔至少为 8.1 x 10.75 英寸的卡纸窗，然后在裁剪之前对照物理面板验证开孔尺寸。测试放入显示屏和 Pi，在提供的背板上描出它们的位置，并裁剪出一个开口，使得 Pi、microSD 卡和电源连接器可以方便触及。Pi 直接连接到显示屏，不需要额外配备保护壳。也不需要使用直角电源线。 如果需要构建较小的版本，可以替换为支持的 7.3 英寸 PIM773。其有效显示区域约为 6.30 x 3.78 英寸，电路板尺寸约为 6.86 x 4.85 英寸。显示节点会将每个完整的标准画板无裁剪、无拉伸地适配到其 800x480 的画布上，仅留下狭窄的纸张本色边缘。在裁剪之前，请务必对照物理面板选择并确认画框和卡纸窗；上述 12 x 16 英寸画框及尺寸专门适用于 PIM774。 ### 优先复用现有部件的构建方案 下图所示的相框是使用手头现有的零件构建的：一个 Inky Impression 显示屏、一个 Compute Module 4 以及一块 Waveshare 底板。CM4 比单纯作为显示用途所需的配置更大、性能更强，但复用它使得这个构建方案无需购买另一台计算机就得以实现。这只是其中一种可行的布局方式，并非强制要求的硬件；对于全新的构建方案，上文提到的体积更小的 Pi Zero 2 W 依然是我们推荐的显示节点。

Before the backing board. Heavy-duty duct tape holds the panel securely while the display node remains accessible.

With the backing fitted. The supplied board was cut around the carrier so power, storage, and service access remain available.

无论您复用什么硬件，在裁剪背板之前，请务必试装每一层组件。避免对电子纸面板施加压力，保持显示屏线缆处于松弛状态，并确保连接器和通风口畅通无阻。 ### 专用控制器 现有的 64 位 macOS 或 Linux 计算机可以直接运行控制器，无需增加额外的硬件成本。如果是独立部署，参考的控制器配置为运行 64 位 Ubuntu Server 的 Raspberry Pi 4： | 部件 | 数量 | 单价 | 总价 | 用途 | | --- | ---: | ---: | ---: | --- | | [Raspberry Pi 4 Model B, 4GB](https://www.adafruit.com/product/4296) | 1 | $120.00 | $120.00 | 运行发现、Codex、审查、目录和 HTTP 服务 | | [官方 Raspberry Pi 5.1V 3A USB-C 电源](https://www.adafruit.com/product/4298) | 1 | $8.74 | $8.74 | 为控制器供电 | | [Flirc 被动散热铝合金 Raspberry Pi 4 保护壳](https://www.adafruit.com/product/4553) | 1 | $14.95 | $14.95 | 静音外壳与被动散热 | | [官方 Raspberry Pi 64GB A2 microSD 卡](https://www.pishop.us/product/raspberry-pi-sd-card-64gb/) | 1 | $29.95 | $29.95 | 用于 64 位操作系统、应用程序、参考资料及生成的资产 | | **专用控制器小计** | | | **$173.64** | 不含税费和运费 | | **完整的专用硬件构建总计** | | | **$532.58** | 带框显示屏加上专用控制器 | 上述参考价格核对于 2026 年 7 月 9 日。零售价格和供货情况可能会有所变动；总计金额不含税费和运费。还需要一台带有 microSD 读卡器的计算机来为这两张卡刷入系统。在正常运行过程中，不需要 HDMI 缆线、键盘、鼠标、直角数据线或显示节点的外壳。 控制器需要 Python 3.11 或更高版本，经过 ChatGPT 订阅认证的 Codex CLI，以及访问 Codex、iNaturalist、可选的 eBird、Zippopotam.us 和已配置研究来源的网络连接。显示节点则需要 Python 3.11 或更高版本，配备 Pimoroni 的 Inky 软件包，并能访问控制器的 HTTP 服务。 PIM774 上报的是 `1600x1200` 的横向画布，而 PIM773 上报的是 `800x480`。不过，画板始终保持以 `1200x1600` 尺寸进行创作，并作为标准的 `1600x1200` 显示资产进行存储。显示节点会保留 PIM774 的原始输出，并自动将完整的画板无裁剪、无拉伸地适配到 PIM773 上。 ## 安装说明 请从符合您控制器运行环境的指南开始： - **Docker 或 NAS：** 请使用 [Docker 控制器指南](docs/docker.md)。该指南会下载一个小型的部署包，并拉取已发布的 AMD64 或 ARM64 [GHCR 镜像](https://github.com/veteranbv/inky-bird-frame/pkgs/container/inky-bird-frame)。它不需要从源码构建项目。 - **macOS、Ubuntu 或 Raspberry Pi OS：** 请使用[原生安装指南](docs/installation.md)。 这两份指南都会在确认控制器运行正常后，指导您完成显示端 Pi 的配置。 整个安装过程包含五个检查点： 1. 准备并诊断控制器； 2. 为显示端 Pi 刷入系统并连接 PIM773 或 PIM774； 3. 在不需要 Codex 或控制器的情况下，显示内置的东部蓝鸲（Eastern Bluebird）； 4. 确认 Pi 能够成功连接到控制器；以及 5. 启用实时轮换和自动生成功能。 原生安装方式会先预览其将要进行的更改。请加上 `--yes` 参数重复执行该命令以应用更改，然后运行相应的诊断程序： ``` inky-bird-frame setup controller --config /path/to/config.toml inky-bird-frame setup controller --config /path/to/config.toml --yes inky-bird-frame doctor controller --config /path/to/config.toml inky-bird-frame setup display --config /path/to/config.toml \ --source-dir /path/to/inky-bird-frame \ --venv "$HOME/.virtualenvs/pimoroni" inky-bird-frame setup display --config /path/to/config.toml \ --source-dir /path/to/inky-bird-frame \ --venv "$HOME/.virtualenvs/pimoroni" --yes inky-bird-frame doctor display --config /path/to/config.toml ``` ## 操作说明 ``` # 刷新 observations 和私有 active catalog，而不调用 Codex。 uv run inky-bird-frame refresh --config config.toml # 生成并审查最新刷新中缺失的 plates。 uv run inky-bird-frame generate --config config.toml # 将更广泛的一次性集合加入队列，而不更改当前的 active display window。 uv run inky-bird-frame seed --config config.toml --source inaturalist \ --window last-year --species-limit 500 # 检查已批准、待处理和失败的 work。 uv run inky-bird-frame status --config config.toml # 提供 catalog 并轮换下一个已批准的 plate。 uv run inky-bird-frame serve --config config.toml uv run inky-bird-frame display-cycle --config config.toml # 预览或针对此 repository 的 catalog 运行仅限 owner 的 publication。 uv run inky-bird-frame catalog-publish --config config.toml --dry-run uv run inky-bird-frame catalog-publish --config config.toml ``` 您可以在 `discovery.sources` 中选择 `inaturalist`、`ebird` 和 `birdweather` 的任意组合。BirdWeather 仅读取来自单个站点的探测摘要；它不接收录音数据，也不管理麦克风。每一个提供者的数据结果在进入目录之前，都会被匹配到同一个 iNaturalist 物种身份标识上。 请为观察时间窗口选择 `last-day`、`last-week`、`last-30-days`、`last-year` 或 `all-time`。数据源提供者自身的限制依然适用。[发现指南](docs/discovery.md)详细说明了凭据配置、数据合并、隐私保护以及相关限制。 轮换模式包括 `sequential`、`shuffle`、`shuffle_bag` 和 `weighted`。默认模式是 `shuffle_bag`：它会在开始新一轮展示前，把当前所有活跃的鸟类分别展示一次，同时将新发现的鸟类加入到当前轮次中。有关所有配置选项及恢复命令，请参阅[操作说明](docs/operations.md)。 ## 相关项目 您是否在寻找可以通过本地麦克风进行监听的项目？由 Teddy Warner 开发的 [AvianVisitors](https://github.com/Twarner491/AvianVisitors) 使用了 BirdNET-Pi，并以实时插图拼贴画的形式展示探测到的鸟类。它还支持 Home Assistant、MQTT、远程访问、eBird 区域过滤、可选的电子墨水屏硬件、BirdWeather 以及完整的套件。Inky Bird Frame 则专注于可重复使用的野外日志画板，并不处理音频。Teddy 详细的 [AvianVisitors 项目文章](https://theodore.net/projects/AvianVisitors/)展示了完整的监听站工作流。 ## 通知提醒 通知功能会在发生值得关注的事件时提醒您：比如发现了新鸟类、画板通过了审查、故障服务已恢复，或者生成过程需要人工介入。日常的成功操作则不会发送通知以保持安静。通知发送使用了重试队列机制，因此通知服务提供商的宕机不会阻塞发现或生成流程。  此示例使用了 Pushover，但这并非必需。您可以使用相同的配置将通知发送到 Discord、ntfy、Gotify、Slack、电子邮件、Home Assistant 以及其他受 Apprise 支持的服务。有关设置示例、事件控制、重试行为和密钥处理，请参阅 [`docs/notifications.md`](docs/notifications.md)。 ## 可复用目录 所有通过审查的物种都存放在 `catalog/species/-/` 路径下： - `portrait.png`：地理位置中立的 `1200x1600` 源画板 - `display.png`：标准的 `1600x1200` 横向图像；PIM773 显示节点会在本地将其适配为 `800x480` - `manifest.json`：包含事实信息、研究和审查来源、参考出处、质量评分、生成数据以及 SHA-256 校验和 - `profile.json`：与清单相匹配的基于事实的物种特征信息（当由当前流水线生成时提供） - `quality-review.json`：与清单相匹配的带来源审查记录（当由当前流水线生成时提供） 下载的源照片、运行日志、待处理工作、被拒绝的工作以及显示状态都保存在被忽略的运行时存储路径下。参考图像的许可信息和来源 URL 会被记录下来，但不会重新分发源位图。 将内容发布到共享目录是可选项，并且独立于实时相框运行。发布程序只接受通过了目录检查的新物种，开启仅针对目录的 Pull Request，并在合并前验证确切的文件。外部的 Pull Request 和 GitHub 托管的工作流绝不会获取到私有控制器的发布凭据。 ## 开发说明 ``` uv sync --extra dev --locked uv run ruff format --check . uv run ruff check . uv run mypy uv run pytest ``` 有关设计、部署和贡献的详细信息，请参阅 [`docs/installation.md`](docs/installation.md)、[`docs/troubleshooting.md`](docs/troubleshooting.md)、[`docs/architecture.md`](docs/architecture.md)、[`docs/operations.md`](docs/operations.md)、[`docs/notifications.md`](docs/notifications.md) 以及 [`CONTRIBUTING.md`](CONTRIBUTING.md)。

标签：AIGC, Raspberry Pi, 信息展示, 内存执行, 物联网, 电子墨水屏, 硬件项目, 自然科学, 请求拦截, 逆向工具