diff --git a/README.md b/README.md index fb86290..a52432c 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,124 @@ # ArborFlow -ArborFlow is a cross-platform visual behavior tree editor for BehaviorTree.CPP. It runs as an Electron desktop app on Windows, Linux, and macOS. +ArborFlow 是一个面向 [BehaviorTree.CPP](https://github.com/BehaviorTree/BehaviorTree.CPP) 的跨平台行为树生成、编辑与运行状态可视化工具。 -## Features +项目使用 Electron、React、TypeScript 和 React Flow 构建，可在 Windows、Linux 与 macOS 上运行。当前版本以单个主行为树为编辑单位，可通过 `SubTree` 节点引用其他行为树。 -- Drag-and-drop behavior tree canvas with cycle and child-count validation -- BehaviorTree.CPP control, decorator, action, condition, and subtree nodes -- Editable ports and blackboard expressions such as `{goal}` -- Automatic tree layout, minimap, zoom, undo, and redo -- ArborFlow project files (`.arborflow`) and BehaviorTree.CPP v4 XML import/export -- Real-time node monitoring over a direct WebSocket or `rosbridge_server` -- Runtime states: `IDLE`, `RUNNING`, `SUCCESS`, `FAILURE`, and `SKIPPED` +## 主要功能 -## Development +- 拖拽创建节点并通过端口连接父子关系 +- 支持控制、装饰、动作、条件和子树节点 +- 自动阻止环路、重复父节点以及非法子节点数量 +- 编辑节点注册名称、端口、黑板表达式、备注和断点标记 +- 自动布局、画布缩放、小地图、撤销与重做 +- 保存和打开 `.arborflow` 工程文件 +- 导入、导出和预览 BehaviorTree.CPP v4 XML +- 通过 WebSocket 或 `rosbridge_server` 实时显示节点状态 +- 实时事件流、消息计数、节点匹配统计、延迟检测和自动重连 -Requirements: Node.js 20 or newer and npm. +支持的运行状态： + +| 状态 | 数值 | 含义 | +| --- | ---: | --- | +| `IDLE` | `0` | 节点空闲 | +| `RUNNING` | `1` | 节点正在执行 | +| `SUCCESS` | `2` | 节点执行成功 | +| `FAILURE` | `3` | 节点执行失败 | +| `SKIPPED` | `4` | 节点被跳过 | + +## 环境要求 + +- Node.js 20 或更高版本 +- npm 10 或更高版本 +- Windows 10/11、主流 Linux 发行版或 macOS + +## 快速开始 + +进入项目目录并安装依赖： + +```powershell +cd "D:\Elec Control\ArborFlow" +npm install +``` + +启动 Electron 开发模式： ```bash -npm install npm run dev ``` -Run a local status server in another terminal to exercise the monitor without ROS: - -```bash -npm run mock:monitor -``` - -Connect ArborFlow to `ws://127.0.0.1:1667` and the demo tree will cycle through live states. - -Build the web assets and type-check the project: +执行类型检查并构建前端资源： ```bash npm run build ``` -Create desktop packages on the current operating system: +构建完成后，可单独启动浏览器预览： ```bash -npm run dist +npm run preview ``` -Platform-specific targets are available as `npm run dist:win`, `npm run dist:linux`, and `npm run dist:mac`. Electron applications should normally be packaged on the matching host OS, especially for macOS signing. +## 基本操作 + +1. 从左侧节点库单击节点，或将节点拖入画布。 +2. 从父节点底部连接点拖到子节点顶部连接点。 +3. 选中节点后，在右侧检查器修改名称、端口、黑板参数或断点。 +4. 使用工具栏的自动布局按钮整理整棵树。 +5. 将工程保存为 `.arborflow`，或导出为 BehaviorTree.CPP XML。 +6. 打开 Monitor，填写机器人地址后连接实时状态流。 + +工程文件保存编辑器坐标、节点 ID、端口、备注等完整信息。XML 只保存 BehaviorTree.CPP 可执行数据，不包含编辑器坐标或实时运行状态。 + +## BehaviorTree.CPP XML + +ArborFlow 导出 BehaviorTree.CPP v4 格式： + +```xml + + + + + + + + + +``` + +同一父节点下的执行顺序按照子节点在画布上的横向位置从左到右确定。导出前必须保证画布中只有一个根节点，并且所有节点组成一棵无环树。 ## Real-time Monitor -Open **Monitor** in the application toolbar and enter either a direct WebSocket endpoint or a `rosbridge_server` endpoint. Node references are matched in this order: +监视器支持两种接入方式： -1. ArborFlow node ID, visible in the Inspector -2. Exact display name or registration name -3. Last segment of a slash-separated path +- ROS 或其他程序直接提供 WebSocket JSON 服务 +- 使用 `rosbridge_server` 订阅 ROS 2 topic -### Direct WebSocket protocol +节点引用按以下顺序匹配： -ArborFlow accepts one JSON object per WebSocket message. A single status event can use any of `nodeId`, `uid`, `node`, `name`, or `path` as the node reference: +1. 检查器中显示的 ArborFlow 节点 ID +2. 节点显示名称或 BehaviorTree.CPP 注册名称 +3. 路径最后一段，例如 `/MainTree/NavigateToPose` 会匹配 `NavigateToPose` + +名称重复时，同名节点会同时更新。需要精确定位时，应发送 ArborFlow 节点 ID。 + +### 直接 WebSocket 协议 + +每个 WebSocket 消息必须是一个 JSON 对象。单节点事件示例： ```json -{"type":"status","nodeId":"navigate_action","status":"RUNNING","timestamp":1784635200000} +{ + "type": "status", + "nodeId": "navigate_action", + "status": "RUNNING", + "timestamp": 1784635200000 +} ``` -Numeric BehaviorTree.CPP status values are supported: `0=IDLE`, `1=RUNNING`, `2=SUCCESS`, `3=FAILURE`, and `4=SKIPPED`. +节点字段可以使用 `nodeId`、`uid`、`node`、`name` 或 `path`。`status` 可以是状态字符串，也可以是 BehaviorTree.CPP 对应的 `0` 至 `4` 数值。 -A full snapshot can update several nodes at once: +一次更新多个节点： ```json { @@ -75,29 +132,138 @@ A full snapshot can update several nodes at once: } ``` -The client sends `{"type":"subscribe","client":"ArborFlow","protocol":1}` after connecting and a ping every five seconds. A server may return the same timestamp using `{"type":"pong","timestamp":1784635200000}` to report round-trip latency. +连接成功后，ArborFlow 会发送订阅消息： -### ROS 2 with rosbridge +```json +{"type":"subscribe","client":"ArborFlow","protocol":1} +``` -Start rosbridge and use its WebSocket address, usually `ws://ROBOT_IP:9090`: +客户端每五秒发送一次 ping。服务端原样返回时间戳即可显示往返延迟： + +```json +{"type":"pong","timestamp":1784635200000} +``` + +### 使用 rosbridge_server + +启动 ROS 2 rosbridge： ```bash ros2 launch rosbridge_server rosbridge_websocket_launch.xml ``` -The default topic is `/arborflow/status` with type `std_msgs/msg/String`. Publish the direct-protocol JSON as the string payload: +在 Monitor 中填写： + +- WebSocket 地址：`ws://ROBOT_IP:9090` +- Topic：`/arborflow/status` + +ArborFlow 会自动发送以下 rosbridge 订阅请求： + +```json +{ + "op": "subscribe", + "topic": "/arborflow/status", + "type": "std_msgs/msg/String" +} +``` + +ROS topic 使用 `std_msgs/msg/String`，将直接 WebSocket 协议中的 JSON 放入 `data` 字段： ```bash ros2 topic pub --once /arborflow/status std_msgs/msg/String \ "{data: '{\"node\":\"NavigateToPose\",\"status\":\"RUNNING\"}'}" ``` -ArborFlow sends the rosbridge subscribe request automatically. The topic can be changed in the monitor panel. +### 本地模拟服务 -## Project format +项目包含一个用于联调的 WebSocket 状态模拟器： -`.arborflow` files retain visual positions, editor metadata, node ports, and stable monitor IDs. XML exports contain only BehaviorTree.CPP data. Runtime monitor state is transient and is never saved into either format. +```bash +npm run mock:monitor +``` + +随后在 Monitor 中连接： + +```text +ws://127.0.0.1:1667 +``` + +模拟器会让示例树中的 `BatteryOK`、`NavigateToPose` 和 `ReportResult` 循环切换状态。可通过环境变量修改端口： + +```powershell +$env:ARBORFLOW_MOCK_PORT=1767 +npm run mock:monitor +``` + +## 打包桌面应用 + +在当前操作系统上构建对应安装包： + +```bash +npm run dist +``` + +也可以使用平台命令： + +```bash +npm run dist:win +npm run dist:linux +npm run dist:mac +``` + +输出目录为 `release/`。建议在目标操作系统上执行对应打包命令，特别是 macOS 签名、公证以及不同 CPU 架构的构建。 + +可用的默认目标： + +| 平台 | 输出格式 | +| --- | --- | +| Windows | NSIS 安装包、Portable | +| Linux | AppImage、deb | +| macOS | dmg、zip | + +重新生成应用图标： + +```bash +npm run icon:render +``` + +## npm 命令 + +| 命令 | 用途 | +| --- | --- | +| `npm run dev` | 启动 Vite 和 Electron 开发环境 | +| `npm run build` | TypeScript 检查并构建前端 | +| `npm run preview` | 预览生产前端资源 | +| `npm run mock:monitor` | 启动本地实时状态模拟器 | +| `npm run icon:render` | 使用 Electron 重新生成 PNG 图标 | +| `npm run dist` | 构建当前平台桌面安装包 | +| `npm run dist:win` | 构建 Windows 包 | +| `npm run dist:linux` | 构建 Linux 包 | +| `npm run dist:mac` | 构建 macOS 包 | + +## 项目结构 + +```text +ArborFlow/ +├─ electron/ Electron 主进程与 preload +├─ public/ 公共静态资源 +├─ scripts/ Mock Monitor 与图标生成脚本 +├─ src/ +│ ├─ components/ 节点、属性面板和监视器组件 +│ ├─ lib/ XML、布局、校验和运行协议 +│ ├─ App.tsx 编辑器主界面与状态管理 +│ └─ styles.css 应用样式 +├─ build/ 应用图标 +├─ package.json npm 与 Electron Builder 配置 +└─ README.md +``` + +## 安全说明 + +Electron 渲染进程启用了上下文隔离和沙箱，并关闭 Node.js 集成。文件打开与保存通过受限的 preload API 调用主进程完成。 + +实时监视器只处理节点状态，不会执行服务端发送的脚本。实际机器人网络中仍建议使用受信任的局域网、`wss://` 或其他安全隧道。 ## License -MIT +本项目使用 MIT License，详见 `LICENSE`。