Architecture¶
Beehave is a pipeline. A tree goes in, an action graph comes out. Every step has one job and one input type, so each can be tested and replaced on its own.
flowchart LR
xml[/"BT.CPP XML<br/>v3 or v4"/] --> parse
py[/"py_trees tree<br/>(live objects)"/] --> adapt["1. Adapt"]
parse["1. Parse"] --> model[("Tree model<br/>Document")]
adapt --> model
model --> flatten["2. Flatten"]
flatten --> flat[("FlatTree")]
flat --> walk["3. Walk"]
walk --> graph[("ActionGraph")]
graph --> render["5. Render"]
render --> out[/"text · Mermaid · DOT · JSON"/]
graph --> stats["Stats"]
simplify["4. Simplify<br/>(Phase 2)"] -.-> graph
The design plan names five steps: parse, flatten, walk, simplify, render.
Phase 1 ships four of them. Simplify (shrinking guards with a BDD or
sympy) is Phase 2, and the walk already keeps guards in a form it can
consume.
The steps¶
| Step | Module | Input | Output | Job |
|---|---|---|---|---|
| Parse | beehave.parsers |
XML files | Document |
Detect the BT.CPP version, read every tree, classify every node, check structure. |
| Adapt | beehave.parsers.pytrees |
a py_trees root | Document |
Read a live py_trees tree without running it. |
| Flatten | beehave.flatten |
Document |
FlatTree |
Inline every subtree, apply port remapping. |
| Walk | beehave.walk |
FlatTree |
ActionGraph |
For each action: what runs next on success, on failure, and under which guard. |
| Render | beehave.render |
ActionGraph |
str |
Text, Mermaid, Graphviz DOT, JSON. |
| Stats | beehave.stats |
FlatTree + ActionGraph |
Stats |
Size, reduction, longest guard, breakage. |
beehave.analyze() runs parse, flatten and walk in one call, and
beehave.analyze_py_trees() does the same from a py_trees tree. The CLI
(beehave graph | stats | trees) is a thin layer over those functions.
One internal model, many parsers¶
The model (beehave.model) does not know about XML or about BT.CPP. A node
has:
- a kind: control, decorator, condition, action or subtree;
- a semantics: what it does, independent of what a library calls it.
SequenceStar(v3) andSequenceWithMemory(v4) are bothSEQUENCE_WITH_MEMORY; - its type as written, its optional name, its ports, its children, and where it was read from.
For BT.CPP v4, a node also carries its pre- and post-condition scripts
(_skipIf, _onSuccess…), which are not ports.
Adding a format means writing a parser that produces this model. Flatten, walk and render do not change. That is how BT.CPP v4 and py_trees were added. See ADR 0002 and the formats guide.
Parse¶
beehave.parsers.detect tells which BT.CPP version a set of files is
written in, from BTCPP_format or from v4-only constructs, and hands them to
btcpp_v3 or btcpp_v4. Both are dialects of one loader
(beehave.parsers._btcpp): it reads one or more files or folders, follows
<include> tags (finding ros_pkg packages with beehave.parsers.ros), and
reads <TreeNodesModel>. A dialect only says what differs: the
built-in nodes, the subtree syntax, which attributes are scripts, and which
definition of a duplicate tree wins. The loader uses expat directly so every
node keeps its line number, and it refuses any DOCTYPE, which rules out
entity expansion attacks.
beehave.parsers.pytrees reads a live py_trees tree instead. It classifies
each object by the class that owns its tick logic, and never calls user code.
Importing the module that builds the tree is a separate, explicit step
(ADR 0010).
A user-defined node is classified by the strongest signal available:
- the project config (
conditions:/actions:inbeehave.yaml); - the explicit XML form (
<Condition ID="X"/>); - the
<TreeNodesModel>declaration; - its shape: no child is an action, one child a decorator, more a control.
The config wins because it is the only place to fix "conditions in disguise": nodes registered as actions that only check something.
Flatten¶
Every SubTree / SubTreePlus (v3) or SubTree (v4) becomes a subtree node
whose single child is the inlined body. Port values inside the body are rewritten through the
reference's remapping, so a node deep inside nested subtrees shows the
blackboard key it really reads. Keys that are not remapped are private to the
subtree instance and are shown as {Subtree/key}.
Walk¶
The walk is a continuation-passing compilation. It is described in detail in Phase 1 and in ADR 0003. In short: compile each node with "where to go on success" and "where to go on failure", and return "what runs first". Actions become vertices, conditions become branch points, and branch points are expanded into guards on the edges. For BT.CPP v4 a third continuation says where to go when a node is skipped (ADR 0009).
Nodes that Phase 1 cannot model exactly are walked with a documented approximation and reported as diagnostics (ADR 0004).
Render¶
Renderers are pure functions of the graph. They are deterministic, so the same tree always gives the same bytes. That lets teams commit graphs next to trees and review the diff in a pull request.
- Text:
A --[failure and not BatteryOK]--> B, one transition per line. - Mermaid: renders on GitHub, GitLab and in these docs.
- DOT: for Graphviz, large graphs and image export.
- JSON: a versioned document (
beehave.action-graph, version 1) for other tools, including the future operator view.
Failure edges are always dashed, so the graph still reads in greyscale and for colour-blind readers.
Errors and diagnostics¶
- Errors (
beehave.BeehaveErrorand subclasses) stop the analysis: the input is malformed, a subtree is missing, the format is unsupported. Every error carries afile:linelocation when one is known. - Diagnostics do not stop the analysis: an approximated node, an include that cannot be followed. They travel with the graph and are printed on stderr by the CLI.
Dependencies¶
The core needs only the standard library plus PyYAML (for the config file). See ADR 0005.
Extension points¶
| You want to… | Touch |
|---|---|
| Support a new built-in node | BUILTINS in the parser, a Semantics member, a rule in walk.py, tests. |
| Support a new tree format | A new module in beehave/parsers/ producing a Document. |
| Add an output format | A new module in beehave/render/ and an entry in FORMATS. |
| Add a metric | beehave/stats.py. |