Control your Valetudo-powered robot vacuum with a game controller — now with real-time joystick input, async network commands, and a terminal-based UI (TUI) for visual feedback.
- 🎮 Smooth joystick control via PlayStation/Xbox controller
- ⚡ Toggle speed level (Circle)
- 🄀 Visualize joystick axes in real-time
- 🔊 Play test sound (Square)
- 🏠 Return to dock and quit (Triangle)
- 🧠 Async
aiohttpbackend for snappy control - 🔢 Terminal UI (TUI) built with
curses - ❌ Cooldown-based button debounce (no double actions)
- Python 3.8+
- A robot vacuum running Valetudo > 2025.05.0 (with
HighResolutionManualControlCapability) - A joystick/gamepad supported by pygame
aiohttp,pygame,curses(built-in on Linux/macOS)
pip install -r requirements.txt
# or individually
pip install aiohttp pygame| Button | Action |
|---|---|
| Left Stick | Move the robot |
| Circle | Cycle speed level |
| Square | Play test sound |
| Triangle | Dock robot and exit |
| X | Toggle Vaccuum |
- Connect your gamepad
- Edit
config.jsonand setvaletudo_urlto your robot's IP - Run:
python controller.py- Control the robot with the left stick. Use buttons as described above.
- Real-time joystick position bars
- Battery level of robot (polled every 5s)
- Current speed level
- Button guide
This repository includes a pytest-based test suite with stubs for pygame, curses, and network calls, so you can run tests without special hardware.
Install dependencies and run tests:
pip install -r requirements.txt
pip install pytest pytest-asyncio
pytest -qGitHub Actions runs the test suite on every push and pull request. See the status badge at the top of this README.
Workflow file: .github/workflows/ci.yml
It sets up Python and runs pytest. Tests use internal stubs for pygame, curses, and network calls, so the CI job does not need to install heavy dependencies.