Groot1Publisher

Visualize BehaviorTree.CPP v4 trees in Groot 1 (legacy)

This package provides a bridge to visualize BehaviorTree.CPP v4 trees in Groot 1 (legacy visualization tool).

🎯 Problem

• Groot 1 was designed for BehaviorTree.CPP v3 and uses a specific ZMQ-based protocol with FlatBuffers serialization
• Groot 2 is designed for BehaviorTree.CPP v4 and uses a different protocol (XML-based tree structure)
• If you have a v4 tree but want to visualize it in Groot 1, this bridge solves that problem!

✨ Features

• ✅ Drop-in replacement for Groot2Publisher when using Groot 1
• ✅ No source code dependencies - just install BehaviorTree.CPP v4 normally
• ✅ ROS2 integration - works with colcon build
• ✅ Standalone CMake - also works without ROS2
• ✅ SubTree support - handles port remapping correctly

📦 Installation

Prerequisites

Install BehaviorTree.CPP v4:

ROS2 (Recommended):

sudo apt install ros-${ROS_DISTRO}-behaviortree-cpp

From source (Not Required if installed via ROS2):

git clone https://github.com/BehaviorTree/BehaviorTree.CPP.git
cd BehaviorTree.CPP
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc)
sudo make install

Install ZeroMQ:

sudo apt install libzmq3-dev

Build Groot1Publisher

ROS2 workspace:

cd ~/your_ros2_ws/src
git clone https://github.com/Vishnu-Kr/Groot1Publisher.git
cd ..
colcon build --packages-select groot1_publisher
source install/setup.bash

Standalone CMake:

git clone https://github.com/Vishnu-Kr/Groot1Publisher.git
cd groot1_publisher
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

🚀 Quick Start

1. Add to Your Code

#include "groot1_publisher/groot1_publisher.h"

// Create your v4 tree
BT::BehaviorTreeFactory factory;
// ... register nodes ...
auto tree = factory.createTreeFromText(xml_text);

// Create Groot1Publisher - replaces Groot2Publisher!
BT::Groot1Publisher publisher(tree);
// Default: max 25 msgs/sec, PUB port 1666, REP port 1667

while (true) {
    tree.tickOnce();
}

2. Link in CMake

find_package(groot1_publisher REQUIRED)
target_link_libraries(your_target PRIVATE groot1_publisher)

3. Connect Groot 1

1. Open Groot 1
2. Select Monitor mode
3. Enter connection:
   • Publisher port: 1666
   • Server port: 1667
4. Click Connect
5. Watch your v4 tree execute in real-time!

📊 Protocol Comparison

Feature	Groot 1 (BT.CPP v3)	Groot 2 (BT.CPP v4)
Tree Structure Format	FlatBuffers	XML
Status Updates	PUB/SUB (pushed)	REQ/REP (polled)
Status Port	1666 (PUB)	5555 (REP)
Tree Port	1667 (REP)	5555 (REP)
Message Rate	Up to 25 Hz	On-demand

📁 Project Structure

groot1_publisher/
├── include/
│   └── groot1_publisher/
│       ├── groot1_publisher.h      # Main header
│       └── flatbuffers/            # Bundled FlatBuffers (Apache 2.0)
│           ├── base.h
│           ├── flatbuffers.h
│           ├── stl_emulation.h
│           ├── BT_logger_generated.h
│           └── bt_flatbuffer_helper.h
├── src/
│   ├── groot1_publisher.cpp        # Implementation
│   └── groot1_example.cpp          # Example usage
├── cmake/
│   └── groot1_publisherConfig.cmake.in
├── CMakeLists.txt
├── package.xml                     # ROS2 package manifest
└── README.md

🔧 API Reference

Constructor

Groot1Publisher(
    const BT::Tree& tree,              // The v4 behavior tree
    unsigned max_msg_per_second = 25,  // Rate limit
    unsigned publisher_port = 1666,    // ZMQ PUB port
    unsigned server_port = 1667        // ZMQ REP port
);

Notes

• Only one instance of Groot1Publisher can exist at a time
• Publisher and server ports must be different
• Status updates are rate-limited to prevent flooding

📋 Dependencies

Dependency	Required	Installation
BehaviorTree.CPP v4	✅	apt install ros-${ROS_DISTRO}-behaviortree-cpp
ZeroMQ (libzmq)	✅	apt install libzmq3-dev
tinyxml2	⚠️ Example only	apt install libtinyxml2-dev

🔨 Build Options

Option	Default	Description
BUILD_GROOT1_EXAMPLES	OFF	Build the example executable

cmake .. -DBUILD_GROOT1_EXAMPLES=ON

🧪 Running the Example

# Build with examples
cmake .. -DBUILD_GROOT1_EXAMPLES=ON
make

# Run
./groot1_example

Expected output:

============================================
 BT.CPP v4 -> Groot 1 Bridge Example
============================================

[Groot1Publisher] Initializing for BT.CPP v4 -> Groot 1 bridge
[Groot1Publisher] Tree serialized: 1234 bytes
[Groot1Publisher] PUB socket bound to tcp://*:1666
[Groot1Publisher] REP socket bound to tcp://*:1667
[Groot1Publisher] Ready! Connect Groot 1 to ports 1666 (SUB) and 1667 (REQ)
...

📝 Technical Details

FlatBuffers

This package bundles the FlatBuffers headers from Google (Apache 2.0 License) to avoid depending on BehaviorTree.CPP source code. The bundled version is compatible with the Groot 1 protocol.

Groot 1 Status Message Format

+------------------+-------------------------+--------------------+------------------------+
| Header Size (4B) | Status Buffer (N bytes) | Transition Count   | Transitions (12B each) |
| uint32           | [uid(2B), status(1B)]*  | uint32             | SerializedTransition[] |
+------------------+-------------------------+--------------------+------------------------+

SerializedTransition (12 bytes)

Offset	Size	Type	Description
0	4	int32	Seconds
4	4	int32	Microseconds
8	2	uint16	Node UID
10	1	int8	Previous status
11	1	int8	New status

🤝 Contributing

Contributions are welcome! Please open an issue or pull request.

� Acknowledgements

• Davide Faconti - Creator of BehaviorTree.CPP and Groot
• Google FlatBuffers - Serialization library used for Groot 1 protocol
• ZeroMQ - Messaging library for publisher/subscriber communication

�📜 License

MIT License - same as BehaviorTree.CPP.

The bundled FlatBuffers headers are under Apache 2.0 License (Copyright Google Inc.).