开发照明 Matter 面板

前言

出于对 Matter 标准协议及第三方设备接入的可拓展性等方面考虑，照明 Matter 模型面板的功能点定义会与照明的 DP 模型有所不同，因此本文会着重介绍照明 Matter 面板的功能点定义及与 DP 模型的区别，以方便面板小程序开发者快速接入。

名词解释

在这里我们介绍一下本文档中可能出现的一些名词：

一路灯（C）：C 为 Cool 的缩写，代表一路白光灯，即可以调节亮度的灯具。
二路灯（CW）：CW 为 Cool Warm 的缩写，代表二路冷暖白光灯，即可以调节亮度和冷暖色的灯具。
三路灯（RGB）：RGB 色彩模式是工业界的一种颜色标准，通过对红（Red）、绿（Green）、蓝（Blue）三个颜色通道的变化，以及相互之间的叠加来得到各式各样的颜色的方式。因此 RGB 灯代表三路彩光灯，指能调节颜色的灯具。
四路灯（RGBC）：代表四路彩光灯，具体由三原色和冷白光组成，即可以调节颜色和白光亮度的灯具。
五路灯（RGBCW）：代表五路彩光灯，具体由三原色和冷暖白光组成，即可以调节颜色、亮度和冷暖的灯具。

参考原型

功能介绍

开关：控制灯具的开关状态。
模式：控制灯具的工作模式，包括白光、彩光、场景、音乐模式，在一路灯下，设备灯具只允许上报 white 白光模式。
亮度调节：控制灯具的白光亮度，数值越大则亮度越高。

功能定义

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
85	亮度调节	brightness_control	可下发可上报（rw）	value	数值范围: 1-254, 间距: 1, 倍数: 0, 单位:

与 DP 模型的区别

开关的功能点标识符不一致，在 Matter 模型下标识符为 switch，DP 模型下为 switch_led。
亮度的功能点标识符不一致，在 Matter 模型下标识符为 brightness_control，DP 模型下为 bright_value。
亮度的功能点数值范围不一致，在 Matter 模型下范围为 10-1000，DP 模型下为 1-254。

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch_led	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
22	白光亮度	bright_value	可下发可上报（rw）	value	数值范围: 10-1000, 间距: 1, 倍数: 0, 单位:

参考原型

功能介绍

开关：控制灯具的开关状态。
模式：控制灯具的工作模式，包括白光、彩光、场景、音乐模式，在二路灯下，设备灯具只允许上报 white 白光模式。
亮度调节：控制灯具的白光亮度，数值越大则亮度越高。
色温调节：控制灯具的冷暖色温，数值越大则 Kelvin 值越小，则对应灯具的色温越暖。

功能定义

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
85	亮度调节	brightness_control	可下发可上报（rw）	value	数值范围: 1-254, 间距: 1, 倍数: 0, 单位:
86	色温调节	color_temp_control	可下发可上报（rw）	value	数值范围: 153-370, 间距: 1, 倍数: 0, 单位:

与 DP 模型的区别

在 DP 模型下，开光、亮度调节和色温调节的功能点标识符不一致，开关的标识符为 switch_led，亮度调节的标识符为 bright_value，色温调节的标识符为 temp_value，除此之外，亮度调节和色温调节的数值范围也有所区别，分别在 10-1000 和 0-1000。

开关的功能点标识符不一致，在 Matter 模型下标识符为 switch，DP 模型下为 switch_led。
亮度的功能点标识符不一致，在 Matter 模型下标识符为 brightness_control，DP 模型下为 bright_value。
亮度的功能点数值范围不一致，在 Matter 模型下范围为 10-1000，DP 模型下为 1-254。
色温的功能点标识符不一致，在 Matter 模型下标识符为 color_temp_control，DP 模型下为 temp_value。
色温的功能点数值范围不一致，在 Matter 模型下范围为 0-1000，DP 模型下为 153-370。

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch_led	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
22	白光亮度	bright_value	可下发可上报（rw）	value	数值范围: 10-1000, 间距: 1, 倍数: 0, 单位:
23	冷暖值	temp_value	可下发可上报（rw）	value	数值范围: 0-1000, 间距: 1, 倍数: 0, 单位:

注意事项

色温调节数值范围为 153-370，对应的 kelvin=1000000 / 色温值，例如色温值为 153，则 kelvin 值为 6536。

注意：由于 Matter 模型三路灯彩光采用的 HSV 模型，因此这里的功能点定义和 DP 模型有较大差别

参考原型

功能介绍

