# rhcoding118/trash-sorting-robot architecture

> Architecture diagram of the GitHub repository rhcoding118/trash-sorting-robot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rhcoding118/trash-sorting-robot
- Repository: https://github.com/rhcoding118/trash-sorting-robot

## Overview

This repository is a robotics/sorting prototype stack that spans CAD, embedded control, perception, and reinforcement-learning training. It is organized around a physical cardboard prototype first, with software used to train and integrate the perception and control layers around that hardware.

1. **System purpose and boundary**
   - The project is not just a model repo; it is an end-to-end waste-sorting robot stack.
   - The core loop is: **camera input / state observation → perception/classification → action selection → actuator control → reward feedback**.

2. **Physical prototype and mechanical design**
   - The `cad/` directory holds the mechanical side of the project.
   - `cad/renders/` and `cad/stl/` indicate exported visualizations and printable/manufacturable parts.
   - The README makes clear this is currently centered on a **cardboard prototype**, which is the physical environment the rest of the system is being built around.

3. **Embedded control layer**
   - `firmware/arm-controller/arm-controller.ino` is the Arduino-style firmware for the arm controller.
   - This is the lowest-level runtime boundary: it receives commands and drives actuators for arm motion, grabbing, and sorting motion.
   - In the architecture diagram, this sits directly above motors/actuators and below any Python-side decision logic.

4. **Python-to-hardware integration**
   - `integrations/serial_bridge.py` is the communication bridge between the Python stack and the embedded controller.
   - Its role is to translate higher-level commands from perception or RL-driven logic into serial messages that the microcontroller can execute.
   - This is the key integration boundary between compute-heavy Python components and real hardware.

5. **Perception subsystem**
   - `perception/vision_pipeline.py` and `perception/utils.py` implement the image-processing/classification path.
   - The models in `perception/models/` show this is a **PyTorch-based CNN classifier** setup, with label metadata in `labels.txt`.
   - The perception output is likely the waste category or class prediction that feeds the downstream decision-making layer.

6. **Model artifacts**
   - `perception/models/wast_classifier_v1.pth` and `perception/models/waste_classifier_final.pth` are trained model checkpoints.
   - These are deployment artifacts, not training code, so they represent the inference-side boundary between training and runtime.
   - The presence of multiple checkpoints suggests iterative model development and evaluation.

7. **Reinforcement learning training subsystem**
   - `training/train_agent.py` is the entry point for agent training.
   - `training/envs/sorting_env.py` defines the environment, which models the sorting task as an RL problem.
   - `training/rewards.py` contains reward shaping, which is important because the README explicitly emphasizes optimizing expected value and accuracy through rewards.

8. **RL problem framing**
   - The README’s “AREA” framing maps the training stack into the standard RL loop:
     - **Agent**: the policy being trained
     - **Rewards**: scoring/feedback logic
     - **Environment**: the sorting task simulation
     - **Actions**: arm, grab, and sort commands
   - In the architecture, the agent chooses actions that maximize long-term reward, rather than a single-step classifier output alone.

9. **Data flow from training to deployment**
   - Training likely uses the environment and reward definitions to learn action selection.
   - Perception models are trained separately and then used during runtime to classify input images.
   - After training, the resulting perception and control decisions can be routed through the serial bridge to the firmware.

10. **Operational split: offline vs runtime**
   - **Offline / development time:** CAD design, RL training, and model fitting.
   - **Runtime / system integration:** vision inference, action selection, serial communication, and actuator execution.
   - This split is important for the architecture diagram because the training loop and the robot control loop are distinct subsystems.

11. **Technologies that materially affect the architecture**
   - Python is the main glue language for perception, integration, and training.
   - PyTorch is implied by the `.pth` model artifacts.
   - Arduino firmware provides deterministic low-level actuator control.
   - Serial communication is the primary coupling mechanism between software and hardware.

