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

阿钱真强道2026-08-24 8:36

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

前言

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

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

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

1. 服务端口与连接说明

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

服务 端口号 说明
DALI 1 接口 2000 对应 DALI 1 总线
DALI 2 接口 2010 对应 DALI 2 总线

连接说明：

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

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

2. 报文帧结构总览

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

字段 类型 必选 说明
frame_type String 是 报文类型（request/keeplive/update）
frame_qn String 是 报文序列号，建议累加
frame_driver String 是 驱动标识，固定为 light-dali
driver_data Object 是 实际控制参数，由 DALI 模块定义
device_info Object 否 发送方设备信息（如 sn）
frame_result String 是 报文结果，固定为 ok

完整示例：

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 字段说明

字段 类型 说明
address_num String 地址编号（根据地址类型取值，见"地址机制"）
address_type String 地址类型：shortaddress（单灯）/ group（分组）/ broadcast（广播）
cmd_name String 指令名称（见"控制指令速查表"）
cmd_type String 指令类型：normal（标准指令）/ extend（扩展指令）
dali_index String 总线编号：1（DALI 1）/ 2（DALI 2）
cmd_value String 指令参数值（亮度/色温/保留值等）

4. 保活报文

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

发送格式：

json 复制代码 
{
  "frame_type": "keeplive"
}

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

json 复制代码 
{
  "frame_type": "keeplive",
  "frame_qn": 1,
  "frame_driver": "light-dali"
}

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

保活策略：

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

5. 控制报文详解

5.1 亮度控制（DAPC）

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

单灯亮度控制：

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"
}

分组亮度控制：

json 复制代码 
{
  "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"
}

全局广播亮度控制：

json 复制代码 
{
  "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。

json 复制代码 
{
  "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）。

指令名与场景对照表：

指令名 对应场景
16 GO TO SCENE 0 场景 0
17 GO TO SCENE 1 场景 1
18 GO TO SCENE 2 场景 2
... ...
31 GO TO SCENE 15 场景 15

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

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

json 复制代码 
{
  "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 基础控制指令

指令名 功能 cmd_type
0 OFF 关灯 normal
5 RECALL MAX LEVEL 开灯（最大亮度） normal
6 RECALL MIN LEVEL 调至最小亮度 normal
1 UP 调亮 normal
2 DOWN 调暗 normal
3 STEP UP 步进调亮 normal
4 STEP DOWN 步进调暗 normal

6. 地址机制

6.1 地址类型

address_type 含义 address_num 范围
shortaddress 单灯短地址 0 ~ 63
group 分组地址 0 ~ 15
broadcast 全局广播 0（忽略）

6.2 地址规则

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

7. 状态更新报文

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

json 复制代码 
{
  "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 字段说明：

字段 类型 说明
address_num Number 灯具地址
address_type String 地址类型（shortaddress/group/broadcast）
color Number 当前色温（K），仅 DT8 单灯上报
brightness Number 当前亮度（0~254）
dali_bus Number 总线编号（1 或 2）
online Number 在线状态（1=在线，0=离线），仅单灯上报
device_type Number 设备报告的类型/版本号（来自 QUERY VERSION NUMBER），仅单灯上报
cmd String 固定为 update_info

更新策略：

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

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

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

⚠️ 注意：分组/广播的亮度为汇总值（取最亮），便于快速判断分区/总线内是否还有灯亮着；若需获取具体某盏灯的状态，请订阅单灯（shortaddress）上报。
⚠️ 注意：控制类指令执行后无确认报文，请通过 update 推送或主动查询确认灯具实际执行结果。

8. UDP 通信可靠性建议

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

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

9. 常用指令速查表

9.1 标准指令（normal）

功能 指令名 cmd_value 说明
关灯 0 OFF 10 忽略
调亮 1 UP 10 忽略
调暗 2 DOWN 10 忽略
步进调亮 3 STEP UP 10 忽略
步进调暗 4 STEP DOWN 10 忽略
开灯 5 RECALL MAX LEVEL 10 最大亮度
暗灯 6 RECALL MIN LEVEL 10 最小亮度
亮度控制 - DIRECT ARC POWER CONTROL 0~254 直接亮度
场景 0~15 16 GO TO SCENE 0 ~ 31 GO TO SCENE 15 100 调用场景

9.2 扩展指令（extend）

功能 指令名 cmd_value 说明
色温控制 control current tc value 2000~7000 当前色温（K）
查询当前色温 get current tc value 忽略 返回色温值
查询场景色温 0~15 get sence tc value 0 ~ get sence tc value 15 忽略 返回场景色温
设置场景色温 0~15 set sence tc value 0 ~ set sence tc value 15 亮度+色温 写入场景色温

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 运维。

我们的市场覆盖：

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

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

相关推荐
阿钱真强道3 天前
06 极物科技 | 创明RS485窗帘 - UDP 通讯协议规范
udp·智能家居·通讯协议·极物·极物智能·极物科技·创明窗帘
阿钱真强道4 天前
04 极物科技 | 创明RS485窗帘 - 快速接入指南
智能家居·rs485·极物·极物智能·极物科技·创明窗帘·窗帘控制
万亿少女的梦1681 个月前
无障碍与智能化融合的老年公寓适老化室内设计研究
室内设计·智能照明·适老化设计·无障碍设计·老年公寓
鉴生Eric1 个月前
双系统自研·全域稳控：拉孚Larfe，重新定义工程级智能照明
智能照明
鉴生Eric1 个月前
拉孚KNX工程智能照明供应商：园区_厂房商用照明改造方案解析
智能照明
大耳朵-小飞象1 个月前
智慧节能技术赋能城市有机更新3.0：智能照明与空调集控的革新实践
智慧城市·能耗系统·智能照明·楼宇智控·0-10v调光模块·物联网灯
大耳朵-小飞象1 个月前
智能调光4巨头争霸！轨道照明如何破局？
运维·智慧城市·智慧路灯·智能照明·楼宇智控·0-10v调光模块
一起聊电气3 个月前
智能电表：解锁智能照明精细化能耗管控新密码
人工智能·科技·能源·智能照明·智能照明模块
HMS工业网络3 个月前
使用电脑快速测试DeviceNet设备通讯
网络协议·通讯协议·devicenet·设备通讯
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新04历年考研数学一、数学二、数学三真题试卷及答案PDF052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法