跳到主要内容

设备管理

更新时间：2026-10-28 15:18:58

设备管理，包括：设备列表等功能。

接口与类型定义详见sdk中dist目录下index.d.ts文件

/**
 * 设备列表
 * @param deviceListReq - 设备列表请求参数
 * @returns
 * @public
 */
declare function getDeviceList(deviceListReq: IDeviceListReq): Promise<IDeviceListResp>;

/**
 * 获取网关子设备
 * @param subListReq - 获取网关子设备列表请求参数
 * @returns
 * @public
 */
declare function getGatewaySubList(subListReq: GatewaySubListReq): Promise<IDeviceListResp>;

/**
 * 获取设备详细
 * 第三方可能用自己的设备列表，只有iotId,productKey,deviceName 需要请求数据用于后续业务开发
 *
 * @param deviceList - 基础设备列表  可能只有iotId,productKey,deviceName
 * @public
 */
declare function getDeviceDetail(deviceList: PlayDeviceInfo[]): Promise<PlayDeviceInfo[]>;

/**
 * 第三方自己管理设备关系，上层主动设置网关与子设备关联关系
 * @param gatewayDevice - 网关设备
 * @param childDeviceList - 子设备列表
 * @public
 */
declare function setGatewayDeviceRelevance(gatewayDevice: ISimpleDeviceInfo, childDeviceList: ISimpleDeviceInfo[]): void;

/**
 * 获取设备状态
 * @param iotId - 设备ID
 * @returns 设备状态 DeviceStatusEnum
 * @public
 */
declare function getDeviceStatus(iotId: string): Promise<DeviceStatusEnum>;

/**
 * 唤醒休眠设备
 * @param iotId - 设备的唯一标识符。
 * @internal
 */
declare function deviceWakeUp(iotId: string): Promise<void>;


/**
 * 解绑用户名下设备（取消被分享）
 * @param iotId - 设备ID
 * @public
 */
declare function unbindAccountAndDev(iotId: string): Promise<void>;

/**
 * 设置设备昵称
 * @param iotId - 设备ID
 * @param nickname - 设备昵称
 * @public
 */
declare function setDeviceNickName(iotId: string, nickname: string): Promise<void>;

export declare namespace RTCXDeviceMgr {
    export {
        getDeviceList,
        getGatewaySubList,
        getDeviceDetail,
        setGatewayDeviceRelevance,
        deviceWakeUp,
        getDeviceStatus,
        unbindAccountAndDev,
        setDeviceNickName,
    }
}

设备列表​

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const deviceList = ref<RTCXDeviceMgrTypes.PlayDeviceInfo[]>([])
    
const params: RTCXDeviceMgrTypes.IDeviceListReq = {
    pageNo: 1,
    pageSize: 100,
}

RTCXDeviceMgr.getDeviceList(params).then((resp) => {
  deviceList.value = resp.data
})
.catch(console.error)

网关子设备​

获取网关子设备列表信息

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const subDeviceList = ref<RTCXDeviceMgrTypes.PlayDeviceInfo[]>([])
    
const params: RTCXDeviceMgrTypes.GatewaySubListReq = {
    deviceInfo,
    pageNo: 1,
    pageSize: 100,
}

RTCXDeviceMgr.getGatewaySubList(params).then((resp) => {
  subDeviceList.value = resp.data
})
.catch(console.error)

设备详细​

第三方可能用自己的设备列表，只有iotId、productKey、deviceName 需要请求数据用于后续业务开发。与设备列表接口返回的字段会少一些。

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const deviceList = ref<RTCXDeviceMgrTypes.PlayDeviceInfo[]>([])
    
const sampleDeviceInfo: RTCXDeviceMgrTypes.ISampleDeviceInfo = {
    iotId: deviceInfo.iotId,
    productKey: deviceInfo.productKey,
    deviceName: deviceInfo.deviceName,
}

return RTCXDeviceMgr.getDeviceDetail([params]).then((resp) => {
  deviceList.value = resp.data
})
.catch(console.error)

设备状态​

查询设备在线状态

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const iotId = "111111"
async function () {
    const status = await RTCXDeviceMgr.getDeviceStatus(iotId);
}

设备解绑​

解绑自有设备或取消被分享设备

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const iotId = "1111111"
function onDeviceUnbindClick() {
  ElMessageBox.confirm('确认解绑设备?').then(() => {
    RTCXDeviceMgr.unbindAccountAndDev(iotId)
      .then(() => {
        ElNotification.success('解绑设备成功')
      })
      .catch(() => {
        ElNotification.error('解绑设备失败')
      })
  })
}

唤醒设备​

根据 RTCXDeviceMgrTypes.PlayDeviceInfo.deviceWorkMode返回设备工作模式区分不同设备。工作模式为XS_IOT_WORK_MODE_LOWPOWER_KEEPLIVE时需要先唤醒设备，设备上线后再正常播放

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const iotId = "1111111"
async function () {
  RTCXDeviceMgr.deviceWakeUp(iotId)
}

设置设备昵称​

