Command reference¶
Every command shares the same connection and display flags, so once you know one you know all of them.
With no command, btview opens the monitor — btview --host robot.local works exactly
like btview tui --host robot.local.
Common flags¶
Connection¶
| Flag | Default | Meaning |
|---|---|---|
--source |
— | Transport URI, e.g. groot2://robot:1667 or replay://run.jsonl. Overrides the three flags below; see transports.md |
--host |
127.0.0.1 |
Address of the publisher |
-p, --port |
1667 |
Groot2 (v4) server port |
--protocol |
v4 |
v4 = Groot2Publisher, v3 = PublisherZMQ |
--server-port |
1667 |
v3 only: REP port carrying the tree |
--publisher-port |
1666 |
v3 only: PUB port carrying status batches |
--timeout |
1.0 |
Seconds to wait for one request |
Display¶
| Flag | Meaning |
|---|---|
--ascii |
ASCII glyphs only — serial consoles, dumb terminals, log files |
--no-color |
No colour (NO_COLOR in the environment does the same) |
--uid |
Show each node's runtime uid |
--ports |
Show port remappings inline |
BTVIEW_ASCII=1 in the environment is equivalent to passing --ascii everywhere, which is
the sane default to put in a robot's shell profile.
Polling¶
--poll-hz sets how often statuses are requested. The default is 10 Hz for interactive
commands, 4 Hz for watch. Lower it on a slow link; the tree structure is only fetched
once (and on demand with r).
btview tui — the monitor¶
btview # localhost, Groot2 defaults
btview tui --host robot.local --poll-hz 5
btview tui --protocol v3 # BehaviorTree.CPP 3.x
Full-screen, mouse-aware, with a node inspector and a transition log. Keys and layout: tui.md.
btview demo — no robot required¶
Runs a synthetic Nav2 tree (plan → follow, with costmap-clearing recoveries and a round-robin of spin/wait/back-up) in a background thread and monitors it over a real socket. Nothing about the UI path is faked, which makes this a genuine install check.
btview snapshot — print once, exit¶
btview snapshot
btview snapshot --active # only running or failing branches
btview snapshot --filter FollowPath # only matching nodes, plus their ancestors
btview snapshot --graph # draw the tree instead of listing it
btview snapshot --uid --ports # everything, for a bug report
btview snapshot --ascii --no-color >> log.txt
Exit status is 0 on success and 1 if the tree could not be fetched, so it drops
straight into a health check.
--graph draws the tree as boxes and connectors rather than an indented list. It is never
wrapped: piped output is rendered at whatever width the graph needs, and a terminal too
narrow for it gets a cropped drawing plus a hint. --box-width N overrides the automatic
sizing when you want wider labels.
btview watch — refresh in place¶
Like snapshot on a loop, redrawing without taking over the screen. Scrollback survives,
which matters when you are sharing a console with other output.
btview echo — one line per change¶
The ros2 topic echo of behaviour trees. Text output is human-readable; --json emits
newline-delimited objects (time, uid, node, from, to) that jq can chew on:
btview show — render a file¶
btview show nav2_bt.xml
btview show my_tree.xml --ports --filter Recovery
btview show my_tree.xml --graph # drawn, not listed
btview show my_tree.xml --graph --box-width 28 > tree.txt
No server, no sockets. Works on hand-written trees and on anything btview export --format
xml produced. Nodes in a file have no runtime status, so the status column reads —.
btview export — get the tree out¶
btview export --format mermaid -o tree.mmd # from a live publisher
btview export --file tree.xml --format dot | dot -Tpng > tree.png
btview export --format json --with-status # structure + current statuses
| Format | Use |
|---|---|
mermaid |
Paste into GitHub issues, PRs, docs |
dot |
Graphviz — PNG, SVG, PDF |
json |
Diffing, scripting, CI assertions |
xml |
BehaviorTree.CPP XML; round-trips through btview show |
--with-status colours the output by what the tree is doing right now.
btview info — diagnostics¶
Prints the endpoint, protocol, tree uuid, node counts by kind, and the round-trip latency of the tree fetch and of status polls. First thing to run when something feels slow.
btview blackboard — v4 only¶
Requests blackboard entries from a Groot2Publisher. Not every BehaviorTree.CPP build
answers these; when yours does not, the error says so rather than hanging.
btview record / btview play¶
btview record -o run.btv.jsonl # until Ctrl+C
btview record -o run.btv.jsonl --duration 300 # or a fixed window
btview play run.btv.jsonl
btview play run.btv.jsonl --speed 4 --loop
The recording is newline-delimited JSON: a header with the tree XML, then one frame per poll. It is small, greps cleanly, and replays into the same monitor you use live — so a failure captured at 3 a.m. on the robot can be watched properly the next morning.
btview bridge — read one transport, write another¶
# let the Groot2 GUI (v4 only) watch a BehaviorTree.CPP 3.x robot
btview bridge --from btcpp3://robot:1667?publisher_port=1666 --to groot2://0.0.0.0:1667
# replay a recording as if it were a live robot
btview bridge --from replay://yesterday.btv.jsonl?speed=2 --to groot2://0.0.0.0:1667
# capture to disk (what 'record' does, spelled generally)
btview bridge --from groot2://robot:1667 --to file://run.btv.jsonl --duration 300
btview transports — what this build speaks¶
Lists the registered source and sink schemes with their options. Adding one is a class plus a decorator — see transports.md.
btview mock — serve a synthetic tree¶
btview mock # Groot2 v4 on 1667
btview mock --protocol v3 # REP 1667 / PUB 1666
btview mock --host 0.0.0.0 --tick-hz 2 # reachable from other machines
Useful for testing a network path, developing against the protocol, or pointing the real Groot2 at something while your robot is in pieces.
Exit statuses¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Error — connection, parse or file problem, already printed |
130 |
Interrupted with Ctrl+C |