diff --git a/commit_msg.txt b/commit_msg.txt new file mode 100644 index 00000000..26cb3b0a --- /dev/null +++ b/commit_msg.txt @@ -0,0 +1 @@ +docs: add progress tracking for Protocol 3.5 implementation diff --git a/progress.txt b/progress.txt new file mode 100644 index 00000000..f6175632 --- /dev/null +++ b/progress.txt @@ -0,0 +1,47 @@ +# Protocol 3.5 Implementation Progress + +## Session: 2026-01-06 + +### Completed This Session + +1. **Protocol 3.5 Cipher Implementation** (PROTO-001 partial) + - Added `is_gcm_mode` property to TuyaCipher + - Added `generate_iv()` for 12-byte random IV generation + - Added `encrypt_gcm()` method for AES-GCM encryption + - Added `decrypt_gcm()` method for AES-GCM decryption + - 12 tests passing for cipher functionality + +2. **Protocol 3.5 Message Format** (PROTO-001 partial) + - Added constants: MAGIC_PREFIX_35 (0x6699), MAGIC_SUFFIX_35 (0x9966) + - Added MESSAGE_PREFIX_FORMAT_35 and MESSAGE_SUFFIX_FORMAT_35 + - Updated `Message.to_bytes()` to detect v3.5 and use GCM format + - Added `Message._to_bytes_v35()` for v3.5 message serialization + - Updated `Message.from_bytes()` to detect 0x6699 prefix + - Added `Message._from_bytes_v35()` for v3.5 message parsing + - 11 tests passing for message format + +### Test Results +- 276 total tests passing +- 23 new tests for Protocol 3.5 +- All lint and type-check passing + +### What Remains for PROTO-001 +- Session key negotiation (3-way handshake) +- Auto-detection of Protocol 3.5 devices +- Integration with TuyaDevice connection flow +- Testing with real Protocol 3.5 devices + +### Next Steps +1. Implement session key negotiation for Protocol 3.5 +2. Update TuyaDevice to handle v3.5 connection handshake +3. Add auto-detection based on device response +4. Test with actual Protocol 3.5 vacuum models + +### Branch +- Working on: `feat/protocol-35-support` +- Base: `main` + +### Files Modified +- `custom_components/robovac/tuyalocalapi.py` - Core Protocol 3.5 implementation +- `tests/test_vacuum/test_protocol_35_cipher.py` - Cipher tests (NEW) +- `tests/test_vacuum/test_protocol_35_message.py` - Message format tests (NEW) diff --git a/site_docs/adding-new-vacuum.md b/site_docs/adding-new-vacuum.md new file mode 100644 index 00000000..6f13041e --- /dev/null +++ b/site_docs/adding-new-vacuum.md @@ -0,0 +1,144 @@ +# Adding a New Vacuum Model + +## Quick Start: Try an Existing Model First + +**Before creating a new model file**, check if a similar model already works: + +1. Look at the [Supported Models](supported-models.md) page +2. Find a model from the **same series** (e.g., G30, X8, L35) +3. Try configuring your vacuum using that model's settings + +Models in the same series often share identical DPS codes. If basic functions +work (start, stop, battery), you may not need a new model file at all! + +## When You Need a New Model + +Create a new model file only if: + +- No existing model from your series works +- Your vacuum has different DPS codes than similar models +- You want to add features not in the existing model + +## Three Simple Steps + +### Step 1: Copy a Similar Model + +Find the most similar model in `custom_components/robovac/vacuums/` and copy it: + +```bash +cp T2250.py T2XXX.py +``` + +Edit the file: + +- Change the class name to match your model (e.g., `T2XXX`) +- Update the docstring with your model name +- Adjust DPS codes if needed (see [Finding DPS Codes](#finding-dps-codes)) + +### Step 2: Register Your Model + +Edit `custom_components/robovac/vacuums/__init__.py`: + +```python +from .T2XXX import T2XXX + +ROBOVAC_MODELS: Dict[str, Type[RobovacModelDetails]] = { + # ... existing models ... + "T2XXX": T2XXX, +} +``` + +### Step 3: Test It + +1. Restart Home Assistant +2. Add your vacuum using the new model +3. Test basic functions: start, stop, return home, battery level + +## Finding DPS Codes + +If your vacuum uses different codes than similar models: + +- **Enable debug logging** in Home Assistant to see raw DPS values +- **Monitor network traffic** between the vacuum and Eufy app +- **Check the Tuya IoT Platform** if you have developer access + +--- + +## Reference + +### Commands Reference + +| Command | Typical Code | Description | +|---------------|--------------|----------------| +| `START_PAUSE` | 2 | Start or pause | +| `DIRECTION` | 3 | Manual control | +| `MODE` | 5 | Cleaning mode | +| `STATUS` | 15 | Current status | +| `RETURN_HOME` | 101 | Go to dock | +| `FAN_SPEED` | 102 | Suction level | +| `LOCATE` | 103 | Find vacuum | +| `BATTERY` | 104 | Battery level | +| `ERROR` | 106 | Error codes | + +**Note**: Codes vary by model. Newer models (protocol 3.4+) often use different +codes (e.g., 152, 153, 158). + +### Complete Example + +```python +"""G30 (T2250)""" +from homeassistant.components.vacuum import VacuumEntityFeature +from .base import RoboVacEntityFeature, RobovacCommand, RobovacModelDetails + + +class T2250(RobovacModelDetails): + homeassistant_features = ( + VacuumEntityFeature.CLEAN_SPOT + | VacuumEntityFeature.FAN_SPEED + | VacuumEntityFeature.LOCATE + | VacuumEntityFeature.PAUSE + | VacuumEntityFeature.RETURN_HOME + | VacuumEntityFeature.SEND_COMMAND + | VacuumEntityFeature.START + | VacuumEntityFeature.STATE + | VacuumEntityFeature.STOP + ) + robovac_features = ( + RoboVacEntityFeature.CLEANING_TIME + | RoboVacEntityFeature.CLEANING_AREA + | RoboVacEntityFeature.DO_NOT_DISTURB + | RoboVacEntityFeature.AUTO_RETURN + ) + commands = { + RobovacCommand.START_PAUSE: {"code": 2}, + RobovacCommand.MODE: { + "code": 5, + "values": { + "auto": "Auto", + "spot": "Spot", + "edge": "Edge", + }, + }, + RobovacCommand.STATUS: {"code": 15}, + RobovacCommand.RETURN_HOME: {"code": 101}, + RobovacCommand.FAN_SPEED: { + "code": 102, + "values": { + "standard": "Standard", + "turbo": "Turbo", + "max": "Max", + }, + }, + RobovacCommand.LOCATE: {"code": 103}, + RobovacCommand.BATTERY: {"code": 104}, + RobovacCommand.ERROR: {"code": 106}, + } +``` + +## Submitting Your Model + +1. Fork the repository +2. Create a branch: `git checkout -b feat/add-t2xxx-support` +3. Add your model file +4. Run `task lint` and `task test` +5. Submit a pull request diff --git a/site_docs/configuration.md b/site_docs/configuration.md index a63aded8..947ae952 100644 --- a/site_docs/configuration.md +++ b/site_docs/configuration.md @@ -17,44 +17,8 @@ You'll need the following information to configure your vacuum: ## Supported Models -The following Eufy RoboVac models are currently supported: - -- **T1250**: RoboVac G40 -- **T2080**: RoboVac G40 Hybrid -- **T2103**: RoboVac 11S -- **T2117**: RoboVac 35C -- **T2118**: RoboVac 30C -- **T2119**: RoboVac 11S Max -- **T2120**: RoboVac 15C -- **T2123**: RoboVac 25C -- **T2128**: RoboVac 15C Max -- **T2130**: RoboVac 30C Max -- **T2132**: RoboVac 25C Max -- **T2150**: RoboVac G10 Hybrid -- **T2181**: RoboVac G20 -- **T2190**: RoboVac G30 -- **T2192**: RoboVac G30 Edge -- **T2193**: RoboVac G30 Verge -- **T2194**: RoboVac L35 Hybrid -- **T2250**: RoboVac G30 -- **T2251**: RoboVac G30 Edge -- **T2252**: RoboVac G30 Verge -- **T2253**: RoboVac G30 Hybrid -- **T2254**: RoboVac G20 Hybrid -- **T2255**: RoboVac G35+ -- **T2259**: RoboVac G40+ -- **T2261**: RoboVac X8 -- **T2262**: RoboVac X8 Hybrid -- **T2267**: RoboVac LR30 Hybrid -- **T2268**: RoboVac LR30 Hybrid+ -- **T2270**: RoboVac G32 Pro -- **T2272**: RoboVac G20 -- **T2273**: RoboVac G30 -- **T2275**: RoboVac L35 Hybrid -- **T2276**: RoboVac L35 Hybrid+ -- **T2277**: RoboVac G40 Hybrid -- **T2278**: RoboVac G40+ -- **T2320**: RoboVac X8 Pro +See the full list of [Supported Models](supported-models.md) with protocol +versions and model series information. ## Finding Your Local Key diff --git a/site_docs/index.md b/site_docs/index.md index ec4b1f4c..de4239b6 100644 --- a/site_docs/index.md +++ b/site_docs/index.md @@ -33,6 +33,8 @@ See the full list in the [Configuration](configuration.md) section. - [Installation Guide](installation.md) - [Configuration](configuration.md) - [Troubleshooting](troubleshooting.md) +- [Supported Models](supported-models.md) +- [Adding a New Vacuum](adding-new-vacuum.md) - [GitHub Issues](https://github.com/damacus/robovac/issues) ## History & Credits diff --git a/site_docs/supported-models.md b/site_docs/supported-models.md new file mode 100644 index 00000000..64aed9ea --- /dev/null +++ b/site_docs/supported-models.md @@ -0,0 +1,92 @@ +# Supported Models + +This page lists all currently supported Eufy RoboVac models. + +## Model Compatibility Table + +| Model Code | Friendly Name | Protocol | +|------------|----------------------|----------| +| T1250 | RoboVac G40 | 3.3 | +| T2080 | RoboVac S1 Pro | 3.4 | +| T2103 | RoboVac 11S | 3.3 | +| T2117 | RoboVac 35C | 3.3 | +| T2118 | RoboVac 30C | 3.3 | +| T2119 | RoboVac 11S Max | 3.3 | +| T2120 | RoboVac 15C | 3.3 | +| T2123 | RoboVac 25C | 3.3 | +| T2128 | RoboVac 15C Max | 3.3 | +| T2130 | RoboVac 30C Max | 3.3 | +| T2132 | RoboVac 25C Max | 3.3 | +| T2150 | RoboVac G10 Hybrid | 3.3 | +| T2181 | RoboVac G20 | 3.3 | +| T2190 | RoboVac G30 | 3.3 | +| T2192 | RoboVac G30 Edge | 3.3 | +| T2193 | RoboVac G30 Verge | 3.3 | +| T2194 | RoboVac L35 Hybrid | 3.4 | +| T2250 | RoboVac G30 | 3.3 | +| T2251 | RoboVac G30 Edge | 3.3 | +| T2252 | RoboVac G30 Verge | 3.3 | +| T2253 | RoboVac G30 Hybrid | 3.3 | +| T2254 | RoboVac G20 Hybrid | 3.3 | +| T2255 | RoboVac G35+ | 3.3 | +| T2259 | RoboVac G40+ | 3.3 | +| T2261 | RoboVac X8 | 3.3 | +| T2262 | RoboVac X8 Hybrid | 3.3 | +| T2267 | RoboVac LR30 Hybrid | 3.4 | +| T2268 | RoboVac LR30 Hybrid+ | 3.4 | +| T2270 | RoboVac G32 Pro | 3.3 | +| T2272 | RoboVac G20 | 3.3 | +| T2273 | RoboVac G30 | 3.3 | +| T2275 | RoboVac L35 Hybrid | 3.4 | +| T2276 | RoboVac L35 Hybrid+ | 3.4 | +| T2277 | eufy Clean L60 SES | 3.4 | +| T2278 | RoboVac G40+ | 3.4 | +| T2280 | RoboVac G40 Hybrid+ | 3.4 | +| T2320 | RoboVac X8 Pro | 3.4 | + +## Model Series + +Models are grouped by series. If your model isn't listed but is from the same +series, it may work with an existing configuration. + +### G Series (Basic) + +- **G20**: T2181, T2254, T2272 +- **G30**: T2190, T2250, T2251, T2252, T2253, T2273 +- **G32**: T2270 +- **G35**: T2255 +- **G40**: T1250, T2259, T2277, T2278, T2280 + +### X Series (Premium) + +- **X8**: T2261, T2262, T2320 + +### L Series (Advanced) + +- **L35**: T2194, T2275, T2276 +- **LR30**: T2267, T2268 +- **L60**: T2277 + +### Classic Series + +- **11S**: T2103, T2119 +- **15C**: T2120, T2128 +- **25C**: T2123, T2132 +- **30C**: T2118, T2130 +- **35C**: T2117 + +### Hybrid Models + +- **G10 Hybrid**: T2150 +- **S1 Pro**: T2080 + +## Don't See Your Model? + +If your vacuum model isn't listed: + +1. **Check similar models** - Models in the same series often share the same + DPS codes +2. **Try an existing configuration** - Select a model from the same series and + test basic functions +3. **Contribute** - See [Adding a New Vacuum](adding-new-vacuum.md) to add + support for your model