物模型功能

更新时间：2026-10-30 14:03:33

物模型SDK提供了App端的物模型（属性、事件、服务），用来开发设备界面，实现手机对设备的查看和控制。

// 导入物模型头文件
import { RTCXThingModel, RTCXThingModelType } from 'rtcxsdk'

初始化

初始化物对象

export default class ThingModelPanel implements IThingModelPanel {
    deviceInfo: ISimpleDeviceInfo;
    constructor(playDeviceInfo: PlayDeviceInfo)
}

调用示例如下：

this.thingModel = new RTCXThingModel(PlayDeviceInfo)

通过订阅监听状态变化，监听获取设备上下线消息、属性变化消息、解绑消息、事件触发消息、设备透传消息

export interface IThingModelPanel {
    /**
     * 订阅
     * @param callback - 回调
     */
    subscribe(callback: IPanelEventCallback): void;
    /**
     * 取消订阅
     * @param callback - 回调
     */
    unsubscribe(callback: IPanelEventCallback): void;
}

调用示例如下:

订阅消息通知

this.msgNotify: IPanelEventCallback = (iotId: string, eventType: RTCXThingModelType.SubscribeEventTypeEnum, data?: Object) =>{
    if (eventType == RTCXThingModelType.SubscribeEventTypeEnum.DEVICE_UNBIND) {
          showToast(this, `设备解绑`)
    } else if (eventType == RTCXThingModelType.SubscribeEventTypeEnum.DEVICE_STATUS) {
        //说明：status表示设备生命周期，目前有以下几个状态，0:未激活；1：上线；2：休眠；3：离线；8：禁用；
          showToast(this, `设备状态变化`)
    } else if (eventType == RTCXThingModelType.SubscribeEventTypeEnum.DEVICE_THING_PROPERTIES_CHANGE) {
          showToast(this, `设备物模型属性变化`)
    } else if (eventType == RTCXThingModelType.SubscribeEventTypeEnum.DEVICE_EVENT_BATCH_NOTIFY) {
          showToast(this, ` ${item.getShowName()} 设备产生了告警事件消息`)
    } else if (eventType == RTCXThingModelType.SubscribeEventTypeEnum.DEV_TRANS_MSG) {
          showToast(this, `设备透传消息`)
    }
}
this.thingModel.subscribe(this.msgNotify)

取消订阅消息通知

this.thingModel.unsubscribe(this.msgNotify)

物的模型

export interface IThingModelPanel {
    /**
     * 获取物模型模板
     */
    getThingTsl(): Promise<ThingTSL|undefined>;
}

调用示例如下：

const tsl = this.thingModel.getThingTsl()

设备属性

export interface IThingModelPanel {
    /**
     * 获取物模型属性
     */
    getThingProperties(): Promise<PropertiesMap|void>;

    /**
     * 设置物模型属性
     * @param items - 属性
     * @param lensId - 镜头ID 可行
     */
    setProperties(items: Record<string, Object>, lensId?: number): Promise<boolean>;

    /**
     * 设置属性的超时时间，最小5秒
     * @param timeout - 超时时间 单位毫秒
     */
    setPropertiesTimeout(timeoutMS: number): void;
}

调用示例如下：

获取物的属性

this.propertiesMap = await this.thingModel!.getThingProperties() as RTCXThingModelType.PropertiesMap
RTCXLogger.i(this.TAG,'获取属性成功')

设置物的属性

const result = this.thingModel?.setProperties({'StreamVideoQuality': 0});
if (result) {
  RTCXLogger.i(this.TAG,'设置属性成功')
}

设备服务

export interface IThingModelPanel {
    /**
     *
     * @param identifier - 服务标识
     * @param args - 参数
     * @param hasResponse - 是否有返回数据 默认false
     * @param lensId - 镜头ID
     * @param timeout - 超时时间
     */
    invokeService<T>(identifier: string, args?: Record<string, Object>, hasResponse?: boolean, lensId?: number, timeout?: number): Promise<InvokeServiceRsp<T> | void>;
}

调用示例如下：

获取缩略图

