beavr-sim

Simulation engine for BEAVR

Simulation Architecture Redesign: beavr-sim and beavr-teleop

This plan describes the architectural split of the Beavr system into two specialized repositories:

1. beavr-sim (New): A dedicated Simulation Server using mjlab and MuJoCo, responsible for physics, task logic, and 24/7 environment hosting.
2. beavr-teleop (Existing): A lightweight Teleoperation Client that connects to the simulation server (or real robots) via ZMQ.

User Review Required

Important

New Repository Required: You will need to create a new git repository named beavr-sim (or mjlabs-sim per your preference). Dependency Change: beavr-teleop will no longer require mujoco installation locally for simulation operations, only pyzmq.

1. New Repository: beavr-sim (The Simulation Engine)

This repository serves as the "Game Console" running the physics engine.

Tech Stack

• Engine: mjlab (https://github.com/mujocolab/mjlab) & mujoco
• Communication: pyzmq (ZeroMQ) for low-latency state/action streaming.
• Structure: Monolithic server that loads "Task" plugins.

Directory Structure

beavr-sim/
├── assets/                  # Central storage for MJCF (XML) files and meshes
│   ├── mujoco_menagerie/    # Robot descriptions (xarm7, leap_hand, etc.)
│   └── scenes/              # Scene descriptions (tables, rooms, props)
├── src/
│   ├── envs/                # mjlab Environment definitions
│   │   ├── base_task.py     # Base class for teleop tasks
│   │   └── aloha_task.py    # Example logic (Gym-Aloha parity)
│   ├── server/
│   │   ├── zmq_server.py    # The Network Interface (REP/PUB)
│   │   └── loop.py          # The Main Physics Loop (24/7 runner)
│   └── main.py              # Entry point
└── requirements.txt         # mjlab, mujoco, pyzmq

The mjlab Integration

We will use mjlab to define Tasks (Scenarios).

• Role of mjlab: It abstraction layer for loading XMLs, handling "resets", and calculating "rewards/success".
• Role of ZMQ Server: It wraps the mjlab environment. It grabs the latest action from the network, feeds it to env.step(), and broadcasts env.obs.

2. Existing Repository: beavr-teleop (The Client)

This repository remains your main controller but becomes "stateless" regarding physics.

3. Workflow Description (for the future)

1. Start Simulation (Terminal 1)

   # In beavr-sim/
   python src/main.py --task=AlohaInsertion
   # > [Server] Listening on 0.0.0.0:5555...
   # > [Physics] Running at 500Hz (Waiting for client...)

2. Start Teleop (Terminal 2)

   # In beavr-teleop/
   python -m beavr.teleop.main --robot_name=generic_arm --sim=True
   # > [Client] Connected to Sim Server at localhost:5555
   # > [Client] Teleoperating...

This work was sponsored by the Department of the Air Force Artificial Intelligence Accelerator and was accomplished under Cooperative Agreement Number FA8750-19-2-1000. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the Department of the Air Force or the U.S. Government. The U.S. Government is authorized to reproduce and distribute reprints for Government purposes notwithstanding any copyright notation herein.