Sub-device Pairing and Management

This topic describes how to pair, bind, and manage sub-devices.

Pairing modes of base station

The pairing and binding methods of base station products are the same as those of IP camera products. For more information, see Pairing and Binding.

Sub-device management

Basic features

Feature	Description
Header file	tuya_xvr_dev.h
Add sub-devices	The base station adds, binds, and activates sub-devices. That is, send an add command to the cloud to link the base station with the sub-devices.
Delete sub-devices	When users delete a sub-device on the app, the base station is notified to unbind the sub-device and synchronize it to the cloud.
Query sub-devices	Query related sub-device information, such as sub-device channel number and sub-device ID.
Sub-device ID	There are two types, sub-device node IDs and device virtual IDs. Node ID: sub_node_id, specifically refers to the UUID of the sub-device. Device ID: dev_id, the virtual ID displayed in the device information on the app. It is generated by the cloud after the sub-device is added successfully.

The above feature descriptions will not be repeated in the following API descriptions.

Data structure and API description

The main data structures and API descriptions are listed below.

Initialize sub-device management module

Initialize the sub-device management module. This operation will initialize the basic resources of the module.

OPERATE_RET tuya_xvr_dev_init();

Bind and activate sub-devices

Bind and activate the sub-devices. This operation will bind the sub-devices to the base station.

OPERATE_RET tuya_xvr_dev_bind(TUYA_XVR_BIND_CTX_T * bind_ctx_ptr);

Base station proactively unbinds sub-devices

Unbind the sub-devices. This operation will unbind the sub-devices and synchronize the status to the cloud.

OPERATE_RET tuya_xvr_dev_remove_sub_node(CHAR_T* sub_node_id);

Get sub-device dev_id

Get the dev_id of the sub-device based on its node ID.

OPERATE_RET tuya_xvr_dev_get_dev_id_by_sub_node_id(CHAR_T*sub_node_id,CHAR_T*dev_id, INT_T dev_id_buf_len);

Get sub-device ring buffer index

For IP cameras or sub-devices capable of outputting audio and video data, the ring buffer (ringbuf) index is associated with stream preview. This interface gets the ring buffer index of an IPC sub-device by its node ID and is used when writing audio and video data for the ring buffer.

OPERATE_RET tuya_xvr_dev_get_ringbuf_idx_by_sub_node_id(CHAR_T* sub_node_id);

Get sub-device basic information

Get the basic information of the sub-device based on the above ring buffer index. For more information, see the struct TUYA_XVR_DEV_INFO_T.

OPERATE_RET tuya_xvr_dev_get_sub_dev_info_by_ringbuf_idx(INT_T ringbuf_idx,TUYA_XVR_DEV_INFO_T* sub_dev_info)

Get sub-device description

Get the complete information of the sub-device based on the sub-device node ID. For more information, see the struct DEV_DESC_IF_S.

DEV_DESC_IF_S* tuya_xvr_dev_get_sub_dev_desc_info(CHAR_T *sub_node_id)

Subscribe to the sub-device binding result

The interface registers a callback function. The binding status of the sub-device will be pushed through the callback after the binding process completes.

OPERATE_RET tuya_xvr_dev_attach_sub_dev_bind_result_cb(sub_dev_bind_result_cb cb)

Subscribe to the sub-device unbinding notification

The interface registers a callback function to receive notifications when a sub-device is unbound.

OPERATE_RET tuya_xvr_dev_attach_sub_dev_remove_cb(sub_dev_remove_cb cb)

How it works

The above interface methods are all used in the demo. The following section focuses on the calling sequence of module initialization and other steps.

Initialize sub-device module

Initialize the sub-device management module. This needs to be done after the SDK initialization is completed. The recommended initialization sequence is as follows:

Add sub-devices

Add sub-devices. Make sure module initialization is completed and callback functions are configured first. The recommended initialization sequence is as follows:

Sub-device live preview

Functional description

A base station device itself does not generate audio and video data. To enable preview functionality, you must add an IP camera sub-device or other sub-devices capable of outputting audio and video streams.

The base station development kit supports live preview of sub-device audio and video streams. This feature works on top of Tuya’s proprietary peer-to-peer (P2P) technology. A device and a mobile app can establish a secure P2P connection for real-time audio and video communication.

Technical principles

The principles are the same as those of IP cameras. Refer to the following documents:

• Live Preview and Two-Way Talk
• Audio and Video Ring Buffer

In short, after successfully adding an IP camera sub-device, its audio and video streams must be written to the base station’s ring buffer. The system will then automatically transmit audio and video data from the ring buffer to the app.

Compared to standalone IP camera devices, the base station contains multiple ring buffer sub-device channels. Each sub-device must be assigned a unique index. Therefore, you are recommended to get the sub-device’s ring buffer index using interfaces from the sub-device management module. Then, initialize the specified ring buffer channel and write audio and video streams to the channel.

Header file

• tuya_ipc_media_adapter.h
• tuya_ipc_media_stream.h

API description

