前言

出于对 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, 单位:

与 DP 模型的区别

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 模型的区别

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

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, 单位:

注意事项

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

参考原型

功能介绍

功能定义

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 模型的区别

DP ID

功能点名称

标识符

数据传输类型

数据类型

功能点属性

20

开关

switch_led

可下发可上报(rw)

bool

21

模式

work_mode

可下发可上报(rw)

enum

枚举值: white, colour, scene, music

24

彩光

colour_data

可下发可上报(rw)

string

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

参考原型

功能介绍

功能定义

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 模型的区别

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

注意事项

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

参考原型

功能介绍

功能定义

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 模型的区别

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

注意事项

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

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

  1. 将 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);
};
  1. 将 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));
}