matter-kit

Info

matter-kit 自 @ray-js/panel-sdk@1.15.0 开始加入，当前仅支持照明品类设备。

轻量的 Matter 设备面板 DP 功能点处理工具库，内置 Matter 协议与标准 DP 协议之间的双向转换，自动处理设备信息、DP 状态上报与下发。

各 API 的详细说明见下文 API 索引中的子文档链接。

接入指南

根据业务场景生成 matter-kit

src/devices/index.ts

import { SmartDeviceModel, createMatterKit } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';

type SmartDeviceSchema = typeof defaultSchema;

export const matterKit = createMatterKit({
  debug: false, // 可选：开启调试模式
});

const options = {
  interceptors: matterKit.interceptors,
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};

使用标准 DP 功能点

接入 matter-kit 后，您可以直接使用标准的 DP 功能点进行开发，matter-kit 会自动处理 Matter 协议与标准协议之间的转换。

import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions } from '@ray-js/panel-sdk';

export default function Home() {
  const power = useProps((props) => props.switch_led);
  const bright = useProps((props) => props.bright_value);
  const temp = useProps((props) => props.temp_value);
  const colour = useProps((props) => props.colour_data);
  const actions = useActions();

  return (
    <View style={{ flex: 1 }}>
      <View onClick={() => actions.switch_led.toggle()}>
        开关: {power ? '开' : '关'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        亮度: {bright}
      </View>
      <View onClick={() => actions.temp_value.set(600)}>
        色温: {temp}
      </View>
      <View onClick={() => actions.colour_data.set('012502ad02ee')}>
        颜色: {colour}
      </View>
    </View>
  );
}

DP 功能点映射关系

matter-kit 会自动处理以下 Matter 协议与标准协议之间的转换：

Matter 协议	标准协议	说明
`switch`	`switch_led`	开关控制
`brightness_control`	`bright_value`	亮度控制（1-254 → 10-1000）
`color_temp_control`	`temp_value`	色温控制（卡尔文 → 0-1000）
`hs_color_set`	`colour_data`	颜色控制（色相+饱和度 → HSV）

转换说明

开关控制

上报：switch → switch_led
下发：switch_led → switch

亮度控制

上报：brightness_control (1-254) → bright_value (10-1000)
下发：bright_value (10-1000) → brightness_control (1-254)

转换公式使用线性映射，确保数值范围的正确转换。

色温控制

上报：color_temp_control (卡尔文) → temp_value (0-1000)
下发：temp_value (0-1000) → color_temp_control (卡尔文)

转换基于色温的卡尔文值进行非线性映射，确保色温滑动条的显示效果。

注意：由于色温转换会丢失精度，matter-kit 会保留原始的 color_temp_control 值。如需获取原始值用于 UI 展示，请使用 useOriginMatterTemp。

颜色控制

上报：hs_color_set (色相+饱和度) + brightness_control (亮度) → colour_data (HSV 格式)
下发：colour_data (HSV 格式) → hs_color_set (色相+饱和度) + brightness_control (亮度)

颜色转换会将 Matter 的色相饱和度与亮度合并为标准协议的 HSV 格式。

使用示例

基础

import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions, createMatterKit } from '@ray-js/panel-sdk';

const matterKit = createMatterKit();

