pib.OS - The Reactive Behavior Tree Middleware

pib.OS is an open-source, Rust-based operating system and middleware tailored for the pib (printable intelligent bot) robotics platform.

It aims to democratize robotics by providing a highly reactive, node-based Behavior Tree (BT) architecture. Designed with a Visual-First mindset, pib.OS serves as the memory-safe backend for drag-and-drop robot programming, empowering non-programmers to create complex robotic behaviors through an intuitive visual interface without writing code.

---

🌟 Core Features

1. Advanced Behavior Tree Engine

• Asynchronous Execution: Every action node is a native Rust Future. pib.OS evaluates the behavior tree asynchronously, allowing true parallel execution of I/O bounds without blocking the tree.
• Comprehensive Control Nodes: Full support for Sequence (fails on first failure), Selector (succeeds on first success), and Parallel (concurrent execution with threshold parameters).
• Decorators & Conditions: Includes standard decorators (Inverter, Timeout) and instant condition nodes for synchronous routing decisions.
• Dynamic Subtrees: Support for modular design by evaluating entire sub-trees dynamically via the SubtreeNode.

2. State & Memory Management

• Zero-Copy Blackboard: A lock-free, concurrent data bus utilizing interior mutability to distribute sensor data efficiently across hundreds of nodes.
• Scoped Blackboards & Port Mapping: Supports local variable scopes for isolated sub-trees, seamlessly mapping explicit keys up to the parent blackboard.

3. Integrated Network & API

• Live Telemetry via WebSockets: An Axum-based server (/ws/telemetry) streams real-time NodeStateEvents and structured logs to the UI.
• Dynamic Node Registry API: A REST endpoint (GET /api/registry) that enumerates all available nodes, their descriptions, and required data ports for dynamic frontend toolbox rendering.
• JSON Tree Parser: Dynamically deserializes complex Behavior Trees configurations (serde_json) directly from the visual editor.
• Zenoh Network Bridging: Built-in integration with Eclipse Zenoh to route real hardware telemetry and commands between the BT Blackboard and external robotic components.

4. Visual Control & Debugging (pib.Cerebra MVP)

• Drag and Drop UI: Visually construct trees using the built-in frontend (Cerebra).
• Visual Debugger: Control execution flow live. Features include a Tick Rate Slider (Slow-Mo), Pause/Resume, and Step-by-Step execution, allowing you to trace logic transitions without pouring over log files.
• Live Log Console: Structured backend tracing events are broadcast to the frontend, complete with Node-ID and level filtering.
• Node & Subtree Management: Easily remove specific nodes or entire sub-trees via dedicated visual controls.

---

🚀 Installation & Setup

Prerequisites

• Rust Toolchain (edition 2021 or newer)
• cargo package manager
• Node.js and npm (for the frontend UI)

1. Clone the Repository

git clone https://github.com/pib-rocks/pib.OS.git
cd pib.OS

2. Build the Rust Backend

Build the middleware and its dependencies in release mode for optimal performance:

cargo build --release

3. Setup the Frontend (pib.Cerebra)

Navigate to the UI directory and install the necessary dependencies:

cd ui
npm install

---

💻 Usage

Running the Backend Server

Start the core execution engine, API, and Telemetry WebSocket server. We recommend adjusting the log level to prevent trace-flooding from the Zenoh network layer:

cd pib.OS
RUST_LOG=info cargo run --bin pib_os

The API server will listen on 0.0.0.0:3000 and the WebSocket telemetry on ws://0.0.0.0:3000/ws/telemetry.

Running the Visual Editor (Frontend)

In a separate terminal window, start the frontend development server:

cd ui
npm run dev

Open your browser and navigate to the provided local address (e.g., http://localhost:4200 or http://localhost:5173). From here, you can drag and drop nodes, wire up port mappings, and execute/monitor the tree live.

---

🧪 Testing

We strictly adhere to Test-Driven Development (TDD) (RED-GREEN-REFACTOR).

Backend (Rust) Tests

To run the full suite of unit and integration tests (covering nodes, blackboard, parsers, and APIs):

cargo test

To run performance benchmarks to ensure no regressions in tree tick latency or blackboard read/writes:

cargo bench

Frontend (UI) Tests

The frontend uses Playwright for End-to-End and component interaction testing (including visual deletion, root node protection, and state management validation).

cd ui
npx playwright test --project=chromium