const result = await this.thingModel?.invokeService<IDevPicture>('GetDevPicture',{'definition': 1, "picType": "jpg"})
if (result) {
  const rsp = result as RTCXThingModelType.InvokeServiceRsp<IDevPicture>
  if (rsp.code == 200) {
    const devPicture = rsp.data as IDevPicture
    RTCXLogger.i(TAG,`设备缩略图：${thingM.deviceInfo.iotId}, ${devPicture.downloadUrl}`)
    this.deviceThumnails[thingM.deviceInfo.iotId] = devPicture
  } else {
    showToast(this, `获取缩略图失败`)
  }
}

信令通道连接状态

App 可通过信令通道连接状态监听，实时获取信令通道的连接状态，该状态针对所有设备全局可用。

在命令控制场景中，可先判断信令通道是否已连接，如果已连接，再触发命令（如：物模型服务控制、设备属性设置等），避免因为信令通道未连接导致发送控制命令失败。

// 导入信令通道相关接口
import { RTCXSignalingClientMgr, RTCXSignalingTypes } from 'rtcxsdk'

连接状态与消息通道定义如下：

/**
 * 信令通道连接状态
 * @public
 */
export declare enum SigConnectState {
  /** 未连接 */
  SigConnectState_Disconnected = 0,
  /** 已连接 */
  SigConnectState_Connected = 1,
}

/**
 * 信令消息通道
 * @public
 */
export declare enum SigMessageChannelEnum {
  /** 用户消息通道 */
  SigMessageChannelEnum_User = 0,
  /** 普通设备消息通道 */
  SigMessageChannelEnum_Device = 1,
  /** 专属设备消息通道 */
  SigMessageChannelEnum_PrivDevice = 2,
  /** AP设备消息通道 */
  SigMessageChannelEnum_ApDevice = 3,
}

/**
 * 信令通道连接状态监听
 * @param connectState - 连接状态
 * @param code - 状态码
 * @param msgChannel - 消息通道
 * @public
 */
export type IMConnectStateListener = (connectState: SigConnectState, code: number, msgChannel: SigMessageChannelEnum) => void;

通道	说明
`SigMessageChannelEnum_User`	用户消息通道
`SigMessageChannelEnum_Device`	普通设备消息通道，通用版设备使用
`SigMessageChannelEnum_PrivDevice`	专属设备消息通道，专属版SDK设备使用
`SigMessageChannelEnum_ApDevice`	AP 设备消息通道

添加监听，只需要监听 msgChannel = 1 的普通设备通道连接状态

// 全局属性，用于维护设备信令连接状态
private connectState: RTCXSignalingTypes.SigConnectState =
  RTCXSignalingTypes.SigConnectState.SigConnectState_Disconnected

private onConnectState: RTCXSignalingTypes.IMConnectStateListener =
  (state: RTCXSignalingTypes.SigConnectState, code: number,
   msgChannel: RTCXSignalingTypes.SigMessageChannelEnum) => {
    // 只需要监听普通设备通道
    if (msgChannel === RTCXSignalingTypes.SigMessageChannelEnum.SigMessageChannelEnum_Device) {
      this.connectState = state
    }
  }

// 添加信令通道连接状态监听
RTCXSignalingClientMgr.sharedInstance.addConnectStateListener(this.onConnectState)

移除监听

建议在页面或组件销毁时移除监听，避免重复添加。

RTCXSignalingClientMgr.sharedInstance.removeConnectStateListener(this.onConnectState)

判断信令通道是否已连接，如果已连接，再触发命令

if (this.connectState === RTCXSignalingTypes.SigConnectState.SigConnectState_Connected) {
  // 信令通道已连接，触发 PTZ 步进转动：方向 0:"左", 1:"右", 2:"上", 3:"下"
  const result = await this.thingModel?.invokeService('PTZActionControl', { 'ActionType': 0, 'Step': 10 })
  if (result) {
    RTCXLogger.i(TAG, 'PTZ步进转动成功')
  }
}

信息

登录成功后 SDK 会自动建立信令通道，退出登录时断开，无需手动连接。
如果同时接入多类设备，需要按设备的接入方式监听对应通道（如专属版设备监听 SigMessageChannelEnum_PrivDevice）。
设备或用户处于离线、网络切换等场景时，连接状态可能发生变化，请以监听回调的最新状态为准。

初始化​

物的模型​

设备属性​

设备服务​

信令通道连接状态​

初始化

物的模型

设备属性

设备服务

信令通道连接状态