网关设备接入

更新时间：2026-03-12 13:51:55

此章节内容仅针对网关含NVR（以下简称网关，也称主设备）相关设备接入进行说明。

概述

AIRTC云平台支持设备直连云平台，也支持网关直连云平台，而网关下的子设备，则通过网关接入云平台。

网关通过接入DeviceSDK可以将网关和子设备的拓扑关系以及子设备的在线状态上报到AIRTC云平台，在客户端可以查看网关和子设备的拓扑关系以及各自的在线状态，并且可以对子设备进行直播、回放、物模型配置、PTZ控制等相关操作。

适用场景

适用于子设备不能直连或者需要拓扑关系管理的场景，例如：接入Wi-Fi网关、蓝牙网关、ZigBee网关、NVR等。

同一个网关下支持接入不同品类的子设备，如：单目摄像头、多目摄像头、烟感、温湿度传感器等。

三元组信息

您需要在AIRTC控制台生成网关设备的 productKey/deviceName/deviceSecret 三元组信息，并将其写入到网关设备中。
通过DeviceSDK初始化网关设备的时候，三元组信息和uuid信息必填（productKey/deviceName/deviceSecret /uuid）。
关于子设备的三元组信息，有两种情况：
- 子设备本身没有三元组信息：初始化子设备的时候，只需要填写 deviceName和uuid信息，子设备 deviceName 和 uuid由厂商自行命名，但是需要保证deviceName 和 uuid在当前产品型号下的唯一性。建议采用【网关的deviceName + 子设备标识】作为子设备的deviceName。子设备的productKey和deviceSecret信息，由DeviceSDK动态向平台获取，并内部维护，此场景下所有子设备的productKey都是相同的
- 子设备本身就有三元组信息：初始化子设备的时候，将三元组信息和uuid一并传入DeviceSDK，DeviceSDK使用传入的三元组信息将设备注册到平台

网关接入过程

子设备接入之前，需要先将网关接入到云平台，网关的接入过程和普通IPC接入流程类似，需要同时接入IoTSDK和StreamSDK，具体流程可以参考普通IPC接入流程: IoTSDK接入和 StreamSDK接入

子设备接入过程

子设备不直接连接AIRTC云平台，所以无需为子设备安装AIRTC DeviceSDK。子设备完全由厂商自行开发。

网关发现子设备、监控子设备在线状态，以及将来自AIRTC云平台的信令发送给子设备等功能，均由网关厂商自行实现，或网关厂商与子设备厂商定义协议实现。

网关接入到AIRTC云平台之后，子设备上线过程如下：

子设备接入网关
网关调用 xs_iot_open 接口创建子设备
网关调用 xs_iot_connect 接口连接子设备
网关设备DeviceSDK向云平台发起子设备的登录请求（子设备和网关复用同一条信令连接），并获取子设备在平台上的绑定关系，如果未绑定，则动态发起子设备的绑定流程
子设备登录成功之后，客户端会显示当前子设备在线

网关接入到AIRTC云平台之后，子设备下线过程如下：

子设备从网关移除
网关调用 xs_iot_disconnect 接口通知云平台子设备的在线状态
网关调用 xs_iot_close 接口将子设备和网关的拓扑关系在云平台上解绑

DeviceSDK接入流程步骤

步骤1：初始化网关设备

初始化设备SDK（包括IoTSDK以及StreamSDK）

/*初始化rtcx-iotsdk*/
static void initIotSdk()
{
    /*初始化iotsdk回调函数指针*/
    xs_iot_callbackFun_st cbFun;
    initIotCallbackFun(&cbFun);		//初始化回调函数指针列表
	/*设置设备的工作模式，区分长上电设备和低功耗保活设备*/
    xs_iotInitParam_st initParam;
    memset(&initParam, 0, sizeof(initParam));
    initParam.configPath = "/etc/config";		//必须是flash中真实存在的可读写路径
    initParam.workMode = XS_IOT_WORK_MODE_LONG_TIME_POWER;
    initParam.maxSubDeviceNum = SUB_DEV_COUNT;	//网关设备，必须设置最大支持的子设备个数

    ret = xs_iot_init(&cbFun, &initParam);
}

/*初始化rtcx-streamsdk*/
static void initStreamSdk()
{
	/*初始化StreamSDK配置参数*/
    xs_streamConfig_st initConfig;
    memset(&initConfig,0,sizeof(initConfig));

    initConfig.device_type = XS_DEVICE_TYPE_GATEWAY;	//设备类型设置成 XS_DEVICE_TYPE_GATEWAY 
    initConfig.sub_num = SUB_DEV_COUNT;	//最大子设备个数设置一下

    /*初始化streamsdk回调函数指针*/
    xs_stream_callbackFun_st streamCbFun;
    memset(&streamCbFun, 0, sizeof(streamCbFun));
    initStreamCallbackFun(&streamCbFun);	//初始化回调函数指针列表
    
    xs_stream_Init(&initConfig, &streamCbFun);
}

