enuxia-vacuum/README.md

# Enuxia Vacuum

**Open, local-first robotics stack for autonomous vacuum robots.**

Enuxia Vacuum is an independent open-source fork of [VacuumTiger](https://github.com/codetiger/VacuumTiger), now developed by **Enuxia** as a platform for fully local robot control, mapping, navigation and cleaning.

The project started from a practical goal: take commodity robot-vacuum hardware and turn it into a robot that can be understood, modified, self-hosted and improved without depending on a proprietary cloud.

Today, our primary development platform is the **Proscenic M6 Pro / 3irobotix CRL-200S**.

> The long-term goal is not merely to reproduce the factory firmware.  
> It is to build a cleaner, more modular and more capable robotics stack around the hardware.

---

## Why Enuxia Vacuum?

Most consumer robot vacuums are closed systems:

- proprietary firmware;
- vendor-controlled cloud services;
- undocumented hardware protocols;
- limited local APIs;
- difficult long-term maintenance;
- little room for experimentation.

Enuxia Vacuum takes the opposite approach:

- **local-first** — the robot can operate without a vendor cloud;
- **open** — hardware protocols and software architecture are inspectable;
- **modular** — hardware access, SLAM, navigation and UI are separated;
- **self-hostable** — high-level computation can run on your own Linux infrastructure;
- **hardware-aware** — the stack is built around real sensors, actuators and failure modes;
- **hackable** — the project is intended to be understood and extended.

---

## Current status

The CRL-200S / M6 Pro platform is already functional as a development robot.

| Area | Status |
|---|---|
| Root / recovery access | ✅ Validated |
| Low-level hardware control | ✅ Validated |
| Wheel encoders | ✅ Validated |
| IMU | ✅ Validated |
| Bumpers | ✅ Validated |
| Cliff sensors | ✅ Validated |
| Battery / charging telemetry | ✅ Validated |
| Vacuum / brushes | ✅ Validated |
| Delta-2D LiDAR | ✅ Decoded and corrected |
| GD32 cold-boot initialization | ✅ Fixed |
| Local sensor streaming | ✅ Operational |
| 2D SLAM | 🟡 Functional, still being consolidated |
| Global navigation | 🟡 Existing baseline |
| Navigation V2 | 🚧 In development |
| Local obstacle avoidance | 🚧 Planned / in development |
| Cleaning coverage planner | 📋 Planned |
| Docking | 📋 Planned |
| Local API | 📋 Planned |
| PWA / Android application | 📋 Planned |

---

## Architecture

The current architecture keeps the hardware-facing code on the robot while allowing heavier robotics workloads to run on a Linux machine on the local network.

```text
┌──────────────────────────────────────────────┐
│                  User layer                  │
│        PWA / Android / diagnostics           │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│               Mission Manager                │
│        map / clean / goto / dock             │
└──────────────────────┬───────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        ▼                             ▼
┌──────────────────┐         ┌──────────────────┐
│    Exploration   │         │ Cleaning Planner │
│ frontier / info  │         │ coverage / rooms │
└────────┬─────────┘         └────────┬─────────┘
         └──────────────┬─────────────┘
                        ▼
               ┌─────────────────┐
               │ Global Planner  │
               │     Theta*      │
               └────────┬────────┘
                        ▼
               ┌─────────────────┐
               │  Local Planner  │
               │      DWA        │
               └────────┬────────┘
                        ▼
               ┌─────────────────┐
               │    SangamIO     │
               │ hardware layer  │
               └────────┬────────┘
                        ▼
               ┌─────────────────┐
               │      Robot      │
               └─────────────────┘
```

A layered local costmap is planned between perception and the local planner:

```text
SLAM static map
Live LiDAR
Bumper contacts
Cliff sensors
No-go zones
Robot footprint
        │
        ▼
 Layered Costmap
        │
        ▼
  Local Planner
```

---

## Repository layout

```text
enuxia-vacuum/
├── sangam-io/       # Hardware abstraction and robot drivers
├── dhruva-slam/     # SLAM, mapping and current navigation stack
├── dhruva-nav/      # Upstream navigation research / reusable building blocks
├── drishti/         # Engineering and diagnostic UI
├── vastu-slam/      # SLAM library
├── protocol-mitm/   # Reverse-engineering / protocol tooling
└── slam-test/       # Integration and algorithm tests
```

The internal component names are intentionally preserved during the first stages of the fork. Renaming them all at once would make upstream comparison and regression analysis unnecessarily difficult.

---

## Primary hardware: Proscenic M6 Pro / CRL-200S

The current development target uses:

- **SoC:** Allwinner A33
- **MCU:** GD32F103
- **LiDAR:** Delta-2D
- **MCU UART:** `/dev/ttyS3`
- **LiDAR UART:** `/dev/ttyS1`
- **Linux:** Tina Linux / OpenWrt based userspace

The hardware driver exposes the robot through SangamIO, which provides a robot-agnostic control and telemetry interface to higher-level software.

### Validated CRL-200S work

The Enuxia fork includes additional work validated on real M6 Pro hardware, including:

- GD32 initialization reliable after cold boot;
- corrected Delta-2D angular decoding;
- stable full-revolution LiDAR scans;
- wheel / bumper / cliff / battery telemetry;
- drive, vacuum and brush control;
- persistent bumper observations in SLAM;
- SLAM pose-graph and submap correction work;
- exploration and navigation failure handling improvements.

---

## SangamIO

[`sangam-io/`](sangam-io/) is the hardware abstraction layer.

It is responsible for:

- robot-specific protocol handling;
- sensor acquisition;
- wheel commands;
- actuators;
- LiDAR control;
- telemetry streaming;
- hardware-independent commands for upper layers.

High-level navigation code should not need to understand the GD32 protocol directly.

See [sangam-io/README.md](sangam-io/README.md).

---

## DhruvaSLAM

[`dhruva-slam/`](dhruva-slam/) provides the current mapping and localization stack.

It includes:

- wheel odometry;
- LiDAR preprocessing;
- scan matching;
- occupancy-grid mapping;
- submaps;
- loop closure;
- pose graph optimization;
- map streaming;
- the current navigation/exploration baseline.

The existing navigator is considered a **baseline**, not the final architecture.

See [dhruva-slam/README.md](dhruva-slam/README.md).

---

## Navigation V2

Navigation is the next major Enuxia development milestone.

The current architecture couples global planning, frontier exploration and recovery too tightly. Navigation V2 will separate these responsibilities.

Target design:

```text
Mission
  ↓
Goal
  ↓
Global planner (Theta*)
  ↓
Global path
  ↓
Local costmap
  ↓
Local planner (DWA)
  ↓
Velocity commands
  ↓
Progress / stuck detector
  ↓
Recovery manager
```

### Goals

Navigation V2 is intended to provide:

- real local obstacle avoidance;
- footprint-aware collision checking;
- dynamic obstacle handling;
- measured, encoder-based recovery;
- repeated-contact memory;
- robust stuck detection;
- independent global and local planning;
- clean separation between exploration and navigation.

A bumper contact must become information, not simply trigger a timed reverse command.

---

## Mapping vs cleaning

Mapping and cleaning are intentionally treated as two separate problems.

### Mapping

```text
unknown space
    ↓
frontier detection
    ↓
safe approach poses
    ↓
navigation
    ↓
map expansion
```

### Cleaning

Once a stable map exists:

```text
saved map
    ↓
room segmentation
    ↓
coverage planning
    ↓
cleaning lanes
    ↓
local obstacle avoidance
    ↓
return to dock
```

Future cleaning modes may include:

- whole-home cleaning;
- room cleaning;
- zone cleaning;
- spot cleaning;
- multiple passes;
- no-go / no-mop areas;
- multi-floor maps.

---

## Building

### SangamIO

```bash
cd sangam-io

rustup target add armv7-unknown-linux-musleabihf

cargo build --release \
  --target armv7-unknown-linux-musleabihf
```

Depending on your toolchain, an ARM cross-linker may be required.

### DhruvaSLAM

```bash
cd dhruva-slam

cargo test
cargo build --release
```

### Drishti

```bash
cd drishti

python -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
python drishti_ui.py --help
```

---

## Safety

This project controls physical hardware.

During development:

- supervise all motion tests;
- keep a reliable way to stop the robot;
- test away from stairs and drops;
- do not bypass cliff protection;
- do not run the factory hardware controller and SangamIO at the same time on platforms where they compete for the same hardware;
- expect experimental navigation code to fail.

Enuxia Vacuum is research and development software. It is not currently a safety-certified robotic system.

---

## Project origin

Enuxia Vacuum did **not** start from a blank repository.

It is derived from the open-source **VacuumTiger** project:

- upstream repository: `codetiger/VacuumTiger`
- original root copyright notice: Copyright © 2024 Harishankar Narayanan
- upstream history is intentionally preserved in this repository

The fork retains upstream code, history and applicable copyright/license notices while developing an independent technical direction under Enuxia.

We are grateful to the upstream project for the reverse-engineering and software foundation that made this work possible.

See [ATTRIBUTION.md](ATTRIBUTION.md) for details.

---

## License

This repository is a derivative work containing code from multiple upstream components.

The root `LICENSE` inherited from VacuumTiger is MIT. Some subprojects also declare MIT, Apache-2.0, or dual MIT/Apache-2.0 licensing in their own metadata.

**Applicable upstream notices and component-specific licenses must be preserved.**

Before packaging or redistributing binaries, review the license metadata of the components you are distributing.

---

## Enuxia

Enuxia develops local-first systems that connect software, infrastructure and physical hardware.

This project follows the same principle:

> **The machine should remain understandable, controllable and useful without depending on somebody else's cloud.**