涂鸦开发者平台产品方案照明吸顶灯吸顶灯免开发方案开放串口协议

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

更新时间: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——恢复原状态。