Flutter可视化监控插件hisma_visual_monitor的使用

简介

hisma_visual_monitor 是一个用于 Hisma（一种分层状态机实现）的可视化监控插件。它通过定义的监控 API 注册监控创建函数，并在状态机创建或其活动状态发生变化时调用这些监控器。

此监控器将状态机信息转换并发送到 visma 应用程序（visma），后者将其渲染到交互式的 Web 用户界面中。

功能

通过结合 visma 和实际的 Flutter 示例应用程序，可以直观地看到 hisma_visual_monitor 的效果。左侧面板中的状态机图会实时更新，无论触发状态变化的事件来自应用程序还是 visma 用户界面：

使用步骤

1. 创建状态机

首先，需要创建你想要监控的状态机。例如，这里我们创建了一个简单的灯光控制状态机。

import 'package:hisma/hisma.dart';
import 'package:hisma_visual_monitor/src/visual_monitor/client/visual_monitor.dart';

// 定义状态、事件和转移类型
enum S { on, off }
enum E { turnOn, turnOff }
enum T { toOn, toOff }

// 创建状态机
Machine<S, E, T> createLightMachine({
  List<Region<S, E, T, dynamic>>? regions,
}) =>
    Machine<S, E, T>(
      name: 'lightMachine',
      events: E.values,
      initialStateId: S.off,
      states: {
        S.off: State(
          etm: {
            E.turnOn: [T.toOn],
          },
          onEntry: Action(
            description: 'Turning off.',
            action: (machine, dynamic arg) async => print('OFF'),
          ),
        ),
        S.on: State(
          etm: {
            E.turnOff: [T.toOff],
          },
          regions: regions,
          onEntry: Action(
            description: 'Turning on.',
            action: (machine, dynamic arg) async => print('ON'),
          ),
        ),
      },
      transitions: {
        T.toOn: Transition(to: S.on),
        T.toOff: Transition(to: S.off),
      },
    );

// 初始化状态机实例
final lightMachine = createLightMachine();

2. 设置可视化监控器

在程序启动时，在 main 函数中设置可视化监控器。

void main() async {
  // 注册可视化监控器
  Machine.monitorCreators = [
    (machine) => VisualMonitor(machine),
  ];

  // 启动状态机
  await lightMachine.start();
  await play();
}

配置远程连接

如果你想连接到运行在不同端口或远程主机上的 visma 实例，可以指定 host 和 port 参数：

Machine.monitorCreators = [
  (machine) => VisualMonitor(
        machine,
        host: '192.168.1.2', // 替换为你的 visma 地址
        port: 1111,          // 替换为你的 visma 端口
      ),
];

自定义机器名称和域名

为了更好地组织状态机，可以通过设置 VisualMonitor.hostname 和 VisualMonitor.domain 来自定义它们的名称和域名：

VisualMonitor.hostname = 'testMachine1';
VisualMonitor.domain = 'groupA';

这允许你在 visma 中按层次结构组织状态机。例如，下图展示了 visma 界面如何根据主机名和域名对状态机进行分组：

3. 运行示例代码

以下是一个完整的示例代码，展示如何使用 hisma_visual_monitor：

// ignore_for_file: avoid_print

import 'package:hisma/hisma.dart';
import 'package:hisma_visual_monitor/src/visual_monitor/client/visual_monitor.dart';

Future<void> main() async {
  // 注册可视化监控器
  Machine.monitorCreators = [
    (machine) => VisualMonitor(machine),
  ];

  // 启动状态机
  await lightMachine.start();
  await play();
}

// 定义状态、事件和转移类型
enum S { on, off }
enum E { turnOn, turnOff }
enum T { toOn, toOff }

// 创建状态机
Machine<S, E, T> createLightMachine({
  List<Region<S, E, T, dynamic>>? regions,
}) =>
    Machine<S, E, T>(
      name: 'lightMachine',
      events: E.values,
      initialStateId: S.off,
      states: {
        S.off: State(
          etm: {
            E.turnOn: [T.toOn],
          },
          onEntry: Action(
            description: 'Turning off.',
            action: (machine, dynamic arg) async => print('OFF'),
          ),
        ),
        S.on: State(
          etm: {
            E.turnOff: [T.toOff],
          },
          regions: regions,
          onEntry: Action(
            description: 'Turning on.',
            action: (machine, dynamic arg) async => print('ON'),
          ),
        ),
      },
      transitions: {
        T.toOn: Transition(to: S.on),
        T.toOff: Transition(to: S.off),
      },
    );

// 初始化状态机实例
final lightMachine = createLightMachine();

// 模拟事件触发
Future<void> play() async {
  while (true) {
    await Future<void>.delayed(const Duration(seconds: 1));
    await lightMachine.fire(E.turnOn);
    await Future<void>.delayed(const Duration(seconds: 1));
    await lightMachine.fire(E.turnOff);
  }
}

注意事项

1. MacOS 平台配置：如果在 macOS 桌面应用中使用 VisualMonitor，需要在项目的 macos/Runner/DebugProfile.entitlements 和 macos/Runner/Release.entitlements 文件中添加以下权限：

   <key>com.apple.security.network.client</key>
   <true/>