Olink 文档

典型案例：灯（Light）的完整映射 ​

本节以灯为例，展示从 MIoT 设备属性到最终 HAP 特征的完整映射链路。

1. MIoT 侧原始数据 ​

米家灯的 MIoT 服务 URN 为 urn:miot-spec-v2:service:light:00007808:zhimi-ma2:1，提供以下属性：

MIoT 属性类型说明
onbool开关
brightnessuint8 (1-100)亮度
color-temperatureuint32 (Kelvin)色温
coloruint32RGB 颜色（由 hue + saturation 组合）

2. Input 层：MIoT → Schema ​

文件：mapping/system/inputs/mijia/device/light.toml

toml
device_type = "light"

# 灯主服务配置
[services.light]
# 读取策略：自动读取，600秒过期，20%抖动比例
read = { strategy = "auto", stale_threshold = 600, jitter_ratio = 0.2 }

# 灯主服务属性映射
[services.light.attributes]
# 电源状态：从灯光服务的开关属性读取
power-state = { source = "on", service = "light"}
# 亮度：从灯光服务的亮度属性读取
brightness = { source = "brightness", service = "light"}
# 色温：从灯光服务的色温属性读取
color-temperature = { source = "color-temperature", service = "light"}

# 色相：从颜色属性读取，带枚举映射转换
# 映射：0→2，1→1，2→0
hue = { source = "color", service = "light", transform = { kind = "enum_map", to_map = [
    { from = 0, to = 2 },
    { from = 1, to = 1 },
    { from = 2, to = 0 },
] } }
# 饱和度：从颜色属性读取，带枚举映射转换
saturation = { source = "color", service = "light", transform = { kind = "enum_map", to_map = [
    { from = 0, to = 2 },
    { from = 1, to = 1 },
    { from = 2, to = 0 },
] } }

# 色彩RGB：虚拟属性，通过 hue + saturation 使用原生合并策略生成 color-rgb 值
color-rgb = { type = "combine", inputs = ["hue", "saturation"], strategy = { type = "native", kind = "color_hs" } }

映射说明：

  • power-state、brightness、color-temperature 均为 1:1 简单映射：属性 key 是目标 schema 属性名，source 是 MIoT 源属性名
  • hue 和 saturation 从同一个 MIoT color 属性读取，通过 enum_map 转换枚举值
  • color-rgb 是虚拟属性（type = "combine"），通过 color_hs 合并器将 hue + saturation 合成为 color-rgb

3. Schema 层：属性与服务定义 ​

服务定义 ​

文件：mapping/system/schemas/services/light.toml

toml
[service]
id = "light"
name = "灯光控制"
required = ["power-state"]
optional = ["brightness", "color-temperature", "hue", "saturation", "color-rgb"]

属性定义 ​

属性格式范围访问HAP 映射
power-statebool—r/w/nPowerState → Lightbulb
brightnessuint80-100%r/w/nBrightness → Lightbulb
color-temperatureuint322000-6500Kr/w/nColorTemperature → Lightbulb
huefloat0-360r/w/nHue → Lightbulb
saturationfloat0-100r/w/nSaturation → Lightbulb
color-rgbuint32—r/w/n—

设备定义 ​

文件：mapping/system/schemas/devices/light.toml

toml
[device]
id = "light"
name = "灯"
category = "lightbulb"
required = ["light"]
optional = []

4. Output 层：Schema → HAP ​

文件：mapping/system/outputs/hap/mapping/light.toml

toml
schema_id = "light"

[[services]]
primary = true
hap_service = "Lightbulb"
schema_service = "light"

[[services.characteristics]]
hap_type = "PowerState"
schema_attr = "power-state"

[[services.characteristics]]
hap_type = "Brightness"
schema_attr = "brightness"
optional = true

[[services.characteristics]]
hap_type = "ColorTemperature"
schema_attr = "color-temperature"
optional = true
min = 140
max = 500
transform = { kind = "reciprocal", factor = 1000000 }

映射说明：

  • Lightbulb 是 HAP 主服务（primary = true）
  • PowerState 是必需特征，对应 schema 的 power-state
  • Brightness 和 ColorTemperature 是可选特征
  • ColorTemperature 做了 reciprocal 倒数转换：HAP 使用 mired（140-500），schema 使用 Kelvin（2000-6500），factor = 1000000（即 mired = 1000000 / kelvin）

5. 完整数据流 ​

MIoT 属性                  Schema 属性              HAP 特征
─────────────────     ───────────────────     ─────────────────
on (bool)          →   power-state (bool)   →  PowerState (0/1)
brightness (1-100) →   brightness (0-100)   →  Brightness (0-100)
color-temperature  →   color-temperature    →  ColorTemperature
  (2000-6500K)          (2000-6500K)            (140-500 mired)
color (hue+saturation) → hue (0-360)         →  Hue (0-360)
                      → saturation (0-100)   →  Saturation (0-100)
                      → color-rgb (uint32)

读路径（MIoT → HAP）： MIoT 上报 on=true → Input 层映射为 power-state=true → Output 层暴露为 HAP 的 PowerState=1

写路径（HAP → MIoT）： HAP 写入 Brightness=50 → Output 层不做转换（无 transform）→ Input 层不做转换 → MIoT 的 brightness=50