You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Two machines (one to run the server and one to do the onboarding)
6
+
- Python (I recommend installing [uv](https://docs.astral.sh/uv/getting-started/installation/))
7
+
- Two machines — one to run the server and one to do the onboarding
8
8
- A domain name that you own
9
-
- A machine that can host this with the following ports exposed (INTERNALLY in YOUR network):
10
-
```
11
-
443
12
-
8883
13
-
```
9
+
- A machine that can host this with ports `443` and `8883` exposed internally on your network
10
+
11
+
## Network Setup
12
+
13
+
1. Pick a URL for this application. It needs to be a subdomain of a domain you own, and it **must** start with `api-`. It does NOT need to be accessible outside your network — in fact, I strongly recommend you keep it internal only for now.
14
+
15
+
For example, if you own `example.com`, I'd recommend `api-roborock.example.com`. Throughout the rest of the docs we'll refer to this as the **FQDN**. If you follow this format, you can just replace `example.com` with your real domain wherever you see it.
16
+
17
+
2. Your network **must** handle its own DNS for the network the vacuum connects to. If it uses an external DNS server like `8.8.8.8`, this will not work.
18
+
19
+
3. Create DNS records pointing to your server's local IP address for both `api-roborock.example.com` and `mqtt-roborock.example.com`.
uv run --no-project src/roborock_local_server/configure.py
37
43
```
38
44
39
45
The wizard asks only for:
40
46
41
-
- your `stack_fqdn` (this is your URL for your server. It MUST start with 'api-')
47
+
- your `stack_fqdn` (the URL for your server — must start with `api-`)
42
48
- embedded MQTT or your own broker
43
49
- whether to use Cloudflare DNS-01 auto-renew
44
50
- your admin password
45
51
46
-
It then writes `config.toml` for you, generates `admin.password_hash`, generates`admin.session_secret`, and if you chose Cloudflare it also writes `secrets/cloudflare_token`.
52
+
It then writes `config.toml`, generates `admin.password_hash` and`admin.session_secret`, and if you chose Cloudflare it also writes `secrets/cloudflare_token`.
47
53
48
54
5. If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack. See: [Custom MQTT](#Custom_mqtt)
49
55
50
56
6. If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`. See: [Custom cert](#custom_cert)
51
57
52
-
7. Decide on your url. it must start with 'api-'. Set the DNS record on your network to resolve your url to your server.
58
+
7. Start the container:
59
+
60
+
```bash
61
+
docker-compose up -d --build
62
+
```
53
63
54
-
If your server is 'api-roborock.example.com', you should set the following DNS records to resolve to your server ip:
55
-
'api-roborock.example.com'
56
-
'mqtt-roborock.example.com'
64
+
8. Go to the admin dashboard: https://api-roborock.example.com/admin (Replace with your real domain.)
57
65
58
-
7. Now you can start the container by running:
59
-
`docker-compose up -d --build`
66
+
9. Import your data from the cloud so things like routines and rooms will work. Enter your email in under cloud import, then hit send code. Once the code is returned enter the code and hit fetch data.
60
67
61
-
8.
68
+
Please look at Onboarding for how to onboard a new device
You can follow this guide whenever you setup a vacuum. If it is a new vacuum, I'd recommend first setting it up on the Roborock app with the official servers and then go through the onboarding here. That way you can be sure your app has installed all of the artifacts it needs for that vacuum and you can check that it is up to date on it's firmware.
4
+
5
+
1. You need to go through this cycle 2-4 times. I recommend having the admin dashboard up (https://api-roborock.example.com)
6
+
7
+
2. On a machine that is NOT running the server, you need to run the onboarding script found in this repo.
8
+
9
+
You need to determine the following parameters:
10
+
11
+
server: This is your server WITHOUT the api- and it should end with a '/' i.e. roborock.example.com/ The onboarding script should help you out if you make a mistake.
12
+
13
+
ssid: This is the name of the network you want the vacuum to connect to, if there is a space make sure to surround it in quotes.
14
+
15
+
password: This is your networks password
16
+
17
+
cst: This is your POSIX timezone. Here are some common ones:
18
+
19
+
Eastern Time (US): EST5EDT,M3.2.0,M11.1.0
20
+
21
+
Central Time (US): CST6CDT,M3.2.0,M11.1.0
22
+
23
+
Mountain Time (US - with DST): MST7MDT,M3.2.0,M11.1.0
24
+
25
+
Mountain Time (Arizona - no DST): MST7
26
+
27
+
Pacific Time (US): PST8PDT,M3.2.0,M11.1.0
28
+
29
+
London (UK): GMT0BST,M3.5.0,M10.5.0
30
+
31
+
Central Europe (Paris/Berlin): CET-1CEST,M3.5.0,M10.5.0
32
+
33
+
India (No DST): IST-5:30
34
+
35
+
Japan (No DST): JST-9
36
+
37
+
country-domain: Two letter key for your country domain, I'm not sure how this is utilized by the vacuum but 'us' is the valid key for the USA.
38
+
39
+
timezone: IANA Time Zone Database identifier i.e. 'America/New_York"
40
+
41
+
42
+
Example command:
43
+
`uv run onboarding.py --server roborock.example.com/ --ssid "My Wifi" --password "Password123" --cst EST5EDT,M3.2.0,M11.1.0 --timezone "America/New_York"`
44
+
45
+
3. The script will walk you through the onboarding process. But you need to Reset the vacuums wifi (You can do this by holding the two buttons on your dock if your vacuum has just two buttons) or by holding the left and right button if your vacuum has three buttons. Hold for 3-5 seconds until you hear "Resetting Wifi". You can find specific instructions for your vacuum by Googling: "How to reset wifi Roborock ..."
46
+
47
+
4. Connect to your vacuum's wifi SSID on a computer that is NOT running the server. Give it a second and then continue on the script.
48
+
49
+
5. You will hear the vacuum say 'Connecting to Wifi - Stand by"
50
+
51
+
6. Check the UI and wait for the "Num Query samples" count to go up by 1. Once it goes up, you can do another cycle on the onboarding script. Some vacuums seem more resistant than others. So the amount of times you have to do it may vary.
52
+
53
+
54
+
55
+
7. Repeat this until you hear the vacuum say "Wifi Connected" It will take 2-3 times. Once you do it twice, wait a few minutes between tries to ensure that the vacuum has enough time to finish the onboarding cycle.
2. On a machine that is not running the server, run our MITM script:
6
+
`uv run mitm_redirect.py --local-api api-roborock.luke-lashley.com`
7
+
8
+
3. Install the Wireguard app on your phone. Then hit the Plus on the wireguard app, add from QR code and scan the code on
9
+
`http://127.0.0.1:8081/#/capture`
10
+
11
+
4. Open `mitm.it` in your web browser. Follow the instructions there for your device. Note on iphone you must open it in Safari. Make sure you follow all of the device specific steps (including installing the cert, trusting it, etc.)
12
+
13
+
5. Once Mitm is configured properly, open the Roborock app, log back in, enter your verification code and the server should automatically show you the vacuums you have on your server. Turn off wireguard, disable the mitm certificate, and then click on one of your devices and you should see the map!
0 commit comments