物模型功能

更新时间：2026-04-03 11:20:37

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

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

初始化

• 初始化方法如下：

class RTCXFluThingApi {
  /// 初始化物模型
  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();

  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()}");
    }
  }

设备服务

  // 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()}");
    }
  }