企业官网建设流程全解析

• 智能家居
• 物联网

CEC Scanner 是 Home Assistant 官方 add-ons 仓库中的一款轻量工具型应用（在最新版本中已更名为 "app"，即应用），其唯一职责是扫描 HDMI 总线上的 CEC（Consumer Electronics Control，消费电子控制）设备并输出它们的物理地址与逻辑地址。本指南将基于 cec_scan/DOCS.md 展开，完整覆盖安装、零配置使用、清单参数解读，并结合仓库源码深入解析其底层实现（libCEC 编译构建与cec-client扫描流程），帮助你在几分钟内定位家中每一台 CEC 设备的地址，为后续的 CEC 自动化与设备联动排查打好基础。

一、CEC Scanner 是什么：核心功能与适用场景

HDMI 总线上的 CEC 协议允许设备之间通过一条低速通道互相控制，例如电视遥控器直接控制功放音量、机顶盒开关等。要调试这类联动，第一步往往是搞清楚"总线上的设备都对应什么地址"。CEC Scanner 正是为此设计的：

• 扫描并发现所有挂接在 HDMI 总线上的 CEC 设备；
• 输出每台设备的逻辑地址（Logical Address）与物理地址（Physical Address）；
• 帮助用户找到特定设备的 CEC 地址，供 Home Assistant 中的hdmi_cec集成或脚本使用。

从 README.md 的描述看，它的定位非常纯粹："Scan & discover HDMI CEC devices and their addresses"（扫描并发现 HDMI CEC 设备及其地址），并且"对于查找设备的 CEC 地址非常有用"。它不是一个常驻服务型插件，而是一次性的诊断工具：启动后执行一次扫描，输出结果后即结束。

二、安装 CEC Scanner

在最新版的 Home Assistant 中，此类组件已从 "Add-ons"（插件）更名为 "Apps"（应用），安装路径也随之调整。按照 cec_scan/DOCS.md 的官方步骤：

1. 在 Home Assistant 前端进入设置（Settings）>应用（Apps）>安装应用（Install app）；
2. 在应用列表中查找"CEC Scanner"并点击进入；
3. 点击"INSTALL"（安装）按钮，等待安装完成。

安装前建议确认你的设备架构受支持。根据 cec_scan/config.yaml，当前版本（4.0）仅支持aarch64与amd64两种架构；在 4.0 版本中官方已移除对armhf、armv7、i386的支持（详见 CHANGELOG.md）。如果你的 Home Assistant 运行在 Raspberry Pi 4/5（64 位系统）、x86_64 主机或等效架构上，即可直接安装。

三、使用：零配置、开箱即用

CEC Scanner 是仓库中极少数"没有任何配置项"的应用之一。cec_scan/DOCS.md 明确说明：

This app has no configuration and runs out of the box.（本应用无任何配置，开箱即用。）

使用流程同样简单：

1. 启动应用（Start the app）；
2. 查看应用日志输出（Check the app log output to see the result），扫描结果会直接打印在日志中。

由于它的启动模式是"运行一次即退出"（见下文清单解析），你不需要保持它常驻运行，也不需要配置任何端口、凭据或选项——安装完成后，只需启动并读取日志即可得到完整的 CEC 设备清单。

四、为什么"没有配置"：应用清单（config.yaml）逐项解析

"无配置"并非偷懒，而是通过应用清单文件 cec_scan/config.yaml 的字段设计明确表达的。该文件是 add-on/app 清单（Supervisor 读取的核心元数据），全文如下：

version: "4.0" slug: cec_scan name: CEC Scanner url: https://github.com/home-assistant/addons/tree/master/cec_scan arch: - aarch64 - amd64 boot: manual description: Scan for HDMI CEC devices image: homeassistant/{arch}-addon-cec_scan options: {} schema: {} startup: once video: true init: false

各字段的含义与影响：

其中video: true是关键：HDMI CEC 硬件（如树莓派的 CEC 内核驱动）通常以视频类设备的形式暴露在系统中，应用需要访问/dev/video*才能与 CEC 总线通信。这一点在 CHANGELOG.md 的 2.4 版本记录中也有印证："Use newvideofeature of Supervisor 199"，即从 2.4 版本起开始使用 Supervisor 199 提供的 video 特性来申请设备权限。

五、底层实现剖析：从编译 libCEC 到一次scan

5.1 镜像构建：从源码编译 libCEC

应用本身不含业务代码，其"扫描能力"全部来自开源库libCEC（Pulse-Eight/libcec）。镜像构建过程在 Dockerfile 中清晰可见：

# Build libcec for HDMI-CEC ARG LIBCEC_VERSION WORKDIR /usr/src RUN \ apk add --no-cache \ eudev-libs \ p8-platform \ && apk add --no-cache --virtual .build-dependencies \ build-base \ cmake \ eudev-dev \ git \ p8-platform-dev \ swig \ linux-headers \ && git clone --depth 1 -b libcec-${LIBCEC_VERSION} \ "https://github.com/Pulse-Eight/libcec" libcec \ && mkdir -p libcec/build \ && cd libcec/build \ && cmake \ -DCMAKE_INSTALL_PREFIX:PATH=/usr/local \ -DHAVE_LINUX_API=1 \ .. \ && make -j$(nproc) \ && make install \ && apk del --no-cache .build-dependencies \ && rm -rf /usr/src/*

关键点：

