useDevices(selector?: (devicesData: { [key: string]: DeviceData }) => any;, equalityFn?: (prev: any, next: any) => boolean;)

Requires:
@ray-js/panel-sdk≥1.16.0
Additional notesRead the full notes
Before use, mount SdmDevicesProvider and configure the associated device mapping. Online status vs network status (keep them distinct):
- To determine whether a specific device is online, use devices.main?.devInfo?.isOnline (aggregated cloud/local online status).
- devices.main?.network reflects the current phone’s network environment (shared by all devices). isConnected indicates whether the phone is connected to the internet, and networkType is the network type; it does not include device online information and has no isOnline field. Performance optimization (best practices):
1. Always use a selector to precisely pick data, e.g., useDevices(devices => devices.main?.network), to ensure components re-render only when the dependent data changes.
2. For derived computations and other complex scenarios, use equalityFn to customize comparison logic and block unnecessary renders.
3. If you want devicesData.lamp1, devicesData.lamp2, etc., to get full DP type inference, see Multi-device management - FAQ.

Description

Get the state collection for the associated device instance list. If selector is not provided, returns the complete device data set, and any state change in any device will trigger a rerender. It is strongly recommended to always pass a selector to pick only the required properties, or provide a custom equalityFn to optimize rendering performance and avoid unnecessary rerenders.

Parameters

ParameterTypeRequiredDescription
selector(devicesData: { [key: string]: DeviceData }) => any;NoSelector function. The input is the state collection object for all associated devices. Keys are device identifiers, and values contain four properties: devInfo, dpSchema, network, bluetooth
equalityFn(prev: any, next: any) => boolean;NoCustom comparison function; if it returns true, re-render is not triggered; default is shallow equal

Return Value

Type: any
Device state selected by the selector; type is inferred from the selector’s return value

Referenced Types

typeDeviceData
PropertyTypeRequiredDescription
YesDevice information (includes codeIds/idCodes for DP Code ↔ ID cross‑lookup)
YesCollection of DP models (keyed by dpCode)
YesThe current phone’s network connection status (shared by all devices; not the device’s online status; to check whether a device is online, see devInfo.isOnline)
bluetooth{ available: boolean; }YesBluetooth adapter status
typeDevInfoDevice information
PropertyTypeRequiredDescription
YesMapping of dp id to dp code
YesMapping of dp code to dp id
capabilityCapabilityYesProduct communication capability bit flags, determined via bitwise operations, such as Wi‑Fi, Bluetooth, ZigBee, SigMesh, etc.

