吸顶灯免开发方案开放串口协议

更新时间:2024-06-20 05:56:37下载pdf

背景信息

该方案支持 Wi-Fi + Bluetooth LE 双模协议的单路可调白光灯(C)、二路调光调色灯(CCT)、三路彩光灯(RGB)、四路彩光灯(RGBW)和五路彩光灯(RGBCW),也支持主辅光源形式的四路全开灯(主灯单路 C+辅灯三路 RGB)和五路全开灯(主灯二路 CCT+辅灯三路 RGB)。

创建入口

  1. 登录 涂鸦开发者平台创建产品页

  2. 在左侧导航栏中,选择 照明 > 吸顶灯

    吸顶灯免开发方案开放串口协议

  3. 零代码实现 页签中选择 Wi-Fi 蓝牙

  4. 选择指定产品。

    吸顶灯免开发方案开放串口协议

功能实现

涂鸦模组中包含开关、白光亮度色温调节、彩光颜色调节、情景模式、音乐律动模式、生物节律、入睡、唤醒、循环定时、随机定时、分段调光、开关渐变、勿扰模式等丰富的功能点。
上述功能已在涂鸦模组中实现,客户无需再次开发,根据需要选取对应功能即可。
红、绿、蓝、冷白和暖白 5 路 LED 光源通过涂鸦模组上的 IO 口进行控制。
同时,开发者可按照本文档中的协议,通过串口向涂鸦模组发送控制指令,从而简单灵活地扩展产品功能,如支持 2.4G、433M 等私有协议遥控器或控制面板,为产品增加机械或触摸按键功能等,实现产品的差异化设计。

下图为利用串口实现支持 2.4G 遥控功能的方案框图:

吸顶灯免开发方案开放串口协议

主协议

串口通信约定

  • 波特率:9,600
  • 数据位:8
  • 奇偶校验:无
  • 停止位:1
  • 数据流控:无
  • MCU:用户控制板控制芯片,与涂鸦模块通过串口对接,这里协议设计上,所有包的交互为全双工通信设计。

帧格式说明

字段 长度(byte) 说明
帧头 2 固定
版本 1 版本类型
命令字 1 具体帧类型
数据长度 2 大端
数据 N 数据
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

说明 :

  • 所有大于 1 个字节的数据均采用大端模式传输。
  • 协议中所有举例说明数据都是十六进制数据。
  • Wi-Fi 模块主动发起的通信发送包超时时间为 1s,重发机制会重发三包。
  • 一般情况下,采用同命令字一发一收同步机制,即一方发出命令。另一方应答,若发送方超时未收到正确的响应包,则超时传输,如下图所示:

吸顶灯免开发方案开放串口协议

命令下发及状态上报

外挂 MCU 发送

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x03
命令字 1 0x34
数据长度 2 1+N
数据 1 子命令:0x20
N 根据控制命令不同,详见 3.3 控制指令表
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

例:开关开启(55aa 03 34 0004 20 ff0101 5b)。

涂鸦模组返回

字段 长度(byte) 说明
帧头 2 0x55aa
版本 1 0x00
命令字 1 0x34
数据长度 2 0x0001
数据 1 子命令:0x20
校验和 1 从帧头开始按字节求和得出的结果对 256 求余

例:开关开启返回(55aa 00 34 0001 20 54)。

控制指令表
涂鸦免开发方案标准串口控制指令及详细的功能逻辑如下表。

序号 控制类别(1 字节) 控制命令(1 字节) 控制数据(变长) 功能逻辑 灯光反馈
1 通用:0xFF 总开关:0x01 字节 1:
  • 0:关闭
  • 1:开启
  • 2:翻转
总开关。与 App 中的总开关状态同步。
2 照明:0x01 开关:0x01
  • 字节 1:
    • 0:关闭
    • 1:开启
    • 2:翻转
  • 字节 2:
    • 1:白光开关
    • 2:彩光开关
