Overview
The engineering problem
A simulated vacuum must cover a furnished room while reacting to obstacles, contact, carpet, and battery level. A planned path alone cannot decide what to do when a waypoint is blocked or a cleaning phase must stop.
Contribution
The public repository contains an independently implemented Python controller, Webots robot and room, editable technical diagrams, and simulation recordings. The controller combines nine mission states with sensor-driven wheel commands and a carpet map carried from vacuuming into mopping.
What exists now
In the Webots world, the Python controller follows cleaning and docking states, reacts to obstacles and carpet sensing, and returns to charge as battery state changes. Public recordings show simulated behaviour. No physical robot or automated simulation suite validates it.
- This on-page diagram traces sensing, action, feedback, and mission recovery. Its text explains every node and connection.
- Repository GIFs show navigation and obstacle avoidance, undocking, and docking in Webots.View simulation recordings (opens in a new tab)
- Device setup, state transitions, thresholds, carpet logic, and docking fallbacks are documented alongside editable diagrams.View technical design (opens in a new tab)
- GitHub Actions runs Ruff lint. The workflow does not execute the simulator or a test suite.View ci lint workflow (opens in a new tab)
Engineering detail
Constraints
- The robot runs in the included 6 m by 6 m Webots room with named simulator devices and a custom charger.
- GPS supplies world-frame position for coverage and docking. The controller does not implement physical localization.
- Coverage uses zigzag waypoints with reactive avoidance and fallback room and rug bounds.
Architecture at a glance
Each Webots step reads LiDAR, contact, surface, position, heading, and battery inputs before safety checks and state dispatch. The selected state sets wheel speeds. New simulator readings close the loop. Vacuuming records carpet cells for mopping, while low battery or completed waypoints lead to return, alignment, docking, and charging.
The upper path moves from simulator sensors through interpreted readings to mission state and wheel action. The lower path shows environmental feedback, carpet memory, and return to charge. Bumper, cliff, and stalled-motion checks can temporarily move cleaning into escape.
- Sensors: Webots supplies LiDAR, bumper, cliff, surface, GPS, compass, and battery readings each step.
- Perception: The controller reduces LiDAR to five minimum-range sectors, reads pose and battery, and records carpet cells during vacuuming.
- Mission state: Nine states separate undocking, two cleaning phases, escape, return, alignment, docking, charging, and finish.
- Wheel action: The active state sets bounded wheel speeds for waypoint following, avoidance, carpet escape, or dock approach.
- Feedback: Motion changes simulator position, proximity, contact, surface, and battery readings for the next step.
- Carpet map: Vacuuming stores 0.25 m surface cells. Mopping uses their bounds, with fixed rug bounds as fallback.
- Return: Low battery, a 20-minute phase limit, or completed waypoints sends the robot to a pre-dock waypoint.
- Dock + charge: Heading alignment and dock approach lead to charging, with contact, GPS, stall, and timeout checks.
- Resume / finish: At 95 percent charge or a timeout, the controller resumes waypoints, starts mopping, or stops after both phases.
Connections: Sensors to Perception (read and reduce); Perception to Mission state (update context); Mission state to Wheel action (select behaviour); Wheel action to Feedback (motion changes world); Feedback to Perception (next control step); Perception to Carpet map (vacuuming observations); Carpet map to Mission state (reshapes mopping path); Mission state to Return (battery); Return to Dock + charge (align and approach); Dock + charge to Resume / finish (charge threshold or timeout); Resume / finish to Mission state (next mission state).
Boundaries: SIMULATOR INPUT + CONTROL; MISSION RECOVERY.
Annotations: Bumper / cliff / stall → ESCAPE → previous state.
Key decisions
How should the controller organize changing behaviour?
Cleaning, recovery, docking, and charging need distinct actions and exit conditions.
- Selected
- One Python controller dispatches nine named states. Contact and cliff checks run before state execution. Escape can return to the previous state.
- Alternatives
- A single continuous waypoint routine without explicit mission states
- Trade-off
- Explicit transitions are inspectable, but the controller and its timers remain in one large Python file.
- Consequence
- The mission can suspend cleaning for escape or return, then resume unvisited waypoints after charging.
How should planned coverage react to obstacles?
Zigzag waypoints route through the room while furniture can block a direct path.
- Selected
- Split the 256-ray, 180-degree LiDAR image into five sectors. Threshold-based turning or slowing takes priority over GPS waypoint steering.
- Alternatives
- Follow precomputed waypoints without local avoidance
- Trade-off
- Sector minima give a simple local reaction without a global obstacle map or guaranteed complete coverage.
- Consequence
- Bumper, cliff, and lack-of-progress checks add escape paths. A nearby waypoint can be skipped after eight seconds without progress.
How should cleaning mode respond to carpet?
The same room is traversed in a vacuuming phase and a later mopping phase.
- Selected
- Record 0.25 m carpet cells from the downward sensor while vacuuming. Generate mopping strips around the observed carpet interval and direct the robot off detected carpet.
- Alternatives
- Reuse the vacuuming path for mopping without surface context
- Trade-off
- Unseen carpet and sensor thresholds limit map accuracy. Fixed rug bounds fill gaps.
- Consequence
- Mopping avoids the mapped zone where possible and reacts if the robot still reaches carpet.
When should cleaning yield to docking?
Waypoints may finish, a phase may run for 20 minutes, or the battery may run low.
- Selected
- Enter RETURNING below 20 percent battery, at the phase limit, or on waypoint completion. Navigate to a pre-dock point, align, approach, and charge.
- Alternatives
- Stop in place at the end of a cleaning phase
- Trade-off
- Docking uses simulator GPS, known geometry, contact and stall checks, and timeouts rather than hardware-tested localization.
- Consequence
- Charging can resume an incomplete phase, start mopping, or finish after both phases.
Reliability and quality
- CI scope
- The source repository's GitHub Actions workflow runs Ruff lint on Python files. It does not run automated behaviour tests or a Webots simulation.
- Inspectable artifacts
- The repository includes the Webots world, controller, technical design, editable Draw.io diagrams, and GIF simulation recordings.
The controller source (opens in a new tab) keeps mission decisions in a single loop. Each Webots step reads devices, checks contact and cliff events, checks for stalled movement, and dispatches the current state. A fixed zigzag route supplies GPS waypoints. Short LiDAR ranges interrupt waypoint steering. The controller turns or slows based on five sectors.
Vacuuming records cells when the downward sensor crosses its carpet threshold. Mopping uses those cells to shorten strips near the rug and directs the robot away if carpet is detected. This map remains in memory for one run. Known rug coordinates cover insufficient observations.
The Webots world (opens in a new tab) supplies the robot, room, furniture, rug, and charger. The technical design (opens in a new tab) records device setup and transition thresholds. These artifacts and the simulation GIFs show intended behaviour and simulator assumptions, without establishing performance on hardware.
What next
A useful next step is repeatable simulation scenarios for obstacle, carpet, and docking transitions before making wider reliability claims.
Limitations
- Recorded behaviour is in Webots. The repository provides no physical vacuum or charger validation.
- GPS gives simulator position. Real-world localization, sensor noise, and hardware timing are outside this implementation.
- Fixed room and rug bounds are fallbacks. Five-sector avoidance and waypoint skipping can leave coverage gaps.
- Carpet cells live in memory for the current run. Mopping depends on surfaces encountered during vacuuming and fallback geometry.
- CI checks Python lint only. There is no automated controller or end-to-end simulation test suite.