-
Notifications
You must be signed in to change notification settings - Fork 64
Add Q10 VacuumTrait Test Scripts #758
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
lboue
wants to merge
3
commits into
Python-roborock:main
Choose a base branch
from
lboue:test-q10-vacuum-trait
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,194 @@ | ||
| # Q10 VacuumTrait Test Scripts | ||
|
|
||
| This directory contains test scripts for the Q10 VacuumTrait functionality added in [PR #754](https://github.com/Python-roborock/python-roborock/pull/754). | ||
|
|
||
| ## Scripts | ||
|
|
||
| ### run_q10_simple.py | ||
| Interactive test script with detailed debug information. This script: | ||
| - Shows comprehensive device information | ||
| - Lists all available property APIs | ||
| - Provides an interactive menu to test vacuum commands | ||
| - Includes error handling and detailed output | ||
|
|
||
| **Use this script when:** | ||
| - You want to verify your device supports Q10 properties | ||
| - You need to debug connection or API issues | ||
| - You want detailed information about what's happening | ||
|
|
||
| ### run_q10_vacuum.py | ||
| Basic test script for Q10 vacuum commands. A simpler version focused on testing the vacuum trait. | ||
|
|
||
| ### run_q10_advanced.py (NEW!) | ||
| Advanced test suite with complex features and detailed diagnostics: | ||
| - Tests multiple cleaning modes (standard, area, fast map) | ||
| - Device status monitoring and diagnostics | ||
| - Structured test suite with multiple test categories | ||
| - Interactive menu for manual command testing | ||
| - Full test suite execution | ||
|
|
||
| **Use this script when:** | ||
| - You want to test advanced cleaning modes | ||
| - You need comprehensive diagnostics | ||
| - You want to verify all VacuumTrait features | ||
| - You're developing or debugging Q10 device support | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Quick Start | ||
|
|
||
| 1. Install the package in development mode: | ||
| ```bash | ||
| python3 -m venv venv | ||
| source venv/bin/activate | ||
| pip install -e . | ||
| ``` | ||
|
|
||
| 2. Run a test script: | ||
| ```bash | ||
| # Simple script with debugging | ||
| python examples/Q10/run_q10_simple.py | ||
|
|
||
| # Basic script (minimal output) | ||
| python examples/Q10/run_q10_vacuum.py | ||
|
|
||
| # Advanced script with diagnostics | ||
| python examples/Q10/run_q10_advanced.py | ||
| ``` | ||
|
|
||
| 3. On first run, you'll be prompted to log in: | ||
| - Enter your Roborock account email | ||
| - A code will be sent to your email | ||
| - Enter the code to complete authentication | ||
| - Credentials are cached for future runs in `~/.cache/roborock-user-params.pkl` | ||
|
|
||
| ### What Each Script Does | ||
|
|
||
| #### test_q10_simple.py | ||
| ```bash | ||
| $ python examples/Q10/run_q10_simple.py | ||
| 📱 Found 1 device(s) | ||
| Device 1: Roborock Q10 S5+ | ||
| ✅ Using device: Roborock Q10 S5+ | ||
| ✅ Device has Q10 properties! | ||
| ✅ Vacuum trait found: <roborock.devices.traits.b01.q10.vacuum.VacuumTrait ...> | ||
| ``` | ||
| - Best for: Verifying device setup and API availability | ||
| - Features: Full device diagnostics and comprehensive menu | ||
|
|
||
| #### test_q10_vacuum.py | ||
| ```bash | ||
| $ python examples/Q10/run_q10_vacuum.py | ||
| 📱 Found 1 device(s) | ||
| 1. Roborock Q10 S5+ (roborock.vacuum.ss07) | ||
| ✅ Using device: Roborock Q10 S5+ | ||
| ``` | ||
| - Best for: Quick testing and command execution | ||
| - Features: Minimal output, clean interface | ||
|
|
||
| #### test_q10_advanced.py | ||
| ```bash | ||
| $ python examples/Q10/run_q10_advanced.py | ||
| [Main Menu] | ||
| 1. Run basic commands test | ||
| 2. Test advanced features | ||
| 3. Check device status | ||
| 4. Interactive menu | ||
| 5. Run all tests | ||
| ``` | ||
| - Best for: Comprehensive testing and development | ||
| - Features: Advanced modes, diagnostics, safety confirmations | ||
|
|
||
| ## Available Commands | ||
|
|
||
| The VacuumTrait provides these commands: | ||
|
|
||
| - **Start cleaning** - Initiates a full cleaning cycle | ||
| - **Pause cleaning** - Pauses the current cleaning operation | ||
| - **Resume cleaning** - Resumes a paused cleaning operation | ||
| - **Stop cleaning** - Stops the cleaning operation completely | ||
| - **Return to dock** - Sends the robot back to its charging dock | ||
|
|
||
| ### Advanced Cleaning Modes | ||
|
|
||
| Additional cleaning modes can be tested with `test_q10_advanced.py` (option 2): | ||
|
|
||
| - **Standard cleaning (cmd=1)** - Full cleaning cycle | ||
| - **Electoral/Area cleaning (cmd=2)** - Clean specific areas/zones | ||
| - **Fast map creation (cmd=4)** - Quickly generate room map | ||
| - ⚠️ **Warning**: This will start the robot moving! | ||
| - Requires explicit confirmation before execution | ||
|
|
||
| ### Device Status Information | ||
|
|
||
| The `test_q10_advanced.py` script (option 3) provides: | ||
|
|
||
| - **Connected**: Whether device is connected to Roborock services | ||
| - **Local connected**: Whether device is reachable on your local network | ||
| - `True` = Direct local connection (LAN/WiFi) | ||
| - `False` = Cloud connection via Roborock servers | ||
| - **Available APIs**: | ||
| - `Command API` = Low-level command interface | ||
| - `Vacuum Trait` = High-level vacuum control interface | ||
|
|
||
| ## Supported Devices | ||
|
|
||
| These scripts are designed for Roborock Q10 devices that support the B01 Q10 protocol. The script will automatically detect if your device has the required `b01_q10_properties` API. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| ### Device Issues | ||
|
|
||
| **"This device doesn't have Q10 properties"** | ||
| - Your device may not be a Q10 model | ||
| - Check the device model shown in the output | ||
| - The device might use a different API (v1_properties, b01_q7_properties, etc.) | ||
| - Supported models: Roborock Q10 Series and compatible devices | ||
|
|
||
| **Commands not working** | ||
| - Ensure device is powered on and connected | ||
| - Check that your account has proper permissions | ||
| - Try stopping any active cleaning cycle first | ||
| - Verify device is online in Roborock app | ||
|
|
||
| ### Authentication Issues | ||
|
|
||
| **"Code login failed"** | ||
| - Ensure you entered the code correctly | ||
| - Codes expire after a few minutes - request a new one | ||
| - Check your email spam folder for the code | ||
|
|
||
| **"No cached login data found"** | ||
| - Delete cached credentials: `rm ~/.cache/roborock-user-params.pkl` | ||
| - Try logging in again with fresh credentials | ||
| - Verify your email and password are correct | ||
|
|
||
| ### Connection Issues | ||
|
|
||
| **Commands sent but no response** | ||
| - Ensure device is online and connected to the internet | ||
| - Check if your WiFi is stable | ||
| - Try the device in the official Roborock app first | ||
| - Verify the robot can reach Roborock servers | ||
|
|
||
| **"Local connected: False"** | ||
| - This is normal - device is using cloud connection | ||
| - Commands may take a moment longer | ||
| - Both local and cloud connections work fine | ||
| - If you need local connection, configure device on same network | ||
|
|
||
| ## Related Documentation | ||
|
|
||
| - [PR #754: Add VacuumTrait to q10 devices](https://github.com/Python-roborock/python-roborock/pull/754) | ||
| - [PR #758: Add Q10 VacuumTrait Test Scripts](https://github.com/Python-roborock/python-roborock/pull/758) | ||
| - [Main example script](../example.py) | ||
| - [Supported Features](../../SUPPORTED_FEATURES.md) | ||
| - [Device Manager Documentation](../../roborock/devices/README.md) | ||
|
|
||
| ## Testing Status | ||
|
|
||
| ✅ **Successfully tested with:** | ||
| - Device: Roborock Q10 S5+ (`roborock.vacuum.ss07`) | ||
| - All basic commands working (start, pause, resume, stop, return to dock) | ||
| - Advanced modes available for testing | ||
| - Cloud and local connection modes supported | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The section headers refer to files as "test_q10_simple.py", "test_q10_vacuum.py", and "test_q10_advanced.py", but the actual files are named "run_q10_simple.py", "run_q10_vacuum.py", and "run_q10_advanced.py". Update all references in the README to use "run_q10_" prefix instead of "test_q10_" to match the actual filenames.