- Wi‑Fi (bit 0, decimal value: 1): Wi‑Fi
- Cable (bit 1, decimal value: 2): Wired
- GPRS (bit 2, decimal value: 4): similar to 2G networks
- NB‑IoT (bit 3, decimal value: 6): IoT SIM network
- Bluetooth (bit 10, decimal value: 1024): Bluetooth point‑to‑point
- BLEMesh (bit 11, decimal value: 2048): proprietary Bluetooth mesh
- ZigBee (bit 12, decimal value: 4096): 2.4 GHz band
- Infrared (bit 13, decimal value: 8192): Infrared
- 433 (subpieces) (bit 14, decimal value: 16384): 433 MHz
- SigMesh (bit 15, decimal value: 32768): Bluetooth standard mesh
- MCU (bit 16, decimal value: 65536): MCU
- SMesh (bit 17, decimal value: 131072): similar to ZigBee
- Cat1 (bit 20, decimal value: 1048576): usually uses 3G networks
- Beacon (bit 21, decimal value: 2097152): Bluetooth Beacon
- Thread (bit 25, decimal value: 33554432): Thread capability
devAttributeDevAttributeYesDevice capability bit flags, reported by firmware
Bit meanings:
- Bit 0: Whether the device supports zero‑config networking
- Bit 1: Device supports dp query protocol 31
- Bit 2: Whether the device has local automation capability
- Bit 3: Whether the device supports Wi‑Fi scanning
- Bit 4: Whether the device supports Google Local Home
- Bit 5: Whether the device supports fast provisioning
- Bit 6: Whether the device supports Bluetooth control
- Bit 7: Whether the device supports security capability
- Bit 8: Whether the device is a shared device
- Bit 9: Whether the device supports sunrise/sunset scheduling
- Bit 10: Whether the device supports fault replacement capability
- Bit 11: Whether the device supports OTA
- Bit 12: Whether the device supports Wi‑Fi backup switchover
- Bit 14: Device supports the Tuya standard protocol
- Bit 15: Device supports custom passthrough
- Bit 16: Whether the device supports industry capabilities
YesProduct information, including schema and function definitions
YesPanel cloud configuration
interfaceDpSchema
PropertyTypeRequiredDescription
attrnumberNoDP attribute flag bit, used to mark additional capabilities of the DP
canTriggerbooleanNoWhether it can be used as an automation trigger condition
codestringYesDP code, e.g., switch
defaultRecommendbooleanNoWhether it is the default recommended DP
editPermissionbooleanNoWhether it has edit permission
executablebooleanNoWhether it can be issued (sent downstream)
extContentstringNoDP extension content, typically a JSON string
iconnamestringNoDP icon name
idstring | numberYesDP ID
mode"rw" | "ro" | "wr"YesDP mode type
rw: writable and reportable (read/write)
ro: report-only (read-only)
wr: write-only
namestringYesDP name, typically used in voice scenarios
NoDP attributes
type"raw" | "obj"YesDP data type categories: raw for raw byte stream, obj for structured object
interfaceNetworkState
PropertyTypeRequiredDescription
isConnectedbooleanYesWhether connected
networkTypestringYesNetwork type: WIFI | 5G | 4G | 3G | 2G | GPRS | UNKNOWN | NONE
signalStrengthnumberYesSignal strength, unit: dBm
typeCapability
export type Capability = number;
typeDevAttribute
export type DevAttribute = number;
interfacePanelConfig
PropertyTypeRequiredDescription
YesCloud scheduling and navigation link configuration
NoFeature configuration
interfaceJumpUrlConfig
PropertyTypeRequiredDescription
code"jump_url"YesNavigation link config code
descriptionstringYesNavigation link config description
namestringYesNavigation link config name
selectedbooleanYesWhether the navigation link config is selected
interfaceTimerConfig
PropertyTypeRequiredDescription
code"timer"YesCloud schedule config code
descriptionstringYesCloud schedule config description
namestringYesCloud schedule config name
selectedbooleanYesWhether the cloud schedule config is selected
interfaceFunConfig
PropertyTypeRequiredDescription
tyabirysr4stringYesBackground color, currently supported only in the Tuya official mini program
tyabirysr4_app"follow" | "--app-B1"YesBackground color follow strategy: 'follow' means inherit from the App; otherwise, specify the App variable path to replace. Currently supported only in the Tuya official mini program
tyabis5d9wstringYesTheme color, currently supported only in the Tuya official mini program
tyabis5d9w_app"follow" | "--app-M1"YesTheme color follow strategy: 'follow' means inherit from the App; otherwise, specify the App variable path to replace. Currently supported only in the Tuya official mini program

Examples

Get the online status of the specified device

import { useDevices } from '@ray-js/panel-sdk';

function DeviceOnlineStatus() {
  // Whether the device is online depends on devInfo.isOnline; re-renders only when the main device's online status changes
  const isOnline = useDevices(devices => devices.main?.devInfo?.isOnline);
  return <Text>Device online: {isOnline ? 'Yes' : 'No'}</Text>;
}

Get the current phone’s network status

import { useDevices } from '@ray-js/panel-sdk';

function PhoneNetworkStatus() {
  // network reflects the current phone's network environment (shared by all devices), not a specific device's online status
  const network = useDevices(devices => devices.main?.network);
  return (
    <Text>
      Network: {network?.networkType} ({network?.isConnected ? 'Connected' : 'Disconnected'})
    </Text>
  );
}

Custom rerender strategy

import { useDevices } from '@ray-js/panel-sdk';

function PhoneNetworkStatus() {
  // Only updates when the phone's network connection status actually changes; jitter in networkType/signal strength won't trigger re-render
  const network = useDevices(
    devices => devices.main?.network,
    (prev, next) => prev?.isConnected === next?.isConnected
  );
  return <Text>Network connected: {network?.isConnected ? 'Yes' : 'No'}</Text>;
}

Get basic information for all devices

import { useDevices } from '@ray-js/panel-sdk';

function DeviceList() {
  const allDevices = useDevices();
  return (
    <View>
      {Object.entries(allDevices).map(([key, data]) => (
        <Text key={key}>{data.devInfo.name}</Text>
      ))}
    </View>
  );
}