白光开关和彩光开关仅针对四路全开和五路全开方案有效。
  • 在情景、音乐、遥控器跑马模式下:
    • 收到白光开或翻转指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)。
    • 收到白光关指令则不处理。
    • 彩光类同。
  • 总开关关闭状态下:
    • 收到白光开或翻转指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)。
    • 收到白光关指令则保持总开关关闭状态不变。
    • 彩光类同。
3 照明:0x01 亮度调节:0x02
  • 字节 1:
    • 0:值
    • 1:加
    • 2:减
  • 字节 2:
    • 1:白光亮度
    • 2:彩光亮度
  • 字节 3:
    • 字节 1 为 0 时表示亮度百分比
      (1-100%)
    • 字节 1 非 0 时表示亮度步进值(1-100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到白光亮度指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)并执行相应指令。彩光类同。
    • 在手动调光模式下且白光关闭时,收到白光亮度指令,则打开白光并执行相应指令,彩光状态保持不变。彩光类同。
    • 在手动调光模式下且白光开启时,收到白光亮度指令,直接按指令执行即可,彩光状态保持不变。彩光类同。
  • 针对 1~5 路方案,收到亮度调节指令,则切换到相应模式(白光或彩光模式)的同时,执行指令内容。
4 照明:0x01 亮度无极调节:0x03
  • 字节 1:
    • 0:连续加开始
    • 1:连续减开始
    • 2:结束
  • 字节 2:
    • 1:白光亮度
    • 2:彩光亮度
  • 字节 3:速率
    (每 1s 调节的百分比,取值范围 10%~100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到白光亮度指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)并执行相应指令。彩光类同。
    • 在手动调光模式下且白光关闭时,收到白光亮度指令,则打开白光并执行相应指令,彩光状态保持不变。彩光类同。
    • 在手动调光模式下且白光开启时,收到白光亮度指令,直接按指令执行即可,彩光状态保持不变。彩光类同。
  • 针对 1~5 路方案,收到亮度调节指令,则切换到相应模式(白光或彩光模式)的同时,执行指令内容。
  • 收到连续加或减指令后,在未收到结束指令前亮度已达到最大或最小时,自动停止调光。
