14 KiB
AGENTS.md
Enuxia Vacuum — Repository Guidance
This repository is maintained as Enuxia Vacuum, an independent open-source fork of VacuumTiger.
The upstream project provided the original software foundation. Enuxia Vacuum preserves that history and attribution while developing its own technical direction, architecture and roadmap.
This file is the main repository guidance for coding agents and automated contributors.
1. Project intent
Enuxia Vacuum is a local-first robotics stack for autonomous vacuum robots.
The project is not intended to merely reproduce proprietary factory behavior. Its goal is to provide an understandable, modifiable and self-hostable robotics platform with:
- low-level hardware control;
- local telemetry;
- mapping and localization;
- robust autonomous navigation;
- cleaning coverage planning;
- docking;
- local APIs;
- engineering diagnostics;
- future user-facing PWA / Android clients.
The primary development platform is currently the Proscenic M6 Pro / 3irobotix CRL-200S.
2. Upstream provenance
Enuxia Vacuum is derived from the open-source VacuumTiger project.
Preserve:
- upstream Git history;
- copyright notices;
- applicable license notices;
- attribution for upstream-originated code;
- component-specific licensing metadata.
Do not rewrite history to imply that upstream code was originally authored by Enuxia.
When making changes, Git history should remain the authoritative record of authorship and evolution.
3. Architecture
The project is being progressively reorganized around clear subsystem boundaries.
User applications
PWA / Android / diagnostics
|
v
Mission Manager
map / clean / goto / dock
|
+-------------------+
| |
v v
Explorer Cleaning Planner
\ /
\ /
v v
Global Goal
|
v
Global Planner
Theta*
|
v
Global Path
|
v
Layered Local Costmap
|
v
Local Planner
DWA
|
v
Velocity Commands
|
v
SangamIO
|
v
Robot
Main responsibilities
SangamIO
Hardware abstraction and robot-specific drivers.
Responsibilities:
- MCU protocol handling;
- LiDAR communication;
- sensor telemetry;
- drive control;
- vacuum and brush actuators;
- platform initialization;
- robot-independent command/telemetry interface.
Higher-level code must not depend directly on CRL-200S / GD32 protocol details when the same information can be obtained through SangamIO.
DhruvaSLAM
Mapping and localization backend.
Responsibilities include:
- odometry;
- LiDAR preprocessing;
- scan matching;
- occupancy-grid mapping;
- submaps;
- keyframes;
- loop closure;
- pose-graph optimization;
- map persistence and publication.
The current repository also contains legacy navigation/exploration logic in DhruvaSLAM. That logic is a baseline, not the target architecture.
Navigation V2
Navigation V2 is the next major architecture.
It should separate:
- global planning;
- local planning;
- obstacle handling;
- progress detection;
- stuck detection;
- recovery;
- exploration.
New navigation development should move toward this architecture rather than increasing coupling inside the legacy navigator.
Drishti
Engineering and diagnostic UI.
It is intended for:
- robot telemetry;
- LiDAR visualization;
- SLAM visualization;
- navigation debugging;
- actuator testing;
- development diagnostics.
Drishti is not the final end-user application.
4. Core architecture rules
Navigation is not SLAM
SLAM answers:
Where is the robot, and what does the environment look like?
Navigation answers:
How should the robot move safely from its current pose to a requested goal?
Do not merge navigation policy into the SLAM core unless a true mapping/localization dependency requires it.
Exploration is not navigation
Exploration chooses where to go next.
Navigation decides how to get there.
The Explorer should provide a goal or approach pose to Navigation and receive a result such as:
Reached
Unreachable
Blocked
Cancelled
SafetyStop
Navigation should not need to understand frontier semantics.
Global planning is not local control
The global planner produces a path through the known map.
The local planner is responsible for:
- short-horizon trajectory selection;
- dynamic obstacle response;
- collision checking;
- robot footprint;
- clearance;
- immediate velocity commands.
Do not use a global A* / Theta* planner as a direct wheel controller.
Mapping is not cleaning
Mapping discovers and models the environment.
Cleaning uses an existing map to cover floor space efficiently.
Future cleaning should use room segmentation and coverage planning rather than frontier exploration as the cleaning strategy.
5. Navigation V2 direction
Target flow:
Goal
|
v
Global Planner (Theta*)
|
v
Global Path
|
v
Layered Local Costmap
|
v
Local Planner (DWA)
|
v
cmd_vel
The local costmap should eventually combine:
Static SLAM map
Live LiDAR obstacles
Bumper/contact observations
Cliff observations
Virtual walls / no-go zones
Robot footprint
Inflation / clearance costs
Recovery
Recovery must be based on measured robot motion, not only elapsed time.
Avoid logic equivalent to:
reverse for 1.5 seconds
then assume recovery succeeded
Prefer:
contact
-> stop
-> record obstacle/contact
-> backup
-> confirm actual encoder/pose displacement
-> choose clear direction
-> rotate
-> verify clearance
-> resume / replan
Repeated bumper hits in the same small region should influence future local navigation instead of causing the robot to retry the same approach indefinitely.
6. CRL-200S / M6 Pro hardware facts
Current validated development platform:
Robot Proscenic M6 Pro / 3irobotix CRL-200S
SoC Allwinner A33
MCU GD32F103
LiDAR Delta-2D
MCU UART /dev/ttyS3
LiDAR UART /dev/ttyS1
Validated Enuxia fork work includes:
- GD32 cold-boot initialization fixes;
- corrected Delta-2D angular decoding;
- stable full-revolution LiDAR scans;
- hardware telemetry;
- drive and actuator control;
- bumper persistence into SLAM state;
- SLAM pose-graph / submap corrections;
- navigation and frontier failure handling improvements.
Do not regress these areas when restructuring the project.
7. Hardware ownership and process safety
On hardware where the factory controller and SangamIO compete for the same MCU/UART or actuators, they must not run simultaneously.
For the CRL-200S development setup:
- SangamIO is the active hardware daemon;
- the original factory hardware controller must remain inactive during SangamIO use.
Never introduce code or documentation that casually starts both hardware stacks.
8. Physical safety
This repository controls physical machinery.
For motion-related work:
- assume experimental code can fail;
- supervise tests;
- keep a reliable stop path available;
- test away from stairs and drops;
- do not disable cliff protection for convenience;
- distinguish bumper recovery from cliff recovery;
- do not blindly reverse after a cliff event;
- fail safely when motion feedback disagrees with commanded motion.
Safety-critical behavior should be explicit and testable.
9. Development style
Prefer small, reviewable changes.
Do not mix unrelated changes such as:
- hardware protocol changes;
- SLAM changes;
- navigation tuning;
- UI changes;
inside the same commit unless the change genuinely spans those layers.
Recommended workflow
1. reproduce a problem
2. identify one hypothesis
3. change one subsystem
4. build / test
5. run a supervised hardware test if required
6. inspect logs
7. commit the validated change
Avoid broad parameter tuning while fixing a logic bug.
10. Rust checks
For Rust components, prefer running:
cargo fmt --check
cargo test
cargo build --release
Use cargo clippy when appropriate.
Do not silence warnings by default if the warning points to a real design issue.
11. Public repository hygiene
This repository is intended to be public.
Never commit:
- Wi-Fi credentials;
- passwords;
- private keys;
- API tokens;
- private infrastructure credentials;
- NAND dumps;
- device partitions containing secrets;
- deployment-specific secrets;
- private maps or logs containing sensitive data;
- generated binaries unless intentionally published as release artifacts.
Prefer example configuration files over real deployment configuration.
Use placeholders such as:
192.0.2.10
robot.local
server.local
instead of private infrastructure addresses in public documentation.
12. Git and upstream workflow
Recommended remote model:
origin -> Enuxia public repository
upstream -> codetiger/VacuumTiger
Do not force-push rewritten upstream history into the public Enuxia repository without a very strong reason.
When useful, upstream changes may be reviewed and selectively integrated.
Do not blindly overwrite Enuxia-modified files with upstream versions.
13. Legacy navigator policy
The current Dhruva navigation stack has been useful for validation and debugging, but it has known architectural limits.
Do not treat the current Navigator behavior as the long-term design.
In particular, avoid adding another local patch solely to preserve a design where:
frontier
-> global path
-> direct waypoint controller
-> timed escape
-> global replan
New work should move toward Navigation V2:
goal
-> global planner
-> local costmap
-> local planner
-> measured recovery
A legacy fix is still acceptable when required for:
- safety;
- data integrity;
- regression prevention;
- preserving the validated baseline;
- enabling migration to Navigation V2.
14. SLAM invariants
Be careful when changing pose-graph or submap code.
Previously observed failure class:
pose graph corrects keyframes/current pose
but submap origins remain in old geometry
This can make the corrected robot pose inconsistent with the rebuilt occupancy grid.
Any future optimization change must consider:
- current pose;
- keyframes;
- submap origins;
- global map invalidation/rebuild;
- active navigation path invalidation.
Do not update only one representation of geometry.
15. Bumper observations
Bumper contacts are useful perception data.
A contact should not exist only as a transient navigation event.
Where appropriate:
- record contact position;
- persist it into the active local mapping representation;
- expose it to local obstacle avoidance;
- deduplicate repeated nearby contacts;
- allow repeated contact history to influence navigation decisions.
Do not let a global-map rebuild silently erase meaningful contact observations.
16. Unknown space
Current design intent:
UNKNOWN = not traversable by the robot center
But UNKNOWN should not necessarily be treated identically to a confirmed physical obstacle for every inflation operation.
Keep the distinction between:
- unknown;
- free;
- occupied / physical obstacle.
This distinction is important for frontier approach planning.
17. Exploration targets
A frontier cell is not necessarily a valid robot-center goal.
Prefer:
unknown region
|
frontier boundary
|
safe approach pose in known free space
The approach pose may include orientation toward the unknown region.
Avoid sending the robot center directly onto unknown cells.
18. Testing philosophy
A robotics feature is not considered validated because it worked once.
Create repeatable physical scenarios.
Important test cases include:
Bed / furniture leg
Expected:
- obstacle detected;
- no repeated charging into the same obstacle;
- local avoidance or clean abandonment.
Soft low obstacle
Expected:
- bumper observation persists;
- measured backup;
- repeated contact strengthens avoidance.
Rug / traction problem
Expected:
- commanded motion without encoder progress is recognized;
- recovery does not loop forever.
Narrow passage
Expected:
- robot footprint respected;
- sufficient clearance.
Dynamic obstacle
Expected:
- local planner stops or avoids;
- global replan only when necessary.
Cliff
Expected:
- immediate stop;
- no unsafe blind reverse;
- persistent forbidden region where appropriate.
19. Public communication
Describe Enuxia Vacuum as:
An independent open-source fork of VacuumTiger developed by Enuxia.
Do not describe the repository as if it were created from scratch.
At the same time, do not frame Enuxia Vacuum as a passive mirror.
The project now has its own:
- validated hardware baseline;
- technical decisions;
- architecture;
- development roadmap;
- navigation redesign;
- future cleaning and application layers.
Use ATTRIBUTION.md for provenance details.
20. Before submitting a change
Check:
[ ] Does this change respect subsystem boundaries?
[ ] Does it preserve hardware safety?
[ ] Does it expose secrets or private infrastructure?
[ ] Does it regress validated M6 Pro behavior?
[ ] Does it add another legacy navigation workaround unnecessarily?
[ ] Are tests/builds passing?
[ ] Is the commit focused?
[ ] Does public documentation remain accurate?
When in doubt, prefer a smaller change with a measurable test.