diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..82cbb264 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,68 @@ +name: Documentation + +on: + push: + branches: [main] + paths: + - "site_docs/**" + - "zensical.toml" + - ".github/workflows/docs.yml" + - "README.md" + - "CHANGELOG.md" + - "LICENSE" + pull_request: + branches: [main] + paths: + - "site_docs/**" + - "zensical.toml" + - ".github/workflows/docs.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v5 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.x + + - name: Set up uv + uses: astral-sh/setup-uv@v5 + + - name: Install dependencies + run: uv pip install --system zensical + + - name: Build documentation + run: zensical build --clean + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: ./site + + deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index a64cc4d6..662bd059 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,6 @@ __pycache__/ .vscode/ *.swp *.swo + +# Zensical build output +site/ diff --git a/feature_list.json b/feature_list.json index 27476d2b..b9024bd8 100644 --- a/feature_list.json +++ b/feature_list.json @@ -1,32 +1,37 @@ { - "description": "RoboVac Feature List - Test cases organized by functional area", - "version": "1.0.0", - "updated": "2025-12-16", - "areas": [ - { - "name": "vacuum_models", - "file": "features/vacuum_models.json", - "count": 12 - }, - { - "name": "core_functionality", - "file": "features/core_functionality.json", - "count": 5 - }, - { - "name": "testing", - "file": "features/testing.json", - "count": 5 + "description": "RoboVac Feature List - Test cases organized by functional area", + "version": "1.0.0", + "updated": "2026-01-06", + "areas": [ + { + "name": "vacuum_models", + "file": "features/vacuum_models.json", + "count": 12 + }, + { + "name": "core_functionality", + "file": "features/core_functionality.json", + "count": 5 + }, + { + "name": "testing", + "file": "features/testing.json", + "count": 5 + }, + { + "name": "documentation", + "file": "features/documentation.json", + "count": 5 + } + ], + "summary": { + "total_features": 27, + "passing": 20, + "failing": 7, + "pass_rate": "74%", + "categories": { + "functional": 17, + "quality": 10 + } } - ], - "summary": { - "total_features": 22, - "passing": 16, - "failing": 6, - "pass_rate": "73%", - "categories": { - "functional": 17, - "quality": 5 - } - } -} +} \ No newline at end of file diff --git a/features/documentation.json b/features/documentation.json new file mode 100644 index 00000000..e35df0a2 --- /dev/null +++ b/features/documentation.json @@ -0,0 +1,62 @@ +[ + { + "id": "DOC-001", + "category": "quality", + "area": "documentation", + "description": "Zensical documentation site is configured", + "steps": [ + "Create zensical.toml configuration file", + "Configure site_name, docs_dir, and site_dir", + "Verify configuration is valid" + ], + "passes": true + }, + { + "id": "DOC-002", + "category": "quality", + "area": "documentation", + "description": "Documentation index page exists", + "steps": [ + "Create docs/index.md with project overview", + "Include installation instructions", + "Include quick start guide" + ], + "passes": true + }, + { + "id": "DOC-003", + "category": "quality", + "area": "documentation", + "description": "GitHub Pages deployment workflow exists", + "steps": [ + "Create .github/workflows/docs.yml", + "Configure GitHub Actions for Zensical build", + "Set up GitHub Pages deployment" + ], + "passes": true + }, + { + "id": "DOC-004", + "category": "quality", + "area": "documentation", + "description": "Documentation builds successfully", + "steps": [ + "Run zensical build --clean", + "Verify site directory is created", + "Check for build errors" + ], + "passes": false + }, + { + "id": "DOC-005", + "category": "quality", + "area": "documentation", + "description": "Navigation structure is defined", + "steps": [ + "Configure nav in zensical.toml", + "Verify all pages are accessible", + "Check navigation order" + ], + "passes": true + } +] diff --git a/site_docs/configuration.md b/site_docs/configuration.md new file mode 100644 index 00000000..bc8f7050 --- /dev/null +++ b/site_docs/configuration.md @@ -0,0 +1,37 @@ +# Configuration + +## Adding the Integration + +1. Go to **Settings** → **Devices & Services** +2. Click **Add Integration** +3. Search for "RoboVac" +4. Follow the configuration wizard + +## Required Information + +You'll need the following information to configure your vacuum: + +- **Device ID**: Your vacuum's unique identifier +- **Local Key**: The encryption key for local communication +- **IP Address**: Your vacuum's local IP address + +## Finding Your Local Key + +The local key can be obtained using various methods: + +1. **Tuya IoT Platform**: Register as a developer and link your device +2. **Third-party tools**: Use tools like `tuya-cli` to extract the key + +## Protocol Version + +Some vacuums require a specific protocol version: + +- **Protocol 3.3**: Most older models +- **Protocol 3.4**: Newer models with enhanced security +- **Protocol 3.5**: Latest models + +If you're unsure, start with 3.3 and adjust if needed. + +## Troubleshooting + +If you encounter issues, see the [Troubleshooting](troubleshooting.md) guide. diff --git a/site_docs/index.md b/site_docs/index.md new file mode 100644 index 00000000..00a390ee --- /dev/null +++ b/site_docs/index.md @@ -0,0 +1,36 @@ +# RoboVac + +Welcome to the RoboVac documentation! RoboVac is a Home Assistant custom +integration for Eufy RoboVac vacuum cleaners. + +## Features + +- **Local Control**: Control your vacuum without cloud dependency +- **Multiple Models**: Support for 30+ Eufy RoboVac models +- **Full Integration**: Start, stop, pause, return to base, and locate +- **Status Monitoring**: Battery level, cleaning status, and error reporting + +## Quick Start + +1. Install via HACS or manually +2. Add the integration in Home Assistant +3. Configure your vacuum's local key and device ID +4. Start cleaning! + +## Supported Models + +RoboVac supports a wide range of Eufy vacuum models including: + +- RoboVac G30 Series (T2250, T2251, T2252, T2253) +- RoboVac L35 Hybrid (T2194) +- RoboVac X8 Series (T2261, T2262) +- And many more... + +See the full list in the [Configuration](configuration.md) section. + +## Getting Help + +- [Installation Guide](installation.md) +- [Configuration](configuration.md) +- [Troubleshooting](troubleshooting.md) +- [GitHub Issues](https://github.com/damacus/robovac/issues) diff --git a/site_docs/installation.md b/site_docs/installation.md new file mode 100644 index 00000000..c1779b0b --- /dev/null +++ b/site_docs/installation.md @@ -0,0 +1,30 @@ +# Installation + +## Prerequisites + +- Home Assistant 2024.1.0 or later +- A Eufy RoboVac with local network access +- Your vacuum's local key and device ID + +## Installation via HACS (Recommended) + +1. Open HACS in Home Assistant +2. Click on "Integrations" +3. Click the three dots in the top right corner +4. Select "Custom repositories" +5. Add `https://github.com/damacus/robovac` as a custom repository +6. Select "Integration" as the category +7. Click "Add" +8. Search for "RoboVac" and install + +## Manual Installation + +1. Download the latest release from GitHub +2. Extract the `custom_components/robovac` folder +3. Copy it to your Home Assistant `custom_components` directory +4. Restart Home Assistant + +## Next Steps + +After installation, proceed to [Configuration](configuration.md) to set up +your vacuum. diff --git a/site_docs/troubleshooting.md b/site_docs/troubleshooting.md new file mode 100644 index 00000000..483d1328 --- /dev/null +++ b/site_docs/troubleshooting.md @@ -0,0 +1,53 @@ +# Troubleshooting + +## Common Issues + +### Vacuum Not Responding + +**Symptoms**: Commands are sent but the vacuum doesn't respond. + +**Solutions**: + +1. Verify the IP address is correct and reachable +2. Check that the local key is correct +3. Ensure the vacuum is on the same network as Home Assistant +4. Try a different protocol version + +### Invalid Local Key + +**Symptoms**: Authentication errors in the logs. + +**Solutions**: + +1. Re-extract the local key from the Tuya platform +2. Ensure no extra spaces or characters in the key +3. Verify the device ID matches + +### Connection Timeout + +**Symptoms**: Timeout errors when trying to connect. + +**Solutions**: + +1. Check your network connectivity +2. Verify the vacuum is powered on +3. Ensure no firewall is blocking the connection +4. Try restarting the vacuum + +### Wrong Protocol Version + +**Symptoms**: Decryption errors or garbled responses. + +**Solutions**: + +1. Try protocol version 3.4 instead of 3.3 +2. For newer models, try protocol 3.5 +3. Check the logs for specific error messages + +## Getting Help + +If you're still having issues: + +1. Check the [GitHub Issues](https://github.com/damacus/robovac/issues) +2. Enable debug logging and review the logs +3. Open a new issue with your logs and configuration diff --git a/zensical.toml b/zensical.toml new file mode 100644 index 00000000..3a3ede59 --- /dev/null +++ b/zensical.toml @@ -0,0 +1,11 @@ +[project] +site_name = "RoboVac Documentation" +docs_dir = "site_docs" +site_dir = "site" + +nav = [ + "index.md", + "installation.md", + "configuration.md", + "troubleshooting.md" +]