跳到主要内容

物模型功能

更新时间：2026-08-25 14:11:38

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

// 导入物模型头文件
import 'package:airtc_engine/src/thing/rtcx_thing.dart';
import 'package:airtc_engine/src/thing/rtcx_thing_controller.dart';

初始化物对象​

  • 初始化方法如下：
class RTCXFluThingController {
/// 初始化物模型
  RTCXFluThingResult buildThing(RTCXFluThingReq req);

  /// 注册物的状态、属性变化或者事件触发的 observer, Thing 类只会 Weak 持有此 observer，
  /// 调用者需要自行保证 observer 的生命周期，如果 dealloc 了，将不再有效
  void registerThingObserver();

  /// 反注册物的状态、属性变化或者事件触发的 observer
  void unregisterThingObserver();

  /// 发送指令 必须初始化物模型后调用
  @async
  RTCXFluThingResult invokeService(RTCXFluThingCommand command);

  /// 获取物的 iotId
  String iotId();

  ///  获取物的 productKey
  String getProductKey();

  ///  获取物的 deviceName
  String getDeviceName();

  ///  获取物的 Profile，在 Profile 中包含了物的模型信息
  @async
  RTCXFluThingProfile getThingProfile();

  void destroy();
}

  • 状态回调代理方法如下：
class RTCXFluThingCallback {
  /// 物的状态变更回调， 0：离线；1：在线；2：休眠；3：休眠离线；
  void onStatusChange(String uuid, RTCXFluThingObserver value);

  /// 物有事件触发，如提示，告警等
  void onEventHappen(String uuid, RTCXFluThingObserver value);

  ///  物的属性发生变化
  void onPropertyChange(String uuid, RTCXFluThingObserver value);

  ///  设备被解绑通知
  void onDeviceUnbind(String uuid, RTCXFluThingObserver value);

  ///   设备端透传信息到用户端通知
  void onDeviceTransferMessage(String uuid, RTCXFluThingObserver value);
}

使用 RTCXFluThingController 调用示例如下:

  • 物模型对象初始化
  // 初始化物模型
  late RTCXFluThingController _thingApi;
  @override
  void initState() {
    super.initState();
    // 物模型通道
    RTCXFluThingReq req = RTCXFluThingReq(
      productKey: widget.productKey,
      deviceName: widget.deviceName,
      iotId: widget.iotId,
      deviceType: widget.deviceType,
    );
    _thingApi = RTCXFluThingController();
    _thingApi.buildThing(req);
    _thingApi.registerThingObserver();
    _thingApi.onStatusChange.listen((data) {
      print("onStatusChange:"+data.toString());
    });
    _thingApi.onDeviceTransferMessage.listen((RTCXFluThingObserver observer) {
      print("onDeviceTransferMessage:"+observer.toString());
    });
  }
  • 释放资源
  @override
  void dispose() {
    super.dispose();
    _thingApi.destroy();
  }
  • 监听获取设备物模型、上下线消息、属性变化消息、解绑消息、事件触发消息、设备透传消息
   // 监听状态变化
   _thingApi.onStatusChange.listen((data) {
      print("onStatusChange:"+data.toString());
      var status = data.params!['status'];
      if(status != null && status is int) {
        switch(status) {
          case 0:
          // 离线
            break;
          case 1:
          // 在线
            break;
          case 2:
          // 休眠
            break;
          case 3:
          // 休眠离线
            break;
          default:
            break;
        }
      }
  });
  
  // 物的属性发生变化
  _thingApi.onPropertyChange.listen((data) {
      // 属性变化
  });
  
  // 物有事件触发，如提示，告警等
  _thingApi.onEventHappen.listen((data){

  });
  
  // 设备被解绑通知
  _thingApi.onDeviceUnbind.listen((data){

  });
  
  // 设备端透传信息到用户端通知
  _thingApi.onDeviceTransferMessage.listen((RTCXFluThingObserver observer) {
     print("onDeviceTransferMessage:"+observer.toString());
  });
  • DeviceName
  void getDeviceName() {
    try {
      final result = _thingApi.getDeviceName();
      print("getDeviceName:${result}");
    } catch(e) {
      print("getDeviceName e:${e.toString()}");
    }
  }
  • ProductKey
  void getProductKey() {
    try {
      final result = _thingApi.getProductKey();
      print("getProductKey:${result}");
    } catch(e) {
      print("getProductKey e:${e.toString()}");
    }
  }
  • iotId
  void getIotId() {
    try {
      final result = _thingApi.iotId();
      print("iotId:${result}");
    } catch(e) {
      print("iotId e:${e.toString()}");
    }
  }

获取设备状态​

class RTCXFluThingController {
  /// 获取物的生命周期
  /// 说明：status表示设备生命周期，目前有以下几个状态，0:未激活；1：上线；2：休眠；3：离线；8：禁用；
  @async
  RTCXFluThingResult getStatus();
}

调用示例如下

  void _getStatus() {
    if(widget.device != null) {
      _thingApi.getStatus().then((result){
        print("_getStatus result:${result.success}, dataObj:${result.dataObject}, resultObj:${result.resultObject}");
      }).catchError((error){
        print("_getStatus error:${error.toString()}");
      });
    }
  }

获取物的模型​

  /// 获取物的模型
  Future<RTCXFluThingProfile> getTsl();

