# xuan-waves/ur3e_rl architecture

> Architecture diagram of the GitHub repository xuan-waves/ur3e_rl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xuan-waves/ur3e_rl
- Repository: https://github.com/xuan-waves/ur3e_rl

## Overview

This is an experimental UR3e insertion stack spanning VR teleoperation, impedance-controlled execution, demonstration collection, SmolVLA behavior cloning, and gated RLT refinement. The documented workflow moves from demonstrations to policy training and rollout, then through gate/token/intervention training to closed-loop trials. Runtime internals are represented by the ROS nodes, robot API, kinematics, safety, and impedance controller. Several learning subsystems are documented but unsampled; their documented capabilities are shown without inferring internal calls.

Main entry points: [`real_teleop/nodes.py`](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/nodes.py) (ROS control nodes), [`scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_rtc.py`](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_rtc.py) (No-rotvec VLA rollout), [`scripts/collect_data/collect_ur3e_vr_impedance.py`](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/collect_data/collect_ur3e_vr_impedance.py) (Impedance data collection), [`mujoco_env/hardware/ur3e_api.py`](https://github.com/xuan-waves/ur3e_rl/blob/master/mujoco_env/hardware/ur3e_api.py) (Robot API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_robot["Robot runtime"]
  node_hardware_entry["Hardware entrypoint"]
  node_ros_nodes["ROS control nodes<br/>[nodes.py]"]
  node_robot_api["Robot API<br/>[ur3e_api.py]"]
end

subgraph group_data["Demonstrations and VLA"]
  node_collector["Impedance data collection"]
  node_dataset[("LeRobot demonstrations<br/>[lerobot_writer.py]")]
  node_bc_train["SmolVLA training"]
  node_vla_rollout["No-rotvec VLA rollout"]
end

subgraph group_refine["RLT refinement"]
  node_gate["RL gate<br/>[train_rlt_gate.py]"]
  node_gate_eval["Gate evaluation and monitor"]
  node_token["Stage1 token learning"]
  node_interventions["HIL interventions"]
  node_stage2["Stage2 actor critic"]
  node_ready["Ready-gate trial loop"]
  node_ready_train["Ready-gate training and evaluation"]
end

subgraph group_shared["Teleoperation core"]
  node_ik["Kinematics and IK<br/>[kinematics.py]"]
  node_safety["Safety limiter<br/>[safety.py]"]
  node_impedance["Impedance control<br/>[controller.py]"]
  node_messages["Robot and VR messages<br/>[messages.py]"]
end

node_operator(("VR operator"))
node_xrobot["XRoboToolkit"]
node_cameras["RealSense cameras"]
node_ur3e["UR3e and gripper"]

node_operator -->|"provides VR input"| node_xrobot
node_xrobot -->|"supplies teleoperation"| node_ros_nodes
node_hardware_entry -->|"starts nodes"| node_ros_nodes
node_ros_nodes -->|"controls robot"| node_robot_api
node_ros_nodes -->|"uses IK"| node_ik
node_ros_nodes -->|"applies limits"| node_safety
node_ros_nodes -->|"runs impedance"| node_impedance
node_ros_nodes -->|"parses commands"| node_messages
node_impedance -->|"commands motion"| node_robot_api
node_robot_api -.->|"drives arm"| node_ur3e
node_cameras -->|"provides images"| node_collector
node_operator -->|"records demonstrations"| node_collector
node_ros_nodes -.->|"publishes robot state"| node_collector
node_collector -->|"writes episodes"| node_dataset
node_dataset -->|"trains on"| node_bc_train
node_bc_train -->|"produces policy"| node_vla_rollout
node_vla_rollout -.->|"publishes targets"| node_ros_nodes
node_vla_rollout -->|"validates rollout"| node_gate
node_gate -->|"evaluates gate"| node_gate_eval
node_vla_rollout -->|"provides frozen VLA"| node_token
node_gate_eval -->|"marks refinement phase"| node_interventions
node_token -->|"guides token features"| node_interventions
node_interventions -->|"trains from buffers"| node_stage2
node_stage2 -->|"refines policy actions"| node_ready
node_ready_train -->|"supplies readiness gate"| node_ready
node_ready -.->|"executes trials"| node_ros_nodes

click node_hardware_entry "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/hardware/ur3e_vr_servoj_ros2.py"
click node_ros_nodes "https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/nodes.py"
click node_robot_api "https://github.com/xuan-waves/ur3e_rl/blob/master/mujoco_env/hardware/ur3e_api.py"
click node_ik "https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/kinematics.py"
click node_safety "https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/safety.py"
click node_impedance "https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/impedance/controller.py"
click node_messages "https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/messages.py"
click node_collector "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/collect_data/collect_ur3e_vr_impedance.py"
click node_dataset "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/collect_data/lerobot_writer.py"
click node_bc_train "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/train_smolvla_no_rotvec/train_ur3e_smolvla_no_rotvec.py"
click node_vla_rollout "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_rtc.py"
click node_gate "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_gate/train_rlt_gate.py"
click node_gate_eval "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_gate/live_rlt_gate_monitor.py"
click node_token "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_token/train_rlt_stage1.py"
click node_interventions "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_train/collect_rlt_interventions.py"
click node_stage2 "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_train/train_hil_serl_stage2.py"
click node_ready "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_ready_loop.py"
click node_ready_train "https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/ready_gate/train_ready_gate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hardware_entry,node_ros_nodes,node_robot_api toneBlue
class node_collector,node_dataset,node_bc_train,node_vla_rollout toneAmber
class node_gate,node_gate_eval,node_token,node_interventions,node_stage2,node_ready,node_ready_train toneMint
class node_ik,node_safety,node_impedance,node_messages toneRose
class node_operator,node_xrobot,node_cameras,node_ur3e toneIndigo
```

## Components

### Robot runtime

- [Hardware entrypoint](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/hardware/ur3e_vr_servoj_ros2.py): `scripts/hardware/ur3e_vr_servoj_ros2.py`
- [ROS control nodes](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/nodes.py): `real_teleop/nodes.py`
- [Robot API](https://github.com/xuan-waves/ur3e_rl/blob/master/mujoco_env/hardware/ur3e_api.py): `mujoco_env/hardware/ur3e_api.py`

### Demonstrations and VLA

- [Impedance data collection](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/collect_data/collect_ur3e_vr_impedance.py): `scripts/collect_data/collect_ur3e_vr_impedance.py`
- [LeRobot demonstrations](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/collect_data/lerobot_writer.py): `scripts/collect_data/lerobot_writer.py`
- [SmolVLA training](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/train_smolvla_no_rotvec/train_ur3e_smolvla_no_rotvec.py): `scripts/train_smolvla_no_rotvec/train_ur3e_smolvla_no_rotvec.py`
- [No-rotvec VLA rollout](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_rtc.py): `scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_rtc.py`

### RLT refinement

- [RL gate](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_gate/train_rlt_gate.py): `scripts/rlt_gate/train_rlt_gate.py`
- [Gate evaluation and monitor](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_gate/live_rlt_gate_monitor.py): `scripts/rlt_gate/live_rlt_gate_monitor.py`
- [Stage1 token learning](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_token/train_rlt_stage1.py): `scripts/rlt_token/train_rlt_stage1.py`
- [HIL interventions](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_train/collect_rlt_interventions.py): `scripts/rlt_train/collect_rlt_interventions.py`
- [Stage2 actor critic](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rlt_train/train_hil_serl_stage2.py): `scripts/rlt_train/train_hil_serl_stage2.py`
- [Ready-gate trial loop](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_ready_loop.py): `scripts/rollout_smolvla_no_rotvec/rollout_ur3e_smolvla_no_rotvec_ready_loop.py`
- [Ready-gate training and evaluation](https://github.com/xuan-waves/ur3e_rl/blob/master/scripts/ready_gate/train_ready_gate.py): `scripts/ready_gate/train_ready_gate.py`

### Teleoperation core

- [Kinematics and IK](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/kinematics.py): `real_teleop/kinematics.py`
- [Safety limiter](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/safety.py): `real_teleop/safety.py`
- [Impedance control](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/impedance/controller.py): `real_teleop/impedance/controller.py`
- [Robot and VR messages](https://github.com/xuan-waves/ur3e_rl/blob/master/real_teleop/messages.py): `real_teleop/messages.py`

### Other components

- **VR operator**
- **XRoboToolkit**
- **RealSense cameras**
- **UR3e and gripper**

## Connections

- VR operator → XRoboToolkit: provides VR input
- XRoboToolkit → ROS control nodes: supplies teleoperation
- Hardware entrypoint → ROS control nodes: starts nodes (evidence: `scripts/hardware/ur3e_vr_servoj_ros2.py`)
- ROS control nodes → Robot API: controls robot (evidence: `real_teleop/nodes.py`)
- ROS control nodes → Kinematics and IK: uses IK (evidence: `real_teleop/nodes.py`)
- ROS control nodes → Safety limiter: applies limits (evidence: `real_teleop/nodes.py`)
- ROS control nodes → Impedance control: runs impedance (evidence: `real_teleop/nodes.py`)
- ROS control nodes → Robot and VR messages: parses commands (evidence: `real_teleop/nodes.py`)
- Impedance control → Robot API: commands motion (evidence: `real_teleop/impedance/controller.py`)
- Robot API → UR3e and gripper: drives arm
- RealSense cameras → Impedance data collection: provides images
- VR operator → Impedance data collection: records demonstrations
- ROS control nodes → Impedance data collection: publishes robot state
- Impedance data collection → LeRobot demonstrations: writes episodes (evidence: `scripts/collect_data/collect_ur3e_vr_impedance.py`)
- LeRobot demonstrations → SmolVLA training: trains on
- SmolVLA training → No-rotvec VLA rollout: produces policy
- No-rotvec VLA rollout → ROS control nodes: publishes targets
- No-rotvec VLA rollout → RL gate: validates rollout
- RL gate → Gate evaluation and monitor: evaluates gate (evidence: `scripts/rlt_gate/live_rlt_gate_monitor.py`)
- No-rotvec VLA rollout → Stage1 token learning: provides frozen VLA
- Gate evaluation and monitor → HIL interventions: marks refinement phase (evidence: `scripts/rlt_train/collect_rlt_interventions.py`)
- Stage1 token learning → HIL interventions: guides token features (evidence: `scripts/rlt_train/collect_rlt_interventions.py`)
- HIL interventions → Stage2 actor critic: trains from buffers
- Stage2 actor critic → Ready-gate trial loop: refines policy actions
- Ready-gate training and evaluation → Ready-gate trial loop: supplies readiness gate
- Ready-gate trial loop → ROS control nodes: executes trials