The following describes the interfaces and parameters of the media adapter and streaming media services. For more information, see the IP camera Audio and Video Ring Buffer.

Initialize media adaptation layer

Initialize the media adapter and set certain callback interfaces.

OPERATE_RET tuya_ipc_media_adapter_init(TUYA_IPC_MEDIA_ADAPTER_VAR_T *p_var);

typedef struct {
    MEDIA_GET_SNAPSHOT_CB get_snapshot_cb;      // Image capture callback
    MEDIA_RECV_VIDEO_CB on_recv_video_cb;       // Video reception callback
    MEDIA_RECV_AUDIO_CB on_recv_audio_cb;       // Audio reception callback
    MEDIA_RECV_FILE_CB on_recv_file_cb;         // File reception callback
    INT_T available_media_memory;               // Maximum media memory resources. P2P single-channel preview occupies 1 MB of memory
} TUYA_IPC_MEDIA_ADAPTER_VAR_T;

Initialize streaming service

Initialize streaming services, including live preview, streaming, and control signaling callbacks.

OPERATE_RET tuya_ipc_media_stream_init(MEDIA_STREAM_VAR_T *stream_var);

typedef struct {
    MEDIA_STREAM_EVENT_CB on_event_cb;    // Media event callback
    INT_T max_client_num;                 // Maximum number of sub-device previews
    TRANS_DEFAULT_QUALITY_E def_live_mode; // Default preview quality
    BOOL_T low_power;            // Low power
    BOOL_T lan_only_mode;        // LAN mode
    UINT_T recv_buffer_size;     // Media reception buffer size
} MEDIA_STREAM_VAR_T;

Set media parameters

Set the audio and video parameters of the sub-device.

device refers to the sub-device index number. After the sub-device is added successfully, you can get the index number through tuya_xvr_dev_get_sub_dev_info_by_ringbuf_idx.

OPERATE_RET tuya_ipc_media_adapter_set_media_info(INT_T device, INT_T channel, DEVICE_MEDIA_INFO media_info);

typedef struct {
    BOOL_T stream_enable[E_IPC_STREAM_MAX];        // Enable the feature

    UINT_T video_fps[E_IPC_STREAM_VIDEO_MAX];        // Video frame rate
    UINT_T video_gop[E_IPC_STREAM_VIDEO_MAX];       // Video group of pictures (GOP)
    TUYA_VIDEO_BITRATE_E video_bitrate[E_IPC_STREAM_VIDEO_MAX];        // Maximum video bitrate
    UINT_T video_width[E_IPC_STREAM_VIDEO_MAX];    // Video width
    UINT_T video_height[E_IPC_STREAM_VIDEO_MAX];   // Video height
    UINT_T video_freq[E_IPC_STREAM_VIDEO_MAX];       // Video frequency
    TUYA_CODEC_ID_E video_codec[E_IPC_STREAM_VIDEO_MAX];    // Video encoding type

    TUYA_CODEC_ID_E audio_codec[E_IPC_STREAM_MAX];        // Audio encoding type
    UINT_T audio_fps[E_IPC_STREAM_MAX];        // Audio frame rate
    TUYA_AUDIO_SAMPLE_E audio_sample[E_IPC_STREAM_MAX];        // Audio sampling rate
    TUYA_AUDIO_DATABITS_E audio_databits[E_IPC_STREAM_MAX];    // Audio bit width
    TUYA_AUDIO_CHANNEL_E audio_channel[E_IPC_STREAM_MAX];    // Audio channel
} IPC_MEDIA_INFO_T;

typedef struct {
    BOOL_T enable;        // Enable the feature
    TUYA_CODEC_ID_E audio_codec;        // Audio encoding type
    TUYA_AUDIO_SAMPLE_E audio_sample;        // Audio sampling rate
    TUYA_AUDIO_DATABITS_E audio_databits;    // Audio bit width
    TUYA_AUDIO_CHANNEL_E audio_channel;    // Audio channel
} MEDIA_AUDIO_DECODE_INFO_T;

typedef struct {
    IPC_MEDIA_INFO_T av_encode_info;        // Audio and video encoding parameters
    MEDIA_AUDIO_DECODE_INFO_T audio_decode_info;        // Audio decoding parameters
    INT_T max_pic_len;        // Maximum length of the picture
    INT_T decoder_cnt;        // The number of other decoders
    TUYA_DECODER_T *decoders;        // Parameters of other decoders
} DEVICE_MEDIA_INFO_T;

How it works

The above interface methods are all used in the demo. The following section focuses on the calling sequence for initializing the media adaptation layer.

Initialize media adapter

Initialize streaming service

Set media parameters

There are typically two scenarios for setting the sub-device media parameters:

• For existing sub-devices, call tuya_ipc_media_adapter_set_media_info after tuya_xvr_dev_init to set the sub-device media parameters before base station initialization.

• To add a sub-device to the base station during operation, you need to use tuya_ipc_media_adapter_set_media_info to add the sub-device media information in the callback registered by tuya_xvr_dev_attach_sub_dev_bind_result_cb.