5 照明:0x01 色温调节:0x04
  • 字节 1:
    • 0:值
    • 1:加
    • 2:减
  • 字节 2:保留位,无意义
  • 字节 3:
    • 字节 1 为 0 时表示色温百分比(0-100%)
    • 字节 1 非 0 时表示色温步进值(0-100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且白光关闭时,收到该指令,则打开白光并执行相应指令,彩光状态保持不变。
    • 在手动调光模式下且白光开启时,收到该指令,直接按指令执行即可,彩光状态保持不变。
  • 针对 2、5 路方案,收到该指令,则切换到白光模式的同时,执行指令内容。
6 照明:0x01 色温无极调节:0x05
  • 字节 1:
    • 0:连续加开始
    • 1:连续减开始
    • 2:结束
  • 字节 2:保留位,无意义
  • 字节 3:速率(每 1s 调节的百分比,取值范围 20%~100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开白光(彩光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且白光关闭时,收到该指令,则打开白光并执行相应指令,彩光状态保持不变。
    • 在手动调光模式下且白光开启时,收到该指令,直接按指令执行即可,彩光状态保持不变。
  • 针对 2、5 路方案:收到该指令,则切换到白光模式的同时,执行指令内容。
  • 收到连续加或减指令后,在未收到结束指令前色温已达到最大或最小时,自动停止调光。
7 照明:0x01 H 值(色调)调节:0x06
  • 字节 1:
    • 0:值
    • 1:加
    • 2:减
  • 字节 2:
    • 字节 1 为 0 时表示百分比(0-100%)
    • 字节 1 非 0 时表示步进值(1-100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
    • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
  • 针对 3~5 路方案,收到该指令,则切换到彩光模式的同时,执行指令内容。
8 照明:0x01 H 值(色调)无极调节:0x07
  • 字节 1:
    • 0:连续加开始
    • 1:连续减开始
    • 2:结束
  • 字节 2:速率
    (每 1s 调节的百分比,取值范围 20%~100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
    • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
  • 针对 3~5 路方案:收到该指令,则切换到彩光模式的同时,执行指令内容。
  • 收到连续加或减指令后,在未收到结束指令前 H 值已达到最大或最小时,自动停止调光。
9 照明:0x01 S 值(饱和度)调节:0x08
  • 字节 1:
    • 0:值
    • 1:加
    • 2:减
  • 字节 2:
    • 字节 1 为 0 时表示百分比(0-100%)
    • 字节 1 非 0 时表示步进值(1-100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
    • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
  • 针对 3~5 路方案,收到该指令,则切换到彩光模式的同时,执行指令内容。
10 照明:0x01 S 值(饱和度)无极调节:0x09
  • 字节 1:
    • 0:连续加开始
    • 1:连续减开始
    • 2:结束
  • 字节 2:速率
    (每 1s 调节的百分比,取值范围 20%~100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
    • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
  • 针对 3~5 路方案:收到该指令,则切换到彩光模式的同时,执行指令内容。
  • 收到连续加或减指令后,在未收到结束指令前 S 值已达到最大或最小时,自动停止调光。
11 照明:0x01 HSV 调节:0x0c
  • 字节 1:
    H 百分比值(0-100%)
  • 字节 2:
    S 百分比值(0-100%)
  • 字节 3:
    V 百分比值(1-100%)
  • 总开关关闭状态下,收到该指令不处理。
  • 针对四路全开和五路全开方案:
    • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
    • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
    • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
  • 针对 3~5 路方案,收到该指令,则切换到彩光模式的同时,执行指令内容。
12 照明:0x01 重置配网:0x0d 字节 1:字节 1 为 0 时, 表示 EZ 配网 任意状态下,收到该指令设备进入 EZ 配网状态。
13 照明:0x01 倒计时:0x0e 字节 1 和 2:倒计时时间
(单位:分钟)
  • 灯关闭的状态下,收到该指令不处理。
  • 未设置倒计时的情况下,收到取消倒计时(赋值为 0)指令,仍然正常执行并给出灯光提示。
  • 设置非 0 时长的倒计时指令成功执行一次,灯光闪烁 1 次。
  • 设置时长为 0 的倒计时(取消倒计时)指令成功执行一次,灯光闪烁 2 次。
14 照明:0x01 情景调节:0x20
  • 字节 1:
    • 0:情景号
    • 3: ****
  • 字节 2:字节 1 为 0 时,情景号 0~3
  • 总开关关闭状态下,收到该指令不处理。
  • 与 App 中的前 4 个默认场景绑定。
  • 收到情景号指令则直接执行该情景。
  • 收到情景$1 $2 指令,则总是从第一个情景进入循环切换,切换中途被其他操作打断则从头开始。
15 照明:0x01 喜好收藏:0x21
  • 字节 1:
    • 1:收藏当前状态
    • 2:切换到该收藏
  • 字节 2 :收藏号 0~1
  • 总开关关闭状态下,收到该指令不处理。
  • 手动调节模式下,收藏当前静态状态。
  • 情景模式下,收藏正在执行的情景(如果自定义情景收藏成功后被删除,则仍然执行该情景,只是上报同步面板时不对应任意一个情景)。
  • 音乐模式下收藏音乐模式。
  • 遥控器跑马模式下收藏相应跑马模式。
  • 默认状态:
      • 收藏 0:
        • 对一路、四路和四路全开方案,单白光亮度 100%。
        • 对二路、五路和五路全开方案,单白光亮度 100% 色温 50%。
        • 对三路灯方案,纯红光 100% 亮度。
      • 收藏 1:
        • 对一路、四路和四路全开方案,单白光亮度 50%。
        • 对二路、五路和五路全开方案,单白光亮度 50% 色温 50%。
        • 对三路灯方案,纯红光 50% 亮度。
    • 高级功能(生物节律、入睡、唤醒、循环定时、随机定时)执行过程中,收到收藏指令,则收藏高级功能开始执行前的最后一个状态。
  • 收藏指令成功执行一次,灯光闪烁 1 次。切换指令成功执行没有灯光提示。
    16 照明:0x01 颜色静态调节:0x22
    • 字节 1:
      • 0:颜色号
      • 3:循环 1
    • 字节 2:
      • 3:RGB
      • 7:7 彩色
        说明: “颜色静态调节”和“颜色动态调节”指令中对应的7彩色按顺序分别为:红(H=0°)、橙(H=30°)、黄(H=60°)、绿(H=120°)、青(H=180°)、蓝(H=240°)、紫(H=300°),饱和度和亮度都为最大100%。
    • 字节 3:字节 1 为 0 时,颜色号 0~6 按顺序分表代表 7 彩色
    • 总开关关闭状态下,收到该指令不处理。
    • 针对四路全开和五路全开方案:
      • 在情景、音乐、遥控器跑马模式下,收到该指令,则切换到手动调光模式的同时,仅打开彩光(白光保持关闭状态)并执行相应指令。
      • 在手动调光模式下且彩光关闭时,收到该指令,则打开彩光并执行相应指令,白光状态保持不变。
      • 在手动调光模式下且彩光开启时,收到该指令,直接按指令执行即可,白光状态保持不变。
    • 针对 3~5 路方案:收到该指令,则切换到彩光模式的同时,执行指令内容。
    • 收到 循环 1 指令,则总是从第一个颜色进入循环切换,切换中途被其他操作打断则从头开始。
      说明: “情景调节”和“颜色静态调节”指令中的“循环1”表示:从低到高,再从低到高,例:1-2-3-1-2-3-1……
    17 照明:0x01 颜色动态调节:0x23
    • 字节 1:
      • 1 :跳变
      • 2:渐变
    • 字节 2:
      • 3:RGB
      • 7:7 彩色
        说明: “颜色静态调节”和“颜色动态调节”指令中对应的7彩色按顺序分别为:红(H=0°)、橙(H=30°)、黄(H=60°)、绿(H=120°)、青(H=180°)、蓝(H=240°)、紫(H=300°),饱和度和亮度都为最大100%。
    • 字节 3:速率 1%-100%
    • 总开关关闭状态下,收到该指令不处理。
    • 主灯开启的任意状态下,收到该指令设备进入指定的跑马模式,App 控制面板切换到情景模式状态下。
    • 速率 1%~100%对应每种颜色的保持时间在 10s~0.1s 之间线性变化。

    说明:

    • 涂鸦模组配网成功和未配网的情况下,串口指令均有效。涂鸦模组处于配网过程中时,串口指令无效。
    • 当数据错误或者数据超出定义范围时,不进行处理,而不是默认值,同时不返回数据。
    • 方案不支持某指令功能时,收到该指令不处理。
    • “倒计时”和“喜好收藏”指令执行后对应的灯光反馈具体逻辑:
      • 针对除三路灯外的其他方案
        • 闪烁 1 次:灯关闭 0.5s——冷白光 50% 亮度亮 0.5s —— 灯关闭 0.5s —— 恢复原状态。
        • 闪烁 2 次:灯关闭 0.5s——冷白光 50% 亮度亮 0.5s——灯关闭 0.5s–冷白光 50% 亮度亮 0.5s——灯关闭 0.5s–恢复原状态。
      • 针对三路灯方案
        • 闪烁 1 次:灯关闭 0.5s——纯红光 50% 亮度亮 0.5s——灯关闭 0.5s——恢复原状态。
        • 闪烁 2 次:灯关闭 0.5s——纯红光 50% 亮度亮 0.5s——灯关闭 0.5s——纯红光 50% 亮度亮 0.5s——灯关闭 0.5s——恢复原状态。