Device SupportGroup Support

useStructuredActions()

Requires:
@ray-js/panel-sdk≥1.10.0
Additional notesRead the full notes
Implemented based on the sdm instance and the dp-kit interceptor. Must be used inside SdmProvider.
Before using, ensure the project has mounted SdmProvider; see Smart Device Model - Usage. New projects can start from the public-sdm example.
Ensure the dp-kit interceptor has been configured; see Interceptors - Usage.
Only send methods for DPs with protocol rules are returned; basic-type DPs are excluded (use useActions for basic types).
Supports both single devices (SmartDeviceModel) and groups (SmartGroupModel). Symmetric with useStructuredProps: useStructuredProps reads structured data via Transformer.parser(), while useStructuredActions formats structured data into DP commands via Transformer.formatter().

Description

Get the collection of structured DP send methods after dp-kit protocol transformation

Parameters

None

Return Value

Type: Record<DpCode, { set: (value: object, options?: SendDpOption) => Promise<boolean> }>
A collection of structured DP send methods. The key is a DP code configured with protocols; each key provides a set(structuredValue) method. The input type of set is determined by the parameter type of the corresponding Transformer.formatter(); internally it calls formatter to convert structured data to a DP string before sending to the device

Referenced Types

typeSendDpOptionDP send options. Can be used as the global default configuration for createDpKit, and can also be overridden in a single publishDps/action call. The global `sendDpOption` suits product-level defaults; options passed for a single send are suitable for temporarily overriding throttling, debouncing, protocol parsing, or optimistic update strategies. Note: requires the dp-kit interceptor.
PropertyTypeDescriptionSince
immediatebooleanWhether to trigger a state update immediately; requires the dp-kit interceptor-
Whether to ignore DP reports; default falsev1.11.0
Whether to sync dpData with cloud device properties; default falsev1.11.0
orderedbooleanWhether to send multiple DPs in the order of the object’s keys; requires the dp-kit interceptor; default false-
checkRepeatbooleanWhether to check for duplicate values and skip sending; requires the dp-kit interceptor; default false
Compared with the current `dpState`; duplicates are detected and not sent		-
delaynumberDelayed send; requires the dp-kit interceptor; default 0, in ms-
throttlenumberSend throttling (conflicts with debounce); requires the dp-kit interceptor; default 0, in ms-
debouncenumberSend debounce (conflicts with throttle); requires the dp-kit interceptor; default 0, in ms-
A per-call DP protocol converter; requires the dp-kit interceptor.
The key is the dpCode and the value is a `{ parser, formatter }` object:
- parser(dpValue: string) => any — parses the raw DP string into a structured object
- formatter(parsedValue: any) => string — serializes the structured object into a DP string
Affects only this invocation and does not override the global protocols configuration in createDpKit		-
typeIgnoreDpChangeInterceptorOptionsConfiguration option to ignore the DP data change interceptor Used to configure the debounce mechanism for DP reporting events on the device panel, preventing immediate responses after panel operations from affecting user experience or business logic
PropertyTypeDescription
whiteDpCodesstring[]DP whitelist; reports will not be ignored
timeoutnumberDebounce timeout check, in milliseconds, default 5000
- The maximum time between sending a DP from the panel and receiving the DP reply; dpDataChange is triggered only if this is exceeded.
- Used to debounce DP reporting events
Custom ignore rules
> Highest priority; when configured, whiteDpCodes and timeout become ineffective
typeDevPropInterceptorOptions
PropertyTypeDescription
blackDpCodesstring[]DP blacklist; will not be synchronized to the cloud
Default device state on first entry; supports async initialization
throttlenumberSend throttling, in milliseconds, defaults to 0
If set to 0, throttling is disabled.
typeDpStateDatapoint status object, where the key is the datapoint code and the value is the datapoint value.
export type DpState = Record<string, DpValue>;
typeDpValueDatapoint value type, which can be boolean, number, or string.
export type DpValue = boolean | number | string;

Examples

Full flow: read + send (using lighting colour_data as an example)

// ---- 1. devices/protocols/index.ts: Instantiate the parser and map it to the DP code ----
import { protocols as sdkProtocols } from '@ray-js/panel-sdk';
import { lampSchemaMap } from '../schema';

export const protocols = {
  [lampSchemaMap.colour_data.code]: new sdkProtocols.ColourTransformer(),
  // ColourTransformer.parser() returns { hue, saturation, value } → read via useStructuredProps
  // ColourTransformer.formatter() accepts { hue, saturation, value } → write via useStructuredActions
};

// ---- 2. devices/index.ts: Create dpKit and pass it to the sdm instance ----
import { SmartDeviceModel, createDpKit } from '@ray-js/panel-sdk';
import { protocols } from '@/devices/protocols';

export const dpKit = createDpKit({ protocols });
export const devices = {
  lamp: new SmartDeviceModel({ interceptors: dpKit.interceptors }),
};

// ---- 3. Page component: Send structured data via useStructuredActions ----
import { View, Text } from '@ray-js/ray';
import { useStructuredProps, useStructuredActions } from '@ray-js/panel-sdk';

export default function Home() {
  // Read: parser() return value determines the type of colour: { hue, saturation, value }
  const colour = useStructuredProps(props => props.colour_data);
  // Write: set() parameter type equals formatter()'s parameter type, both are { hue, saturation, value }
  const actions = useStructuredActions();

  return (
    <View onClick={() => actions.colour_data.set({ hue: 120, saturation: 800, value: 900 })}>
      <Text>Hue: {colour.hue}</Text>
      <Text>Saturation: {colour.saturation}</Text>
      <Text>Value: {colour.value}</Text>
    </View>
  );
}