#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) 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. For TypeScript type inference and more, see 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.

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

#Typical Scenarios

#Scenario 1: All device IDs available at launch

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

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:

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 (add, delete, batchAdd, batchDelete).