---
name: "useDevices"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.16.0" }
title: "useDevices"
---

## useDevices

> [VERSION] @ray-js/panel-sdk >= 1.16.0

> 💡 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](/en/miniapp/solution-panel/ability/common/multi-device/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

`Params`

| 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 | Description |
| --- | --- | --- |
| `devInfo` | `DevInfo` | Device information (includes codeIds/idCodes for DP Code ↔ ID cross‑lookup) |
| `dpSchema` | `DpSchema` | Collection of DP models (keyed by dpCode) |
| `network` | `NetworkState` | 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; }` | Bluetooth adapter status |

##### `type` DevInfo

Device information

| Property | Type | Description |
| --- | --- | --- |
| `idCodes` | `Record<string, string>` | Mapping of dp id to dp code |
| `codeIds` | `Record<string, string>` | Mapping of dp code to dp id |
| `capability` | `Capability` | 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` | 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 |
| `schema` | `DpSchema[]` | Product information, including schema and function definitions |
| `panelConfig` | `PanelConfig` | Panel cloud configuration |

##### `interface` DpSchema

| Property | Type | Description |
| --- | --- | --- |
| `attr` | `number` | DP attribute flag bit, used to mark additional capabilities of the DP |
| `canTrigger` | `boolean` | Whether it can be used as an automation trigger condition |
| `code` | `string` | DP code, e.g., switch |
| `defaultRecommend` | `boolean` | Whether it is the default recommended DP |
| `editPermission` | `boolean` | Whether it has edit permission |
| `executable` | `boolean` | Whether it can be issued (sent downstream) |
| `extContent` | `string` | DP extension content, typically a JSON string |
| `iconname` | `string` | DP icon name |
| `id` | `string \| number` | DP ID |
| `mode` | `"rw" \| "ro" \| "wr"` | DP mode type rw: writable and reportable (read/write) ro: report-only (read-only) wr: write-only |
| `name` | `string` | DP name, typically used in voice scenarios |
| `property` | `Object` | DP attributes |
| `type` | `"raw" \| "obj"` | DP data type categories: raw for raw byte stream, obj for structured object |

##### `interface` NetworkState

| Property | Type | Description |
| --- | --- | --- |
| `isConnected` | `boolean` | Whether connected |
| `networkType` | `string` | Network type: WIFI \| 5G \| 4G \| 3G \| 2G \| GPRS \| UNKNOWN \| NONE |
| `signalStrength` | `number` | Signal strength, unit: dBm |

##### `type` GetSmartDeviceModelDevInfo

| Property | Type | Description |
| --- | --- | --- |
| `dpCodes` | `object` |  |
| `dps` | `object` |  |
| `idCodes` | `object` |  |
| `codeIds` | `object` |  |
| `schema` | `S` |  |

##### `type` Capability

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 wireless
- Cable (bit 1, decimal value: 2): Wired
- GPRS (bit 2, decimal value: 4): 2G-like network
- NB-IoT (bit 3, decimal value: 6): IoT SIM network
- Bluetooth (bit 10, decimal value: 1024): Single-point Bluetooth
- 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): Standard Bluetooth 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 network
- Beacon (bit 21, decimal value: 2097152): Bluetooth Beacon
- Thread (bit 25, decimal value: 33554432): Thread capability

```typescript
export type Capability = number;
```

##### `type` DevAttribute

Device capability bitmask, reported by firmware

Bit meanings:
- Bit 1 (bit 0): Whether the device supports zero-configuration networking
- Bit 2 (bit 1): Device supports dp query protocol 31
- Bit 3 (bit 2): Whether the device has local linkage capability
- Bit 4 (bit 3): Whether the device supports Wi-Fi scanning
- Bit 5 (bit 4): Whether the device supports Google Local Home
- Bit 6 (bit 5): Whether the device supports fast provisioning (Lightning pairing)
- Bit 7 (bit 6): Whether the device supports Bluetooth control
- Bit 8 (bit 7): Whether the device supports security capabilities
- Bit 9 (bit 8): Whether the device is a shared device
- Bit 10 (bit 9): Whether the device supports sunrise/sunset scheduling
- Bit 11 (bit 10): Whether the device supports fault replacement capability
- Bit 12 (bit 11): Whether the device supports OTA
- Bit 13 (bit 12): Whether the device supports Wi-Fi backup switchover
- Bit 15 (bit 14): Device supports the Tuya standard protocol
- Bit 16 (bit 15): Device supports custom passthrough
- Bit 17 (bit 16): Whether the device supports industry capabilities

```typescript
export type DevAttribute = number;
```

##### `interface` PanelConfig

| Property | Type | Description |
| --- | --- | --- |
| `bic` | `CloudConfig[]` | Cloud scheduling and navigation link configuration |
| `fun` | `FunConfig` | Feature configuration |

##### `type` DpId

```typescript
type DpId = number;
```

##### `interface` JumpUrlConfig

| Property | Type | Description |
| --- | --- | --- |
| `code` | `"jump_url"` | Navigation link config code |
| `description` | `string` | Navigation link config description |
| `name` | `string` | Navigation link config name |
| `selected` | `boolean` | Whether the navigation link config is selected |

##### `interface` TimerConfig

| Property | Type | Description |
| --- | --- | --- |
| `code` | `"timer"` | Cloud schedule config code |
| `description` | `string` | Cloud schedule config description |
| `name` | `string` | Cloud schedule config name |
| `selected` | `boolean` | Whether the cloud schedule config is selected |

##### `interface` FunConfig

| Property | Type | Description |
| --- | --- | --- |
| `tyabirysr4` | `string` | Background color, currently supported only in the Tuya official mini program |
| `tyabirysr4_app` | `"follow" \| "--app-B1"` | 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` | Theme color, currently supported only in the Tuya official mini program |
| `tyabis5d9w_app` | `"follow" \| "--app-M1"` | 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 |

##### `interface` CloudConfig

| Property | Type | Description |
| --- | --- | --- |
| `jump_url` | `JumpUrlConfig` | Navigation link configuration |
| `timer` | `TimerConfig` | Cloud scheduling configuration |

##### `type` DpSchema.property

| Property | Type | Description |
| --- | --- | --- |
| `type` | `"string" \| "bool" \| "value" \| "enum" \| "bitmap" \| "raw"` | DP type |
| `range` | `string[] \| string[]` | Enum value range; present only when type = enum |
| `label` | `string[] \| string[]` | Fault label list; present only when type = bitmap |
| `maxlen` | `number` | Maximum length for fault bitmap; present only when type = bitmap |
| `unit` | `string` | Unit (type = value only) |
| `min` | `number` | Minimum value (type = value only) |
| `max` | `number` | Maximum value (type = value only) |
| `scale` | `number` | Precision (type = value only) |
| `step` | `number` | Step (type = value only) |


### Examples

#### Get the online status of the specified device

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

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

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

```tsx
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>
  );
}
```