KNX 对接说明
适用型号 M100A · M100B · M100K 固件要求 V3.2.6 及以上 文档版本 1.2（2025-08-03）
米悦背景音乐主机可接入 KNX 总线，由 KNX 面板直接控制播放、音量、静音、 音源与播放模式，并向总线回报播放状态与曲目信息。
1. 接入方式
按主机型号选择接入方式：
| 方式 | 支持型号 | 说明 |
|---|---|---|
| KNX 独立串口板 | 仅 M100K | 直连 KNX 总线，最稳定 |
| KNX 串口板（485 接口） | M100K | 可配合部分 KNX–485 网关使用 |
| KNXnet/IP 隧道 | M100A · M100B | 会占用路由器一个隧道槽 |
| KNXnet/IP Routing | M100A · M100B | UDP 组播，不占隧道槽；需给主机指定一个未被占用的 KNX 物理地址 |
注意 Routing 走 UDP 组播，丢包率高于 TCP 隧道。对稳定性要求高的项目优先选隧道方式。
2. 组地址
可直接导入示例组地址文件 group-address-example.xml（ETS 中导入），
或参考 default-group-addresses.xml 手工建立。
2.1 控制组地址（KNX → 主机）
| 功能 | 默认组地址 | 数据格式 | 取值 |
|---|---|---|---|
| 播放 | 13/0/0 | 1 bit | 0 暂停 1 播放 |
| 音量步进调节 | 13/0/1 | 4 bit | 见下方调光式音量表 |
| 音量增减 | 13/0/2 | 1 bit | 0 降低 1 增加 |
| 静音开关 | 13/0/3 | 1 bit | 0 取消静音 1 静音 |
| 绝对音量 | 13/0/4 | 1 byte | 00–FF |
| 切换曲目 | 13/0/5 | 1 bit | 0 上一首 1 下一首 |
| 播放模式 | 13/0/6 | 1 byte | 0 列表循环 1 单曲循环 2 随机 3 顺序 |
| SPDIF | 13/0/8 | 1 bit | 0 关 1 开 |
| 蓝牙 | 13/0/9 | 1 bit | 0 关 1 开（仅 M100B 有蓝牙） |
调光式音量步进
13/0/1 使用 KNX 标准调光数据类型（4 bit）：
| 值 | 动作 | 值 | 动作 |
|---|---|---|---|
0 | 停止调节 | 8 | 停止调节 |
1 | 调低 100% | 9 | 调高 100% |
2 | 调低 50% | 10 | 调高 50% |
3 | 调低 25% | 11 | 调高 25% |
4 | 调低 12.5% | 12 | 调高 12.5% |
5 | 调低 6.25% | 13 | 调高 6.25% |
6 | 调低 3.125% | 14 | 调高 3.125% |
7 | 调低 1.5625% | 15 | 调高 1.5625% |
2.2 状态回报组地址（主机 → KNX）
| 功能 | 默认组地址 | 数据格式 | 取值 |
|---|---|---|---|
| 播放状态 | 13/1/0 | 1 bit | 0 暂停 1 播放 |
| 静音状态 | 13/1/3 | 1 bit | 0 未静音 1 静音 |
| 当前音量 | 13/1/4 | 1 byte | 00–FF |
| 播放模式 | 13/1/6 | 1 byte | 1 单曲循环 2 随机 3 顺序 4 列表循环 |
| SPDIF 状态 | 13/1/8 | 1 bit | 0 关 1 开 |
| 蓝牙状态 | 13/1/9 | 1 bit | 0 关 1 开（仅 M100B） |
| 歌手 | 13/1/11 | 14 byte | 建好组地址后拖入接收对象 |
| 专辑 | 13/1/12 | 14 byte | 建好组地址后拖入接收对象 |
| 曲名 | 13/1/13 | 14 byte | 建好组地址后拖入接收对象 |
播放模式取值不对称 控制用
0–3，回报用1–4，两侧含义也不同。 做状态联动时需要按上表分别映射，不能直接透传。
2.3 预留但未实现
以下地址已在协议中预留，当前固件尚未实现功能：
| 功能 | 组地址 | 格式 |
|---|---|---|
| 从属（从机）模式 | 13/0/7 / 13/1/7 | 1 bit |
| 同步播放 | 无默认地址 | 14 byte |
| 时间 | 无默认地址 | 3 byte |
| 日期 | 无默认地址 | 3 byte |
3. 修改组地址
组地址可在 APP 内修改，无需重新烧录固件：
米悦 APP（iOS / Android / 鸿蒙）→ 右下角「设置」→「开发者选项」→「KNX 配置」
也可以用 KNX 组地址配置工具（Android APK）批量下发。
4. 场景触发
在米悦 APP 的**「功能」→「情景」**中创建情景，触发码选择 KNX。
支持的触发类型：
- 1 byte 场景
- 1 bit 开关
其它类型暂不支持。
场景号偏移 KNX 的场景号与实际收发的 1 byte 数据相差 1。 米悦程序使用的是 1 byte 实际数据，不是场景号，配置时请自行换算。
4.1 场景可编排的内容
- 自定义时间播报、文字播报、天气预报的顺序，各项可单独开关
- 自定义曲目播放
4.2 TTS 播放结束后的行为
语音播报结束后有四种模式：
| 模式 | 行为 |
|---|---|
| 保持原状 | 播报前在播放就继续播放，原来暂停就保持暂停 |
| 强制暂停 | 无论播报前状态如何，播报结束一律暂停 |
| 继续播放 | 无论播报前状态如何，播报结束继续播放当前队列；队列为空则播放本地存储的音乐 |
| 替换队列 | 播报结束后用指定的歌单、电台或榜单替换播放队列 |
4.3 感应延时
设置场景的持续时长，到时自动停止。
- 延时期间再次触发不会响应，但会把延时顺延
- 设为
00表示无延时，可连续触发