---
title: Usage
---

# Multi-Device Management Usage

The multi-device management capability is built on `SmartDevicesManager` and the extended `SdmProvider`, enabling management of multiple device instances within a single MiniApp — including reading their state and sending commands independently.

## Relationship with Smart Group Model

**Smart Group Model (SGM)** is for **group devices** manually created through the Tuya App on a device detail page. The group panel is allocated by the Tuya cloud, and developers integrate via `SmartGroupModel` — its behavior is consistent with a single-device panel.

**Multi-Device Management** is fundamentally different: it does not depend on the cloud-side group concept. Instead, it lets you **freely manage** multiple independent device instances within the MiniApp — you can `add` / `batchAdd` any device IDs at any time, and read each device's DP state or send commands independently via multi-device Hooks. Typical use cases include gateway sub-device batch control pages and multi-device linkage panels.

## Relationship with Single Device

- **Single device**: Use [Smart Device Model (SDM)](/en/miniapp/solution-panel/ability/common/sdm/usage) with `SdmProvider value={singleDevice}` for `useProps`, `useDevice`, `useActions`, etc.
- **Multi-Device Management**: Inject `SmartDevicesManager` via `SdmProvider`'s `deviceManager` and use multi-device Hooks: `useDevices`, `useDevicesProps`, `useDevicesActions`, etc. See [Multi-Device Management - Hooks](/en/miniapp/solution-panel/ability/common/multi-device/hooks/useDevices). For TypeScript type inference and more, see [FAQ](/en/miniapp/solution-panel/ability/common/multi-device/faq).

## SdmProvider Multi-Device Setup

In multi-device mode, pass a `deviceManager` (`SmartDevicesManager` instance) to the root provider. Use `isNeedMainDeviceInitialized` and `isNeedAllDevicesInitialized` to control when to render children after initialization.

```tsx | pure
import React, { useEffect } from 'react';
import { SdmProvider, SmartDevicesManager } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();

export default function App({ children }) {
  useEffect(() => {
    deviceManager.init();
    return () => {
      deviceManager.destroy();
    };
  }, []);

  return (
    <SdmProvider
      deviceManager={deviceManager}
      isNeedMainDeviceInitialized={false}
      isNeedAllDevicesInitialized={false}
    >
      {children}
    </SdmProvider>
  );
}
```

<Callout type="info" emoji="ℹ️">
  With `isNeedAllDevicesInitialized={true}`, SdmProvider waits until all added devices are initialized before rendering children. With `false`, children render immediately. Enable this when the device list is known upfront; set to `false` when the number of devices is dynamic.
</Callout>

## Typical Scenarios

### Scenario 1: All device IDs available at launch

Suitable for gateway sub-device batch control pages — call `batchAdd` at launch:

```tsx | pure
import { SmartDevicesManager, SdmProvider } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();

deviceManager.batchAdd([
  { key: 'lamp1', deviceId: 'xxx_device_id_1' },
  { key: 'lamp2', deviceId: 'xxx_device_id_2' },
]);
```

### Scenario 2: Main device first, sub-devices loaded asynchronously

Initialize the main device separately and pass it via `value`; add sub-devices via `add` / `batchAdd` asynchronously:

```tsx | pure
import { SmartDeviceModel, SmartDevicesManager, SdmProvider } from '@ray-js/panel-sdk';

const mainDevice = new SmartDeviceModel({ deviceId: 'main_device_id' });
const deviceManager = new SmartDevicesManager();

export default function App({ children }) {
  useEffect(() => {
    mainDevice.init();
    deviceManager.init();
    fetchSubDeviceIds().then(ids => {
      deviceManager.batchAdd(ids.map((deviceId, i) => ({ key: `sub${i}`, deviceId })));
    });
    return () => { deviceManager.destroy(); };
  }, []);

  return (
    <SdmProvider
      value={mainDevice}
      deviceManager={deviceManager}
      isNeedMainDeviceInitialized
      isNeedAllDevicesInitialized={false}
    >
      {children}
    </SdmProvider>
  );
}
```

For API details, see [Multi-Device Management - API](/en/miniapp/solution-panel/ability/common/multi-device/api/constructor) (add, delete, batchAdd, batchDelete).