创建网关设备，建立连接

/*创建网关，并建立连接，返回生成的deviceId*/
static xs_int32 initPrimaryDevice(xs_deviceInfo_st* deviceInfo)
{
	/*创建网关*/
    xs_int32 devId = xs_iot_open(XS_IOT_DEV_TYPE_MASTER, deviceInfo);
    if (devId < 0){
    	//创建网关错误
    	return devId;
    }
    xs_int32 code = xs_iot_connect(devId);
    
    if (code != XS_STREAM_EC_SUCCESS) {
    	//连接错误
    }
    
    /*启动streamsdk服务*/
    xs_stream_start();
    return devId;
}

步骤2：添加子设备

创建子设备，并建立连接，子设备建立连接之后，SDK内部触发自动绑定流程

static xs_int32 createSubDevice(xs_deviceInfo_st* deviceInfo)
{
	if (!deviceInfo->deviceName) {
		//子设备只需要有deviceName即可，productkey和device secret信息SDK内部维护
		return -1;
	}
	int32_t devId = xs_iot_open(XS_IOT_DEV_TYPE_SLAVE, &g_devAuth[devSeq].devInfo);
	if (devId < 0){
		return -1;
	}
	
	//注意：如果子设备是普通IOT设备（无IPC功能），不需要调用streamsdk相关接口
	xs_DeviceParams_st deviceParam;
    memset(&deviceParam,0,sizeof(deviceParam));
    deviceParam.lensCount = 1;		//网关子设备，支持单目和多目子设备
    xs_stream_setDeviceParams(devId, &deviceParam);
    
    //创建子设备流，此函数可以参考SDK demo程序
    createStreamSource(devId);
    
    //子设备上线
    xs_iot_connect(devId);
    return devId;
}

子设备上线（xs_iot_connect）后，SDK会将拓扑关系和在线状态同步到云端，云端会保存子设备和网关的绑定关系以及在线状态。

步骤3：子设备上下线

当子设备和网关拓扑关系建立之后，如果子设备和网关处于连接状态，需要通过xs_iot_connect通知SDK，SDK会将状态同步到云端，此时APP上看到设备是在线状态。

当子设备和网关连接断开之后（拓扑关系还在），需要通过 xs_iot_disconnect函数通知SDK，SDK会将状态同步到云端，此时APP上看到设备是离线状态。

子设备上线和离线的通知也是通过下面的回调函数触发，通过devId进行区分

/**
 * @brief 设备在线状态回调
 * @param [IN] devId: 设备ID，xs_iot_open接口返回的ID
 * @param [IN] connectStatus: 在线状态，1表示设备在线,  0 表示设备离线
 * @return 0:成功， 其他值：错误码
 */
typedef xs_int32(*xs_connectStatusCallback)(xs_int32 devId, xs_int32 connectStatus);

步骤4：子设备业务处理

子设备的业务处理，比如：物模型相关的回调、智能事件上报、自定义事件上报等。也和普通IPC设备采用相同的接口，区别就是通过子设备的devId进行区分。具体接口和功能可以参考普通IPC的接入流程文档，见IoTSDK接入和StreamSDK接入。

步骤5：删除子设备

当子设备和网关的拓扑关系解除之后，需要通过 xs_iot_close 函数通知SDK，SDK会通知云端子设备已经解绑，此时APP上就不会再显示子设备信息

static void destroySubDevice(xs_int32 devId)
{
    /*先销毁流，再销毁设备*/
    destroyStreamSource(devId);
    xs_iot_disconnect(devId);
    xs_iot_close(devId);
}

注意：子设备绑定和解绑的操作可以在离线状态下执行，SDK内部会记录子设备和网关的拓扑关系，待设备和云端重新建立建立后，会将拓扑关系和在线状态同步到云端。

步骤6：反初始化网关设备

程序退出时，可以反初始化网关设备（不会影响平台端网关设备和用户的绑定关系），此步骤是非必要操作，也可以不执行

/*反初始化设备*/
static void uninitPrimaryDevice(xs_deviceInfo_st* deviceInfo)
{
	xs_iot_disconnect(devId);
	xs_iot_close(devId);
}

概述​

适用场景​

三元组信息​

网关接入过程​

子设备接入过程​

DeviceSDK接入流程步骤​

步骤1：初始化网关设备​

步骤2：添加子设备​

步骤3：子设备上下线​

步骤4：子设备业务处理​

步骤5：删除子设备​

步骤6：反初始化网关设备​

概述