export default function Home() {
  const power = useProps((props) => props.switch_led);
  const bright = useProps((props) => props.bright_value);
  const actions = useActions();

  return (
    <View>
      <View onClick={() => actions.switch_led.toggle()}>
        开关: {power ? '开' : '关'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        亮度: {bright}
      </View>
    </View>
  );
}

路数

结合 schema 判断路数、白光能力等，完整说明见 getMatterRoad。

import React from 'react';
import { View } from '@ray-js/ray';
import { useDpSchema, createMatterKit } from '@ray-js/panel-sdk';

const matterKit = createMatterKit();

export default function DeviceInfo() {
  const dpSchema = useDpSchema();
  const road = matterKit.utils.getMatterRoad(dpSchema);
  const hasWhite = matterKit.utils.checkIsMatterHasWhite(dpSchema);

  return (
    <View>
      <View>设备路数: {road} 路</View>
      <View>是否有白光: {hasWhite ? '是' : '否'}</View>
    </View>
  );
}

颜色（useColourData）

Matter 面板下颜色的 value 会由 matter-kit 对齐为 bright_value。推荐直接使用 SDK 的 useColourData，详见 resolveColorData。

import React from 'react';
import { View } from '@ray-js/ray';
import { useColourData, useActions } from '@ray-js/panel-sdk';

export default function ColorControl() {
  const colorData = useColourData(); // { hue, saturation, value }，Matter 下 value 来自 bright_value
  const actions = useActions();

  return (
    <View>
      <View>色相: {colorData?.hue}</View>
      <View>饱和度: {colorData?.saturation}</View>
      <View>亮度: {colorData?.value}</View>
    </View>
  );
}

更多示例（手动 resolveColorData、shouldConvert / debug 等）见 resolveColorData、useOriginMatterTemp、createMatterKit。

与 dp-kit 配合使用

matter-kit 可以与 dp-kit 配合使用，实现更强大的功能：

import { SmartDeviceModel, createMatterKit, createDpKit } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';
import ColourTransformer from '@ray-js/panel-sdk/lib/protocols/lamp/ColourTransformer';

type SmartDeviceSchema = typeof defaultSchema;

const matterKit = createMatterKit();
const dpKit = createDpKit<SmartDeviceSchema>({
  protocols: {
    colour_data: new ColourTransformer(),
  },
  sendDpOption: {
    immediate: true, // 立即更新状态
  },
});

const options = {
  interceptors: {
    init: {
      ...matterKit.interceptors.init,
      ...dpKit.interceptors.init,
    },
    request: {
      publishDps: [
        ...dpKit.interceptors.request.publishDps,
        ...matterKit.interceptors.request.publishDps,
      ],
    },
    response: dpKit.interceptors.response,
  },
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};

注意：拦截器的顺序很重要。在配合使用时，建议将 dp-kit 的 publishDps 拦截器放在 matter-kit 之前，这样 dp-kit 会先处理标准协议的数据，然后 matter-kit 再将其转换为 Matter 协议。

注意事项

转换精度：色温转换会丢失精度，如需获取原始值，请使用 useOriginMatterTemp。
拦截器顺序：与 dp-kit 配合使用时，注意拦截器的顺序，建议 dp-kit 在前，matter-kit 在后。
Schema 转换：matter-kit 会自动在 schema 中新增标准 DP 功能点（如 switch_led、bright_value 等），同时保留原始的 Matter DP 功能点（如 switch、brightness_control 等），用于路数判断等功能。
颜色数据：Matter 协议的颜色数据由 hs_color_set（色相+饱和度）和 brightness_control（亮度）组成，matter-kit 会自动将其合并为标准协议的 colour_data（HSV 格式）。
调试模式：在生产环境中建议关闭调试模式，避免控制台输出过多日志。参见 createMatterKit。

API 索引

文档	说明
createMatterKit	工厂函数、`CreateMatterKitOptions`（`shouldConvert`、`debug`、`config`）
resolveMatterDevInfo	Matter 设备信息 → 标准 schema
mapMatterDpState	上报/合并：Matter DP 状态 → 标准 DP
mapPublishMatterDps	下发：标准 DP → Matter DP
resolveColorData	颜色解析；推荐 `useColourData`，可选手动 `resolveColorData`
useOriginMatterTemp	读取原始 `color_temp_control`，避免精度损失
checkIsMatterDevice	判断是否为 Matter 面板
checkIsMatterHasWhite	判断是否具备白光能力
getMatterRoad	路数推断（1～5 或 0 未知）
temp2Number / number2Temp	色温卡尔文 ↔ `temp_value` 数值
bright2Number / number2Bright	Matter 亮度 ↔ 标准 `bright_value`
getTempRgb	色温（卡尔文）→ RGB 十六进制字符串（UI 色条等）

#matter-kit

#接入指南

#根据业务场景生成 matter-kit

#使用标准 DP 功能点

#DP 功能点映射关系

#转换说明

#开关控制

#亮度控制

#色温控制

#颜色控制

#使用示例

#基础

#路数

#颜色（useColourData）

#与 dp-kit 配合使用

#注意事项

#API 索引