开关：控制灯具的开关状态。
模式：控制灯具的工作模式，包括白光、彩光、场景、音乐模式，在三路灯下，设备灯具只允许上报 colour 彩光模式。
HS 颜色调节：控制灯具的彩光值中的色相和饱和度，数值范围均为 0-254，转换为字符串则为 HHSS 这样的格式，第一个字节代表 Hue 值的十六进制，第二个字节代表 Saturation 值的十六进制，如 00fe 代表色相为 0，饱和度为 254，最终应用到 UI 层，需要分别将色相和饱和度分别从 0-254 转成 0-360 和 0-100。
亮度调节：控制灯具的彩光亮度，即 HSV 模型中的 V，数值越大则亮度越高。

功能定义

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
23	HS 颜色调节	hs_color_set	可下发可上报（rw）	value	最大长度: 255
85	亮度调节	brightness_control	可下发可上报（rw）	value	数值范围: 1-254, 间距: 1, 倍数: 0, 单位:

与 DP 模型的区别

开关的功能点标识符不一致，在 Matter 模型下标识符为 switch，DP 模型下为 switch_led。
彩光调节的逻辑不同，在 Matter 模型下，彩光调节需要分为两个功能点，即 hs_color_set 和 brightness_control，即控制彩光的色相或饱和度时下发 hs_color_set，在控制彩光的亮度时下发 brightness_control，而在 DP 模型下，彩光调节只需要一个功能点，即 colour_data，直接控制灯具的色相饱和度和亮度。

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch_led	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
24	彩光	colour_data	可下发可上报（rw）	string

注意：由于 Matter 模型四路灯彩光采用的 HSV 模型，因此这里的功能点定义和 DP 模型有较大差别

参考原型

功能介绍

开关：控制灯具的开关状态。
模式：控制灯具的工作模式，包括白光、彩光、场景、音乐模式，在四路灯下，设备灯具只允许上报 white 白光模式或 colour 彩光模式。
*白光亮度：该功能点不会对设备产生实际的影响，只用于 UI 层判断是否为四路灯，因为 brightness_control 既可以控制白光亮度也可以控制彩光亮度。*
HS 颜色调节：控制灯具的彩光值中的色相和饱和度，数值范围均为 0-254，转换为字符串则为 HHSS 这样的格式，第一个字节代表 Hue 值的十六进制，第二个字节代表 Saturation 值的十六进制，如 00fe 代表色相为 0，饱和度为 254，最终应用到 UI 层，需要分别将色相和饱和度分别从 0-254 转成 0-360 和 0-100。
亮度调节：根据当前模式的状态固件来判断控制灯具的白光亮度还是彩光亮度，数值越大则亮度越高，在彩光模式下代表的是 HSV 模型中的 V。

功能定义

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
22	白光亮度	bright_value	可下发可上报（rw）	value	数值范围: 10-1000, 间距: 1, 倍数: 0, 单位:
23	HS 颜色调节	hs_color_set	可下发可上报（rw）	value	最大长度: 255
85	亮度调节	brightness_control	可下发可上报（rw）	value	数值范围: 1-254, 间距: 1, 倍数: 0, 单位:

与 DP 模型的区别

开关的功能点标识符不一致，在 Matter 模型下标识符为 switch，DP 模型下为 switch_led。
彩光调节的逻辑不同，在 Matter 模型下，彩光调节需要分为两个功能点，即 hs_color_set 和 brightness_control，即控制彩光的色相或饱和度时下发 hs_color_set，在控制彩光的亮度时下发 brightness_control，而在 DP 模型下，彩光调节只需要一个功能点，即 colour_data，直接控制灯具的色相饱和度和亮度。
白光亮度调节的逻辑不同，在 Matter 模型下，在模式为 white 时，调节 brightness_control 控制的是白光亮度，在模式为 colour 时，调节 brightness_control 控制的是彩光亮度，而在 DP 模型下，调节白光亮度的功能点固定为 bright_value。

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch_led	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
22	白光亮度	bright_value	可下发可上报（rw）	value	数值范围: 10-1000, 间距: 1, 倍数: 0, 单位:
24	彩光	colour_data	可下发可上报（rw）	string

注意事项

色温调节数值范围为 153-370，对应的 kelvin=1000000 / 色温值，例如色温值为 153，则 kelvin 值为 6536。

注意：由于 Matter 模型五路灯彩光采用的 HSV 模型，因此这里的功能点定义和 DP 模型有较大差别

参考原型

功能介绍

开关：控制灯具的开关状态。
模式：控制灯具的工作模式，包括白光、彩光、场景、音乐模式，在四路灯下，设备灯具只允许上报 white 白光模式或 colour 彩光模式。
HS 颜色调节：控制灯具的彩光值中的色相和饱和度，数值范围均为 0-254，转换为字符串则为 HHSS 这样的格式，第一个字节代表 Hue 值的十六进制，第二个字节代表 Saturation 值的十六进制，如 00fe 代表色相为 0，饱和度为 254，最终应用到 UI 层，需要分别将色相和饱和度分别从 0-254 转成 0-360 和 0-100。
亮度调节：根据当前模式的状态固件来判断控制灯具的白光亮度还是彩光亮度，数值越大则亮度越高，在彩光模式下代表的是 HSV 模型中的 V。
色温调节：控制灯具的冷暖色温，数值越大则 Kelvin 值越小，则对应灯具的色温越暖。

