# ir-lab/irl_control architecture

> Architecture diagram of the GitHub repository ir-lab/irl_control, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ir-lab/irl_control
- Repository: https://github.com/ir-lab/irl_control

## Overview

##### Project Type and Purpose
- This is a Python-based simulation and control *framework* for bimanual robot manipulation (dual-arm UR5) built on MuJoCo.
- It provides:
- Core APIs for robot abstraction, control algorithms (OSC, admittance), and simulation management.
- Pluggable input-device drivers (PS Move, Space Mouse) for teleoperation.
- YAML/XML-driven configuration for robot kinematics, PID gains, action sequences, and scene descriptions.
- Example scripts as user entry points, and a mesh/scene repository for 3D objects.

##### File Structure
Top-level:
- setup.py, requirements.in, README.md → packaging and dependencies
- mujoco_app.py, osc.py, robot.py, utils.py, osc.py, version.py → core library entry points
irl_control/ (core package):
- action_sequence_configs/*.yaml → high-level task definitions
- device.py → abstract Device class
- input_devices/ → concrete device drivers (ps_move.py, space_mouse.py)
- robot.py → Robot abstraction (kinematics, jacobians, state interfaces)
- mujoco_app.py → application loop: load scene, attach controllers, step sim, render
- osc.py → operational‐space control implementations
- utils.py → shared utilities (logging, data handling)
- meshes/, scenes/ → 3D asset repository and MuJoCo XML scene files
- robot_configs/*.yaml → per-robot and per-task PID/gain settings
- examples/ → demo scripts showing usage patterns
- tests/ → automated tests invoking run_tests.py

##### README for Insights
- Simulation backbone: MuJoCo (via mujoco-py)
- Extensible framework: add new input devices, new control algorithms, new mesh/scene assets
- Config-driven: YAML for gains, tasks; XML for scenes
- Demo-driven: examples illustrate how library pieces fit together

##### Be Detailed
- Versioning/test harness (version.py, tests/) in a peripheral “development & QA” section.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Devices" 
        direction TB
        PS["PS Move Controller"]:::ext
        SM["3D Space Mouse"]:::ext
        IDM["Input Device Manager\n(irl_control/device.py)"]:::core
    end

    %% Configuration Assets
    subgraph "Configuration Manager"
        direction TB
        ConfigY["YAML Configs"]:::config
        ConfigX["XML Scenes"]:::config
    end

    %% Action Sequence
    ASM["Action Sequence Manager\n(irl_control/action_sequence_configs)"]:::core

    %% Core Library Modules
    subgraph "Core Library"
        direction TB
        OSC["Controllers (OSC & Admittance)\n(irl_control/osc.py)"]:::core
        Robot["Robot Abstraction\n(irl_control/robot.py)"]:::core
        SceneMgr["Scene Manager\n(irl_control/scenes/*.xml)"]:::core
        Mesh["Mesh Repository\n(irl_control/meshes/)"]:::core
        Utils["Utilities & Logging\n(irl_control/utils.py)"]:::core
    end

    %% Simulation Engine
    MuJoCo["MuJoCo API\n(mujoco-py)"]:::ext

    %% Application Loop
    App["Application Loop\n(irl_control/mujoco_app.py)"]:::core

    %% Examples & Tests
    subgraph "Examples & Tests"
        direction TB
        Examples["Examples Layer\n(irl_control/examples/*.py)"]:::example
        Tests["Test Harness\n(irl_control/tests/run_tests.py)"]:::example
    end

    %% Relationships
    Examples -->|instantiate| App
    App -->|loads| SceneMgr
    App -->|loads| Robot
    App -->|attaches/polls| IDM
    PS -->|input| IDM
    SM -->|input| IDM
    App -->|uses| ConfigY
    App -->|uses| ConfigX
    App -->|selects| OSC
    ASM -->|invokes| OSC
    ConfigY -->|loads| ASM
    ConfigY -->|loads| Robot
    ConfigY -->|loads gains| OSC
    ConfigX -->|loads scenes| SceneMgr
    OSC -->|commands| MuJoCo
    MuJoCo -->|state| Robot
    Robot -->|state| OSC
    MuJoCo -->|assets| SceneMgr
    SceneMgr -->|meshes| Mesh
    Utils -->|supports| App
    Utils -->|supports| OSC
    Examples -->|demo| ASM
    Tests -->|validate| Examples

    %% Click Events
    click PS "https://github.com/ir-lab/irl_control/blob/master/irl_control/input_devices/ps_move.py"
    click SM "https://github.com/ir-lab/irl_control/blob/master/irl_control/input_devices/space_mouse.py"
    click IDM "https://github.com/ir-lab/irl_control/blob/master/irl_control/device.py"
    click ASM "https://github.com/ir-lab/irl_control/blob/master/irl_control/action_sequence_configs/insertion_task.yaml"
    click ASM "https://github.com/ir-lab/irl_control/blob/master/irl_control/action_sequence_configs/iros2022_task.yaml"
    click OSC "https://github.com/ir-lab/irl_control/blob/master/irl_control/osc.py"
    click Robot "https://github.com/ir-lab/irl_control/blob/master/irl_control/robot.py"
    click App "https://github.com/ir-lab/irl_control/blob/master/irl_control/mujoco_app.py"
    click SceneMgr "https://github.com/ir-lab/irl_control/blob/master/irl_control/scenes/dual_ur5.xml"
    click SceneMgr "https://github.com/ir-lab/irl_control/blob/master/irl_control/scenes/insertion_task_scene.xml"
    click Mesh "https://github.com/ir-lab/irl_control/tree/master/irl_control/meshes/"
    click ConfigY "https://github.com/ir-lab/irl_control/blob/master/irl_control/robot_configs/default_xyz.yaml"
    click ConfigY "https://github.com/ir-lab/irl_control/blob/master/irl_control/robot_configs/iros2022.yaml"
    click ConfigY "https://github.com/ir-lab/irl_control/blob/master/irl_control/robot_configs/default_xyz_abg.yaml"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/ps_move_example.py"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/space_mouse_example.py"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/admit_test.py"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/force_test.py"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/gain_test.py"
    click Examples "https://github.com/ir-lab/irl_control/blob/master/irl_control/examples/insertion_task.py"
    click Utils "https://github.com/ir-lab/irl_control/blob/master/irl_control/utils.py"
    click Tests "https://github.com/ir-lab/irl_control/blob/master/irl_control/tests/run_tests.py"

    %% Styles
    classDef core stroke:#0000FF,fill:#E0F7FF;
    classDef ext stroke:#008000,fill:#E0FFE0;
    classDef config stroke:#FFA500,fill:#FFF5E5;
    classDef example stroke:#888888,fill:#F0F0F0;
```
