08 极物科技 | DALI调光灯 - UDP 通讯协议规范

极物科技 | DALI调光灯 - UDP 通讯协议规范

前言

极物科技致力于智能控制系统及硬件研发，以"极物OS+多协议融合"打破生态壁垒。

一句话概述：本文提供极物主机 DALI 调光灯服务的完整 UDP 通讯协议规范，供需要进行二次开发或系统对接的技术伙伴参考。

本文聚焦于 极物主机 DALI 调光灯的 UDP 通讯协议规范，详细解析服务端口与保活机制、报文帧结构、控制报文格式（亮度/色温/场景）、地址机制及状态更新报文，为二次开发和第三方中控对接提供完整的协议参考。

1. 服务端口与连接说明

极物主机 DALI 调光服务提供 UDP 接口，双路 DALI 总线使用独立端口：

连接说明：

• 客户端通过 UDP 协议向主机对应端口发送 JSON 报文
• 一个端口支持多个客户端同时连接
• 服务地址：极物主机 IP（默认监听 0.0.0.0）

⚠️ 注意：DALI 2 总线默认处于关闭状态，需在 Web 配置中启用后，2010 端口才会提供服务。

2. 报文帧结构总览

所有控制报文遵循统一的 JSON 帧结构：

完整示例：

{
  "driver_data": {
    "address_num": "1",
    "address_type": "shortaddress",
    "cmd_name": "-   DIRECT ARC POWER CONTROL",
    "cmd_type": "normal",
    "dali_index": "1",
    "cmd_value": "254"
  },
  "frame_type": "request",
  "frame_qn": "112233",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

3. driver_data 字段说明

4. 保活报文

保活报文用于确认客户端与服务端的连接状态。服务端对每个客户端维护独立的保活计时，超过设定超时时间未收到该客户端的保活报文，将主动关闭该客户端连接。

发送格式：

{
  "frame_type": "keeplive"
}

返回格式（主机原样确认，并附加报文序列号与驱动标识）：

{
  "frame_type": "keeplive",
  "frame_qn": 1,
  "frame_driver": "light-dali"
}

收到相同的 frame_type: "keeplive" 即表示连接正常。

保活策略：

• 建议每 5 秒发送一次保活报文
• 客户端若在保活超时时间内未收到保活报文的返回值，应主动断开并重新建立连接
• 服务端支持多客户端连接，因此各客户端必须独立发送保活报文

5. 控制报文详解

5.1 亮度控制（DAPC）

控制灯具到指定亮度，亮度范围为 0~254（对应 0%~100%）。

单灯亮度控制：

{
  "driver_data": {
    "address_num": "1",
    "address_type": "shortaddress",
    "cmd_name": "-   DIRECT ARC POWER CONTROL",
    "cmd_type": "normal",
    "dali_index": "1",
    "cmd_value": "254"
  },
  "frame_type": "request",
  "frame_qn": "112233",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

分组亮度控制：

{
  "driver_data": {
    "address_num": "1",
    "address_type": "group",
    "cmd_name": "-   DIRECT ARC POWER CONTROL",
    "cmd_type": "normal",
    "dali_index": "1",
    "cmd_value": "127"
  },
  "frame_type": "request",
  "frame_qn": "112234",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

全局广播亮度控制：

{
  "driver_data": {
    "address_num": "1",
    "address_type": "broadcast",
    "cmd_name": "-   DIRECT ARC POWER CONTROL",
    "cmd_type": "normal",
    "dali_index": "1",
    "cmd_value": "254"
  },
  "frame_type": "request",
  "frame_qn": "112235",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

5.2 色温控制（DT8 扩展）

控制 DT8 双色温灯具的色温，范围 2000K~7000K。

{
  "driver_data": {
    "address_num": "1",
    "address_type": "broadcast",
    "cmd_name": "control current tc value",
    "cmd_type": "extend",
    "dali_index": "1",
    "cmd_value": "4000"
  },
  "frame_type": "request",
  "frame_qn": "112236",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

5.3 场景控制

调用灯具内部存储的场景（场景 0~15）。

指令名与场景对照表：

⚠️ 注意：场景指令的 cmd_value 字段无效，照抄即可。

示例 - 调用分组 1 的场景 0：

{
  "driver_data": {
    "address_num": "1",
    "address_type": "group",
    "cmd_name": "16  GO TO SCENE  0",
    "cmd_type": "normal",
    "dali_index": "1",
    "cmd_value": "100"
  },
  "frame_type": "request",
  "frame_qn": "112237",
  "frame_driver": "light-dali",
  "device_info": {
    "sn": "11111"
  },
  "frame_result": "ok"
}

5.4 基础控制指令

6. 地址机制

6.1 地址类型

6.2 地址规则

• 单灯（shortaddress）：对指定短地址的单个灯具进行控制
• 分组（group）：对指定分组内的所有灯具进行统一控制
• 广播（broadcast）：对当前 DALI 总线上的所有灯具进行控制

7. 状态更新报文

DALI 服务会主动向所有已连接的客户端推送灯具状态，报文格式如下：

{
  "frame_type": "update",
  "frame_qn": 274,
  "frame_driver": "light-dali",
  "driver_data": {
    "address_num": 1,
    "color": 3000,
    "brightness": 250,
    "dali_bus": 1,
    "online": 1,
    "device_type": 8,
    "cmd": "update_info",
    "address_type": "shortaddress"
  }
}

driver_data 字段说明：

更新策略：

1. 数据有变化时立即发送一次
2. 新客户端接入时发送一次所有灯具信息

分组/广播指令的亮度汇总规则：

• 分组（group）上报的 brightness 为该分组下所有灯中最亮的那盏灯的亮度值（取最亮值）
• 广播（broadcast）上报的 brightness 为该 DALI 总线下所有灯中最亮的那盏灯的亮度值

⚠️ 注意：分组/广播的亮度为汇总值（取最亮），便于快速判断分区/总线内是否还有灯亮着；若需获取具体某盏灯的状态，请订阅单灯（shortaddress）上报。

⚠️ 注意：控制类指令执行后无确认报文，请通过 update 推送或主动查询确认灯具实际执行结果。

8. UDP 通信可靠性建议

本服务对控制指令不返回确认报文（控制后可通过状态推送或主动查询确认执行结果）。由于 UDP 协议不保证报文可靠到达，建议第三方系统遵循以下策略：

1. 序列号管理：frame_qn 字段建议每次发送累加，用于报文去重与追踪
2. 控制确认：控制指令下发后，通过订阅状态更新报文或主动查询来确认灯具实际执行结果
3. 非阻塞接收：接收 socket 需设置超时，避免阻塞
4. 保活检测：定期发送保活报文，检测连接状态，断线后自动重连

9. 常用指令速查表

9.1 标准指令（normal）

9.2 扩展指令（extend）

10. 典型应用示例

10.1 控制灯具到 50% 亮度

• address_type：shortaddress
• address_num：1（灯具短地址）
• cmd_name：- DIRECT ARC POWER CONTROL
• cmd_value：127（约 50% 亮度）

10.2 设置整组灯具色温 4000K

• address_type：group
• address_num：1（分组地址）
• cmd_name：control current tc value
• cmd_value：4000

10.3 广播关闭所有灯具

• address_type：broadcast
• cmd_name：0 OFF

10.4 调用场景

• address_type：group
• address_num：1（分组地址）
• cmd_name：16 GO TO SCENE 0（场景 0）

11. 注意事项

1. 报文精确匹配：cmd_name 字段必须严格匹配指令名（含空格），否则无法识别
2. 地址唯一：单灯短地址 0~63 需唯一，避免通讯冲突
3. 广播地址：broadcast 类型的 address_num 字段被忽略
4. DALI 2 主动推送：DALI 2 服务默认关闭，需启用后才可接收状态推送
5. 客户端保活：所有客户端必须周期性发送保活报文，超过保活超时未发送的客户端将被服务端断开

12. 相关文档

• 《极物科技 | DALI调光灯 - 快速接入指南》
• 《极物科技 | DALI调光灯 - IEC 62386 底层协议解析》
• 《极物科技 | DALI调光灯 - DT8 双色温控制专题》
• 《极物科技 | DALI调光灯 - 功能接口与调试指南》
• 《极物科技 | DALI调光灯 - 设备发现与地址分配机制》
• 《极物科技 | DALI调光灯 - 状态上报与监控机制》
• 《极物科技 | DALI调光灯 - 工程实施与运维指南》

关于极物科技（ZEEWO）

极物科技（Zeewo）致力于为用户提供智能控制系统及硬件产品。我们以总线系统为技术底座，以**“稳定、可靠、快速响应”**为产品底线，是国内少有的拥有 KNX、DALI 全套软硬件自主研发能力的厂商之一。

我们的核心能力：

• 系统架构：自研极物 OS，支持多协议无界融合（KNX/DALI/CAN/RS485/IP）。
• 核心硬件：带双路 DALI 的 KNX 主机、超薄全金属定制面板、各类智选传感器及网关。
• 生态互联：深度融入 Apple HomeKit、Matter、小度、HomeAssistant 及纯血鸿蒙生态。
• 调试交付：独家支持 ETS 导出 XML 直接导入进行 APP 免编程调试，支持远程 WEB 运维。

我们的市场覆盖：
服务网点已覆盖全国核心城市（含长三角、珠三角、成渝等），并以高品质的方案深耕家居生活、酒店民宿、企业办公、疗愈康养、餐馆会所等多个细分领域。

(如果您在开发或落地中遇到技术问题，欢迎通过官网或后台私信与我交流探讨)