{"id":31802052,"url":"https://github.com/thelostleo/ros_fishtank_bot","last_synced_at":"2026-05-07T15:37:35.082Z","repository":{"id":308995579,"uuid":"1034494385","full_name":"TheLostLeo/ROS_FISHTANK_BOT","owner":"TheLostLeo","description":"This is a Fish tank cleaning system that uses ROS1 to make a master slave system that allow for swarm kind bot cleaning system","archived":false,"fork":false,"pushed_at":"2025-08-09T05:22:37.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-09T06:20:59.441Z","etag":null,"topics":["raspberry-pi","ros","ros-noetic","rospy","websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheLostLeo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T13:33:09.000Z","updated_at":"2025-08-09T05:22:40.000Z","dependencies_parsed_at":"2025-08-09T06:21:00.857Z","dependency_job_id":"57bb1313-ffb7-400a-b524-89c75777538d","html_url":"https://github.com/TheLostLeo/ROS_FISHTANK_BOT","commit_stats":null,"previous_names":["thelostleo/ros_fishtank_bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TheLostLeo/ROS_FISHTANK_BOT","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLostLeo%2FROS_FISHTANK_BOT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLostLeo%2FROS_FISHTANK_BOT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLostLeo%2FROS_FISHTANK_BOT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLostLeo%2FROS_FISHTANK_BOT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheLostLeo","download_url":"https://codeload.github.com/TheLostLeo/ROS_FISHTANK_BOT/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLostLeo%2FROS_FISHTANK_BOT/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005657,"owners_count":26083941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["raspberry-pi","ros","ros-noetic","rospy","websocket"],"created_at":"2025-10-11T00:16:24.700Z","updated_at":"2025-10-11T00:16:30.268Z","avatar_url":"https://github.com/TheLostLeo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tank Cleaning Robot ROS System\n\nA comprehensive ROS-based autonomous tank cleaning robot system with distributed master-brain architecture, water pump control, and professional communication interfaces.\n\n## Overview\n\nThis repository contains a complete ROS system for controlling an autonomous tank cleaning robot with integrated water management. The system features a distributed architecture with centralized coordination, dedicated subsystem controllers, WebSocket communication, and professional status reporting.\n\n## System Architecture\n\nThe system consists of two main packages with a centralized brain architecture:\n\n- **tank_snode**: Autonomous tank robot with sensors, motors, and local intelligence\n- **master_snode**: Central coordination brain with specialized subsystem controllers\n\n### Master-Brain Architecture\n\n```\nUser Interface → Master Brain → Subsystem Controllers → Hardware/Tank\n     ↑              ↓              ↓                    ↓\nResponse Topics ← Status Updates ← Component Status ← Actual Operations\n```\n\n## Project Structure\n\n```\n├── master_snode/                    # Master coordination package\n│   ├── launch/\n│   │   └── master.launch           # Complete system launcher\n│   ├── scripts/\n│   │   ├── master_node.py          # Central brain coordinator  \n│   │   ├── bot_controller.py       # WebSocket communication handler\n│   │   ├── water_pump_controller.py # Demo water pump control\n│   │   └── test_user_input.py      # Interactive testing interface\n│   ├── CMakeLists.txt\n│   └── package.xml\n├── tank_snode/                      # Tank robot package  \n│   ├── launch/\n│   │   └── tank_bot.launch         # Launch file for all tank nodes\n│   ├── scripts/\n│   │   ├── comm_node.py            # WebSocket server \u0026 communication\n│   │   ├── decision_node.py        # Cleaning pattern logic\n│   │   ├── ir_sensor_node.py       # IR sensor interface\n│   │   └── motor_node.py           # Motor control (demo)\n│   ├── src/                        # C++ source files (if any)\n│   ├── CMakeLists.txt\n│   └── package.xml\n├── .env                            # Environment variables (user-created)\n├── example.env                     # Environment variable template\n├── .gitignore                      # Version control exclusions\n└── README.md                       # This file\n```\n\n## Package Dependencies\n\n### Required ROS Packages\n- **rospy** - Python client library for ROS\n- **std_msgs** - Standard ROS message types\n- **sensor_msgs** - Sensor-specific message types\n- **geometry_msgs** - Geometric primitive messages\n- **catkin** - ROS build system\n\n## Getting Started\n\n### Prerequisites\n\n- ROS Noetic (Ubuntu 20.04)\n- Python 3.8+\n- Catkin workspace\n\n### Installation\n\n1. Clone this repository into your catkin workspace:\n```bash\ncd ~/catkin_ws/src\ngit clone https://github.com/TheLostLeo/ROS_FISHTANK_BOT.git\n```\n\n2. Build the packages:\n```bash\ncd ~/catkin_ws\ncatkin_make\nsource devel/setup.bash\n```\n\n3. Set up Python virtual environment:\n```bash\ncd ~/catkin_ws/src\npython3 -m venv myenv\nsource myenv/bin/activate\npip install -r requirements.txt  \n```\n\n3. Configure environment variables:\n```bash\n# Copy the example environment file\ncp example.env .env\n\n# Edit .env file to customize WebSocket settings (optional)\n# Default: WEBSOCKET_HOST=localhost, WEBSOCKET_PORT=8765\nnano .env  # or use your preferred editor\n```\n\n### Usage\n\n### Usage\n\n#### Complete System Launch (Recommended)\n```bash\n# Terminal 1: Start tank robot system\nroslaunch tank_snode tank_bot.launch\n\n# Terminal 2: Start master brain with all controllers\nroslaunch master_snode master.launch\n```\n\n#### Interactive Testing Commands\nThe test interface provides comprehensive control over the entire system:\n\n```\nAvailable Commands:\nTANK CONTROLS:\n  1. start         - Start tank cleaning operation\n  2. stop          - Stop tank cleaning operation \n  3. status        - Get current tank status\nPUMP CONTROLS:\n  4. drain         - Drain tank water\n  5. fill          - Fill tank with fresh water\n  6. water_change  - Complete water change cycle\n  7. pump_stop     - Stop all pump operations\nSYSTEM:\n  8. system_status - Get complete system status\n  9. help          - Show this menu\n 10. quit          - Exit test program\n```\n## Key Features\n\n### Central Brain Architecture\n- **Master Brain**: Central coordinator managing all subsystems via ROS topics\n- **Bot Controller**: Dedicated WebSocket handler for tank communication\n- **Water Pump Controller**: Hardware control with simulation fallback\n- **Professional Communication**: Status updates only when changes occur\n\n### Advanced System Coordination\n- **Topic-Based Communication**: Pure ROS messaging between all components\n- **State-Change Reporting**: Smart status updates prevent message spam\n- **One-Time Warnings**: Health monitoring without repetitive alerts\n- **Comprehensive Status**: Complete system status with JSON formatting\n\n### Tank Robot Features\n- **Autonomous Navigation**: Systematic zig-zag cleaning pattern\n- **Edge Detection**: IR sensor-based obstacle and wall detection\n- **Smart State Management**: Nodes only print on state changes\n- **Quiet Initialization**: Professional startup with ready confirmation\n- **Modular Design**: Separate nodes for sensors, motors, decision-making\n\n### Water Management System\n- **Demo Pump Control**: Simulated water pump operations without hardware\n- **Operation Feedback**: Start/stop/completion messages to master brain\n- **Water Level Simulation**: Realistic water level changes during operations\n- **Multi-Phase Cycles**: Complete water change cycles (drain → fill)\n- **Safety Monitoring**: Warnings for simultaneous pump/cleaning operations\n\n### Interactive Testing System\n- **Enhanced Command Menu**: Tank controls + pump controls + system status\n- **Professional Output**: Clean status reports without spam\n- **Multiple Operation Modes**: Interactive, command-line, and automated testing\n- **Real-Time Feedback**: Immediate command acknowledgment and status updates\n- **Comprehensive Controls**: \n  - Tank: `start`, `stop`, `status`\n  - Pump: `drain`, `fill`, `water_change`, `pump_stop`\n  - System: `system_status`\n\n### Configuration Management\n- **Environment Variables**: Secure WebSocket configuration via .env files\n- **python-dotenv Integration**: Professional environment variable handling\n- **Security**: Sensitive configuration excluded from version control (.gitignore)\n- **Easy Setup**: Copy example.env to .env for quick configuration\n- **Default Values**: Works out-of-the-box with localhost:8765\n\n\n## ROS Topics \u0026 Communication\n\n### Master Brain Topics\n- `/master_control` - Receives commands from user interface\n- `/master_status` - Publishes comprehensive system status (JSON)\n- `/master_commands` - Command confirmations and responses\n- `/bot_commands` - Sends commands to tank via bot controller\n- `/pump_control` - Sends commands to water pump controller\n\n### Tank Communication Topics\n- `/tank_response` - Tank command responses via bot controller\n- `/tank_status` - Tank status updates (cleaning/idle states)\n- `/bot_connection` - Bot controller connection status\n\n### Water Pump Topics\n- `/pump_status` - Pump operation status (running, operation, flow rate)\n- `/pump_response` - Pump operation feedback (start/stop/completion)\n- `/water_level` - Water level sensor data (OK/LOW)\n- `/flow_rate` - Current pump flow rate information\n\n### Tank Node Internal Topics  \n- `/tank_control` - Internal tank control signals\n- `/ir_sensor_data` - IR sensor readings and edge detection\n- `/motor_commands` - Motor control commands and responses\n- `/decision_state` - Decision node state and cleaning patterns\n\n### WebSocket Communication\n- **Protocol**: JSON-based message exchange between bot controller and tank\n- **Default Port**: 8765 (configurable via .env)\n- **Message Types**: \n  - Command execution (`start`, `stop`, `status`)\n  - Status updates (cleaning state, system health)\n  - Error handling and connection management\n- **Security**: Host/port configured via environment variables\n\n### Code Quality Standards\n\n- **Professional Output**: Nodes print only on state changes, not continuous status\n- **One-Time Warnings**: System health warnings appear once per condition\n- **State-Change Logging**: Smart status updates prevent console spam  \n- **Quiet Initialization**: Clean startup with ready confirmation messages\n- **Modular Architecture**: Clear separation of concerns across specialized nodes\n- **Comprehensive Error Handling**: Robust error management and recovery\n- **Topic-Based Coordination**: Pure ROS communication between all components\n\n### Architecture Highlights\n\n- **Central Brain Pattern**: Master node coordinates all subsystem controllers\n- **Specialized Controllers**: Dedicated nodes for WebSocket, pump, and coordination\n- **Professional Communication**: Status updates only when information changes\n- **Smart Status Management**: Prevents repetitive messages and console spam\n- **Real-Time Feedback**: Immediate acknowledgment of commands with operation progress\n- **Comprehensive Monitoring**: System health warnings with intelligent state tracking\n\n### Troubleshooting\n\n**System Startup:**\n- Start tank_snode first, then master_snode\n- Ensure .env file exists: `cp example.env .env`\n- Verify all nodes launch successfully in separate terminals\n\n**Connection Issues:**\n- Check WebSocket port availability (default: 8765)\n- Verify bot controller connects to tank communication node\n- Monitor connection status via `/bot_connection` topic\n\n**Command Not Working:**\n- Use `system_status` command to verify system state\n- Check ROS topics: `rostopic list` and `rostopic echo /master_commands`\n- Monitor master brain coordination messages\n- Verify all subsystem controllers are running\n\n**Water Pump Issues:**\n- Pump controller runs in demo mode (no hardware required)\n- Check `/pump_response` topic for operation feedback\n- Monitor `/pump_status` for current operation state\n- Use `pump_stop` to halt any running operations\n\n**Environment Variable Issues:**\n- Missing .env file: Copy `example.env` to `.env`\n- Port conflicts: Change `WEBSOCKET_PORT` in .env file\n- Host binding issues: Set `WEBSOCKET_HOST=0.0.0.0` for network access\n\n**Build Issues:**\n- Clean build: `catkin_make clean \u0026\u0026 catkin_make`\n- Check all required ROS packages are installed\n- Verify Python dependencies\n- Ensure proper workspace sourcing: `source devel/setup.bash`\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Repository Information\n\n- **Repository**: [ROS_FISHTANK_BOT](https://github.com/TheLostLeo/ROS_FISHTANK_BOT)\n- **Author**: TheLostLeo\n- **ROS Version**: Noetic (Ubuntu 20.04)\n- **Python Version**: 3.8+\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelostleo%2Fros_fishtank_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthelostleo%2Fros_fishtank_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelostleo%2Fros_fishtank_bot/lists"}