Roborock RC

A browser-based remote control interface for the Roborock Z70 (Saros) robot vacuum, built with FastAPI and WebSockets.

Control your robot in real time from any browser — drive it around, trigger arm actions, and send it back to its dock.

Features

• Live remote control via keyboard or on-screen gamepad
• WebSocket-driven movement (velocity + angular speed)
• Arm grab/retract commands
• Return-to-dock button
• Two-step email verification support

---

Step-by-Step Installation

Step 1 — Install Python

Make sure you have Python 3.11 or newer installed.

• Windows: Download from python.org/downloads and run the installer.

  During install, check "Add Python to PATH" before clicking Install.

• macOS: brew install python (requires Homebrew), or download from python.org.
• Linux: sudo apt install python3 python3-pip (Ubuntu/Debian)

Verify it worked:

python --version

You should see Python 3.11.x or higher.

---

Step 2 — Install Git

• Windows: Download from git-scm.com and run the installer.
• macOS: brew install git or it may already be installed.
• Linux: sudo apt install git

Verify:

git --version

---

Step 3 — Clone the Repository

git clone https://github.com/amitamit10/roborock-rc.git
cd roborock-rc

---

Step 4 — (Recommended) Create a Virtual Environment

This keeps the project's dependencies isolated from the rest of your system.

python -m venv venv

Activate it:

• Windows:

  venv\Scripts\activate

• macOS / Linux:

  source venv/bin/activate

You should see (venv) appear at the start of your terminal prompt.

---

Step 5 — Install Dependencies

pip install -r requirements.txt

This installs FastAPI, the Roborock library, and everything else the app needs.

---

Step 6 — Configure Your Credentials

Copy the example env file:

• Windows:

  copy .env.example .env

• macOS / Linux:

  cp .env.example .env

Open the .env file in any text editor and fill in your Roborock account details:

ROBOROCK_EMAIL=your@email.com
ROBOROCK_PASSWORD=yourpassword

Your credentials are stored locally only and are never uploaded to GitHub (the .env file is gitignored).

---

Step 7 — Run the Server

python app.py

You should see output like:

INFO  roborock  Connected to Saros Z70
INFO  roborock  Ready — connected to: Saros Z70

Two-step verification: If your Roborock account has 2FA enabled, the server will pause and ask you to enter a code sent to your email. Type it in the terminal and press Enter.

---

Step 8 — Open the Controller

Open your browser and go to:

http://localhost:8080

You should see the RC controller interface. Your robot is ready to drive.

---

Controls

Key / Button	Action
W / Up arrow	Move forward
S / Down arrow	Move backward
A / Left arrow	Turn left
D / Right arrow	Turn right
Grab button	Trigger arm grab
Retract button	Retract arm
Dock button	Return to charging dock

---

Running Tests

pytest

---

Troubleshooting

"No Roborock devices found" — Make sure your robot is connected to the Roborock app and your account credentials in .env are correct.

"ModuleNotFoundError" — Make sure you activated the virtual environment (Step 4) before running.

Port already in use — Another process is using port 8080. You can change the port in app.py on the last line: port=8080.