import {
  RTCXDeviceMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'

const iotId = "111111"
const nickname = "xxxxxx"
async function () {
  RTCXDeviceMgr.setDeviceNickName(iotId, nickname)
}

设备缩略图​

/**
 * 获取设备直播缩略图 设备需要在线
 *
 * @param deviceInfo - 设备信息，设备列表获取
 * @param thumbnailType - 缩略图类型
 * @public
 */
declare function getLiveThumbnail(deviceInfo: IDeviceInfo, thumbnailType?: ThumbnailType): Promise<ThumbnailInfo | undefined>;
export declare namespace RTCXDeviceThumbnailMgr {
    export {
        getLiveThumbnail
    }
}

示例

import {
  RTCXDeviceThumbnailMgr,
  RTCXDeviceMgrTypes,
} from '@rtcx/websdk'


onMounted(() => {
  getDeviceList()
    .then((resp) => {
      const list = resp.data
      deviceList.value = list
      if (list.length && list[0].nodeType == RTCXDeviceMgrTypes.DeviceNodeTypeEnum.DEVICE) {
        onDeviceSelected(deviceList.value[0])
      }
      setTimeout(() => {
        deviceList.value.forEach((item) => {
          RTCXDeviceThumbnailMgr.getLiveThumbnail(item).then(
            (thumbnailInfo: RTCXDeviceMgrTypes.ThumbnailInfo | undefined) => {
              if (thumbnailInfo) item.thumbnail = thumbnailInfo.downloadUrl
            }
          )
        })
      })
    })
    .catch(console.error)
}

设备配置​

/**
 * 设备配置项管理
 * @public
 */
export declare const RTCXDeviceEntityMgr: {
    /**
     * 设置设备配置项（单个）
     *
     * @param iotId - 设备ID
     * @param entityEnum - 设置项
     * @param value - 设置内容
     */
    setDeviceEntity(iotId: string, entityEnum: DeviceEntityEnum, value: string): void | Promise<IGatewayResponse>;
    /**
     * 获取指定ID配置
     *
     * @param iotId - 设备ID
     * @param entityEnum - 配置ID
     */
    getDeviceEntity(iotId: string, entityEnum: DeviceEntityEnum): Promise<string|undefined>;
};

配置项 DeviceEntityEnum

/**
 * 设备配置
 * @public
 */
declare enum DeviceEntityEnum {
    /**
     * 消息推送设置
     */
    MSG_PUSH_SETTING = 1003,
}

消息通知计划


/**
 * 推送设置
 * @public
 */
declare interface MsgPushSetting {
    /** 推送关闭计划列表 */
    sch: MsgPushSettingSchedule[];
    /** 是否接收推送消息 */
    sta: number;
    /** 是否推送图片 */
    img: number;
    /** 推送间隔 单位：秒 */
    interval: number;
}

/**
 * 推送计划
 * @public
 */
declare interface MsgPushSettingSchedule {
    /** 开始时间，utc时间，秒 */
    start: number;
    /** 结束时间，utc时间，秒 （end时间应始终大于start时间，跨天的时候，end为第二天的时间） */
    end: number;
    /** 对应的值仅在"rpt"为2时有效，存在重复设置值：SUN:0x0001, MON:0x0002, TUE:0x0004, WED:0x0008, THU:0x0010, FRI:0x0020, SATU:0x0040，支持按位或操作 */
    wk: number;
    /** 重复类型，0：执行一次 1：每天重复 2：每周重复 3：每月重复 （目前支持1和2） */
    rpt: number;
    /** 推送关闭计划状态 1表示状态开，0表示状态关 */
    sta: number;
}

获取设备配置​

/**
 * 获取指定ID配置
 *
 * @param iotId - 设备ID
 * @param entityEnum - 配置ID
 */
getDeviceEntity(iotId: string, entityEnum: DeviceEntityEnum): Promise<string|undefined>;

示例

import { RTCXDeviceEntityMgr, RTCXDeviceMgrTypes} from '@rtcx/websdk'
async function (iotId: string){
	const result = await RTCXDeviceEntityMgr.getDeviceEntity(
        iotId, 
        RTCXDeviceMgrTypes.DeviceEntityEnum.MSG_PUSH_SETTING, 
        );
	if(result) {
		const msgNotifySetting =  JSON.parse(result) as RTCXDeviceMgrTypes.MsgPushSetting
    }
}

设置设备配置​


/**
 * 设置设备配置项（单个）
 *
 * @param iotId - 设备ID
 * @param entityEnum - 设置项
 * @param value - 设置内容
 */
setDeviceEntity(iotId: string, entityEnum: DeviceEntityEnum, value: string): void | Promise<IGatewayResponse>;

示例

import { RTCXDeviceEntityMgr, RTCXDeviceMgrTypes} from '@rtcx/websdk'
const msgNotifySetting: RTCXDeviceMgrTypes.MsgPushSetting = {
    ....
}  
async function (iotId: string){
	const result = await RTCXDeviceEntityMgr.setDeviceEntity(
        iotId, 
        RTCXDeviceMgrTypes.DeviceEntityEnum.MSG_PUSH_SETTING, 
        JSON.stringify(msgNotifySetting)
        );
}

云台预置位​

收藏常看的云台位置，方便快速转动设备镜头至相应位置


/**
 * 预置位管理
 * @public
 */
export declare class RTCXPTZPresetMgr {
    private presetList;
    private iotId;
    /**
     *
     * @param iotId - 设备ID
     *
     */
    constructor(iotId: string);
    /**
     * 获取设备预置位列表
     *
     */
    getPresetList(): Promise<PTZPresetRspItem[]>;
    /**
     * 添加预置位
     *
     * @param reqParams - [PTZPresetReq]
     */
    addPreset(reqParams: PTZPresetReq): Promise<PTZPresetRspItem>;
    /**
     * 删除预置位
     *
     * @param item - 列表返回的预置位项[PTZPresetRspItem]
     */
    removePreset(item: PTZPresetRspItem): Promise<boolean>;
    /**
     * 更新预置位,一般用于修改名称
     *
     * @param item - 列表返回的预置位项[PTZPresetRspItem]
     */
    updatePreset(item: PTZPresetRspItem): Promise<boolean>;
}

构建对象​

import {
  RTCXDeviceMgrTypes,
  RTCXPTZPresetMgr,
  RTCXThingModelTypes,
} from '@rtcx/websdk'

const iotId: string = ''
let presetMgr: RTCXPTZPresetMgr = new RTCXPTZPresetMgr(iotId)

获取设备预置位列表​

import {
  RTCXPTZPresetMgr,
  RTCXThingModelTypes,
} from '@rtcx/websdk'


let presetMgr: RTCXPTZPresetMgr | null = null

// 加载预置位列表
async function loadPresetList() {
  if (!props.deviceInfo?.iotId) return
  
  loading.value = true
  try {
    if (!presetMgr) {
      presetMgr = new RTCXPTZPresetMgr(props.deviceInfo.iotId)
    }
    presetList.value = await presetMgr.getPresetList()
  } catch (error) {
    console.error('加载预置位列表失败:', error)
    ElMessage.error('加载预置位列表失败')
  } finally {
    loading.value = false
  }
}

RTCXThingModelTypes.PTZPresetRspItem

/**
 * 预置位列表
 *
 * @public
 */
declare interface PTZPresetRspItem {
    /**
     * 预置位信息
     */
    readonly ptz: string;
    /**
     * 预置位名称
     */
    name?: string;
    /**
     * 预置位图片ID
     */
    readonly picId?: string;
    /**
     * 预置位图片地址
     */
    readonly picUrl?: string;
}

添加预置位​

  1. 通过物模型或其它途径获取设备当前云台位置信息

  2. 用户输入位置名称

  3. 获取设备当前位置画面（可截图播放器当前直播画面）

import {
  RTCXPTZPresetMgr,
  RTCXThingModelTypes,
} from '@rtcx/websdk'

const ptzPosition = "获取到的当前云台位置信息"
const presetName ="常看位置"

async function handleAddPreset() {
  try {
    if (!presetMgr) {
      presetMgr = new RTCXPTZPresetMgr(props.deviceInfo.iotId)
    }
    
    await presetMgr.addPreset({
      ptz: ptzPosition,
      name: presetName,
    })
    
    ElMessage.success('添加预置位成功')
  } catch (error) {
    console.error('添加预置位失败:', error)
    ElMessage.error('添加预置位失败')
  }
}

RTCXThingModelTypes.PTZPresetReq

/**
 * 预置位保存参数 预置位名称与截图至少有一个
 *
 * @public
 */
    declare interface PTZPresetReq {
    /**
     * 预置位信息
     */
    ptz: string;
    /**
     * 预置位名称 可选
     */
    name?: string;
    /**
     * 预置位截图  可选 (暂不支持)
     */
    img?: Blob | File;
}

删除预置位​

传入列表中获取数据，删除指定预置位

import {
  RTCXPTZPresetMgr,
  RTCXThingModelTypes,
} from '@rtcx/websdk'

async function handleDeletePreset(item: RTCXThingModelTypes.PTZPresetRspItem) {

  try {
    if (!presetMgr) {
      presetMgr = new RTCXPTZPresetMgr(props.deviceInfo.iotId)
    }
    
    await presetMgr.removePreset(item)
  } catch (error) {
    console.error('删除预置位失败:', error)
  } finally {
    loading.value = false
  }
}

修改预置位名称​

更新预置位名称 如果ptz信息或图片变化请删除重新添加

import {
  RTCXPTZPresetMgr,
  RTCXThingModelTypes,
} from '@rtcx/websdk'

const presetName = "新的位置名称"

async function handleSaveEdit() {
  try {
    if (!presetMgr) {
      presetMgr = new RTCXPTZPresetMgr(props.deviceInfo.iotId)
    }
    
    await presetMgr.updatePreset({
      ...currentEditItem.value,
      name: presetName,
    })
    
    ElMessage.success('修改预置位名称成功')
    await loadPresetList()
  } catch (error) {
    console.error('修改预置位名称失败:', error)
    ElMessage.error('修改预置位名称失败')
  }
}