esphome（Native API）

adapter = "esphome" 直接连接 ESPHome 节点的 Native API：TCP 6053、Noise PSK 加密、实体枚举、状态订阅和命令下发。它不需要 MQTT broker，也不依赖 Home Assistant。

为什么实体仍要写进配置

rha 的 describe() 必须离线、无副作用：rha check 不能为了判断规则引用是否存在而先 访问硬件。因此配置声明稳定的 RHA 能力名和 ESPHome 的 (platform, object_id, device_id)， 连接后再用 ListEntities 找到这次启动真正使用的协议 key。

这样 ESPHome 重新编译后内部 key 可以变化，而 RHA 实体 id 不变；固件删除实体、改变 number 范围或重排 select 选项时，连接会明确失败，不会静默改变规则和 bridge 的导出集合。 未声明的 ESPHome 实体会被忽略。

这里的 object_id 是 Native API 返回的字段，不是 ESPHome YAML 里的组件 id:。

CT30W 示例

下列 object_id、number 范围与 select 选项只是结构示例，必须与这台 CT30W 当前固件实际 暴露的 descriptor 一致。

[[device]]
name = "ct30w"
adapter = "esphome"
host = "192.168.50.197"
encryption_key = "${RHA_ESPHOME_CT30W_KEY}"
# password = "${RHA_ESPHOME_CT30W_PASSWORD}" # 仅 ESPHome 2025.12 及更早固件
expected_name = "ct30w"
manufacturer = "Orvibo"
model = "CT30W"

  [[device.entity]]
  name = "power"
  platform = "switch"
  object_id = "power"
  class = "switch"

  [[device.entity]]
  name = "target_temperature"
  platform = "number"
  object_id = "temperature"
  unit = "°C"
  min = 16.0
  max = 30.0
  step = 1.0

  [[device.entity]]
  name = "mode"
  platform = "select"
  object_id = "mode"
  options = ["auto", "cool", "heat", "fan_only", "dry"]

  [[device.entity]]
  name = "timed_off"
  platform = "time"
  object_id = "timed_off"

密钥应放在服务环境里，不要提交进仓库：

export RHA_ESPHOME_CT30W_KEY='<api.encryption.key 的 base64 文本>'
rha --config /etc/rha check
rha --config /etc/rha serve

控制：

rha --config /etc/rha set ct30w.power on
rha --config /etc/rha set ct30w.target_temperature 24
rha --config /etc/rha set ct30w.mode cool
rha --config /etc/rha set ct30w.timed_off 01:30:00

当前支持的平台

ESPHome platform	RHA 类型	读	写	必要附加配置
binary_sensor	bool sensor	是	否	—
sensor	float sensor	是	否	—
text_sensor	string sensor	是	否	—
switch	bool switch	是	是	—
number	float switch	是	是	min / max / step
select	string switch	是	是	有序 options
time	string switch	是	是	HH:MM[:SS]
datetime	string switch	是	是	RFC 3339，1970–2106

number 命令会校验范围与步长；select 只接受声明的选项。连接时还会把配置与设备返回的 能力描述逐项比对。

运行时行为

每台 ESPHome node 都是独立的受监督任务：TCP + Noise 握手 → Hello →（API 1.13 及更早 版本执行旧式密码认证）→ DeviceInfo → ListEntities → SubscribeStates。完成后实体才标为 available；断线、身份不符或 descriptor 变化时，该节点退出并由设备级 supervisor 标 unavailable、指数退避重连，其他设备不受影响。

Native API 命令没有单独的执行确认。socket 写入成功后命令返回成功，真实状态随后由设备 的状态推送回填；optimistic 实体也走同一条订阅路径。

当前边界

只支持加密 Native API 和静态主机配置；暂不支持 plaintext、mDNS 自动发现、OTA、日志流、 Bluetooth proxy、voice assistant，以及 button、light、fan、cover、climate、lock、 valve、media_player、update 等其他平台。若固件把 CT30W 暴露为单一 climate entity， 本版本不会把它拆成 RHA 实体。

字段

设备级：

字段	类型	默认	说明
connect_timeout_secs	integer	可省略	TCP + Noise + API 初始化的超时秒数，默认 10。
encryption_key*	string Secret	—	ESPHome api.encryption.key 的 base64 文本。建议用 ${ENV} 插值。 敏感值。建议写成 ${ENV} 由环境变量插值, 不要把明文提交进配置文件。该值绝不进日志与 trace。
entity	array	可省略	离线声明的实体清单；运行时按 (platform, object_id, device_id) 对接真实 key。
expected_mac	string	可省略	可选身份校验：设备 MAC 必须一致，大小写与 :/- 不影响比较。
expected_name	string	可省略	可选身份校验：Noise ServerHello、HelloResponse 与 DeviceInfo 中出现的节点名必须一致。
host*	string	—	ESPHome 节点的主机名或 IP，不带协议前缀。
keepalive_secs	integer	可省略	空闲保活间隔秒数，默认 30；连续三个周期没有任何入站帧就重连。
manufacturer	string	可省略	北向协议显示用厂商。
model	string	可省略	北向协议显示用型号。
password	string Secret	可省略	ESPHome 2025.12 及更早版本的旧 API 密码；2026.1 起已移除。 敏感值。建议写成 ${ENV} 由环境变量插值, 不要把明文提交进配置文件。该值绝不进日志与 trace。
port	integer ≤ 65535	可省略	Native API 端口，默认 6053。

每个 [[device.entity]]：

字段	类型	默认	说明
class	string DeviceClass	可省略	RHA 跨生态语义类。 一个实体承载的语义。 刻意窄 —— 封闭枚举加一项就要动 core 和所有 bridge, 宁可少。刻意不照抄 HomeKit 的 Service 列表: DeviceClass::Power 与 DeviceClass::Weight 在 HAP 里没有 标准对应, 照抄的话这两个语义根本进不来, 接 MQTT/HA 时又得重新发明。内核词汇表与 任何单一协议的对象模型必须分开。
device_id	integer	0	一个 ESPHome node 内有多个逻辑 device 时用于消歧；缺省 0。
max	number	可省略	number 的最大值。
min	number	可省略	number 的最小值，必须与 max/step 一起写。
name*	string	—	RHA 能力名，最终实体 id 是 <device>.<name>。
object_id*	string	—	Native API ListEntities 返回的 object_id（不是 ESPHome YAML 的组件 id）。
options	array	[]	select 的合法选项，顺序必须与 ESPHome 一致。
platform*	string Platform	—	ESPHome 平台类型。
step	number	可省略	number 的步长。
unit	string	可省略	仅用于显示。

platform 的取值：

取值	含义
binary_sensor	—
sensor	—
text_sensor	—
switch	—
number	—
select	—
time	—
datetime	—