How rhcoding118/trash-sorting-robot works
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: vision_pipeline.py Vision pipeline · serial_bridge.py Serial bridge · train_agent.py Train agent · arm-controller.ino Arm controller
Components 14
Physical layer
Mechanical prototype and fabricated parts
- Cardboard proto · Physical waste-sorting prototype the stack is built around
cad - CAD exports · Rendered and printable mechanical outputs
cad/renders
Embedded layer
Microcontroller firmware and actuator control
- Arm controller · Low-level actuator control for the robot arm
firmware/arm-controller/arm-controller.ino - Robot action · Arm, grab, and sort commands sent to hardware
Python ML layer
Perception, integration, and learning code
- Serial bridge · Translates Python commands into microcontroller serial messages
integrations/serial_bridge.py - Vision pipeline · Image processing and classification entry point
perception/vision_pipeline.py - Vision utils · Helper logic used by the perception pipeline
perception/utils.py - Classifier v1 · Trained perception model artifact
perception/models/wast_classifier_v1.pth - Classifier final · Latest deployed perception model artifact
perception/models/waste_classifier_final.pth - Class labels · Label mapping for waste classes
perception/models/labels.txt - Camera/state · Runtime observations entering perception and decision logic
RL training
Offline environment, rewards, and agent optimization
- Train agent · Entry point for policy training
training/train_agent.py - Sorting env · Task environment for learning sorting behavior
training/envs/sorting_env.py - Rewards · Scoring and feedback used during training
training/rewards.py
Connections 16
- 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