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.
- 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
| Parameter | Type | Required | Description |
|---|---|---|---|
selector | (devicesData: { [key: string]: DeviceData }) => any; | No | Selector 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; | No | Custom 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
type
DeviceData| Property | Type | Required | Description |
|---|---|---|---|
| Yes | Device information (includes codeIds/idCodes for DP Code ↔ ID cross‑lookup) | ||
| Yes | Collection of DP models (keyed by dpCode) | ||
| Yes | The 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; } | Yes | Bluetooth adapter status |
type
DevInfoDevice information| Property | Type | Required | Description |
|---|---|---|---|
| Yes | Mapping of dp id to dp code | ||
| Yes | Mapping of dp code to dp id | ||
capability | Capability | Yes | Product 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 |
devAttribute | DevAttribute | Yes | Device 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 |
| Yes | Product information, including schema and function definitions | ||
| Yes | Panel cloud configuration |
interface
DpSchema| Property | Type | Required | Description |
|---|---|---|---|
attr | number | No | DP attribute flag bit, used to mark additional capabilities of the DP |
canTrigger | boolean | No | Whether it can be used as an automation trigger condition |
code | string | Yes | DP code, e.g., switch |
defaultRecommend | boolean | No | Whether it is the default recommended DP |
editPermission | boolean | No | Whether it has edit permission |
executable | boolean | No | Whether it can be issued (sent downstream) |
extContent | string | No | DP extension content, typically a JSON string |
iconname | string | No | DP icon name |
id | string | number | Yes | DP ID |
mode | "rw" | "ro" | "wr" | Yes | DP mode type rw: writable and reportable (read/write) ro: report-only (read-only) wr: write-only |
name | string | Yes | DP name, typically used in voice scenarios |
| No | DP attributes | ||
type | "raw" | "obj" | Yes | DP data type categories: raw for raw byte stream, obj for structured object |
interface
NetworkState| Property | Type | Required | Description |
|---|---|---|---|
isConnected | boolean | Yes | Whether connected |
networkType | string | Yes | Network type: WIFI | 5G | 4G | 3G | 2G | GPRS | UNKNOWN | NONE |
signalStrength | number | Yes | Signal strength, unit: dBm |
type
Capabilitytype
DevAttributeinterface
PanelConfig| Property | Type | Required | Description |
|---|---|---|---|
| Yes | Cloud scheduling and navigation link configuration | ||
| No | Feature configuration |
interface
JumpUrlConfig| Property | Type | Required | Description |
|---|---|---|---|
code | "jump_url" | Yes | Navigation link config code |
description | string | Yes | Navigation link config description |
name | string | Yes | Navigation link config name |
selected | boolean | Yes | Whether the navigation link config is selected |
interface
TimerConfig| Property | Type | Required | Description |
|---|---|---|---|
code | "timer" | Yes | Cloud schedule config code |
description | string | Yes | Cloud schedule config description |
name | string | Yes | Cloud schedule config name |
selected | boolean | Yes | Whether the cloud schedule config is selected |
interface
FunConfig| Property | Type | Required | Description |
|---|---|---|---|
tyabirysr4 | string | Yes | Background color, currently supported only in the Tuya official mini program |
tyabirysr4_app | "follow" | "--app-B1" | Yes | Background 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 |
tyabis5d9w | string | Yes | Theme color, currently supported only in the Tuya official mini program |
tyabis5d9w_app | "follow" | "--app-M1" | Yes | Theme 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 |