功能定义

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
23	HS 颜色调节	hs_color_set	可下发可上报（rw）	value	最大长度: 255
85	亮度调节	brightness_control	可下发可上报（rw）	value	数值范围: 1-254, 间距: 1, 倍数: 0, 单位:
86	色温调节	color_temp_control	可下发可上报（rw）	value	数值范围: 153-370, 间距: 1, 倍数: 0, 单位:

与 DP 模型的区别

开关的功能点标识符不一致，在 Matter 模型下标识符为 switch，DP 模型下为 switch_led。
色温的功能点标识符不一致，在 Matter 模型下标识符为 color_temp_control，DP 模型下为 temp_value。
彩光调节的逻辑不同，在 Matter 模型下，彩光调节需要分为两个功能点，即 hs_color_set 和 brightness_control，即控制彩光的色相或饱和度时下发 hs_color_set，在控制彩光的亮度时下发 brightness_control，而在 DP 模型下，彩光调节只需要一个功能点，即 colour_data，直接控制灯具的色相饱和度和亮度。
白光亮度调节的逻辑不同，在 Matter 模型下，在模式为 white 时，调节 brightness_control 控制的是白光亮度，在模式为 colour 时，调节 brightness_control 控制的是彩光亮度，而在 DP 模型下，调节白光亮度的功能点固定为 bright_value。

DP ID	功能点名称	标识符	数据传输类型	数据类型	功能点属性
20	开关	switch_led	可下发可上报（rw）	bool
21	模式	work_mode	可下发可上报（rw）	enum	枚举值: white, colour, scene, music
22	白光亮度	bright_value	可下发可上报（rw）	value	数值范围: 10-1000, 间距: 1, 倍数: 0, 单位:
23	冷暖值	temp_value	可下发可上报（rw）	value	数值范围: 0-1000, 间距: 1, 倍数: 0, 单位:
24	彩光	colour_data	可下发可上报（rw）	string

注意事项

色温调节数值范围为 153-370，对应的 kelvin=1000000 / 色温值，例如色温值为 153，则 kelvin 值为 6536。

由于实时调节功能是涂鸦特有的功能点模型，具体的协议说明见下图:

在色温定义中我们可以看到，control_data 功能点中色温的范围仍然是 0-1000，而在 Matter 模型下，色温 color_temp_control DP 范围通常在 153-370，因此在实时调节的时候，我们需要将色温的值根据以下规则进行转换。

将 Matter 模型下的 color_temp_control 色温 DP 转换为 Kelvin 值，即 kelvin=1000000 / 色温值，比如 153 对应的 Kelvin 值为 6536（冷光），370 对应的 Kelvin 值为 2702（暖光）。

import _ from 'lodash';

/**
 * 将 Matter 标准的照明色温值转换为 kelvin 值
 *
 * @param tempDp 当前 Matter 标准的照明色温 DP 值
 * @returns 当前 Matter 标准的照明色温值 对应的 kelvin 值
 */
export const tempM2Kelvin = (tempMatter: number) => {
  const tempMatterMin = 153; // 实际开发环境建议从 color_temp_control DP 的产品定义中获取实际的 min、max 值
  const tempMatterMax = 370;
  // 这里有个反比计算最小和最大的温度转换为 kelvin 单位时的值
  const kelvinsMin = 1000000 / tempMatterMax;
  const kelvinsMax = 1000000 / tempMatterMin;

  // 根据设定范围将温度值转换为 kelvin 单位
  const kelvin = 1000000 / tempMatter;

  // 对计算后的值进行四舍五入，并限制其值在设定的范围内
  return _.clamp(Math.round(kelvin), kelvinsMin, kelvinsMax);
};

将 Kelvin 值转换为 control_data 功能点中色温对应范围的 0-1000，转换到 kelvin 值对应范围的 2702-6536。

import { utils } from '@ray-js/panel-sdk';

export const kelvin2Temp = (kelvin: number) => {
  const tempMatterMin = 153; // 实际开发环境建议从 color_temp_control DP 的产品定义中获取实际的 min、max 值
  const tempMatterMax = 370;
  // 这里有个反比计算最小和最大的温度转换为 kelvin 单位时的值
  const kelvinsMin = 1000000 / tempMatterMax;
  const kelvinsMax = 1000000 / tempMatterMin;
  return Math.round(utils.calcPosition(kelvin, kelvinsMin, kelvinsMax, 0, 1000));
}

恭喜你 🎉 完成了本教程的学习！
有任何问题可以联系 Tuya MiniApp Team

反馈