Cleanerbot

Cleanerbot is a robotic toilet-cleaning system developed as a university capstone project. The project explores how industrial robotic-arm concepts can be adapted to a small-scale household cleaning application.

The system uses a custom 5-degree-of-freedom robotic arm together with ROS 2, MoveIt 2, RViz, robot kinematics, trajectory planning, and an ESP32-based servo controller.

The software allows the robot to be modelled and visualised in ROS, planned using MoveIt, and controlled physically by transmitting joint commands from ROS to the ESP32.

Please refer to the video for the development of the simulation https://drive.google.com/file/d/11hbCymXCikakGu0YpHP9UGCK55OFIKny/view?usp=drive_link

Project Overview

Cleanerbot consists of two main components:

ROS 2 Robotic Arm Workspace

Robot model (URDF/Xacro)
RViz visualisation
MoveIt 2 motion planning
Joint state communication
Trajectory generation
Gazebo simulation
Serial communication

ESP32 Robot Controller

Receives joint commands from ROS
Converts commands into servo movements
Controls the physical robotic arm

System Architecture

                  ┌─────────────┐
                  │    RViz     │
                  │ Interactive │
                  │   Marker    │
                  └──────┬──────┘
                         │
                         ▼
                  ┌─────────────┐
                  │   MoveIt 2  │
                  │   Motion    │
                  │   Planner   │
                  └──────┬──────┘
                         │
                         ▼
                 Joint Positions
                         │
                         ▼
                  /joint_states
                         │
                         ▼
               ┌─────────────────┐
               │ ROS Serial Node │
               │     Python      │
               └────────┬────────┘
                        │ USB Serial
                        ▼
                    ┌───────┐
                    │ ESP32 │
                    └───┬───┘
                        │
                        ▼
                     Servos
                        │
                        ▼
                 Physical Robot Arm

Robot Design

The robot uses five rotational joints:

Joint	Function
joint_base	Base rotation (yaw)
joint_1	Shoulder pitch
joint_2	Elbow pitch
joint_3	Wrist pitch
joint_4	Wrist rotation

Robot links:

base_link
link_1
link_2
link_3
link_4
link_5
camera_link

Repository Structure

Cleanerbot/
│
├── src/
│   ├── Robot description packages
│   ├── URDF/Xacro files
│   ├── MoveIt configuration
│   ├── Gazebo configuration
│   ├── Launch files
│   └── ROS nodes
│
├── RobotArm_controller/
│   └── ESP32 controller code
│
├── README.md
└── LICENSE

Software Requirements

The project was developed using:

Ubuntu 22.04 LTS
ROS 2 Humble
MoveIt 2
RViz 2
Gazebo
Python 3
ESP32
Arduino IDE / PlatformIO
Git

ROS 2 Installation

Install ROS 2 Humble Desktop:

sudo apt update
sudo apt install ros-humble-desktop

Source ROS:

source /opt/ros/humble/setup.bash

Add to .bashrc:

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

Required Packages

Development Tools

sudo apt install \
python3-colcon-common-extensions \
python3-rosdep \
python3-pip \
git

MoveIt 2

sudo apt install ros-humble-moveit

MoveIt Setup Assistant

sudo apt install ros-humble-moveit-setup-assistant

RViz

sudo apt install ros-humble-rviz2

Robot State Publisher

sudo apt install ros-humble-robot-state-publisher

Joint State Publisher

sudo apt install \
ros-humble-joint-state-publisher \
ros-humble-joint-state-publisher-gui

Xacro

sudo apt install ros-humble-xacro

ROS 2 Control

sudo apt install \
ros-humble-ros2-control \
ros-humble-ros2-controllers

Gazebo

sudo apt install \
ros-humble-gazebo-ros \
ros-humble-gazebo-ros-pkgs \
ros-humble-gazebo-ros2-control

Serial Communication

pip3 install pyserial

or

sudo apt install python3-serial

Installing Dependencies Automatically

Initialize rosdep:

sudo rosdep init
rosdep update

Install dependencies:

rosdep install --from-paths src --ignore-src -r -y

Clone the Repository

git clone https://github.com/Smleeep/Cleanerbot.git
cd Cleanerbot

Build the Workspace

source /opt/ros/humble/setup.bash
colcon build

After building:

source install/setup.bash

