hivebr — OpenLab Simulator

A lightweight 2D simulation framework for single- and multi-robot mobile navigation, built on Pygame, with a dual-paradigm OpenLab API for centralized and decentralized control.

Robots in the simulator are called B-bots (for bee), keeping the hive metaphor.

📖 Full documentation: https://eliasjof.github.io/hivebr_simulator/

Installation

pip install hivebr

Optional extras:

pip install "hivebr[maps]"   # occupancy grids (Pillow + scipy)
pip install "hivebr[plot]"   # data logger plots (matplotlib)

Quick start

from hivebr import HiveBrAgent, SwarmExperiment

class Patrol(HiveBrAgent):
    def loop(self, state, neighbors):
        # state.goal holds the current waypoint (x, y, theta)
        return 0.5, 0.0

exp = SwarmExperiment(robots=3, backend="navsim2d")
exp.assign_agent(robot_ids=[0, 1, 2], agent_class=Patrol)
exp.assign_route(0, [[5, 2, 0.0], [5, 6, 0.0]])
exp.run()

A single robot is just a fleet with N = 1. Switching backend="ros2" reuses the same agent code on the physical arena.

Dual paradigm

Features

• Mono or fleet, one API. A single robot is a fleet with N = 1.
• Interactive GUI. Pan/zoom, load occupancy-grid maps, switch themes, toggle LiDAR, add waypoints and obstacles with the mouse.
• Two environment representations. Analytic circular obstacles and image-based occupancy grids with inflation.
• Precision sensing. Ray-casting LiDAR (DDA) against the grid plus analytic circle intersections.
• Deterministic fleets. Each timestep is computed from a frozen snapshot of the fleet state, independent of update order.
• Research-ready. Pluggable controllers, path planners (A*, RRT, RRT*, PRM, BIT*, OMPL, RRT-Dubins), and a data logger for offline analysis.

Robot models

Run the examples

# from a clone of the repository (examples are not shipped in the wheel)
python examples/controle_robodiferencial.py
python examples/decentralized_swarm.py
python examples/multi_robot_differential.py

Links

• Documentation: https://eliasjof.github.io/hivebr_simulator/
• Repository: https://github.com/eliasjof/hivebr_simulator
• Issue tracker: https://github.com/eliasjof/hivebr_simulator/issues

License

MIT — free for educational and research use. See LICENSE.