devices.toml

设备清单。每台设备一个 [[device]] 块，公共字段在下面， 私有参数取决于 adapter 的取值，见左侧「设备协议」下各页。

[[device]]
name = "plug_bedroom"
adapter = "miot"
# 以下都是 miot 的私有参数
ip = "192.168.52.60"
token = "00112233445566778899aabbccddeeff"
model = "cuco.plug.v3"

公共字段

字段	类型	默认	说明
adapter*	string	—	用哪个 adapter 驱动这台设备。它同时决定了这一段里还能写哪些私有参数 (那些参数走 params, 字段表见各 adapter 页)。 认得的取值: miot(小米 / 米家的 IP 设备)、reolink(摄像头 / 门铃)、 roborock(扫地机)、mibeacon(BLE 广播设备; 只在 Linux 上、且二进制编进了 mibeacon feature 时才注册)、fake(虚拟设备, 给 demo 和测试用)。 写别的值在 check 阶段就报 unknown adapter, 不会留到运行期。
class	object	可省略	逐实体覆盖 adapter 推断出的语义类, 键是能力名(实体 id 的点号之后那半)。 [[device]] name = "plug_bedroom" adapter = "miot" model = "cuco.plug.v3" [device.class] switch_s2_on_p1 = "light" # 这个插座接的是台灯 必须是显式字段, 不能落进 adapter 私有参数 —— 各 adapter 的参数结构体带 deny_unknown_fields(如 MiotDevice), 多出一个 class 键会让所有 miot 设备解析失败。
name*	string	—	这台设备的名字, 同时是它所有实体 id 的前缀(<name>.<能力名>)。 必须 snake_case(首字符 a-z, 其余只能是 a-z0-9_), 否则 check 报 device name ... must be snake_case; 跨整个 devices.toml 不能重名。 规则的 entity、bridge 的 export、[storage] 的 record / exclude 全都按这个 前缀来写, 所以改名等于要把引用它的每一处一起改 —— 先想好再定。
retain	string	可省略	这台设备的历史保留策略。只有两种合法写法: 不写(状态历史跟着 [storage].retention_days 定期被清), 或者在这台设备的 [[device]] 段里写一行 retain = "forever"(它的状态历史永不清)。 写第三种值("weekly" 之类)是 check 期硬错误 (retain must be "forever" or absent), 不会被当成「随便什么非空值都算开启」。 两个边界: 豁免的粒度是整台设备(不能只保留其中一个实体), 而且只豁免状态 历史 —— 规则轨迹一律按 cutoff 清掉, 不看这个字段。给温湿度计这类要留长期曲线的 设备用; 给高频上报的设备写 forever, 库就只会一直涨。

语义类（[device.class]）

adapter 会自动推导每个实体的语义类，北向协议（HomeKit 等）靠它决定把实体 映射成什么。推导不对时可以逐实体覆盖——键是能力名，也就是实体 id 点号之后那半：

[[device]]
name = "plug_bedroom"
adapter = "miot"
ip = "192.168.52.60"
token = "00112233445566778899aabbccddeeff"
model = "cuco.plug.v3"

[device.class]
switch_s2_on_p1 = "light"   # 这个插座接的是台灯

这是一张封闭词汇表，全部取值：

取值	含义
outlet	智能插座的主开关。
light	灯。插座接了台灯、或想把指示灯暴露出去时, 由用户在 devices.toml 里标。
fan	风扇电源。
switch	认不出具体形态的通用开关(电饭煲、养生壶这类)。兜底项 —— 能标得更具体就 别用它, bridge 只能把它映射成最朴素的开关。
speed	转速/风速档位。设备原生刻度(1-4 档、1-100 无级都算), 不是百分比 —— 换算成协议刻度是 bridge 的事, 取值域见 [crate::domain::ValueDomain]。
swing	摆动开关(风扇摆头、空调扫风)。
lock	物理按键锁(童锁)。
temperature	温度。规范单位 摄氏度。
humidity	相对湿度。规范单位 百分比(0-100)。
battery	电量。规范单位 百分比(0-100)。
power	瞬时功率。规范单位 瓦特。
weight	体重。规范单位 千克。
button	按钮/门铃被按下。