Optional:

echo "source ~/Cleanerbot/install/setup.bash" >> ~/.bashrc

How Cleanerbot Works

1. Robot Description

The robot is described using a URDF/Xacro model.

The model defines:

Links
Joints
Joint limits
Collision geometry
Visual geometry
Masses
Inertial properties

Robot kinematic chain:

base_link
    │
joint_base
    │
 link_1
    │
 joint_1
    │
 link_2
    │
 joint_2
    │
 link_3
    │
 joint_3
    │
 link_4
    │
 joint_4
    │
 link_5

2. Robot State Publisher

robot_state_publisher reads the robot model and current joint positions and publishes TF transforms used by RViz.

URDF
  +
Joint States
  │
  ▼
robot_state_publisher
  │
  ▼
TF Transforms
  │
  ▼
RViz

3. Joint States

ROS uses the /joint_states topic to store current robot positions.

Example:

joint_base = -1.2 rad
joint_1    =  0.8 rad
joint_2    =  1.0 rad
joint_3    =  0.3 rad
joint_4    = -0.2 rad

4. MoveIt 2

MoveIt handles:

Inverse kinematics
Motion planning
Collision checking
Trajectory generation

Target Pose
      │
      ▼
Inverse Kinematics
      │
      ▼
Joint Angles
      │
      ▼
Trajectory Planning
      │
      ▼
Motion Execution

5. RViz

RViz provides a graphical interface for:

Viewing the robot
Planning trajectories
Visualising collisions
Manipulating end-effector targets

Interactive markers can be moved to generate robot motions.

6. Serial Communication

The physical robot receives commands through a Python serial bridge.

Process:

ROS Joint States
       │
       ▼
Python Node
       │
       ▼
Radians → Degrees
       │
       ▼
Serial Message
       │
       ▼
ESP32

7. ESP32 Controller

The ESP32:

Receives serial data
Parses joint angles
Converts angles into servo commands
Moves the physical arm

ROS
 │
 ▼
Serial Bridge
 │
 ▼
ESP32
 │
 ├── Servo 1
 ├── Servo 2
 ├── Servo 3
 ├── Servo 4
 └── Servo 5

Coordinate Units

ROS uses SI units:

Quantity	Unit
Distance	metres
Rotation	radians
Mass	kilograms
Time	seconds

Servo controllers typically use degrees.

Conversion:

degrees = radians × 180 / π

Development Workflow

Rebuild after making changes:

cd ~/Cleanerbot
colcon build
source install/setup.bash

For faster Python development:

colcon build --symlink-install

Useful Commands

List nodes:

ros2 node list

List topics:

ros2 topic list

View joint states:

ros2 topic echo /joint_states

View topic information:

ros2 topic info /joint_states

Generate TF tree:

ros2 run tf2_tools view_frames

Validate URDF:

check_urdf robot.urdf

Troubleshooting

Package Not Found

source /opt/ros/humble/setup.bash
source install/setup.bash

Missing Dependencies

rosdep install --from-paths src --ignore-src -r -y
colcon build

Joint States Missing

ros2 topic list

Ensure a joint state publisher or controller is running.

Serial Port Issues

Find connected device:

ls /dev/ttyUSB*

or

ls /dev/ttyACM*

Add serial permissions:

sudo usermod -a -G dialout $USER

Log out and back in afterwards.

Future Improvements

Potential future developments include:

Computer vision
Automatic toilet detection
Surface recognition
Camera-based localisation
Force sensing
Automated cleaning trajectories
Improved simulation
Autonomous cleaning routines

Technologies Used

ROS 2 Humble
MoveIt 2
RViz 2
Gazebo
ROS 2 Control
URDF
Xacro
Python
C++
ESP32
Serial Communication
Robotic Kinematics
Motion Planning

Project Purpose

Cleanerbot was developed to investigate the integration of:

Robotics
Embedded Systems
Kinematics
Motion Planning
Simulation
Software Development
Hardware Control
Autonomous Systems

The project demonstrates how industrial robotic-arm software architectures can be adapted to a household robotic cleaning application.

Author

Developed as a university engineering capstone project.

GitHub:

https://github.com/Smleeep/Cleanerbot

Name		Name	Last commit message	Last commit date
RobotArm_controller		RobotArm_controller
src		src
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation