随着涂鸦小程序的生态逐步完善，开发者越来越多，当一个新人开发者需要开发类似照明灯带这种品类时常常伴随着无法下手的窘境，为了提升外部开发者的开发体验，官方开发者整理了照明幻彩灯带这个经典品类的开发导则，从而使无论新人开发者还是熟练开发者都可以从这里找到自己想要实现的功能模块。

本文介绍幻彩灯带常见的开发功能模块：

• 通用能力：
  • 开关
  • 白光模式
  • 情景
  • 音乐律动
  • 倒计时
  • 定时
• 品类能力
  • 彩光涂抹
  • 灯带裁剪

灯光路数

• 根据支持的白光、彩光 dp 不同，照明中灯分为一路至五路
• 其含义为:
  1. 一路灯（C）：C 为 Cool 的缩写，代表一路白光灯，即可以调节亮度的灯具。
  2. 二路灯（CW）：CW 为 Cool Warm 的缩写，代表二路冷暖白光灯，即可以调节亮度和冷暖色的灯具。
  3. 三路灯（RGB）：RGB 色彩模式是工业界的一种颜色标准，通过对红（Red）、绿（Green）、蓝（Blue）三个颜色通道的变化，以及相互之间的叠加来得到各式各样的颜色的方式。因此 RGB 灯代表三路彩光灯，指能调节颜色的灯具。
  4. 四路灯（RGBC）：代表四路彩光灯，具体由三原色和冷白光组成，即可以调节颜色和白光亮度的灯具。
  5. 五路灯（RGBCW）：代表五路彩光灯，具体由三原色和冷暖白光组成，即可以调节颜色、亮度和冷暖的灯具。

更多概念

• 开发中需要知道的名词概念

监听 dp

• 面板的状态需要跟设备保持一致，状态是根据 dp 的上报下发来同步的，那么如何知道设备有上报 dp 呢？
• 两种方式：
  • SDM 方式：
    • 一般直接使用 SDM 开发模版，使用 Tuya MiniApp Tools 进行创建项目时可以选择 SDM 模版。
    • 使用 useActions() 和 useProps() 分别可以进行 dp 的下发和读取更新，具体见 SDM文档。
  • 非 SDM 方式:
    • 使用 onDpDataChange 进行 dp 监听，如果有变化则进行状态同步。

功能介绍

• 开关分为通断电开关和 App 端开关。有两种开关的效果：渐变和无渐变，可以在开发者平台上配置

DP 协议

如何开发

• 当用户操作开关时，直接下发开关 dp 即可
• 两种方式：
  1. 直接使用 publishDps

  const switch_dpId = 1;
  ty.device.publishDps({
    deviceId: 'vdevo169477319679442',
    dps: { [switch_dpId]: false },
    mode: 1,
    pipelines: [0, 1, 2, 3, 4, 5, 6],
    options: {},
    success: res => {
      console.log(res);
    },
    fail: error => {
      console.log(error);
    },
  });
  

  2. 如果使用了智能设备模型开发模式
  • 使用 useActions hooks 进行下发

  import React from 'react';
  import { View } from '@ray-js/ray';
  import { useProps, useActions } from '@ray-js/panel-sdk';
  
  export default function Home() {
    const switch_led = useProps(props => props.switch_led);
    const actions = useActions();
    return (
      <View
        style={{ flex: 1 }}
        onClick={() => {
          actions.switch_led.toggle();
        }}
      >
        <View>switch_led: {switch_led}</View>
      </View>
    );
  }
  

注意事项

• 暂无

相关物料

• 【功能页】：无
• 【组件】：无
• 【教程】：无
• 【SDK】：无
• 【API】：无

功能介绍

• a. 亮度值 亮度调节默认有渐变效果，从1%亮度调节到100%亮度渐变时间为800ms。 亮度调节范围：1%-100%，面板下发的值的范围：10-1000，亮度调节范围和面板下发的值为线性对应关系。 免开发平台上，白光亮度最大值默认为100%，白光亮度最小值默认为10%，支持自主设置。白光亮度最小值建议不要设置低于10%，避免存在调节到最低亮度灯熄灭的情况发生。
  • 亮度转换公式。
• b. 冷暖值 球泡灯常见色温范围为：2700K-6500K，色温越高，对应的颜色越冷。 色温调节范围：0%-100%，面板下发的值的范围：0-1000，色温调节范围和面板下发的值为线性对应关系。
• c. 彩光支持路数
  • 一路
  • 二路

DP 协议

如何开发

• 当用户操作开关时，直接下发亮度、色温 dp 即可。
• 下发方式与上面开关 dp 下发类似，只需要将 dpId 和对应的具体 dp 值替换即可。

注意事项

• 暂无

相关物料

• 【功能页】：无
• 【组件】：
  • 常规触摸滑动条
  • 常规百分比滑动条
  • 竖向触摸滑动条
  • 竖向百分比滑动条
  • 常规亮度滑动条
  • 色温滑动条
  • 矩形色温色盘
  • 圆形色温色盘
• 【教程】：无
• 【SDK】：无
• 【API】：无

功能介绍

• 情景能力作为智能照明中一个非常重要的部分，可以丰富灯光玩法，实现灯的各种效果，有标准情景和允许客户自定义的情景。

DP 协议

• dpCode: dreamlight_scene_mode 详情

  序号	名称	长度	类型	属性	备注
  1	版本号	1	数值	0-25 5	默认1
  2	情景模式编号	1	数值	0-255	无
  3	变换方式	1	数值	0-255	无
  4	单元切换间隔时间	1	数值	0-100	无
  5	单元变化时间	1	数值	0-100	无
  6	设置项A	1	比特	Bit0：预留标识：null10：预留1：预留Bit1：预留标识：null20：预留1：预留Bit2：拓展标识：extra10：模式1：模式Bit3：拓展标识：extra20：模式1：模式Bit4：方向标识：direction0：顺时针1：逆时针Bit5：预留标识：null30：预留1：预留Bit6：预留标识：null40：预留1：预留Bit7：段落标识：segment0：全段1：分段	无
  7	设置项B	1	比特	Bit0：预留标识：null50：预留1：预留Bit1：预留标识：null60：预留1：预留Bit2：预留标识：null70：预留1：预留Bit3：预留标识：null80：预留1：预留Bit4：预留标识：null90：预留1：预留Bit5：预留标识：null100：预留1：预留Bit6：预留标识：null110：预留1：预留Bit7：预留标识：null120：预留1：预留	无
  8	设置项C	1	比特	Bit0：预留标识：null50：预留1：预留Bit1：预留标识：null60：预留1：预留Bit2：预留标识：null70：预留1：预留Bit3：预留标识：null80：预留1：预留Bit4：预留标识：null90：预留1：预留Bit5：预留标识：null100：预留1：预留Bit6：预留标识：null110：预留1：预留Bit7：预留标识：null120：预留1：预留	无
  9	亮度	1	数值	0-100	无
  10	色度	2	数值	0-360	无
  11	饱和度	1	数值	0-100	无

如何开发

• 我们在 Tuya MiniApp Tools 上提供了扩展插件来辅助开发，点击 扩展管理 后可以看到 面板 IDE 照明情景库扩展, 下载后按照扩展上的说明方法使用即可。

注意事项

• 自定义情景个数限制：
  • 由于嵌入式内存空间有限，一般情况下运行添加的自定义个数是有限制的，一般不超过10个

相关物料

• 【功能页】：无
• 【组件】：无
• 【教程】：无
• 【SDK】：无
• 【API】：
  • 在线情景库接口 => 获取情景库数据
  • 在线情景库接口 => 判断情景库是否存在新版本
  • 在线情景库接口 => 更新情景库到最新版本
  • 在线情景库接口 => 获取绑定数据类型

功能介绍

1. 设备音乐律动（本地音乐律动） 概念：通过本地麦克风采集音量信号，对信号的电压值进行一定的计算来实现音乐律动的效果。 由于该方案没有一个统一的实现逻辑，现在照明做过的有两个本地音乐律动逻辑。具体可参看。 注意： 如果在音乐模式下，打开灯光开关，固件上报开的音乐dp，音乐状态打开。
2. App音乐律动 手机麦克风采集外界音乐的音频信息，通过涂鸦智能 App 对音频信息进行时域和频域转换，输出HSV，实现灯光随着音乐节奏进行变化的效果.
3. 由 App 结合产品的控制面板,通过手机的外设收集周围的声音,App 能力负责收音并且提供给面板相关能力的接口,面板负责根据指定模式去固件间隔300ms下发音乐律动的dp,设备根据指定的协议解析控制命令让设备显示相应的颜色。

DP 协议

如何开发

• 我们在 Tuya MiniApp Tools 上提供了扩展插件来辅助开发，点击 扩展管理 后可以看到 面板 IDE 照明律动库扩展, 下载后按照扩展上的说明方法使用即可。

