出于对 Matter 标准协议及第三方设备接入的可拓展性等方面考虑,照明 Matter 模型面板的功能点定义会与照明的 DP 模型有所不同,因此本文会着重介绍照明 Matter 面板的功能点定义及与 DP 模型的区别,以方便面板小程序开发者快速接入。
在这里我们介绍一下本文档中可能出现的一些名词:
DP ID | 功能点名称 | 标识符 | 数据传输类型 | 数据类型 | 功能点属性 | |
20 | 开关 | switch | 可下发可上报(rw) | bool | ||
21 | 模式 | work_mode | 可下发可上报(rw) | enum | 枚举值: white, colour, scene, music | |
85 | 亮度调节 | brightness_control | 可下发可上报(rw) | value | 数值范围: 1-254, 间距: 1, 倍数: 0, 单位: |
switch
,DP 模型下为 switch_led
。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, 单位: |
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 模型下,开光、亮度调节和色温调节的功能点标识符不一致,开关的标识符为 switch_led
,亮度调节的标识符为 bright_value
,色温调节的标识符为 temp_value
,除此之外,亮度调节和色温调节的数值范围也有所区别,分别在 10-1000
和 0-1000
。
switch
,DP 模型下为 switch_led
。brightness_control
,DP 模型下为 bright_value
。color_temp_control
,DP 模型下为 temp_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, 单位: |
kelvin=1000000 / 色温值
,例如色温值为 153,则 kelvin 值为 6536。注意:由于 Matter 模型三路灯彩光采用的 HSV 模型,因此这里的功能点定义和 DP 模型有较大差别
0-254
转成 0-360
和 0-100
。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, 单位: |
switch
,DP 模型下为 switch_led
。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 模型有较大差别
0-254
转成 0-360
和 0-100
。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, 单位: |
switch
,DP 模型下为 switch_led
。hs_color_set
和 brightness_control
,即控制彩光的色相或饱和度时下发 hs_color_set
,在控制彩光的亮度时下发 brightness_control
,而在 DP 模型下,彩光调节只需要一个功能点,即 colour_data
,直接控制灯具的色相饱和度和亮度。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 |
kelvin=1000000 / 色温值
,例如色温值为 153,则 kelvin 值为 6536。注意:由于 Matter 模型五路灯彩光采用的 HSV 模型,因此这里的功能点定义和 DP 模型有较大差别
0-254
转成 0-360
和 0-100
。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, 单位: |
switch
,DP 模型下为 switch_led
。color_temp_control
,DP 模型下为 temp_value
。hs_color_set
和 brightness_control
,即控制彩光的色相或饱和度时下发 hs_color_set
,在控制彩光的亮度时下发 brightness_control
,而在 DP 模型下,彩光调节只需要一个功能点,即 colour_data
,直接控制灯具的色相饱和度和亮度。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 |
kelvin=1000000 / 色温值
,例如色温值为 153,则 kelvin 值为 6536。由于实时调节功能是涂鸦特有的功能点模型,具体的协议说明见下图:
在色温定义中我们可以看到,control_data
功能点中色温的范围仍然是 0-1000,而在 Matter 模型下,色温 color_temp_control
DP 范围通常在 153-370,因此在实时调节的时候,我们需要将色温的值根据以下规则进行转换。
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);
};
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));
}