# nuomizai/simple_test architecture

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

- Interactive diagram: https://gitdiagram.com/nuomizai/simple_test
- Repository: https://github.com/nuomizai/simple_test

## Overview

##### What this project is (type + purpose)
**XROCS** is a **Python hardware interface / robotics control SDK** that provides a unified API to control a **robot arm (UR5)**, a **camera (Orbbec)**, and a **gripper (Robotiq)**. It is not a traditional “web system”; it’s a **robotics integration library** that likely runs on a control PC and talks to:
- the robot controller (UR),
- ROS2 nodes for camera acquisition (Orbbec),
- and the gripper driver (Robotiq),
while exposing a clean Python interface to higher-level applications (e.g., RL environments like `rl_envs` / `HIL-RL`).

##### Read the file tree as architecture clues
Top-level files indicate the main modules and integration points:

- `ur_station.py` / `ur.py`
UR robot arm abstraction + a “station” orchestration concept (robot + peripherals together).
- `robotiq_gripper.py`
Robotiq gripper interface (likely via UR tool IO or separate connection, depending on implementation).
- `orbbec_camera_ros2.py`, `ros2_node_manager.py`
Camera is integrated through **ROS2 nodes**; there’s a manager to start/stop/monitor ROS2 nodes.
- `camera_utils.py`
Utility layer for camera data transforms, conversions, calibration helpers, etc.
- `core/config_loader.py`, `configuration.toml`
- `core/station_loader.py`
Factory/loader: constructs the “station” from config (dependency injection style).
- `rg_driver_opt.py`
Looks like “Robotiq Gripper driver optimization” or alternative backend; treat as an optional driver path.
- `Rate.py`
Common robotics control primitive (rate/loop timing). This matters for depicting control loops.

This structure implies a **layered architecture**:
1) **Application layer** (examples in external repos + `ur_station_example.py` referenced in README)
##### Station orchestration layer (`ur_station.py`, station loader)
3) **Device abstraction / driver layer** (`ur.py`, `robotiq_gripper.py`, `orbbec_camera_ros2.py`)

##### What to put
- a **Container/Context** view (what processes exist and what they connect to), and
- a **Component** view (how the Python package is internally organized).

##### External actors / systems
- **User application** (e.g., `rl_envs/base_env.py`, `HIL-RL`, scripts like `ur_station_example.py`)
- **UR Controller** (physical UR5 controller; network endpoint)
- **Robotiq Gripper hardware** (attached to UR tool or separate controller)
- **Orbbec Camera hardware**
- **ROS2 runtime** (daemon + nodes; camera drivers typically run as ROS2 nodes)

##### XROCS runtime (your Python process)
Inside the “XROCS Python Process” boundary, include:
- **Config subsystem**
- `configuration.toml`
- `core/config_loader.py`
- **Station factory / loader**
- `core/station_loader.py`
- **Station abstraction**
- `ur_station.py` (represents “the whole lab station”: robot + camera + gripper)
- **Robot interface**
- `ur.py`
- **Gripper interface**
- `robotiq_gripper.py`
- optionally `rg_driver_opt.py` (as an alternate/optional implementation)
- **Camera interface**
- `orbbec_camera_ros2.py`
- `camera_utils.py`
- **ROS2 node orchestration**
- `ros2_node_manager.py`
- **Timing**
- `Rate.py` (control loop timing; show as used by station/robot loops)

##### URStation → delegates
- motion commands to **UR driver** (`ur.py`)
- gripper commands to **Robotiq driver** (`robotiq_gripper.py`)
- camera start/stop/stream calls to **Orbbec ROS2 adapter** (`orbbec_camera_ros2.py`)
3. **Orbbec ROS2 adapter** → uses **ROS2NodeManager** (`ros2_node_manager.py`) to launch/monitor ROS2 camera nodes
5. **Gripper driver** → communicates to the gripper (either “via UR tool interface” or “direct”; if uncertain, show as “Gripper link (UR tool / fieldbus / network)”)

##### Configuration path
- `configuration.toml` → `core/config_loader.py` → `core/station_loader.py` → constructs `URStation`, `UR`, `OrbbecCameraROS2`, `RobotiqGripper` with correct endpoints/topics/params.

##### Architectural patterns to call out (explicitly annotate

- **Facade / Unified Interface**: `ur_station.py` is the single entry point that unifies robot + camera + gripper.
- **Adapter pattern**: `orbbec_camera_ros2.py` adapts ROS2 camera nodes/topics into a Python-friendly camera API.
- **Factory/Dependency Injection**: `core/station_loader.py` builds the station from config (swap hardware without changing higher-level code).
- **Layering**: app → station → drivers → external runtimes/hardware.

