---
title: matter-kit overview
summary: matter-kit is an SDM interceptor toolkit in @ray-js/panel-sdk (1.15.0+) for lighting devices. Use createMatterKit for Matter ↔ standard DP conversion; composable with dp-kit.
questions:
  - From which @ray-js/panel-sdk version is matter-kit available, and which device category is supported?
  - What are the four core Matter ↔ standard DP mappings?
  - How should publishDps interceptors be ordered when combining with dp-kit?
  - Which hook reads the original color temperature when conversion loses precision?
---

# matter-kit

<Alert type="info">
matter-kit added since @ray-js/panel-sdk@1.15.0. Currently only **lighting category** devices are supported.
</Alert>

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](#api-index) below for links to each child page.

## Integration Guide

### Generate matter-kit Based on Business Scenarios

> src/devices/index.ts

```ts | pure
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.

```tsx | pure
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:

| Matter protocol        | Standard protocol | Description                                      |
| ---------------------- | ----------------- | ------------------------------------------------ |
| `switch`               | `switch_led`      | Power control                                    |
| `brightness_control`   | `bright_value`    | Brightness (1-254 → 10-1000)                   |
| `color_temp_control`   | `temp_value`      | Color temperature (Kelvin → 0-1000)            |
| `hs_color_set`         | `colour_data`     | Color (hue+saturation → HSV)                     |

### 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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/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

```tsx | pure
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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getMatterRoad).

```tsx | pure
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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData).

```tsx | pure
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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData), [useOriginMatterTemp](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp), [createMatterKit](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit) (`shouldConvert` / `debug`).

## Use with dp-kit

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

```ts | pure
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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/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](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit).

## API index

| Page | Description |
| ---- | ----------- |
| [createMatterKit](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit) | Factory and `CreateMatterKitOptions` (`shouldConvert`, `debug`, `config`) |
| [resolveMatterDevInfo](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveMatterDevInfo) | Matter device info → standard schema |
| [mapMatterDpState](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/mapMatterDpState) | Report/merge: Matter DP state → standard DP |
| [mapPublishMatterDps](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/mapPublishMatterDps) | Publish: standard DP → Matter DP |
| [resolveColorData](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData) | Color parsing; prefer `useColourData`, optional manual `resolveColorData` |
| [useOriginMatterTemp](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp) | Read raw `color_temp_control` |
| [checkIsMatterDevice](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/checkIsMatterDevice) | Detect Matter panel |
| [checkIsMatterHasWhite](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/checkIsMatterHasWhite) | Detect white-light capability |
| [getMatterRoad](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getMatterRoad) | Road count (1–5 or 0 unknown) |
| [temp2Number](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/temp2Number) / [number2Temp](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/number2Temp) | Kelvin ↔ `temp_value` |
| [bright2Number](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/bright2Number) / [number2Bright](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/number2Bright) | Matter brightness ↔ standard `bright_value` |
| [getTempRgb](/en/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getTempRgb) | Kelvin → RGB hex string (UI gradients) |