---
name: "useDevice"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.2.0" }
title: "useDevice - Implemented based on the sdm instance, triggers component re-renders when smart device info, network status, Bluetooth status, and other data change"
summary: "useDevice is a React Hook provided by @ray-js/panel-sdk, implemented based on the SDM instance. You can use a selector function to subscribe to device info (devInfo), network status (network.isConnected), Bluetooth status, and other data. The component automatically re-renders when data changes. Supports a custom equalityFn to control re-rendering (built-in shallow equal). You can get the dpSchema DP model collection (key is dpCode), look up IDs from DP codes via codeIds, or look up codes from IDs via idCodes. In a group environment, GroupInfo is returned instead of DeviceInfo, and you need to handle field differences such as groupId/devId, name/groupName, and online status (deviceList.some vs isCloudOnline). SdmProvider must be mounted before use."
questions:
  - "How to get device information? How to get network status?"
  - "How does the selector function of useDevice subscribe to device.network.isConnected network connection status?"
  - "useDevice has built-in shallow equal comparison. How to use a custom equalityFn to re-render only when specific fields change?"
  - "What is the structure of the object returned by device.dpSchema (key is dpCode, value contains attr, mode, property, etc.)?"
  - "How to use device.devInfo.codeIds from useDevice to get the DP ID corresponding to a DP code?"
  - "What are device.devInfo.idCodes and device.devInfo.codeIds used for respectively in Code/ID lookups?"
  - "In a group environment, useDevice returns GroupInfo instead of DeviceInfo. Which fields need compatibility handling (groupId/devId, name/groupName)?"
  - "How to determine online status in a group environment (deviceList.some(dev => dev.isOnline) vs isCloudOnline)?"
  - "Why must SdmProvider be mounted before using useDevice? Where can I find the public-sdm example project?"
  - "What do ReadonlyDpSchemaList and DeviceData represent in the TypeScript generic signature of useDevice?"
  - "What underlying SDM APIs are associated with useDevice (getDevInfo, getDpSchema, getNetwork, getBluetooth)?"
---

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Device Support</span>
  <span style={{ backgroundColor: '#faad14', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Partial Support</span>
</div>

## useDevice

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

> 💡 Built on the sdm instance. Must be used inside SdmProvider.
> Before use, make sure SdmProvider is mounted in your project. For integration, see [Smart Device Model - Usage](/en/miniapp/solution-panel/ability/common/sdm/usage). For brand-new projects, you can start from the [public-sdm](https://github.com/Tuya-Community/tuya-ray-materials/tree/main/template/PublicSdmTemplate) example project. Online status vs network status (keep them distinct):
> - To determine whether the device is online, use device.devInfo.isOnline (aggregated cloud/local online status).
> - device.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.

### Description

Get device info, DP schema, network status, and Bluetooth status; re-renders the component when data changes. If no selector is provided, returns the full DeviceData and any field change triggers a re-render. It is recommended to always provide a selector to pick only the required fields to optimize rendering performance

### Parameters

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `selector` | `(device: DeviceData) => any;` | No | Selector function; the input is a device data object containing devInfo, dpSchema, network, and bluetooth. The return type is determined by the selector and can be any value |
| `equalityFn` | `(prevDeviceData: DeviceData, nextDeviceData: DeviceData) => boolean;` | No | Custom comparator; returning true prevents re-render |

### Return Value

Type: `DeviceData`

The return type is determined by the selector and can be any value

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

### 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 complete device data

```tsx
import { useDevice } from '@ray-js/panel-sdk';

function Home() {
  const { devInfo, network } = useDevice();
  return <Text>{devInfo.name} - Network: {network.isConnected ? 'Connected' : 'Disconnected'}</Text>;
}
```

#### Subscribe to network status

```tsx
import { useDevice } from '@ray-js/panel-sdk';

function Home() {
  const isConnected = useDevice(device => device.network.isConnected);
  return <Text>Network: {isConnected ? 'Connected' : 'Disconnected'}</Text>;
}
```

#### Custom rerender

```tsx
// Only update when the network connection changes
const network = useDevice(
  device => device.network,
  (prev, next) => prev.isConnected === next.isConnected,
);
```

#### Get the collection of DP models

```tsx
const dpSchema = useDevice(device => device.dpSchema);
// dpSchema: { switch_led: { code, property, type, mode, ... }, ... }
```

#### Cross-lookup DP Code ↔ ID via codeIds / idCodes

```tsx
const devInfo = useDevice(device => device.devInfo);
const dpId = devInfo.codeIds['switch_led'];   // code → id
const dpCode = devInfo.idCodes[1];             // id → code
```

#### Group environment compatibility

```tsx
// In a group, devInfo is actually GroupInfo; some fields need adaptation
import { useDevice } from '@ray-js/panel-sdk';
import { Text, getLaunchOptionsSync } from '@ray-js/ray';

function Home() {
  const isGroup = !!getLaunchOptionsSync()?.query?.groupId;
  const devInfo = useDevice(d => d.devInfo);

  const id = isGroup ? devInfo.groupId : devInfo.devId;
  const name = devInfo.name || (isGroup ? devInfo.groupName : 'Device');
  const isOnline = isGroup
    ? devInfo.deviceList?.some(d => d.isOnline)
    : devInfo.isCloudOnline;

  return <Text>{name}({id}) - {isOnline ? 'Online' : 'Offline'}</Text>;
}
```