**Runtime/Deployment View**
- [User App / RL Env / Example Script]
→ (calls) [XROCS: URStation]
→ [UR Driver (ur.py)] → (TCP/IP) → [UR Controller] → [UR5 Arm]
→ [Robotiq Driver (robotiq_gripper.py)] → (tool IO / link) → [Robotiq Gripper]
→ [Orbbec Adapter (orbbec_camera_ros2.py)]
→ [ROS2NodeManager (ros2_node_manager.py)] → (spawn/manage) → [ROS2 Orbbec Camera Node(s)]
← (ROS2 topics) ← [ROS2 Orbbec Camera Node(s)] ← (USB) ← [Orbbec Camera HW]
→ [camera_utils.py] → (frames) → back to [User App]
- [configuration.toml] → [config_loader] → [station_loader] → builds [URStation]
- [Rate.py] used by [URStation] and/or [User App] for loop timing

That is already “detailed and essential” for this project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Diagram 1: Runtime / Deployment (Process + Hardware View)
    %% =========================================================

    subgraph "Runtime / Deployment View"
        direction TB

        subgraph "User Space"
            direction TB
            UserApp["User App / RL Env / Example Script"]:::external
        end

        subgraph "Control PC: Python Process"
            direction TB

            subgraph "XROCS (in-process Python SDK)"
                direction TB

                XInit["__init__.py (Package Entry)"]:::module

                subgraph "Config & Dependency Injection"
                    direction TB
                    ConfigFile[("configuration.toml")]:::config
                    ConfigLoader["core/config_loader.py (Config Loader)"]:::module
                    StationLoader["core/station_loader.py (Station Loader / Factory)"]:::module
                end

                subgraph "Unified Facade (Station)"
                    direction TB
                    URStation["ur_station.py (URStation Facade / Station API)"]:::facade
                    Rate["Rate.py (Rate / Loop Timing)"]:::module
                end

                subgraph "Device Abstractions / Drivers"
                    direction TB
                    URDriver["ur.py (UR Driver / Robot API)"]:::module
                    GripperDriver["robotiq_gripper.py (Robotiq Gripper API)"]:::module
                    GripperOpt["rg_driver_opt.py (Optional Gripper Backend)"]:::optional
                    OrbbecAdapter["orbbec_camera_ros2.py (OrbbecCameraROS2 Adapter / Camera API)"]:::module
                    ROS2Mgr["ros2_node_manager.py (ROS2NodeManager)"]:::module
                    CamUtils["camera_utils.py (Camera Utils)"]:::module
                end
            end
        end

        subgraph "External Runtimes"
            direction TB
            URController["UR Controller (UR5 Control Box)"]:::runtime
            ROS2Runtime["ROS2 Runtime (daemon + DDS)"]:::runtime
            ROS2OrbbecNodes["ROS2 Orbbec Camera Node(s)"]:::runtime
        end

        subgraph "Physical Hardware"
            direction TB
            UR5HW["UR5 Robot Arm (Hardware)"]:::hardware
            GripperHW["Robotiq Gripper (Hardware)"]:::hardware
            OrbbecHW["Orbbec Camera (Hardware)"]:::hardware
        end

        %% ---- Runtime interactions (vertical emphasis) ----
        UserApp -->|"calls Station API"| URStation
        UserApp -->|"uses loop timing (N Hz)"| Rate

        ConfigFile -->|"config params"| ConfigLoader -->|"validated config"| StationLoader -->|"constructs & wires"| URStation
        StationLoader -->|"creates"| URDriver
        StationLoader -->|"creates"| GripperDriver
        StationLoader -->|"creates"| OrbbecAdapter

        URStation -->|"motion commands"| URDriver
        URDriver -->|"UR protocol / TCP/IP"| URController -->|"controls"| UR5HW

        URStation -->|"gripper commands"| GripperDriver
        GripperDriver -.->|"optional alt backend"| GripperOpt
        GripperDriver -->|"tool IO / fieldbus / network (driver-dependent)"| GripperHW

        URStation -->|"camera start/stop/stream"| OrbbecAdapter
        OrbbecAdapter -->|"launch/monitor nodes"| ROS2Mgr -->|"spawn/manage"| ROS2OrbbecNodes
        ROS2Runtime ---|"DDS discovery/transport"| ROS2OrbbecNodes
        OrbbecHW -->|"USB"| ROS2OrbbecNodes
        ROS2OrbbecNodes -->|"ROS2 topics/services (frames)"| OrbbecAdapter -->|"frame transforms/convert"| CamUtils -->|"observations/frames"| URStation -->|"returns observations"| UserApp

        %% ---- Pattern annotations ----
        NoteFacade["Pattern: Facade / Unified Interface"]:::note
        NoteAdapter["Pattern: Adapter (ROS2 → Python Camera API)"]:::note
        NoteFactory["Pattern: Factory / Dependency Injection (from config)"]:::note

        NoteFacade --> URStation
        NoteAdapter --> OrbbecAdapter
        NoteFactory --> StationLoader
    end

    %% =========================================================
    %% Diagram 2: Code / Component (Module Dependencies View)
    %% =========================================================

    subgraph "Code / Component View (Module Dependencies)"
        direction TB

        subgraph "xrocs package"
            direction TB
            CInit["__init__.py"]:::module

            subgraph "core/"
                direction TB
                CCore["core/ (namespace)"]:::module
                CConfig["core/config_loader.py"]:::module
                CStation["core/station_loader.py"]:::module
            end

            subgraph "station"
                direction TB
                CURStation["ur_station.py"]:::facade
                CRate["Rate.py"]:::module
            end

            subgraph "devices"
                direction TB
                CUR["ur.py"]:::module
                CGrip["robotiq_gripper.py"]:::module
                CGripOpt["rg_driver_opt.py"]:::optional
                COrbbec["orbbec_camera_ros2.py"]:::module
                CROS2Mgr["ros2_node_manager.py"]:::module
                CCamUtils["camera_utils.py"]:::module
            end

            CConfig -->|"loads"| CStation
            CStation -->|"builds"| CURStation

            CURStation -->|"delegates"| CUR
            CURStation -->|"delegates"| CGrip
            CGrip -.->|"optional"| CGripOpt
            CURStation -->|"delegates"| COrbbec

            COrbbec -->|"uses"| CROS2Mgr
            COrbbec -->|"uses"| CCamUtils

            CURStation -->|"uses (loop timing)"| CRate
        end

        CfgFile2[("configuration.toml")]:::config
        CfgFile2 -->|"config params"| CConfig
    end

    %% =========================
    %% Click events (mappings)
    %% =========================
    click ConfigFile "https://github.com/nuomizai/simple_test/blob/main/configuration.toml"
    click CfgFile2 "https://github.com/nuomizai/simple_test/blob/main/configuration.toml"

    click ConfigLoader "https://github.com/nuomizai/simple_test/blob/main/core/config_loader.py"
    click CConfig "https://github.com/nuomizai/simple_test/blob/main/core/config_loader.py"

    click StationLoader "https://github.com/nuomizai/simple_test/blob/main/core/station_loader.py"
    click CStation "https://github.com/nuomizai/simple_test/blob/main/core/station_loader.py"

    click URStation "https://github.com/nuomizai/simple_test/blob/main/ur_station.py"
    click CURStation "https://github.com/nuomizai/simple_test/blob/main/ur_station.py"

    click URDriver "https://github.com/nuomizai/simple_test/blob/main/ur.py"
    click CUR "https://github.com/nuomizai/simple_test/blob/main/ur.py"

    click GripperDriver "https://github.com/nuomizai/simple_test/blob/main/robotiq_gripper.py"
    click CGrip "https://github.com/nuomizai/simple_test/blob/main/robotiq_gripper.py"

    click GripperOpt "https://github.com/nuomizai/simple_test/blob/main/rg_driver_opt.py"
    click CGripOpt "https://github.com/nuomizai/simple_test/blob/main/rg_driver_opt.py"

    click OrbbecAdapter "https://github.com/nuomizai/simple_test/blob/main/orbbec_camera_ros2.py"
    click COrbbec "https://github.com/nuomizai/simple_test/blob/main/orbbec_camera_ros2.py"

    click ROS2Mgr "https://github.com/nuomizai/simple_test/blob/main/ros2_node_manager.py"
    click CROS2Mgr "https://github.com/nuomizai/simple_test/blob/main/ros2_node_manager.py"

    click CamUtils "https://github.com/nuomizai/simple_test/blob/main/camera_utils.py"
    click CCamUtils "https://github.com/nuomizai/simple_test/blob/main/camera_utils.py"

    click Rate "https://github.com/nuomizai/simple_test/blob/main/Rate.py"
    click CRate "https://github.com/nuomizai/simple_test/blob/main/Rate.py"

    click XInit "https://github.com/nuomizai/simple_test/blob/main/__init__.py"
    click CInit "https://github.com/nuomizai/simple_test/blob/main/__init__.py"

    click CCore "https://github.com/nuomizai/simple_test/tree/main/core/"

    %% =========================
    %% Styles
    %% =========================
    classDef module fill:#1E88E5,stroke:#0D47A1,stroke-width:1.5px,color:#ffffff
    classDef facade fill:#1565C0,stroke:#0D47A1,stroke-width:2px,color:#ffffff
    classDef external fill:#6A1B9A,stroke:#4A148C,stroke-width:1.5px,color:#ffffff
    classDef runtime fill:#2E7D32,stroke:#1B5E20,stroke-width:1.5px,color:#ffffff
    classDef hardware fill:#616161,stroke:#212121,stroke-width:1.5px,color:#ffffff
    classDef config fill:#FB8C00,stroke:#E65100,stroke-width:1.5px,color:#1b1b1b
    classDef optional fill:#00838F,stroke:#004D40,stroke-width:1.5px,color:#ffffff,stroke-dasharray: 4 3
    classDef note fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#3a2a00
```