• 基础镜像：基于BUILD_FROM（由 Home Assistant 构建系统注入的 Alpine Linux 基础镜像）构建，运行时只保留eudev-libs与p8-platform两个动态库依赖；
• 编译依赖：通过build-base、cmake、eudev-dev、p8-platform-dev、swig、linux-headers等构建依赖完成编译，编译结束后用apk del全部清理，保证最终镜像体积精简；
• C 语言适配：cmake阶段显式指定-DHAVE_LINUX_API=1，强制启用 libCEC 的 Linux 原生 API 适配层。结合 CHANGELOG.md 3.0 版本记录 "Using the Upstream Linux support only"（仅使用上游 Linux 支持），可以推断当前版本不再依赖平台厂商的私有 CEC 库，而统一走 Linux 内核原生 CEC 接口，从而在 aarch64/amd64 上获得一致的扫描行为；
• 版本管理：ARG LIBCEC_VERSION由构建系统传入，当前 4.0 版本对应的 libCEC 版本为7.1.1（见 CHANGELOG.md 4.0 记录 "Update libCEC to 7.1.1"）。

5.2 扫描执行：run 脚本中的一行命令

应用真正的"扫描逻辑"只有一行，位于服务启动脚本 rootfs/etc/services.d/cec-scan/run：

#!/usr/bin/with-contenv bashio # Start CEC scan service bashio::log.info "Starting CEC client scan..." echo scan | cec-client -s -d 1

解析这行命令：

• echo scan |：向cec-client的标准输入写入scan指令，触发一次完整的 CEC 总线扫描；
• cec-client：libCEC 自带的命令行客户端工具，负责与 CEC 适配器通信；
• -s：从命令语义看，表示扫描完成后即退出（静默模式），与startup: once的"运行一次"设计完全吻合；
• -d 1：将调试日志级别设为 1，减少无关输出，让设备清单更容易从日志中辨认。

扫描产生的设备地址列表（逻辑地址、物理地址以及设备厂商与型号信息）会全部输出到应用日志中，这正是 DOCS.md 要求"查看日志输出"的原因——日志就是该应用唯一的输出界面。

5.3 生命周期管理：S6 监督树与自动收尾

容器内采用 s6-overlay 监督体系（3.0 版本起引入，见 CHANGELOG.md 记录 "Using s6-overlay style"）。当扫描命令执行完毕后，rootfs/etc/services.d/cec-scan/finish 脚本会接管收尾工作：

#!/usr/bin/env bashio # Take down the S6 supervision tree when service is done /run/s6/basedir/bin/halt

它显式调用 s6 的halt指令关闭整个监督树，确保应用不会"扫描完还空转"，从而配合startup: once实现"启动 → 扫描 → 输出 → 退出"的完整一次性生命周期。

六、架构支持与版本演进

通过 CHANGELOG.md 可以完整追溯 CEC Scanner 的能力演进，也能帮助你判断当前版本的行为预期：

• 1.0：首次支持 Raspberry Pi 64 位，libCEC 升级到 4.0.3；
• 2.0：改用 Alpine 原生的树莓派 64 位库；
• 2.1：补充 README；精简 armhf/aarch64 镜像体积；改善 armv7 支持；
• 2.2：修复树莓派上偶发的 "autodetect FAILED" 问题（由 2.1 引入），升级到 Alpine 3.11；
• 2.3：新增对 Meson AOCEC、EXYNOS 以及 Linux 原生 CEC 的支持；
• 2.4：使用 Supervisor 199 的video特性申请视频设备访问权限；
• 3.0：只保留上游 Linux 支持；全面切换为 s6-overlay 风格；升级到 Alpine 3.14；
• 4.0：移除 armhf、armv7、i386 架构支持；升级到 Alpine 3.23；libCEC 升级到 7.1.1。

从演进脉络可以推断，当前版本聚焦于 aarch64/amd64 两类现代架构，并通过 Linux 内核原生 CEC 接口获得跨平台一致的扫描行为；如果你仍在使用 32 位设备，则需要选择 3.0 及更早版本（注意早期版本的 libCEC 与 Alpine 版本较旧）。

七、常见问题与支持渠道

扫描不到任何设备？首先确认 HDMI 线缆与设备之间的 CEC 已启用（多数电视需在设置中开启 HDMI-CEC 功能），并确认运行环境满足video: true对应的设备访问权限；其次确认设备架构在支持列表内。

如何再次扫描？由于startup: once设计，每次扫描都需要手动重新启动应用，这是预期行为，并非异常。

获取帮助：按照 cec_scan/DOCS.md 的说明，你可以在 Home Assistant 官方的 Discord 聊天社区、Home Assistant 社区论坛，以及 Reddit 的 r/homeassistant 子版块提问；如果确认是应用本身的缺陷，可以在项目仓库中提交 issue，附上完整的应用日志与硬件信息，便于维护者定位问题。

结语

CEC Scanner 用一个极简的"零配置 + 运行一次 + 看日志"模型，把 HDMI CEC 设备发现这件事做到了极致简单：安装、启动、读日志三步即可拿到完整的 CEC 设备地址清单。通过阅读 Dockerfile 与 run 脚本，你可以清楚地看到它背后是 libCEC 7.1.1 的 Linux 原生支持与一行echo scan | cec-client -s -d 1的精简实现——这正是 Home Assistant 官方 add-ons 仓库"小工具解决大问题"风格的典型代表。

• 智能家居
• 物联网