useStructuredDevicesActions()

Requires:
@ray-js/panel-sdk≥1.16.0

Description

Get a collection of structured DP action methods for associated devices; must be used with the dp-kit interceptor

Parameters

None

Return Value

Type: DevicesActions
A collection of structured action methods; the key is the device identifier and the value is that device’s structured actions.
Usage is the same as single-device useStructuredActions

Referenced Types

interfaceDevicesActions
interface DevicesActions {
  [key: string]: {
    set: (value: object, options?: SendDpOption) => Promise<boolean>;
  };
}
typeDpValueDatapoint value type, which can be boolean, number, or string.
export type DpValue = boolean | number | string;

Examples

End-to-end flow: configure dp-kit + read + send (using lighting colour_data as an example)

// ---- 1. devices/protocols/index.ts: Instantiate 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 useStructuredDevicesProps
  // ColourTransformer.formatter() accepts { hue, saturation, value } → write via useStructuredDevicesActions
};

// ---- 2. devices/index.ts: Create dpKit and inject into SmartDevicesManager ----
import { createDpKit, SmartDevicesManager } from '@ray-js/panel-sdk';
import { protocols } from '@/devices/protocols';

export const dpKit = createDpKit({ protocols });
export const deviceManager = new SmartDevicesManager();

// Inject dp-kit interceptors during batchAdd
deviceManager.batchAdd([
  { key: 'lamp1', deviceId: 'xxx_device_id_1', interceptors: dpKit.interceptors },
  { key: 'lamp2', deviceId: 'xxx_device_id_2', interceptors: dpKit.interceptors },
]);

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

export default function ColourControl() {
  // Recommended: select only the required state to avoid unnecessary re-renders due to unrelated changes
  const colourData = useStructuredDevicesProps(props => props.lamp1?.colour_data);
  const actions = useStructuredDevicesActions();

  const setHue = (hue: number) => {
    actions.lamp1?.colour_data.set({ ...colourData, hue });
  };

  return (
    <View onClick={() => setHue(120)}>
      <Text>Current hue: {colourData?.hue}</Text>
      <Text>Click to set hue to 120</Text>
    </View>
  );
}