注意事项

暂无

相关物料

• 【功能页】：无
• 【组件】：无
  • 音乐律动组件
• 【教程】：无
• 【SDK】：
  • 监听 App 音乐拾音 => onMusic2RgbChange
  • 取消 App 音乐拾音 => offMusic2RgbChange
• 【API】：无

功能介绍

• 定时分类：
  • 云定时
    • 使用范围：带网关或wifi设备使用
    • 应用场景：有网关下使用，整体体验较好，定时执行后可以有 App 通知提醒用户。
      • 优缺点：
        • 优点：
          • App 提醒功能
          • 允许远程操作定时
        • 缺点：
          • 如果断网，定时无法执行
  • 本地定时
    • 使用范围：无网关的设备，一般用于sigmesh或单点蓝牙设备（完整DP协议说明）或Beacon设备（22.2 Beacon 完整DP协议说明）
    • 应用场景：主要是在无网关的情况下，涂鸦云定时不能正常工作，此时需要定时能力的话，就需要本地定时，在客户端设置好定时后，下发定时dp给设备，后续设置的定时逻辑在设备端脱离网关本地执行。
    • 优缺点：
      • 优点：
        • 断网后仍可执行，稳定性较高
      • 缺点：
        • 无网关的话，需要直连手机

如何开发

• 幻彩灯带支持云定时。
  1. 可以直接调用小程序模块组件 实现。
  2. 如果需要更多能力，可以跳转 RN 面板实现。
  3. 自行实现，云定时增删改查接口：
  • 添加定时
  • 更新定时
  • 删除定时
  • 更新状态
  • 同步定时

注意事项

暂无

相关物料

• 【功能页】：
  • 定时功能页
• 【组件】：
  • 定时组件
• 【教程】：无
• 【SDK】：无
• 【API】：无

功能介绍

• 倒计时可以设置当前灯具多长时间后关闭或开启。
  • 如果当前是开启，设置时长结束后就会关闭。
  • 如果当前是关闭，设置时长结束后就会开启。

DP 协议

如何开发

• 参考上面 dp 操作，直接下发对应 dp 值。

注意事项

• 在哪些情况下，倒计时功能会取消（清零）？ 1、面板下发倒计时DP为0（即通过控制面板中的清除按钮将倒计时取消或者将倒计时的时间重新设置为0小时0分钟）； 2、倒计时执行计时周期内，设备开/关状态发生改变，包括设备本地按键控制、App 面板远程控制、定时控制执行等； 3、设备断电重新上电或者模组重启。
• 倒计时上报时间间隔是多少？不是实时上报，需要面板自行倒数时间，所以面板上一般可能会有30s的误差，设备倒计时正常。
  1. Wi-Fi+BLE：30S

相关物料

• 【功能页】：
  • 倒计时功能页
• 【组件】：
  • 倒计时组件
  • 倒计时弹窗组件
• 【教程】：无
• 【SDK】：无
• 【API】：无

功能介绍

• 用户可在 App 上进行修正调整灯带长度，来调节灯光显示范围。

DP 协议

• 通过多个 dp 的配合来进行灯带长度或个数显示的调节。

  dpId	含义	dpCode	上报下发	数值类型	属性	备注
  46 (dpid)	灯带长度(可选)	light_length	只上报（ro）	数值型（Value）	数值范围: 1-10000, 间距: 1, 倍数: 0, 单位: cm	幻彩灯带在UI面板上展示的总长度
  47	灯带点数(必选)	light_pixel	只上报（ro）	数值型（Value）	数值范围: 1-1024, 间距: 1, 倍数: 0	幻彩灯带驱动芯片总数
  53	点数/长度设置(可选)	lightpixel_number_set	可下发可上报（rw）	数值型（Value）	数值范围: 1-1000, 间距: 1, 倍数: 0	幻彩灯带裁剪之后，对长度重新进行设置

【灯带长度】为可选功能，如果选中了此DP点，则面板上会以长度单位（米）来显示灯带长度设置内容，如果不选中此DP点，则以点数/数量来显示灯带点数设置内容 【灯带点数】为必选功能，表示设备驱动的总芯片数量/总点数，这个DP仅上报，面板能通过这个DP点获取到设备总点数 【点数/长度设置】为可选功能，如果选中了此DP点，则面板会显示灯带长度设置的板块，用户可在 App 上进行修正调整灯带长度，来调节灯光显示范围；如果不选择此DP点，则面板上不显示灯带长度设置的内容，用户无法进行二次设置