调用示例如下：

void _getTSL() {
    if (widget.device != null) {
      _thingApi
          .getTsl()
          .then((RTCXFluThingProfile profile) {
            print(
              "_getTSL properties:${profile.properties}, services:${profile.services}, events:${profile.events}",
            );
            thingProfile = profile;
          })
          .catchError((error) {
            print("_getTSL error:${error.toString()}");
          });
    }
  }

设备属性​

  ///  获取物的所有属性的当前值
  @async
  RTCXFluThingResult getPropertiesFull();

  /// 获取指定物模型属性列表
  @async
  RTCXFluThingResult getProperties(RTCXFluThingQueryPropertiesReq req);

  /// 获取物的模型
  @async
  RTCXFluThingProfile getTsl();

  /// 设置物的属性值，可以同时设置一个或者多个属性
  /// 设置物模型属性,请求
  /// params 属性 key-value 对， 格式如{"items":{"power":"on", temperature:30}}
  /// extraData 附加控制属性  key:"IotPerformanceId" 性能测试
  /// key:"Channel", value: ChannelPolicyCloud ChannelPolicyLocal   ChannelPolicyLocalPrefer
  /// key:"QosLevel", value: Qos_CON Qos_NON
  /// key:"NeedRsp", value:TRUE FALSE
  /// key:"Flag", 用于commonservice flag参数
  /// key:"LensId",value:@(1)镜头ID，仅多目设备需要单独设置指定镜头属性时填写， 如 {@"LensId":@(0)}
  /// key:"TimeoutInterval"，value:10，接口响应超时时间，单位：秒，不设置默认10秒，如：{@"TimeoutInterval":@(10)}
  /// 结果回调函数
  @async
  RTCXFluThingResult setProperties(Map params, Map extraData);

调用示例如下：

  • 获取物的所有属性
  void _queryProperties() {
    if(widget.device != null) {
      _thingApi.getPropertiesFull().then((result){
        print("getPropertiesFull result:${result.success}, dataObj:${result.dataObject}");
        if (result.resultObject != null && result.resultObject is Map) {
          Map aData = (result.resultObject as Map);
          print("getPropertiesFull aData:${aData}");
          widget.device?.thingProperties = aData["propertyMap"];
        }
      }).catchError((error){
        print("getPropertiesFull error:${error.toString()}");
      });
    }
  }
  • 获取物的指定属性
  void _queryTargetProperties() {
    if(widget.device != null) {
      RTCXFluThingQueryPropertiesReq req = RTCXFluThingQueryPropertiesReq(
          identifierList: [
            "deviceSdkAbility",
            "StreamSdkVersion"
          ]
      );
      _thingApi.getProperties(req).then((result){
        print("_queryTargetProperties result:${result.success}, dataObj:${result.dataObject}");
        if (result.resultObject != null && result.resultObject is Map) {
          Map aData = (result.resultObject as Map);
          print("_queryTargetProperties aData:${aData}");
        }
      }).catchError((error){
        print("_queryTargetProperties error:${error.toString()}");
      });
    }
  }
  • 设置物的属性
  // 设置清晰度StreamVideoQuality
  void _setVideoQuality() {
    if(widget.device != null) {
      Map params = {
        "StreamVideoQuality": 1,
      };
      Map extraData = {

      };
      _thingApi.setProperties(params, extraData).then((result){
        print("_setVideoQuality:${result.success}, dataObject:${result.dataObject}, resultObject:${result.resultObject}");
        Fluttertoast.showToast(msg: "setProperties ${result.toString()}");
      }).catchError((error){
        print("_setVideoQuality error:${error.toString()}");
        Fluttertoast.showToast(msg: "setProperties ${error.toString()}");
      });
    }
  }

设备服务​

  // RTCXFluThingCommand中
  // command服务的唯一标识符
  // params调用服务的入参，请参考物的模型 tsl，形如 {"arg1":"val1", "arg2":"val2"}
  // extraData附加控制属性
  /// 发送指令，必须初始化物模型后调用
  Future<RTCXFluThingResult> invokeService(RTCXFluThingCommand command) {
    return _api.invokeService(uuid, command);
  }

调用示例如下：

  • 设备缩略图
  Future<void> getDeviceThumb() async {
    try {
      final result = await _thingApi.invokeService(
        RTCXFluThingCommand(
          command: "GetDevPicture",
          params: {
            "definition": 1,
            "picType": "jpg",
          },
        ),
      );
      Fluttertoast.showToast(msg: "获取缩略图${result == true ? "成功" : "失败"}, ${result.dataObject}");
    } catch(e) {
      Fluttertoast.showToast(msg: "获取缩略图失败:${e.toString()}");
    }
  }
  • PTZ控制
  Future<void> ptzActionControl() async {
    try {
      final result = await _thingApi.invokeService(
        RTCXFluThingCommand(
          command: "PTZActionControl",
          params: {
            "ActionType": 1,
            "Step": 10,
          },
        ),
      );
      if(result.success && result.dataObject != null) {
        Map<String, dynamic> dataObjectMap = jsonDecode(result.dataObject!);
      }
      print("ptzActionControl result:${result.success},dataObject:${result.dataObject}");
    } catch(e) {
      print("ptzActionControl e:${e.toString()}");
    }
  }