How amanchauhan-dev/ros_ws works
This repository is a ROS workspace for e-Yantra task4c, organized as several Python ROS packages rather than one monolith. The packages are separated by robot capability: mobile navigation, perception/shape detection, and arm manipulation. The workspace also includes multiple “versioned” and “real case” scripts, which suggests iterative development and scenario-specific task logic.
1. Top-level architecture
The repo is split into five main packages: ebot_3578, kc_3578, arm_3578, perp_3578, and shape_3578. Each package has its own package.xml, setup.py, and test/lint scaffolding, indicating ROS-native deployment boundaries. The overall system is best drawn as a set of ROS nodes/modules communicating through ROS topics/services/actions, not as a traditional layered application.
2. Mobile robot / navigation subsystem (ebot_3578)
This package owns the base navigation side. It contains a navigation map bundle (map.pgm, map.yaml, map.npy, map_occupancy_grid.npy) plus scripts such as navigation.py, nav_v1.py, position_fetcher.py, and pgm_to_occupancy_grid.py. Architecturally, this is the localization/navigation boundary: map assets feed navigation logic, and position/state utilities likely expose the robot’s pose for higher-level coordination.
3. High-level integration/control package (kc_3578)
kc_3578 contains perception.py, shape_detection.py, navigation.py, and arm_manipulation.py. This looks like the orchestration layer that ties the major subsystems together. For a diagram, treat it as the coordination boundary that consumes perception outputs, decides navigation behavior, and triggers arm actions.
4. Arm manipulation subsystem (arm_3578)
This is the largest package and contains multiple generations of task logic: final/, new/, and real_cases/. Files like final_arm_manipulation_3578.py, final_ferti_sol.py, hybrid_logic.py, unload_script.py, and the real_case*.py scripts show that the arm behavior was developed through several strategies and task variants. The role of this package is end-effector control and task execution such as unloading, sorting, and handling fruits/fertilizer-like objects.
5. Perception experimentation package (perp_3578)
This package contains old/ and new/ versions (p1.py, p2.py, p3.py), which strongly suggests a prototype-to-final evolution of perception logic. It likely acts as an experimental branch for vision processing or object classification before logic is consolidated into kc_3578 and shape_3578.
6. Shape detection package (shape_3578)
shape_3578 contains shape_v1.py and shape_v2.py, which appears to isolate shape classification/detection logic. In the architecture diagram, this should sit under the perception stream, providing object labels or geometric categories to the coordinator and/or arm task planner.
7. Data flow between subsystems
The main flow appears to be: environment/map inputs and robot pose into navigation, sensor/perception inputs into shape detection, and detected object/task state into arm manipulation. kc_3578 likely sits in the middle, receiving perception outputs and commanding ebot_3578 and arm_3578 accordingly. The system is therefore a closed-loop robotics pipeline: sense → interpret → navigate → manipulate.
8. Static assets and offline artifacts
The navigation package includes precomputed map representations (.pgm, .yaml, .npy). These are important architecture artifacts because they allow navigation without runtime map generation. The repository is not storing large business data or databases; its persistent artifacts are mostly robot maps and task scripts.
9. Versioned task logic
The presence of directories like final, new, real_cases, old, and multiple v1/v2/v3 files indicates that several algorithmic variants coexist. These are not separate product subsystems; they are alternative implementations or tuned versions for different competition scenarios. In a diagram, they should be shown as internal implementation branches under the arm/perception layers.
10. Tooling and quality boundary
Every package includes test files for copyright, flake8, and pep257, which shows the code is intended to meet ROS/Python packaging and style constraints. The README also emphasizes no virtualenv dependency and no plotting/graphing logic, so the architecture is meant to run directly in the ROS environment with logging-based observability.
11. How to draw the diagram
A good diagram would show:
- a ROS workspace boundary containing the five packages,
- ebot_3578 as the navigation/map subsystem,
- shape_3578 and perp_3578 as perception-related subsystems,
- arm_3578 as the actuation/task-execution subsystem,
- kc_3578 as the coordination layer linking perception, navigation, and manipulation.
12. Overall system character
This is a robotics task workspace, not a general application stack. Its architecture is dominated by ROS package boundaries, map-driven navigation, perception-to-action control flow, and multiple competing implementations of the same core behaviors for competition tuning.
Main entry points: arm_manipulation.py Arm bridge · kc_3578 kc_3578 · arm_3578 arm_3578 · nav_map Map bundle
Components 20
Navigation
Map-driven base motion and pose utilities.
- ebot_3578 · Mobile base navigation package with map assets and pose utilities.
ebot_3578 - Map bundle · Precomputed map representations used by navigation.
ebot_3578/ebot_3578/nav_map - Navigation logic · Navigation routines for moving the robot through the workspace.
ebot_3578/ebot_3578/nav_map/navigation.py - Pose fetcher · Fetches or exposes robot position/state for navigation coordination.
ebot_3578/ebot_3578/nav_map/position_fetcher.py - Grid convert · Converts PGM maps into occupancy grid form.
ebot_3578/ebot_3578/nav_map/pgm_to_occupancy_grid.py
Perception
Vision and shape analysis components.
- shape_3578 · Dedicated shape detection package.
shape_3578 - Shape v1 · First shape detection implementation.
shape_3578/shape_3578/shape_v1.py - Shape v2 · Refined shape detection implementation.
shape_3578/shape_3578/shape_v2.py - perp_3578 · Perception experimentation package with versioned prototypes.
perp_3578 - Old vision · Earlier perception prototype.
perp_3578/perp_3578/old/p1.py - New vision · Newer perception experiments and revisions.
perp_3578/perp_3578/new/p2.py
Manipulation
Arm task execution and unloading logic.
- arm_3578 · Arm manipulation package with multiple task variants.
arm_3578 - Arm logic · Current arm manipulation and hybrid task logic.
arm_3578/arm_3578/new/final_arm_manipulation_3578.py - Final tasks · Finalized unloading, fruit sorting, and fertilizer routines.
arm_3578/arm_3578/final - Real cases · Scenario-specific arm routines for real-case tuning.
arm_3578/arm_3578/real_cases
Integration
Coordinator package that ties subsystems together.
- kc_3578 · High-level coordination package for perception, navigation, and arm control.
kc_3578 - Perception bridge · Bridges perception outputs into the control flow.
kc_3578/kc_3578/perception.py - Shape bridge · Routes shape detection results into the coordinator logic.
kc_3578/kc_3578/shape_detection.py - Nav bridge · Wraps or triggers navigation behavior from the coordinator.
kc_3578/kc_3578/navigation.py - Arm bridge · Triggers manipulation workflows from the coordinator.
kc_3578/kc_3578/arm_manipulation.py
Connections 22
- ebot_3578 → Map bundle: uses · Navigation consumes static map artifacts.
- Map bundle → Grid convert: feeds · Map data can be converted into occupancy grids.
- Map bundle → Navigation logic: supports · Map assets support base navigation routines.
- Pose fetcher → Navigation logic: state for · Pose utilities provide position/state to navigation.
- kc_3578 → Perception bridge: coordinates · Coordinator manages perception flow.
- kc_3578 → Shape bridge: coordinates · Coordinator manages shape detection flow.
- kc_3578 → Nav bridge: coordinates · Coordinator manages navigation flow.
- kc_3578 → Arm bridge: coordinates · Coordinator manages manipulation flow.
- Shape bridge → shape_3578: delegates to · Shape bridge relies on dedicated shape detection package.
- Perception bridge → perp_3578: delegates to · Perception bridge can use experimentation outputs.
- shape_3578 → Shape v1: implements · Contains first shape detection version.
- shape_3578 → Shape v2: implements · Contains second shape detection version.
- perp_3578 → Old vision: contains · Houses earlier prototype vision code.
- perp_3578 → New vision: contains · Houses newer prototype vision code.
- Nav bridge → ebot_3578: drives · Coordinator drives the mobile base package.
- Arm bridge → arm_3578: drives · Coordinator drives arm manipulation package.
- arm_3578 → Arm logic: implements · Current manipulation logic lives in the new branch.
- arm_3578 → Final tasks: implements · Final task scripts implement completed workflows.
- arm_3578 → Real cases: implements · Real-case scripts capture scenario-specific variants.
- Perception bridge → Arm bridge: informs · Perception results inform manipulation decisions.
- Shape bridge → Arm bridge: informs · Detected shapes guide arm task selection.
- Nav bridge → Arm bridge: sequencing · Navigation outcomes can gate manipulation steps.