#matter-kit

A lightweight Matter device panel DP feature processing toolkit, built-in support for bidirectional conversion between Matter protocol and standard DP protocol, automatically handling device information, DP state reporting, and publishing conversions.

See the API index below for links to each child page.

#Integration Guide

#Generate matter-kit Based on Business Scenarios

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, // Optional: enable debug mode
});

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

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

#Use Standard DP Features

After integrating matter-kit, you can directly use standard DP features for development. matter-kit will automatically handle the conversion between Matter protocol and standard protocol.

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: {power ? 'On' : 'Off'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        Brightness: {bright}
      </View>
      <View onClick={() => actions.temp_value.set(600)}>
        Temperature: {temp}
      </View>
      <View onClick={() => actions.colour_data.set('012502ad02ee')}>
        Color: {colour}
      </View>
    </View>
  );
}

#DP Feature Mapping

matter-kit automatically handles conversion between the following Matter protocol and standard protocol:

#Conversion Details

#Power Control

• Report: switch → switch_led
• Publish: switch_led → switch

#Brightness Control

• Report: brightness_control (1-254) → bright_value (10-1000)
• Publish: bright_value (10-1000) → brightness_control (1-254)

Linear mapping is used to keep ranges consistent.

#Color Temperature Control

• Report: color_temp_control (Kelvin) → temp_value (0-1000)
• Publish: temp_value (0-1000) → color_temp_control (Kelvin)

Nonlinear mapping is used for slider UX.

Note: Color temperature conversion may lose precision. matter-kit keeps the original color_temp_control. For UI that needs the raw value, use useOriginMatterTemp.

#Color Control

• Report: hs_color_set (hue+saturation) + brightness_control (brightness) → colour_data (HSV)
• Publish: colour_data (HSV) → hs_color_set (hue+saturation) + brightness_control (brightness)

#Usage Examples

#Basic

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: {power ? 'On' : 'Off'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        Brightness: {bright}
      </View>
    </View>
  );
}

#Road count

Use schema to infer road count and white capability. See 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: {road}</View>
      <View>Has white: {hasWhite ? 'yes' : 'no'}</View>
    </View>
  );
}

#Color (useColourData)

On Matter panels, color value is aligned with bright_value. Prefer SDK useColourData; see 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 }; on Matter, value comes from bright_value
  const actions = useActions();

  return (
    <View>
      <View>Hue: {colorData?.hue}</View>
      <View>Saturation: {colorData?.saturation}</View>
      <View>Value: {colorData?.value}</View>
    </View>
  );
}

More examples: resolveColorData, useOriginMatterTemp, createMatterKit (shouldConvert / debug).

#Use with dp-kit

matter-kit can be used together with dp-kit to achieve more powerful functionality:

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, // Update state immediately
  },
});

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),
};

Note: Interceptor order matters. Place dp-kit publishDps before matter-kit so dp-kit handles standard protocol first, then matter-kit converts to Matter protocol.

#Notes

1. Precision: For original color temperature, use useOriginMatterTemp.

2. Order: With dp-kit, keep dp-kit before matter-kit on publishDps.

3. Schema: matter-kit adds standard DPs (e.g. switch_led, bright_value) while retaining Matter DPs (e.g. switch, brightness_control) for road detection and similar logic.

4. Color: Matter color uses hs_color_set + brightness_control; matter-kit merges into standard colour_data (HSV).

5. Debug: Disable debug in production to avoid noisy logs. See createMatterKit.

#API index