如何开发

• 裁剪dp逻辑
  • light_pixel与light_length dp都存在
    • 首次配网，light_pixel与lightpixel_number_set初始数据上报一样
    • 面板进行长度设置时需要下发 lightpixel_number_set dp，实际上是点数
    • 举个例子🌰：
      • light_length => 200cm === 2m
      • light_pixel => 100 对应的意思是在2m上有100个灯珠
      • 进行长度设置时需要转换为点数下发：
        • 比如从中间裁剪了，那么剩余长度应该为1m
          • 主要是页面展示中需要，下发时直接使用灯珠数
          • 下发值为：50 对应的灯珠数
      • 下发最大最小限制：
        • const max = lightPixel;
        • const min = 10;
  • light_pixel dp存在,light_length dp不存在
    • 首次配网，light_pixel与lightpixel_number_set初始数据上报一样
    • 面板进行长度设置时需要下发 lightpixel_number_set dp，实际上是点数
      • 举个例子🌰：
        • light_pixel => 100 对应的意思是灯带有100个灯珠
        • 直接下发对应的灯珠数据
        • 下发最大最小限制：
          • const max = lightPixel;
          • const min = 10;
• 参考上面 dp 操作，直接下发对应 dp 值。
  • 注意 dp 下发的只灯珠数，对应 lightpixel_number_set dp。

注意事项

• 设备裁剪保存后，要实现在裁剪的RGB混光状态会恢复到之前运行的状态
  • 只需要重新下发设置 work_mode

// 退出时恢复workMode
const workModeCode = 'work_mode';
useUnmount(() => {
	dragon.putDpData({ [workModeCode]: workMode }, { checkCurrent: false});
});

相关物料

• 【功能页】：
  • 灯带裁剪功能页
• 【组件】：无
• 【教程】：无
• 【SDK】：无
• 【API】：无

功能介绍

• a. 彩光利用HSV模型，面板下发HSV模型的字符串

1. 色调（H） 色调调节范围：0-360，面板下发的值的范围0-360，色环调节范围和面板下发的值为线性对应关系。
2. 饱和度（S） 饱和度调节范围：0%-100%，面板下发的值的范围0-1000，色环调节范围和面板下发的值为线性对应关系。
3. 明度（V） 明度调节范围：1%-100%，面板下发的值的范围10-1000，色环调节范围和面板下发的值为线性对应关系。

• b. 彩光支持路数
  • 三路
  • 四路
  • 五路

DP 协议

• paint_colour_data dp 详情

  版本号	调节模式	调节效果	段数	数据
  1byte	1byte	1byte	1byte	见下表
  0x00	0x00:白光模式 0x01:彩光模式 0x02:色卡模式 0x03:组合模式	0x00：无效果 0x01：段段之间有过渡 0x02：闪烁 0x03：呼吸 0x04：闪耀	灯带段数	见下表

• 白光模式：

  调节动作	B亮度	T色温
  1byte	2byte	2byte
  0x00：油漆桶	0-1000	0-1000

• 彩光、色卡模式：

  调节动作	HSV	段选	数据1	数据2	数据x...
  1byte	6byte	1byte	1byte	1byte	...
  0x00：油漆桶 0X01：铅笔（点选）0X02：橡皮擦（擦除	彩光HSV色值（2+2+2）	7bit：(0：连续；1：不连续)0bit-6bit：(连续时，无意义；不连续时，代表段的总数)	连续：起始编号 不连续：段编号	连续：结束编号 不连续：段编号	...

• 组合模式

  组合模式（预留）	颜色1	颜色2	...
  1byte	6byte	6byte	...
  0x00：均匀	彩光HSV色值（2+2+2）	彩光HSV色值（2+2+2）	...

如何开发

• 灯带组件参考
  • 安装后在 node_module/@ray-js/lamp-strip-light-smear/src/README.md 中描述了具体实现的逻辑

注意事项

• 涂抹灯带的ui实现:
  1. 小程序中可以使用canvas/svg + 碰撞💥检测来实现。
  2. 在RN中则是使用对应的图片然后动态修改颜色以及其渐变色实现。

相关物料

• 【功能页】：无
• 【组件】：
  • 灯带涂抹组件
  • Canvas 图形库
• 【教程】：无
• 【SDK】：无
• 【API】：无

• 🎉 恭喜你已经了解如何开发一款幻彩灯带了，尝试去开发吧！
• 有任何问题可以联系 Tuya MiniApp Team