batchAdd – Tuya MiniApp

SmartDevicesManager.batchAdd(configs: AddConfig[], options?: BatchAddOptions)

Requires:

@ray-js/panel-sdk≥1.16.0

Description

Add device instances to the multi-device manager in bulk. It first fetches device info in batch (a single network request), then initializes concurrently according to concurrency; partial failures are supported and the result distinguishes success and failure lists. Each device can configure interceptors and logConfig independently.

Parameters

Parameter	Type	Required	Description
		Yes	List of device configs
		No	Configuration options

Return Value

Type: Promise<BatchAddResult>

Result object containing success and failed; success is a map of successfully initialized device instances, failed is a list of devices that failed to initialize

Referenced Types

typeBatchAddResult

Property	Type	Description
`success`	Record<string, SmartDeviceModel>	Mapping of successfully initialized device instances
`failed`	FailedDeviceInfo[]	List of devices that failed to initialize

typeInitDpStateInterceptor

export type InitDpStateInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = InitDpStateInterceptorParams
> = Interceptor<S, P, InitDpStateInterceptorParams>;

typeInitDevInfoInterceptor

export type InitDevInfoInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = {
    devInfo: GetSmartDeviceModelDevInfo<any>;
    action: InitDevInfoInterceptorAction;
  }
> = Interceptor<
  S,
  P,
  {
    devInfo: GetSmartDeviceModelDevInfo<any>;
    action: InitDevInfoInterceptorAction;
  }
>;

typeOnDpDataChangeInterceptor

export type OnDpDataChangeInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = DpDataChangeParams
> = Interceptor<S, P, DpDataChangeParams>;

typeOnDeviceOnlineStatusUpdateInterceptor

export type OnDeviceOnlineStatusUpdateInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = DeviceOnlineStatusUpdateParams
> = Interceptor<S, P, DeviceOnlineStatusUpdateParams>;

typeOnDeviceInfoUpdatedInterceptor

export type OnDeviceInfoUpdatedInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = DeviceInfoUpdatedParams
> = Interceptor<S, P, DeviceInfoUpdatedParams>;

typeOnNetworkStatusChangeInterceptor

export type OnNetworkStatusChangeInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = NetworkStatusChangeParams
> = Interceptor<S, P, NetworkStatusChangeParams>;

typeOnBluetoothAdapterStateChangeInterceptor

export type OnBluetoothAdapterStateChangeInterceptor<
  S extends ReadonlyDpSchemaList = any,
  P = BluetoothAdapterStatusChangeParams
> = Interceptor<S, P, BluetoothAdapterStatusChangeParams>;

typeInitDpStateInterceptorParams

Property	Type	Required	Description
		Yes	Current device DP state
		Yes	New device DP state
`action`	"init" \| "onDpDataChange" \| "onDeviceInfoUpdated" \| "dp-kit"	Yes	Interceptor action

typeGetSmartDeviceModelDevInfo

Property	Type	Required
`dpCodes`	object	Yes
`dps`	object	Yes
`idCodes`	object	Yes
`codeIds`	object	Yes
`schema`	S	Yes

typeSmartDeviceModelAbilityContainer type for SmartDeviceModel abilities, used only for generic constraints and internal composition.

export type SmartDeviceModelAbility<A extends SmartDeviceAbility = SmartDeviceAbility> = {
  [abilityName: string]: A;
};

typePublishDpsOptionsUnderlying option type of publishDps, reused by the SDK’s internal request chain.

Property	Type	Required	Description
		No

typeDpValueDatapoint value type, which can be boolean, number, or string.

export type DpValue = boolean | number | string;

typeSendDpOptionDP send options. Can be used as the global default configuration for createDpKit, and can also be overridden in a single publishDps/action call. The global `sendDpOption` suits product-level defaults; options passed for a single send are suitable for temporarily overriding throttling, debouncing, protocol parsing, or optimistic update strategies. Note: requires the dp-kit interceptor.

Property	Type	Required	Description	Since
`immediate`	boolean	No	Whether to trigger a state update immediately; requires the dp-kit interceptor	-
		No	Whether to ignore DP reports; default false	v1.11.0
		No	Whether to sync dpData with cloud device properties; default false	v1.11.0
`ordered`	boolean	No	Whether to send multiple DPs in the order of the object’s keys; requires the dp-kit interceptor; default false	-
`checkRepeat`	boolean	No	Whether to check for duplicate values and skip sending; requires the dp-kit interceptor; default false Compared with the current `dpState`; duplicates are detected and not sent	-
`delay`	number	No	Delayed send; requires the dp-kit interceptor; default 0, in ms	-
`throttle`	number	No	Send throttling (conflicts with debounce); requires the dp-kit interceptor; default 0, in ms	-
`debounce`	number	No	Send debounce (conflicts with throttle); requires the dp-kit interceptor; default 0, in ms	-
		No	A per-call DP protocol converter; requires the dp-kit interceptor. The key is the dpCode and the value is a `{ parser, formatter }` object: - parser(dpValue: string) => any — parses the raw DP string into a structured object - formatter(parsedValue: any) => string — serializes the structured object into a DP string Affects only this invocation and does not override the global protocols configuration in createDpKit	-

typeCapability

export type Capability = number;

typeDevAttribute

export type DevAttribute = number;

Valid Values

`DevInfo.schema.mode`

Value	Description	Since
`rw`	-	-
`ro`	-	-
`wr`	-	-

`DevInfo.schema.property.type`

Value	Description	Since
`string`	-	-
`bool`	-	-
`value`	-	-
`enum`	-	-
`bitmap`	-	-
`raw`	-	-

`DevInfo.schema.type`

Value	Description	Since
`raw`	-	-
`obj`	-	-

`FunConfig.tyabirysr4_app`

Value	Description	Since
`follow`	-	-
`--app-B1`	-	-

`FunConfig.tyabis5d9w_app`

Value	Description	Since
`follow`	-	-
`--app-M1`	-	-

`LogConfig.level`

Value	Description	Since
`VERBOSE`	-	-
`SUCCESS`	-	-
`INFO`	-	-
`WARN`	-	-
`FATAL`	-	-

Examples

Add devices in bulk

import { SmartDevicesManager, createDpKit } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();
const dpKit = createDpKit({ protocols });

const result = await deviceManager.batchAdd([
  {
    key: 'lamp1',
    deviceId: 'xxx_device_id_1',
    interceptors: dpKit.interceptors, // Use structured DP with dp-kit
  },
  {
    key: 'lamp2',
    deviceId: 'xxx_device_id_2',
    interceptors: dpKit.interceptors,
    logConfig: { level: 'VERBOSE' }, // Enable detailed logs for this device only
  },
  {
    key: 'failedDevice',
    deviceId: 'invalid_device_id',
  },
], { concurrency: 5 });

if (result.failed.length > 0) {
  console.warn('Some devices failed to initialize:', result.failed);
}
// batchAdd return example:
{
  "success": {
    "lamp1": "<SmartDeviceModel>",
    "lamp2": "<SmartDeviceModel>"
  },
  "failed": [
    {
      "key": "failedDevice",
      "deviceId": "invalid_device_id",
      "error": "Device info not found for invalid_device_id"
    }
  ]
}