12. **What to show in a diagram**
   - A good architecture diagram should show three major layers:
     - **Mechanical/physical layer:** CAD prototype, arm, grabber, sorting mechanisms
     - **Embedded layer:** Arduino firmware controlling actuators
     - **Python ML layer:** perception pipeline, RL training, and serial bridge
   - Also show the two feedback loops:
     - **Training loop:** environment → reward → agent update
     - **Runtime loop:** camera/image → classifier/agent → serial commands → firmware → physical action

Main entry points: [`perception/vision_pipeline.py`](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/vision_pipeline.py) (Vision pipeline), [`integrations/serial_bridge.py`](https://github.com/rhcoding118/trash-sorting-robot/blob/main/integrations/serial_bridge.py) (Serial bridge), [`training/train_agent.py`](https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/train_agent.py) (Train agent), [`firmware/arm-controller/arm-controller.ino`](https://github.com/rhcoding118/trash-sorting-robot/blob/main/firmware/arm-controller/arm-controller.ino) (Arm controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physical["Physical layer"]
  node_cad_prototype["Cardboard proto<br/>mechanical prototype"]
  node_cad_exports["CAD exports<br/>fabrication assets"]
end

subgraph group_embedded["Embedded layer"]
  node_arm_firmware["Arm controller<br/>arduino firmware<br/>[arm-controller.ino]"]
  node_robot_action(("Robot action<br/>command output"))
end

subgraph group_python["Python ML layer"]
  node_serial_bridge["Serial bridge<br/>python integration<br/>[serial_bridge.py]"]
  node_vision_pipeline["Vision pipeline<br/>perception code<br/>[vision_pipeline.py]"]
  node_vision_utils["Vision utils<br/>perception support<br/>[utils.py]"]
  node_model_ckpt1[("Classifier v1<br/>pth checkpoint")]
  node_model_ckpt2[("Classifier final<br/>pth checkpoint")]
  node_labels["Class labels<br/>metadata<br/>[labels.txt]"]
  node_camera_state(("Camera/state<br/>observation source"))
end

subgraph group_training["RL training"]
  node_train_agent["Train agent<br/>rl trainer<br/>[train_agent.py]"]
  node_sorting_env["Sorting env<br/>rl environment<br/>[sorting_env.py]"]
  node_rewards["Rewards<br/>reward shaping<br/>[rewards.py]"]
end

node_cad_prototype -->|"designs"| node_cad_exports
node_vision_utils -->|"supports"| node_vision_pipeline
node_vision_pipeline -->|"maps classes"| node_labels
node_vision_pipeline -->|"runs inference"| node_model_ckpt2
node_model_ckpt1 -.->|"iterates to"| node_model_ckpt2
node_camera_state -->|"observed by"| node_vision_pipeline
node_vision_pipeline -->|"sends decisions"| node_serial_bridge
node_train_agent -->|"trains in"| node_sorting_env
node_sorting_env -->|"scores with"| node_rewards
node_rewards -->|"updates policy"| node_train_agent
node_train_agent -->|"produces"| node_robot_action
node_serial_bridge -->|"encodes"| node_robot_action
node_robot_action -->|"executes on"| node_arm_firmware
node_arm_firmware -->|"moves"| node_cad_prototype
node_serial_bridge -->|"serial link"| node_arm_firmware
node_camera_state -.->|"simulates"| node_sorting_env

click node_cad_prototype "https://github.com/rhcoding118/trash-sorting-robot/tree/main/cad"
click node_cad_exports "https://github.com/rhcoding118/trash-sorting-robot/tree/main/cad/renders"
click node_arm_firmware "https://github.com/rhcoding118/trash-sorting-robot/blob/main/firmware/arm-controller/arm-controller.ino"
click node_serial_bridge "https://github.com/rhcoding118/trash-sorting-robot/blob/main/integrations/serial_bridge.py"
click node_vision_pipeline "https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/vision_pipeline.py"
click node_vision_utils "https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/utils.py"
click node_model_ckpt1 "https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/wast_classifier_v1.pth"
click node_model_ckpt2 "https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/waste_classifier_final.pth"
click node_labels "https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/labels.txt"
click node_train_agent "https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/train_agent.py"
click node_sorting_env "https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/envs/sorting_env.py"
click node_rewards "https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/rewards.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_cad_prototype,node_cad_exports toneBlue
class node_arm_firmware,node_robot_action toneAmber
class node_serial_bridge,node_vision_pipeline,node_vision_utils,node_model_ckpt1,node_model_ckpt2,node_labels,node_camera_state toneMint
class node_train_agent,node_sorting_env,node_rewards toneRose
```

## Components

### Physical layer

Mechanical prototype and fabricated parts

- [Cardboard proto](https://github.com/rhcoding118/trash-sorting-robot/tree/main/cad): mechanical prototype · Physical waste-sorting prototype the stack is built around · `cad`
- [CAD exports](https://github.com/rhcoding118/trash-sorting-robot/tree/main/cad/renders): fabrication assets · Rendered and printable mechanical outputs · `cad/renders`

### Embedded layer

Microcontroller firmware and actuator control

- [Arm controller](https://github.com/rhcoding118/trash-sorting-robot/blob/main/firmware/arm-controller/arm-controller.ino): arduino firmware · Low-level actuator control for the robot arm · `firmware/arm-controller/arm-controller.ino`
- **Robot action**: command output · Arm, grab, and sort commands sent to hardware

### Python ML layer

Perception, integration, and learning code

- [Serial bridge](https://github.com/rhcoding118/trash-sorting-robot/blob/main/integrations/serial_bridge.py): python integration · Translates Python commands into microcontroller serial messages · `integrations/serial_bridge.py`
- [Vision pipeline](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/vision_pipeline.py): perception code · Image processing and classification entry point · `perception/vision_pipeline.py`
- [Vision utils](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/utils.py): perception support · Helper logic used by the perception pipeline · `perception/utils.py`
- [Classifier v1](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/wast_classifier_v1.pth): pth checkpoint · Trained perception model artifact · `perception/models/wast_classifier_v1.pth`
- [Classifier final](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/waste_classifier_final.pth): pth checkpoint · Latest deployed perception model artifact · `perception/models/waste_classifier_final.pth`
- [Class labels](https://github.com/rhcoding118/trash-sorting-robot/blob/main/perception/models/labels.txt): metadata · Label mapping for waste classes · `perception/models/labels.txt`
- **Camera/state**: observation source · Runtime observations entering perception and decision logic

### RL training

Offline environment, rewards, and agent optimization

- [Train agent](https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/train_agent.py): rl trainer · Entry point for policy training · `training/train_agent.py`
- [Sorting env](https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/envs/sorting_env.py): rl environment · Task environment for learning sorting behavior · `training/envs/sorting_env.py`
- [Rewards](https://github.com/rhcoding118/trash-sorting-robot/blob/main/training/rewards.py): reward shaping · Scoring and feedback used during training · `training/rewards.py`

## Connections

- Cardboard proto → CAD exports: designs · Mechanical concepts are exported as fabrication assets
- Vision utils → Vision pipeline: supports · Shared helpers feed the perception pipeline
- Vision pipeline → Class labels: maps classes · Classifier outputs are resolved to waste labels
- Vision pipeline → Classifier final: runs inference · Runtime perception uses the trained checkpoint
- Classifier v1 → Classifier final: iterates to · Model development progresses through successive checkpoints
- Camera/state → Vision pipeline: observed by · Captured images or state observations enter perception
- Vision pipeline → Serial bridge: sends decisions · Perception results are forwarded into hardware integration
- Train agent → Sorting env: trains in · Agent learns inside the sorting environment
- Sorting env → Rewards: scores with · Environment feedback is shaped by reward logic
- Rewards → Train agent: updates policy · Reward signals drive agent optimization
- Train agent → Robot action: produces · Training learns action selection for the robot
- Serial bridge → Robot action: encodes · High-level commands are converted to executable robot actions
- Robot action → Arm controller: executes on · Firmware receives commands and drives actuators
- Arm controller → Cardboard proto: moves · Embedded control actuates the physical prototype
- Serial bridge → Arm controller: serial link · Python communicates with the microcontroller over serial
- Camera/state → Sorting env: simulates · The environment models the observation-action loop
