SplitFlapGatewayCompanion

# 分页闸道伴侣 > ### 📖 [分页闸道维基 — 全面的文档](https://github.com/avandeputte/SplitFlapGateway/wiki) > 快速开始 · 选择配置 · 配置和校准 · 分页闸道和矩阵闸道 · 伴侣及其应用 · API 和线路协议 — 整个生态系统，都记录在一个地方。 一个网页应用，向由 **SplitFlapGateway** 驱动的分页显示屏发送丰富的内容 — 时钟、天气、股票、体育、名言、动画、组合消息。 闸道（ESP32）拥有 *硬件*：RS-485 总线、模块发现、配置、校准和诊断。伴侣拥有 *内容*：应用、播放列表、时间表、触发器和实时预览。两者运行在不同的机器上，但感觉像 **一个产品** — 它们共享外观和选项卡条，相互链接，伴侣注册自己，以便在闸道上出现 **伴侣** 选项卡。每个方面都告诉对方它有哪些选项卡，以便导航始终与两个方面实际存在的内容相匹配。 伴侣自带 **自己的应用库**，在插件运行时运行，与 [csader/splitflap-os](https://github.com/csader/splitflap-os) 的行为相同 — 因此任何 splitflap-os 应用都不需要修改即可直接使用。构建自己的应用？ **[编写应用](https://github.com/avandeputte/SplitFlapGateway/wiki/Writing-Apps)** 是一份完整的指南；另请参阅 [兼容性](https://github.com/avandeputte/SplitFlapGateway/wiki/Compatibility) 和 [ATTRIBUTION.md](ATTRIBUTION.md)。 > **许可证：** CC BY-NC-SA 4.0（非商业、共享、署名）— splitflap-os 的衍生品。参见 [LICENSE](LICENSE)。 --- ## 功能 - **应用** — 伴侣自己的库（功能性、频道和测验），在与 splitflap-os 应用兼容的运行时环境中（一致性测试确保每个应用都满足契约）。带有单点运行和实时“▶ 运行”状态的磁贴网格，**应用库** 用于添加或删除应用，**上传您自己的应用** （应用文件夹的 `.zip` 文件）— 持久化到数据卷。库中显示每个应用的描述、类型、版本和类别，带有搜索和类别筛选器。 - **基于清单的设置** — 完整渲染器：文本 / 数字 / 密码 / 文本区域 / 选择 / 切换，**search_chips** （位置、股票、加密货币、时区的实时搜索），步进器，内联切换，`visible_when`，`sync_values` 和计算字段。 - **多个显示屏同时运行** — 从一个伴侣驱动多个闸道。每个墙壁都有自己的几何形状、应用、播放列表、触发器和设置，头部有一个切换器，可以在它们之间切换。参见 **[多个显示屏](#多个显示屏)**。 - **矩阵闸道墙壁获得完整字母表** — 在您输入的文本中，包含小写字母和重音符号，十四种 **象形文字** （`♥ ☺ ♪ ● ■ ⌂ ← ↑ → ↓ ☀` 等），颜色按 *名称* 而不是按七个字母来表示。物理分页显示屏的驱动方式与以前完全相同。参见 **[字符](#字符)**。 - **组合** — 带有颜色瓷砖和每种过渡样式的单击输入网格（`ltr`、`rtl`、`spiral`、`slot`、`columns`、`outside_in` 等）。 - **实时预览 + 首页全部** — 板块镜像墙壁上的内容，**⌂ 首页全部** 将每个模块返回到其空白首页，停止正在播放的任何内容。停止应用或播放列表会使墙壁变空白：没有任何正在运行的内容意味着没有任何显示内容，时钟冻结在 11:34 上显然是 *错误* 的，而不是 *关闭*。 - **播放列表** — 顺序运行应用和消息，带有每个条目的时长；保存、运行、循环。**每个条目的设置** 允许同一个应用出现多次，配置不同（例如两个城市的天气，以两种语言显示）。 - **时间表** — 按一天中的时间窗口运行应用或播放列表，或关闭显示屏，按工作日，另有 **静音时段**。 - **触发器** — 监视事件的应用（国际空间站经过、游戏、天气），并简要 **中断** 显示屏，带有每个触发器的冷却时间。 - **本地化** — 一个全局 **语言** 加 **位置** 和 **时区**，所有这些都位于全局设置的顶部。带有 🌐 徽章的应用遵循它们：翻译后的单词、本地日期顺序、数字格式、12 小时/24 小时和按国家划分的货币/假期。所有这些都可以在每个应用和每个播放列表条目中重写。参见 **[本地化](#本地化)**。 - **闸道，集中一处** — 闸道的校准 / 模块 / 诊断 UI 直接在伴侣中打开（作为 Home Assistant 应用，直接在侧边栏中），因此您无需离开即可配置硬件。 - **Home Assistant** — 原生 **[HACS 集成](#home-assistant-hacs-integration)**， **[MQTT 设备](#home-assistant-mqtt)**，一键式 **[侧边栏应用](#home-assistant-app-add-on)**， **[Vestaboard 兼容 API](#vestaboard-compatible-api)**，以及用于 LLM 客户端的 **[MCP 服务器](#mcp-server)**。 - **打包** — 多架构 Docker 镜像（健康检查 + `/data` 卷），一键安装程序，以及 Home Assistant 应用。 闸道是 **事实来源**，网格大小从中读取，启动时从中读取。在伴侣通过 **REST** 驱动显示屏 — 一个页面一个请求，无需代理 — 因此动画流畅。MQTT 是可选的，仅用于 Home Assistant MQTT 设备（应用 / 播放列表 / 停止实体）；由于 Matrix Portal Gateway **固件 3.0** 已从闸道中删除 MQTT，因此代理在伴侣中配置，而不是从闸道中读取。 --- ## 快速开始 ### Home Assistant 应用（最简单，如果您运行 HA） Home Assistant 称这些为“应用”（以前称为“附加组件”）。此存储库是一个应用存储库： 1. **设置 → 应用 → 应用商店 → ⋮ → 仓库**，然后添加：`https://github.com/avandeputte/SplitFlapGatewayCompanion` 2. 安装 **SplitFlap Gateway Companion**，在配置选项卡中设置 `gateway_url`。 3. **启动**，然后 **打开 Web UI** — 它出现在侧边栏中，与 HA 风格一致。 更多详细信息、选项和两个通道在 **[Home Assistant 应用](#home-assistant-app-add-on)** 中。 ### Docker ```bash docker run -d --name splitflap-companion -p 8000:8000 \ -e GATEWAY_URL=http://192.168.1.50 \ -e COMPANION_PUBLIC_URL=http://192.168.1.42:8000 \ -v companion-data:/data \ ghcr.io/avandeputte/splitflap-gateway-companion:latest # 打开 http://localhost:8000 ``` `COMPANION_PUBLIC_URL` 是 **本机的局域网地址** （不是闸道的地址），这是伴侣向闸道注册的地址，以便闸道的 **伴侣** 选项卡可以链接回它。在 Docker 中运行时，请始终设置此参数：容器内，伴侣只能看到自己的 `172.17.x.x` 网桥地址，而您的闸道 — 一个位于局域网上的设备 — 无法访问。 如果它必须猜测，则会记录警告。[安装脚本](#安装脚本) 会为您填写此参数，而其他内容则不依赖于此：驱动显示屏无论如何都有效。 镜像是 **多架构** 的，因此同一个标签在 x86（Windows / Linux）和 arm64（Raspberry Pi 64 位，Apple Silicon）上运行 — Docker 会拉取正确的架构。 将 `GATEWAY_URL` 指向您的闸道；这通常是必需的（应用拒绝在没有它的情况下启动）。或者使用 Compose： ```bash docker compose pull && docker compose up -d # 在 .env 中设置 GHCR_OWNER ``` ### 安装脚本 一条命令在 Raspberry Pi 或任何 x86-64 Linux 盒子上设置所有内容 — 它安装 Docker（如果需要），询问几个问题，编写一个 `docker-compose` 项目并启动伴侣： ```bash curl -fsSL https://raw.githubusercontent.com/avandeputte/SplitFlapGatewayCompanion/main/install.sh | bash ``` 它安装 Docker（如果不存在），可选地部署 Mosquitto 代理（仅适用于 Home Assistant MQTT 设备 — 如果您的闸道已经有一个代理，则跳过），询问网关 URL 和可选的 MQTT 密码，创建容器（自动检测主机 IP，以便闸道可以链接回来），并且可以添加一个 Watchtower 容器，每 6 小时自动更新。每个提示都有一个 env-var 重写，用于无人值守的安装： ```bash GATEWAY_URL=http://192.168.1.50 DEPLOY_MQTT=no AUTO_UPDATE=yes \ bash -c "$(curl -fsSL https://raw.githubusercontent.com/avandeputte/SplitFlapGatewayCompanion/main/install.sh)" ``` 要手动更新：`cd <project-dir> && docker compose pull && docker compose up -d`. ### 本地开发 ```bash cd backend python3 -m venv .venv && . .venv/bin/activate pip install -r requirements-dev.txt GATEWAY_URL=http://192.168.1.50 python -m app # 需要；绑定 0.0.0.0:8000 GATEWAY_URL=http://192.168.1.50 COMPANION_RELOAD=1 python -m app # 自动重载 pytest # 运行测试 ``` > 使用 `python -m app` 运行，而不是裸 `uvicorn app.main:app`：裸命令绑定到 `127.0.0.1`（仅限本地主机），因此伴侣在您的局域网上不可访问，网关注册的 URL 将无法工作。`python -m app` 绑定到 `0.0.0.0` 并遵循 `COMPANION_HOST` / `COMPANION_PORT`。 --- ## 配置 **没有伴侣配置文件。** 配置在运行时从 `defaults ← gateway ← environment` 派生，并且从不写入磁盘，因此无需播种、迁移或备份。 - **环境** — 您设置的内容： **`GATEWAY_URL`** （**必需**）和用于 Home Assistant MQTT 设备的 `COMPANION_MQTT_BROKER`（以及 `_USER` / `_PASSWORD` 如果需要身份验证）。环境变量始终生效。 - **闸道（事实来源）** — 网格大小从闸道的 `/api/config` 读取，启动时和 **同步** 时读取。（固件 3.0 已从闸道中删除 MQTT，因此不再从中读取代理 — 在伴侣中设置。） - **默认值** — 默认情况下使用的合理默认值，直到闸道响应。 作为 Home Assistant 应用，没有环境变量 — 相同的设置来自配置选项卡（参见 [Home Assistant 应用](#home-assistant-app-add-on)）。 `<data_dir>`（一个 Docker 卷）保存您的 **应用设置、播放列表、触发器和上传的应用** — 而不是任何伴侣配置，这些配置从不持久化。 | 环境变量 | 含义 | 默认值 | | --- | --- | --- | | `GATEWAY_URL` | 闸道基本 URL（REST + 配置同步 + 状态）。**必需** | *（无；必需）* | | `COMPANION_PUBLIC_URL` | 伴侣自己的 URL，注册给闸道用于其“伴侣”选项卡 | *（自动检测）* | | `COMPANION_SYNC_FROM_GATEWAY` | 启动时从闸道拉取网格大小 | `true` | | `COMPANION_MQTT_PASSWORD` | Home Assistant 设备的 MQTT 密码 | — | | `COMPANION_HA` | Home Assistant MQTT 设备：`auto`（开启时设置代理）\| `true` \| `false` | `auto` | | `COMPANION_HA_URL` / `_TOKEN` | Home Assistant 基本 URL + 长时令牌，以便应用（**HA 仪表板**，**Home Assistant**）可以在独立 Docker 中读取实体状态 — 附加组件使用 Supervisor 代理 | — | | `COMPANION_VESTABOARD` / `_KEY` | 启用 [Vestaboard API](#vestaboard-compatible-api) 并固定其密钥 | `off` | | `COMPANION_MCP` / `_TOKEN` | 启用 [MCP 服务器](#mcp-server) 并固定其令牌 | `off` | | `GATEWAY_URL` | **必需。** 您的闸道。接受 **逗号分隔的列表** 以驱动 [多个显示屏](#多个显示屏) | — | | `COMPANION_MODULE_ID_BASE` | 网格索引 0 的模块 ID | `0` | | `COMPANION_GRID_ROWS` / `_COLS` | 手动面板大小覆盖 | *（来自闸道）* | | `COMPANION_MQTT_BROKER` / `_PORT` / `_USER` | Home Assistant 设备的 MQTT 代理/端口/用户（例如代理 `core-mosquitto`） | *（未设置 — HA 关闭）* | | `COMPANION_SETTINGS_STORE` | 设置存储位置：`mirror` \| `local` \| `gateway` — 参见下文 | `mirror` | | `COMPANION_DATA_DIR` | 应用设置、播放列表、触发器 + 上传的应用存储位置 | `<repo>/data` | | `COMPANION_DEV_MODE` | 在 ⚙ 工具菜单中启用 **模拟模式** — 在模拟时运行应用，无需驱动墙壁，网格覆盖 | `off` | | `COMPANION_LOG_LEVEL` | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL` | `INFO` | ### 设置存储 伴侣将其设置、播放列表和触发器存储在 `<data_dir>/app_settings.json` 中，也可以将它们镜像到闸道上，以便新的容器继承它们。`COMPANION_SETTINGS_STORE`： - **`mirror`** （默认）— 本地文件是主要的，每次更改都会镜像到闸道（压缩，防抖）。带有本地文件的全新主机在启动时 **从闸道恢复**；空闸道从本地副本中播种。 - **`local`** — 仅本地文件；闸道从未被触及。 - **`gateway`** — 仅存储在闸道上，本地不写入（无磁盘伴侣）。 设置很小（~1-2 KB 压缩后），写入是防抖的，伴侣在设置传输期间暂停显示帧，因此它不会淹没闸道。上传的自定义应用存储在 `<data_dir>/apps/` 中 — 只有设置 blob 会移动。 ### 字符 **墙壁决定大小写，而不是应用。** 物理分页显示屏没有小写翻页，其一字节协议没有小写字节 — `r` 的字节已经意味着 **红色**。因此，发送到分页显示屏的文本被折叠为大写，以一种 **Windows-1252 感知** 的方式：`É`、`Ü`、`ç` 和 `ß` 存活下来，而 `ß` **不** 扩展为 `SS`（这将无声地吃掉一个单元格）。 **矩阵闸道** 不同。其模块是绘制的，而不是机械的，因此没有任何限制：237 个翻页，每个 Windows-1252 字符，每个小写字母和十四种象形文字。它通过索引寻址 API 驱动，可以访问它们，因此您输入的文本在 **Compose** 中，在 **Vestaboard 端点** 发送，或给 LLM 到达 **如同您编写的一样** — 七种颜色按 *名称* 而不是七个字母来表示。 | | 分页显示屏 | 矩阵闸道 | | --- | --- | --- | | 小写字母 | 折叠为大写 | 按原样显示 | | 象形文字 `♥ ☺ ♪ ● ■ ⌂ ← ↑ → ↓ ☀` | 最近的字符（`↑` → `^`） | 显示 | | 颜色 🟥🟩🟦🟨🟧🟪⬜ | 是 | 是，按名称显示 | 更喜欢 Matrix Gateway 上的经典外观？ **全局设置中的全部大写** 仍然会折叠它 — 而且不会带来其他成本：墙壁仍然会获得其象形文字和命名颜色。 这是 **每个显示屏的**，因此一个墙壁可以大声喧哗，而另一个则不会。 伴侣 **不** 监控字符：每个字符（口音，`€`，标点符号）都会通过，一个模块会用其自身翻页空白的任何内容来空白。墙壁无法完全显示的字符在 **空白** 而不是 **拒绝的页面**。 ### 网格 → 模块映射 显示屏按行主序填充：模块 = `module_id_base + (行 * 列 + 列)`。 将行/列/基数设置为与网关中模块的配置方式相匹配。 ### 上传您自己的应用 **应用库 → 上传** 接受一个应用文件夹的 `.zip` 文件 — `manifest.json` 加上 `app.py`（功能性）或 `data.json`（频道，或问题/答案对的测验），与内置应用的格式相同。上传会被验证（清单 + 功能应用的 `fetch()` 必须导入），写入 `<data_dir>/apps/<id>/`，因此它在重启和镜像升级后仍然存在，立即启用和加载。 **[编写应用](https://github.com/avandeputte/SplitFlapGateway/wiki/Writing-Apps)** 是完整的指南。 > ⚠️ 功能应用的 `app.py` 在伴侣主机上运行任意 Python 代码 — 仅上传您信任的应用。（与 splitflap-os 插件相同的信任模型。） --- ## 多个显示屏 一个伴侣可以驱动多个闸道。每个闸道都是一个 **显示屏**，具有自己的几何形状、已安装的应用、播放列表、触发器和设置 — 以及自己的 Home Assistant 设备。 **添加一个。** 要么将它们列在 `GATEWAY_URL` 中，用逗号分隔： ```bash GATEWAY_URL=http://192.168.1.218,http://192.168.1.50 ``` …或者在应用中添加一个：**⚙ 工具 → 显示屏**。在那里添加的显示屏会立即启动 — 无需重启 — 并从第一个显示屏的全局设置（位置、语言、API 密钥）开始，这样您就不必重新输入它们。它们从那时起就成为该显示屏自己的。 在头部出现一个切换器，一旦您有多个显示屏；它后面跟着实时预览、组合、播放列表、触发器和闸道的选项卡。**只有一个显示屏时，它被完全隐藏**，因此单个闸道设置看起来与以前完全相同。 **默认显示屏** 是未指定显示屏的所有内容驱动的显示屏：裸 `/api/…` 路由，Vestaboard 端点，具有 `display` 的 MCP 调用，现有 HACS 条目。它是一个您可以做出的选择（⚙ 工具 → 显示屏 → *设为默认*），而不会根据当前正在播放的内容进行推断，并且它被记住。 **显式寻址一个：** | 界面 | 方法 | | --- | --- | | REST | 在任何 `/api/…` 路由上使用 `?display=<id>`（未知 ID → **404**，而非错误的墙壁） | | 闸道的自身 UI | `/gw/<id>/` | | Vestaboard | `/local-api/<id>/message` | | MCP | 每个工具上的 `display` 参数，加上 `list_displays` | **存储位置。** `data/displays.json` 保存注册表，每个显示屏的设置存储在 `data/displays/<id>/` 中。两者都存储在 **每个** 闸道的设置 blob 中 — 因此，如果伴侣的磁盘丢失，给它一个单独的闸道 URL，您的其他墙壁就会恢复，包括它们的名字和您选择的默认设置。 --- ## Home Assistant 从 Home Assistant 使用伴侣的五种方式，从最集成到最不集成。 …（其他部分翻译略） ### Home Assistant 应用（插件） 在 HA 边栏中运行完整的伴侣，主题匹配，从 配置选项卡进行配置 —— 无需环境变量，无需命令行。按照 [快速入门](#home-assistant-app-easiest-if-you-run-ha) 中的方法安装。 **通道。** 应用同时发布在两个通道上，每个通道都有自己的商店入口： | 文件夹 | 商店入口 | |---|---| | [addon/](addon/) | SplitFlap Gateway Companion | | [addon-beta/](addon-beta/) | SplitFlap Gateway Companion **（测试版）** | 除非您想要预发布版本，否则请选择稳定通道。两个通道都运行相同的已发布镜像 —— 没有特定于应用的构建。两个通道都可以安装，但它们发布相同的宿主 端口（8000），因此 **一次只能运行一个**，除非您在其中一个通道上重新映射端口 （配置选项卡 → 网络）。 **选项**（配置选项卡）：`gateway_url`（必填），`mqtt_broker` + `mqtt_port` / `mqtt_username` / `mqtt_password`，`companion_public_url`， `home_assistant`，`vestaboard` + `vestaboard_key`，`mcp` + `mcp_token`， `ui_language`，`dev_mode`，`log_level`. 使其原生化的原因： - **边栏（ingress）。** UI 和网关自己的配置 UI 都在 Home Assistant 内打开 —— 无需跳转到单独的选项卡。 - **统一的设计语言。** 整个项目 —— 伴侣和网关 UI 相同 —— 都遵循 Home Assistant 的设计语言，亮色和暗色主题跟随您的系统。分屏板本身保持黑暗： 它显示物理翻页。 - **自我发现。** 它向 Supervisor 请求主机的真实地址和已发布的 端口，以便网关可以链接回它。 Ingress 涵盖 *UI*。Vestaboard API 和 MCP 服务器由客户端访问 ，这些客户端不是 HA 前端，因此应用还为它们发布 **8000** 端口。 ### Home Assistant（HACS 集成） 原生集成 —— 通过 [HACS](https://hacs.xyz) 安装，将其指向 伴侣的 URL，它会添加一个 **SplitFlap** 设备，包含： | 实体 | 功能 | |---|---| | **应用**（选择） | 运行已安装的应用，或 `关闭` 以停止 | | **播放列表**（选择） | 运行已保存的播放列表，或 `关闭` | | **显示中**（传感器） | 当前在翻页板上的应用 —— 即使在播放列表中 | | **消息**（传感器） | 翻页板显示的文本（带有 `行` 属性） | | **板**（图像） | 墙壁的实时图像 —— 分屏瓷砖，颜色翻页，装饰和象形图。可以将其放入任何图片卡片或附加到通知；仅在板更改时重绘。 | | **清除 / 停止 / 首页所有**（按钮） | — | | `splitflap.message`（服务） | 显示文本，带有可选样式和 **定时自动恢复** | 与 Vestaboard 集成不同，这会显示 **应用和播放列表**。它不需要 MQTT 代理 —— 它直接与伴侣通信。驱动 [多个显示屏](#multiple-displays)？ 配置流程会询问每个条目是哪个墙壁 —— 每个显示屏都是其自己的设备，因此为每个墙壁添加 集成。`splitflap.message` 服务在 `seconds` 设置时，会显示一条消息，持续该时间，然后返回到正在播放的内容： ```yaml action: - service: splitflap.message data: text: "晚餐准备好了" seconds: 30 ``` 集成位于 [custom_components/splitflap/](custom_components/splitflap/)。 ### Home Assistant（MQTT） 使用 `COMPANION_HA=auto`（默认值），伴侣会在 **MQTT 代理配置** 时启用 HA （`COMPANION_MQTT_BROKER` 或插件中的代理选项 —— 固件 3.0 已从网关中删除 MQTT，因此代理在伴侣中设置）。它发布一个 自动发现设备，**SplitFlap Companion**，包含伴侣特有的控件： | 实体 | 类型 | 功能 | |---|---|---| | 应用 | 选择 | 运行应用（或 `关闭` 以停止）；状态显示正在运行的应用 | | 播放列表 | 选择 | 运行播放列表（或 `关闭`）；状态显示正在运行的播放列表 | | 停止 | 按钮 | 停止正在运行的任何内容 | 如果您已经运行 MQTT 并且不想使用 HACS 集成，请使用此选项；HACS 集成是更丰富的选项。 ### Vestaboard 兼容 API 一款 **[Vestaboard](https://www.vestaboard.com/)** 是一款商用分屏显示，带有 广泛使用的 [本地 API](https://docs.vestaboard.com/docs/local-api/endpoints)。打开 此功能后，伴侣会响应该 API，因此为 Vestaboard 编写的任何内容 —— 一个 `rest_command`， [ha-vestaboard](https://github.com/natekspencer/ha-vestaboard) 集成，脚本，客户端库 —— 都可以在您的墙壁上无缝运行。Vestaboard 笔记是 3 × 15，恰好是默认网格。 ```bash COMPANION_VESTABOARD=1 # 默认关闭 COMPANION_VESTABOARD_KEY= # 留空 -> 生成一次，与您的设置一起保存 ``` 它也可以在 **⚙ 工具菜单** 中切换，您可以在其中读取生成的密钥。 | 端点 | 功能 | |---|---| | `POST /local-api/message` | 显示消息。采用字符代码矩阵，`{"characters": [[…]], "strategy": "…"}`，或 `{"text": "…"}`（扩展 — 真实 API 仅限矩阵，但大多数 HA 设置发送文本）。返回 **201**，如真实板卡 | | `GET /local-api/message` | 板卡为 `{"message": [[…]]}` — 矩阵封装如真实 API 返回，因此读取 `response["message"]` 的客户端无需修改 | | `POST /local-api/enablement` | Vestaboard 的密钥握手 — 仅当您设置 `COMPANION_VESTABOARD_ENABLEMENT_TOKEN` | 每个调用都需要 `X-Vestaboard-Local-Api-Key` 头部；该密钥仅保护这些路由。 硬编码真实板卡的客户端 **端口 7000** 可以通过发布 容器在其上 (`-p 7000:8000`) 满足要求 —— 没有第二个服务器。Home Assistant： ```yaml rest_command: splitflap_message: url: "http://companion-host:8000/local-api/message" method: POST headers: X-Vestaboard-Local-Api-Key: !secret splitflap_api_key content_type: "application/json" payload: '{"text": "{{ message }}"}' ``` **字符。** 代码遵循 Vestaboard 的 [表格](https://docs.vestaboard.com/docs/charactercodes/)：`0` 空白，`1–26` A–Z， `27–35` 1–9，`36` 0，标点符号，和 `63–69` 颜色芯片（`r o y g b p w`，紫色 → `p`）。两个是有损的：**黑色（70）→ 空白** 和 **填充（71）→ 白色**。 **几何形状：** 3 × 15 消息单元格对单元格；6 × 22 Flagship 消息被修剪 其空白填充并在您的墙壁上居中。**动画：** Vestaboard 的 `策略` 映射到过渡样式（`column` → `columns`，`edges-to-center` → `outside_in`， …）；`step_interval_ms` / `step_size` 被接受并被忽略。 ### MCP 服务器 打开此功能后，显示屏成为一组 **[MCP](https://modelcontextprotocol.io) 工具**，因此 LLM 客户端 —— Claude，代理， IDE —— 可以用文字驱动墙壁： *"将站会时间放在板上"*, *"现在显示什么？"*, *"显示巴黎天气 30 秒钟"*。 ```bash COMPANION_MCP=1 # 默认关闭 COMPANION_MCP_TOKEN= # 留空 -> 生成一次，与您的设置一起保存 ``` 将客户端指向 `http://<host>:8000/mcp`，并使用 `Authorization: Bearer <token>`。 令牌在 **⚙ 工具菜单** 中显示，也可以运行时切换服务器。 对于 [多个显示屏](#multiple-displays)，每个工具都带有可选的 `display` 参数，并且 `list_displays` 工具会枚举它们 —— 因此 *"厨房墙上有什么？"* 有效。省略它，您将获得 **默认** 显示屏，这是每个提示写入 多显示屏之前保持不变的显示屏。 | 工具 | 功能 | |---|---| | `get_display` | 翻页板上显示的内容，逐行；驱动它们的内容；以及在播放列表中，屏幕上正在运行的应用及其在旋转中的位置 | | `show_message` | 在板上显示文本，居中并自动换行。`seconds` 暂时显示，然后恢复到正在播放的内容 | | `clear_display` | 清空所有模块 | | `list_apps` / `run_app` | 已安装的应用（带有 `configurable` 标志），并运行一个 | | `get_app_settings` / `configure_app` | 读取和更改应用的设置（位置，跑马灯，…） | | `list_playlists` / `run_playlist` | 保存的播放列表及其运行顺序，并运行一个 | | `stop` | 停止正在运行的应用或播放列表 | | `list_styles` | `show_message` 接受的过渡样式 | 令牌仅保护 `/mcp` —— 它是此端点的凭证，而不是主机安全边界。 DNS 重新绑定保护故意关闭，因为伴侣通过其 LAN 给出的名称访问 （`homeassistant.local:8000`，IP 地址， 反向代理）；承载令牌是保护它的凭证， 它不是一个可以被恶意页面重放的 cookie。 --- ## 本地化 在 **全局设置** 的顶部设置 **语言**，**位置** 和 **时区**。适配的 应用带有 🌐 徽章（在瓷砖上，在库中，在播放列表选择器中）。 语言是那些字符适合模块的 Windows-1252 代码页： **英语（美国 / 英国 / 澳大利亚）** 加 法语，德语，西班牙语，意大利语，葡萄牙语， 荷兰语和其他西欧语言。 **语言控制**（适用于 🌐 应用）： - **单词** — 标签和状态文本被翻译（SUNRISE → 日出，GOLD → 金， 天气状况，月相，倒计时单位 …）。未翻译的单词会回落到 英语，因此不会出现任何问题。 - **日期顺序** — `JULY 9`（美国），`9 JULY`（英国 / 澳大利亚），`9 JUILLET`（法语），`9. JULI`（德语）， 通过 CLDR。 - **数字格式** — `1,234.50`（美国 / 英国）vs `1.234,50`（德语 / 西班牙语 / 意大利语 / 荷兰语 / 葡萄牙语）vs `1 234,50` （法语），用于价格，汇率和百分比。 - **时钟** — 英语为 12 小时带 AM/PM，其他语言为 24 小时。 - **字时钟和幸运语** — 真正按语言：字时钟构建每种语言的语法 （`HALB ELF` = 10:30 in 德语），幸运语应用提供英式和澳式版本。 **货币和节假日遵循位置，而不是语言** — 法语可以是法国（欧元）， 加拿大（加元）或瑞士（瑞士法郎），因此这些关键因素取决于配置的位置 （反向地理编码到一个国家，缓存）：汇率默认为您国家的 货币，公共节假日显示您国家的历法，细致到 **省 / 状态** （魁北克 ≠ 不列颠哥伦比亚），您语言中常见的那些。 **覆盖。** 每个 🌐 应用都有自己的 **语言** 选择器（空白 = 遵循全局），并且 每个与位置相关的应用都有一个 **位置** 覆盖 —— 每个应用 *和* 每个播放列表条目， 因此一个播放列表可以在法语中显示巴黎，在日语中显示东京。 构建本地化的应用？ **[编写应用](https://github.com/avandeputte/SplitFlapGateway/wiki/Writing-Apps)** 记录了注入的 `i18n`，`get_weather` 和 `get_location` 帮助程序。