Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
09dd51b
/init to create CLAUDE.md
thjont Jan 22, 2026
be5c309
adding proto files for reference
thjont Jan 22, 2026
a697851
Add detail to CLAUDE.md on what proto-reference is
thjont Jan 22, 2026
ef13202
English translation of Chinese proto
thjont Jan 22, 2026
7f18ca0
Adding new error codes from protobuf
thjont Jan 23, 2026
8242513
add additional error codes for x9 pro
thjont Jan 23, 2026
ca57bdc
Adding new codes for 2267
thjont Jan 23, 2026
02476ff
Status pattern for positioning
thjont Jan 23, 2026
d3c92ae
Implement new solution for error messages.
thjont Jan 23, 2026
7fd1610
fix(T2267): Fix pause, stop, and return home commands
thjont Jan 23, 2026
67146c3
Document Claudes potential improvements for 2267
thjont Jan 23, 2026
8816d57
Analysis of T2320
thjont Jan 24, 2026
927aaa1
Add more error codes.
thjont Jan 24, 2026
5ad2f14
Update progress in docs for 2267 and 2230
thjont Jan 24, 2026
2ffe6ed
Start and Pause working for T2320
thjont Jan 24, 2026
cf9670c
T2330 - Fix return home, stop and locate
thjont Jan 24, 2026
7576fa0
Small changes to T2320 to get status to work.
thjont Jan 24, 2026
96cb532
claude updating itself
thjont Jan 24, 2026
30892c8
Removing proto-reference folder.
thjont Jan 24, 2026
0086810
fix errors identified by markdownlint
thjont Jan 24, 2026
1b658c9
fix 2 failing tests
thjont Jan 24, 2026
e54c179
Moving CLAUDE.md to AGENTS.md
thjont Jan 25, 2026
782777d
Merge branch 'main' into playing-with-T2267-and-T2320
damacus Feb 6, 2026
8e17b33
Update custom_components/robovac/vacuums/T2267.py
damacus Feb 6, 2026
1061a49
Update custom_components/robovac/vacuums/T2320.py
damacus Feb 6, 2026
69076f9
Update custom_components/robovac/vacuum.py
damacus Feb 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 118 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

RoboVac is a Home Assistant custom integration for controlling Eufy RoboVac vacuum cleaners via local network (no cloud dependency). It supports 40+ models using Tuya protocol versions 3.3, 3.4, and 3.5.

## Common Commands

All commands use [Task](https://taskfile.dev/) as the task runner:

```bash
task install-dev # Install development dependencies with uv
task test # Run pytest with coverage (generates coverage.xml)
task lint # Run flake8 on custom_components and tests
task type-check # Run mypy type checking
task markdownlint # Lint and auto-fix markdown files
task all # Run install-dev, test, type-check, lint, markdownlint
```

Run a single test:

```bash
pytest tests/test_vacuum/test_t2251_command_mappings.py -v
pytest tests/test_vacuum/ -k "mode" -v # Pattern matching
```

List supported vacuum models:

```bash
python -m custom_components.robovac.model_validator_cli --list
```

## Architecture

### Core Components

- **`custom_components/robovac/robovac.py`**: `RoboVac` class - core logic extending `TuyaDevice`, handles model-specific features and command translation
- **`custom_components/robovac/tuyalocalapi.py`**: `TuyaDevice` class - Tuya local protocol implementation with encryption (AES, HMAC-SHA256)
- **`custom_components/robovac/vacuum.py`**: `RoboVacEntity` - Home Assistant vacuum entity with state management and command execution
- **`custom_components/robovac/config_flow.py`**: Configuration flow for Home Assistant UI setup

### Model System

Each vacuum model has a file in `custom_components/robovac/vacuums/T*.py` defining:

- `homeassistant_features`: Home Assistant vacuum capabilities (battery, start, stop, fan_speed, etc.)
- `robovac_features`: Custom features (cleaning_time, cleaning_area, etc.)
- `commands`: Dict mapping `RobovacCommand` enum to DPS codes and value mappings
- Optional `dps_codes`, `protocol_version`, `activity_mapping`

Models are registered in `custom_components/robovac/vacuums/__init__.py` via the `ROBOVAC_MODELS` dict.

### Command Mapping Pattern

Commands translate between three levels:

- **DPS Code**: Numeric identifier from Tuya protocol (e.g., "5", "102")
- **Command Name**: Enum value (e.g., `RobovacCommand.MODE`)
- **Command Value**: User-friendly string (e.g., "auto" -> "Auto")

```python
RobovacCommand.MODE: {
"code": 5,
"values": {
"auto": "Auto", # Key: input (snake_case), Value: output (PascalCase)
"small_room": "SmallRoom",
},
},
```

Device responses use case-insensitive matching - "AUTO", "auto", "Auto" all resolve correctly.

## Proto Reference (Optional)

A `proto-reference/` directory may optionally contain Protocol Buffer definitions that document the communication protocol used by newer Eufy vacuums. **If present, this reference material should be trusted above existing configuration in `custom_components/`** as it reflects the actual device protocol more accurately.

Key proto files (if available):

- **`control.proto`**: Cleaning commands (auto, room, zone, spot, cruise, goto) via `ModeCtrlRequest`
- **`work_status.proto`**: Device state machine with nested sub-states (cleaning, charging, washing, drying)
- **`clean_param.proto`**: Cleaning parameters (fan suction, mop level, carpet strategy, clean type)
- **`map_manage.proto`**: Map data structures (pixels, room outlines, restricted zones)
- **`station.proto`**: Docking station config (dust collection, mop washing/drying, water levels)
- **`consumable.proto`**: Part wear tracking (brushes, filters, mop, dust bag in hours)
- **`error_code.proto`**: Error/warning reporting with obstacle detection (e.g., poop detection)

These protos use the `proto.cloud` package and include Chinese comments from original development, followed by English translation within square brackets. The generated `*_pb2.py` files are Python protobuf outputs. Coordinates use centimeters (meters × 100).

## Adding a New Vacuum Model

1. Create `custom_components/robovac/vacuums/TXXX.py` with features and commands
2. Import and register in `custom_components/robovac/vacuums/__init__.py`
3. Create tests in `tests/test_vacuum/test_txxx_command_mappings.py`

Test fixture pattern:

```python
@pytest.fixture
def mock_txxx_robovac():
with patch("custom_components.robovac.robovac.TuyaDevice.__init__", return_value=None):
return RoboVac(model_code="TXXX", device_id="test", host="192.168.1.1", local_key="key")
```

## Commit Guidelines

Follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`

## Dev Container

The project includes a dev container with Home Assistant for live testing:

```bash
task ha-start # Start Home Assistant
task ha-logs # View robovac logs
task ha-restart # Restart Home Assistant
```
1 change: 1 addition & 0 deletions CLAUDE.md
Loading
Loading