tassello 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 Tassello follows [semantic versioning](https://semver.org): before 1.0, a new minor version may
 change the plugin API (`tassello/sdk`, `tassello/server`, `tassello/vite`), as noted here.
 
+## Unreleased
+
+- Behavior Tree Inspector widget: what a BT.CPP behavior tree is doing, from its
+  `nav2_msgs/BehaviorTreeLog` (Nav2's `/behavior_tree_log`), on the tree of its XML file: the
+  running branch, each node's status, last result, counts and ports, and the latest transitions,
+  as a graph or a list. The server follows the log for every page and keeps the nodes' state.
+- The inspector records its log into rosbags (`ros2 bag record`), and plays rosbags back in the
+  widget (MCAP or SQLite, Humble's or Jazzy's), with pause, seek and speed.
+- Behavior Tree Editor widget: a BT.CPP behavior tree's XML file of the robot, edited as a graph,
+  with a palette of nodes (BT.CPP's, Nav2's, node libraries of `TreeNodesModel`, the file's own),
+  drag and drop, a side panel for the nodes' names and ports, subtrees, undo and redo, copy and
+  paste, and an XML view. Saves only what changed, keeping the file's comments and layout, and
+  never over changes made on the robot since it was read.
+- The file browser is resizable, and shows long names whole.
+- Plugins: the `behavior-tree` property kind, `connection.subscribeBehaviorTree`,
+  `recordBehaviorTree`, `subscribeBehaviorTreePlayback`, `controlBehaviorTreePlayback`,
+  `subscribeBehaviorTreeFile`, `saveBehaviorTreeFile`.
+- Uploads take behavior trees (XML) as well as images.
+- Logs widget: the ROS log (`/rosout`), as rqt_console and swri_console show it: every node's
+  messages coloured by level, the nodes running and those that logged with their counts, filters
+  by node, level and text (terms or regular expressions, to show or to hide), pause, follow,
+  clear, download, and a message's details. A widget can be for some nodes only (`amcl,
+  *_server`). The server follows the log for every page and keeps its latest 10,000 messages.
+- Plugins: `connection.subscribeRosout`, and the `LogsIcon`, `NodesIcon`, `SearchIcon`,
+  `BanIcon`, `FilterIcon`, `DownloadIcon` and `ArrowDownToLineIcon` icons.
+
 ## 0.1.0
 
 The first release, from the Dieletrikbot's web dashboard.

package/README.md

@@ -10,7 +10,8 @@ and plugins add more.
 - **Panels of widgets** on a grid: add, move and resize them in the browser, no code or config files.
 - **Every device**: a desktop canvas, and layouts of their own for tablets and phones.
 - **Built in**: teleop pads, a Nav2 map with goals, the robot's URDF in 3D, an arm jogger, cameras,
-  images, command buttons and a systemd application manager.
+  images, command buttons, a systemd application manager, a behavior tree inspector and
+  editor, and the ROS log of every node.
 - **Plugins**: widgets of your own, with server-side code if they need it, as npm or ROS packages.
 - **One process**: a ROS 2 node in Node.js. Nothing to install on the robot but Node.js.
 
@@ -113,6 +114,9 @@ after the others on the devices already arranged.
 | **Image Viewer** | A static image: a file of the robot, typed (`/…`, `~/…`, `package://…`) or picked by browsing its folders, or an image uploaded from the page's device |
 | **Button** | Runs a bash command on the robot, showing its output. Takes its running colour until the command finishes, on every page showing it; pressing it again stops the command |
 | **Application Manager** | The robot's systemd services matching a name: their state, whether they start at boot, buttons to start, stop and restart them, and their journal |
+| **Behavior Tree Inspector** | What a BT.CPP behavior tree is doing, from its log (Nav2's `/behavior_tree_log`): the tree of its XML file with the running branch lit, each node's status, last result, counts and ports, and the latest transitions. As a graph (pan, zoom, follow the running nodes) or a list. Records the log into rosbags, and plays rosbags back at any speed |
+| **Behavior Tree Editor** | Edits a BT.CPP behavior tree's XML file of the robot as a graph: nodes from a palette (BT.CPP's, Nav2's, your libraries'), dragged where they go, moved with their children, their names and ports edited in a side panel. Subtrees, undo and redo, copy and paste, an XML view. Saves only what changed, never over changes made meanwhile |
+| **Logs** | The ROS log (`/rosout`), as rqt_console and swri_console show it: every node's messages coloured by level, the nodes running and those that logged with their counts, filtered by node, by level and by text (terms or a regular expression, to show or to hide). Pause, follow the newest, clear, download, and a message's details: where it was logged |
 
 Their properties (topics, frames, speeds, colours, ...) are edited in the side panel of edit mode.
 
@@ -153,6 +157,58 @@ Notes on some of them:
 - **Image Viewer** reads only images (PNG, JPEG, GIF, WebP, BMP, SVG). Uploads are kept next to
   the panels (`~/.local/share/tassello/images`). Images are served sandboxed: an SVG cannot run
   scripts in the dashboard.
+- **Behavior Tree Inspector** follows a `nav2_msgs/BehaviorTreeLog` topic, which BT.CPP trees
+  log with Nav2's `RosTopicLogger`: Nav2's bt_navigator on `/behavior_tree_log`. Its *tree file*
+  is the XML the robot runs (`/…`, `~/…`, `package://…`, browsed or uploaded), read with its
+  includes and subtrees, and again when it changes; e.g. Nav2's default,
+  `package://nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml`.
+  Without it, the nodes are listed as the log names them. Since Jazzy, the log gives the nodes'
+  UIDs, which tell them apart exactly; before, nodes of the same name (a `RecoveryNode` named
+  after its action) are told apart by their statuses and their parents'. The log only says what
+  changes: the server follows it for every page, and for 10 minutes after the last one closes,
+  so that a page opened later sees the nodes as they are. A node reset to idle by its parent
+  shows how it last ended.
+
+  Its record button records the log on the robot with `ros2 bag record`, into a new folder
+  (`<recordings folder>/behavior_tree_<date>_<time>` by default), until pressed again: every
+  page showing the topic shows it recording. Its playback button opens a rosbag of the robot
+  (a bag's folder, or its `.mcap` or `.db3` file, e.g. of a whole run recorded with
+  `ros2 bag record -a`) and plays its log in the widget, on the tree of its file, without
+  publishing anything: pause, seek and choose the speed (0.1× to 16×). Bags of Humble and of
+  Jazzy are read either way; SQLite bags need Node.js 22.13, zstd compressed MCAP 22.15.
+- **Behavior Tree Editor** edits one BehaviorTree of the file at a time (its toolbar switches
+  between them, adds new ones, and double clicking a subtree opens its tree, even in an included
+  file). Add a node from the palette by dragging it where it goes (into a node, or beside one), or
+  click it to add it into the selected node, or after it. Drag nodes to move them with their
+  children. The side panel edits the selected node's name and ports, with their types, defaults
+  and descriptions from its model, and its other attributes (BT.CPP 4's `_skipIf`, `_while`…);
+  it moves, duplicates, wraps, unwraps and replaces it. What BT.CPP would refuse, such as a
+  decorator without its child, is marked. Keys: Delete, Ctrl+Z, Ctrl+Shift+Z, Ctrl+C, Ctrl+X,
+  Ctrl+V, Ctrl+D, Ctrl+S, the arrows to move the selection (Alt: the node).
+
+  The palette has BT.CPP's nodes (of the file's format, `BTCPP_format`), Nav2's (its
+  `nav2_tree_nodes.xml`, when installed), those of the file's `TreeNodesModel` and includes, and
+  those of the *node libraries*: XML files of `TreeNodesModel`, as Groot exports them, set in the
+  widget's properties or loaded from the palette. Saving writes back only the elements changed,
+  the rest of the file (comments, blank lines, indentation) as it was. The file is read again when
+  it changes on the robot: without changes in the editor it is shown at once, with changes the
+  editor asks which to keep, and a save over a file changed since it was read is refused.
+  Uploads, and files the server cannot write, are saved elsewhere with *Save as*. The editor keeps
+  its changes while the page is open, and the page asks before closing with changes not saved.
+- **Logs** follows `/rosout` (`rcl_interfaces/msg/Log`), on which every node's logger publishes.
+  Its list of nodes has those running in the ROS graph and those that logged, with their
+  warnings and errors: choose some to see only theirs. A node's logger is named after it, dots
+  for slashes (`robot1.amcl` for `/robot1/amcl`). The level buttons show and hide each level
+  (Shift+click: that level only); *Include* and *Exclude* keep or drop the messages containing any
+  of their terms, separated by `;`, or matching a regular expression. Pausing holds the list while
+  the new messages wait; clearing empties it for this page. A message clicked shows whole, with its
+  file, line and function; the arrow keys go through the list. *Download* saves the messages shown
+  as ROS prints them (`[WARN] [1729435407.512346] [robot1.amcl]: ...`). The widget's properties
+  set its nodes (names or globs, e.g. `amcl, *_server`: one widget per subsystem), the levels and
+  filters it opens with, and the time shown: the clock, ROS stamps, or none. The server follows the
+  log for every page, keeping its latest 10,000 messages, and for 10 minutes after the last page
+  closes: a page opened later sees what was logged meanwhile, and when first opened, what each
+  node logged in its last 10 seconds (rosout's own history).
 
 ## Plugins
 
@@ -180,8 +236,10 @@ and ship example panels. See **[docs/plugins.md](docs/plugins.md)**.
 ## Security
 
 Tassello has no login. **Anyone who can open the page can drive the robot, run any command as
-the server's user and read its images**: keep it on a network you trust, or behind a reverse
-proxy with authentication (it serves everything under `/`, its WebSocket at `/ws`).
+the server's user, read its images, behavior trees and the behavior tree logs of its rosbags,
+record rosbags into new folders, and write behavior tree files (XML files whose root is
+`<root>`, over others of the same kind only)**: keep it on a network you trust, or behind a reverse proxy
+with authentication (it serves everything under `/`, its WebSocket at `/ws`).
 
 ## How it works
 
@@ -207,6 +265,11 @@ Safety and bandwidth are the server's concern:
   of their publishers, so latched maps arrive.
 - Topics are subscribed once, whatever the number of pages, with the type and QoS of their
   publishers; TF only while a page shows the robot.
+- Behavior tree logs, streams of transitions, are followed whole, none dropped: each page gets
+  the nodes that changed, at most 10 times a second, however fast the tree ticks.
+- The ROS log is followed once for every page: each gets the new messages at most 10 times a
+  second, at most 500 at a time (a node logging faster has some skipped, which the page shows).
+  Only the rows in sight are drawn.
 - A button runs the command saved in its panel, never one sent by the page.
 
 ## Developing

package/dist/server/behavior_tree_file.d.ts

@@ -0,0 +1,17 @@
+import type { BehaviorTreeInfo, BtNode, BtNodeKind } from '../shared/protocol.ts';
+import { type XmlElement } from '../shared/xml.ts';
+import { type Logger } from './util.ts';
+export interface BehaviorTreeFile {
+    treeId: string;
+    nodes: BtNode[];
+    warnings: string[];
+    files: string[];
+}
+export declare function resolveTreeFile(source: string, uploadsDir: string, home?: string): string;
+export declare function instantiate(trees: Map<string, XmlElement>, mainId: string, kinds: Map<string, BtNodeKind>, warnings: string[]): BtNode[];
+export declare function loadBehaviorTree(file: string): Promise<BehaviorTreeFile>;
+export type TreeInfo = Omit<BehaviorTreeInfo, 'type' | 'id'>;
+export declare function readTree(source: string, uploadsDir: string, logger: Logger): Promise<{
+    tree: TreeInfo;
+    files: string[];
+}>;

package/dist/server/behavior_tree_file.js

@@ -0,0 +1,232 @@
+// The behavior trees' XML files (BT.CPP's format, 3 and 4), for the behavior
+// tree inspector widgets: the tree the robot runs, as BT.CPP instantiates it,
+// its nodes in the order of their UIDs: depth first, from the first child of
+// the main BehaviorTree, each SubTree followed by its tree's nodes.
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EXPLICIT, guessKind } from '../shared/bt_nodes.js';
+import { parseXml } from '../shared/xml.js';
+import { isUploadName } from './files.js';
+import { errorMessage, packageShareDirectory } from './util.js';
+// Beyond this, a file (or a recursion of subtrees missed) is not a tree to show
+const MAX_NODES = 5000;
+const PACKAGE_URL = /^package:\/\/([^/]+)\/(.+)$/;
+// The XML file a widget names: a robot path (/…, ~/…), package://… or
+// uploads/<name>. Throws for anything else: only XML files are read.
+export function resolveTreeFile(source, uploadsDir, home = os.homedir()) {
+    const value = source.trim();
+    let file;
+    if (value.startsWith('uploads/')) {
+        const name = value.slice('uploads/'.length);
+        if (!isUploadName(name)) {
+            throw new Error(`No upload "${name}"`);
+        }
+        file = path.join(uploadsDir, name);
+    }
+    else if (PACKAGE_URL.test(value)) {
+        const [, name, relative] = PACKAGE_URL.exec(value);
+        const share = packageShareDirectory(name);
+        if (!share) {
+            throw new Error(`No package "${name}": is its workspace sourced?`);
+        }
+        file = path.resolve(share, relative);
+        if (!file.startsWith(share + path.sep)) {
+            throw new Error(`"${value}" is not in its package`);
+        }
+    }
+    else {
+        const expanded = value === '~' || value.startsWith('~/') ? path.join(home, value.slice(1)) : value;
+        if (!path.isAbsolute(expanded)) {
+            throw new Error(`Not a path: "${source}" (/…, ~/…, package://…)`);
+        }
+        file = path.resolve(expanded);
+    }
+    if (path.extname(file).toLowerCase() !== '.xml') {
+        throw new Error(`Not an XML file: "${source}"`);
+    }
+    return file;
+}
+function modelKinds(root, kinds) {
+    for (const model of root.children.filter((child) => child.name === 'TreeNodesModel')) {
+        for (const node of model.children) {
+            const kind = EXPLICIT[node.name];
+            if (kind && node.attributes.ID) {
+                kinds.set(node.attributes.ID, kind);
+            }
+        }
+    }
+}
+// Nav2's node models, when installed: what its nodes are
+let nav2Kinds = null;
+function loadNav2Kinds() {
+    nav2Kinds ??= (async () => {
+        const kinds = new Map();
+        const share = packageShareDirectory('nav2_behavior_tree');
+        if (share) {
+            try {
+                modelKinds(parseXml(await fs.readFile(path.join(share, 'nav2_tree_nodes.xml'), 'utf8')), kinds);
+            }
+            catch {
+                // Not there, or not readable: the known nodes and the guesses will do
+            }
+        }
+        return kinds;
+    })();
+    return nav2Kinds;
+}
+// The tree's nodes, from the main BehaviorTree; subtrees not defined, and
+// recursions, are reported and left unexpanded
+export function instantiate(trees, mainId, kinds, warnings) {
+    const nodes = [];
+    const visit = (element, parent, expanding) => {
+        if (nodes.length >= MAX_NODES) {
+            throw new Error(`The tree has more than ${MAX_NODES} nodes`);
+        }
+        const explicit = EXPLICIT[element.name];
+        const { name, ...ports } = element.attributes;
+        let type = element.name;
+        if (explicit === 'subtree') {
+            type = 'SubTree';
+        }
+        else if (explicit && ports.ID) {
+            type = ports.ID;
+            delete ports.ID;
+        }
+        const subtreeId = explicit === 'subtree' ? (ports.ID ?? '') : '';
+        const index = nodes.length;
+        nodes.push({
+            name: name ?? (subtreeId || type),
+            type,
+            kind: explicit ?? kinds.get(type) ?? guessKind(type, element.children.length),
+            parent,
+            ports,
+        });
+        if (explicit !== 'subtree') {
+            for (const child of element.children) {
+                visit(child, index, expanding);
+            }
+            return;
+        }
+        const definition = trees.get(subtreeId);
+        if (!subtreeId) {
+            warnings.push(`A SubTree without ID, line ${element.line}`);
+        }
+        else if (expanding.includes(subtreeId)) {
+            warnings.push(`The subtree ${subtreeId} includes itself, line ${element.line}`);
+        }
+        else if (!definition) {
+            warnings.push(`No BehaviorTree ${subtreeId}, for the SubTree of line ${element.line}`);
+        }
+        else if (definition.children[0]) {
+            visit(definition.children[0], index, [...expanding, subtreeId]);
+        }
+    };
+    const main = trees.get(mainId)?.children[0];
+    if (!main) {
+        throw new Error(`The BehaviorTree ${mainId} is empty`);
+    }
+    visit(main, -1, [mainId]);
+    return nodes;
+}
+// The tree of the file, its includes followed (relative to it, or to their
+// ros_pkg's share directory). The main tree is the one main_tree_to_execute
+// names, else the first of the file that no other uses as a subtree.
+export async function loadBehaviorTree(file) {
+    const trees = new Map();
+    // The trees of the file itself, in order
+    const own = [];
+    const kinds = new Map(await loadNav2Kinds());
+    const warnings = [];
+    const files = [];
+    let mainId = '';
+    const read = async (current, top) => {
+        files.push(current);
+        let root;
+        try {
+            root = parseXml(await fs.readFile(current, 'utf8'));
+        }
+        catch (e) {
+            const code = e.code;
+            throw new Error(`Cannot read ${current}: ${code ?? errorMessage(e)}`);
+        }
+        if (root.name !== 'root') {
+            throw new Error(`${current} is not a behavior tree: its root element is <${root.name}>, not <root>`);
+        }
+        if (top) {
+            mainId = root.attributes.main_tree_to_execute ?? '';
+        }
+        modelKinds(root, kinds);
+        for (const child of root.children) {
+            if (child.name === 'include') {
+                const { ros_pkg: rosPackage, path: relative = '' } = child.attributes;
+                const share = rosPackage ? packageShareDirectory(rosPackage) : path.dirname(current);
+                if (!share) {
+                    warnings.push(`Not included: ${relative}, of the package ${rosPackage}, not found`);
+                    continue;
+                }
+                const included = path.resolve(share, relative);
+                if (files.includes(included)) {
+                    continue;
+                }
+                try {
+                    await read(included, false);
+                }
+                catch (e) {
+                    warnings.push(`Not included: ${errorMessage(e)}`);
+                }
+            }
+            else if (child.name === 'BehaviorTree') {
+                const id = child.attributes.ID ?? (trees.size === 0 ? 'MainTree' : `BehaviorTree ${trees.size + 1}`);
+                if (trees.has(id)) {
+                    warnings.push(`BehaviorTree ${id} defined twice: the first one is shown`);
+                    continue;
+                }
+                trees.set(id, child);
+                if (top) {
+                    own.push(id);
+                }
+            }
+        }
+    };
+    await read(file, true);
+    if (trees.size === 0) {
+        throw new Error(`${file} has no BehaviorTree`);
+    }
+    if (mainId && !trees.has(mainId)) {
+        warnings.push(`No BehaviorTree ${mainId}, the main_tree_to_execute`);
+        mainId = '';
+    }
+    if (!mainId) {
+        const used = new Set();
+        const collect = (element) => {
+            if (EXPLICIT[element.name] === 'subtree' && element.attributes.ID) {
+                used.add(element.attributes.ID);
+            }
+            element.children.forEach(collect);
+        };
+        trees.forEach(collect);
+        const candidates = [...own, ...trees.keys()];
+        mainId = candidates.find((id) => !used.has(id)) ?? candidates[0];
+    }
+    return { treeId: mainId, nodes: instantiate(trees, mainId, kinds, warnings), warnings, files };
+}
+// The tree a widget names (empty: none), or why it could not be read; and
+// the files read, to read it again when they change
+export async function readTree(source, uploadsDir, logger) {
+    const tree = { treeId: '', nodes: [], error: null, warnings: [] };
+    if (!source) {
+        return { tree, files: [] };
+    }
+    let files = [];
+    try {
+        const file = resolveTreeFile(source, uploadsDir);
+        files = [file];
+        const loaded = await loadBehaviorTree(file);
+        return { tree: { treeId: loaded.treeId, nodes: loaded.nodes, error: null, warnings: loaded.warnings }, files: loaded.files };
+    }
+    catch (e) {
+        logger.warn(`Behavior tree ${source}: ${errorMessage(e)}`);
+        return { tree: { ...tree, error: errorMessage(e) }, files };
+    }
+}

package/dist/server/behavior_tree_files.d.ts

@@ -0,0 +1,18 @@
+import type { BehaviorTreeFile, BehaviorTreeModels, BehaviorTreeSaved } from '../shared/protocol.ts';
+import { type Logger } from './util.ts';
+export type FileState = Omit<BehaviorTreeFile, 'type' | 'id'>;
+export type ModelsState = Omit<BehaviorTreeModels, 'type' | 'id'>;
+export interface BehaviorTreeFileWatcher {
+    onFile: (file: FileState) => void;
+    onModels: (models: ModelsState) => void;
+}
+export declare function contentVersion(text: string): string;
+export declare class BehaviorTreeFiles {
+    private readonly uploadsDir;
+    private readonly logger;
+    private readonly watched;
+    constructor(uploadsDir: string, logger: Logger);
+    watch(source: string, libraries: string[], watcher: BehaviorTreeFileWatcher): () => void;
+    save(source: string, text: string, base: string | null, create: boolean): Promise<BehaviorTreeSaved>;
+    stopAll(): void;
+}