{"id":20377872,"url":"https://github.com/konqi/roborock-bridge","last_synced_at":"2025-04-12T07:52:38.072Z","repository":{"id":214773483,"uuid":"722223495","full_name":"konqi/roborock-bridge","owner":"konqi","description":"Bridge between a local mqtt broker and your roborock vaccuum through the vendor apis","archived":false,"fork":false,"pushed_at":"2025-03-26T16:25:41.000Z","size":469,"stargazers_count":9,"open_issues_count":14,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T07:52:30.653Z","etag":null,"topics":["home-automation","mqtt","roborock","vacuum"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/konqi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-22T17:44:09.000Z","updated_at":"2025-04-06T08:10:41.000Z","dependencies_parsed_at":"2024-06-18T11:28:11.377Z","dependency_job_id":"b529dec0-3929-4a1f-9c3d-3238f347e883","html_url":"https://github.com/konqi/roborock-bridge","commit_stats":null,"previous_names":["konqi/roborock-bridge"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konqi%2Froborock-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konqi%2Froborock-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konqi%2Froborock-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konqi%2Froborock-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konqi","download_url":"https://codeload.github.com/konqi/roborock-bridge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248537034,"owners_count":21120690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-automation","mqtt","roborock","vacuum"],"created_at":"2024-11-15T01:46:51.437Z","updated_at":"2025-04-12T07:52:38.043Z","avatar_url":"https://github.com/konqi.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# roborock-bridge\n\nThis service connects to RR's servers and provides status information from your robot to your mqtt broker.\nIt can also send simple commands and requests to the robot.\n\n## Setup \u0026 Start\n\nTo start experimenting you can start the application with docker compose.\nIf you want to use the application for real you'll have to start it the regular way.\n\n### Quickstart with docker compose\n\nTo get started quick you can use docker compose.\nThis will start:\n\n- the bridge itself\n- an mqtt broker\n- the web ui\n\nCreate an env file that contains\n\n```properties\nUSERNAME=\u003cemail\u003e\nPASSWORD=\u003cpassword\u003e\n```\n\nStart up everything with\n\n```shell\ndocker compose --env-file \u003cyour-env-file\u003e up\n```\n\nNow open up a browser and navigate to http://localhost:8080.\n\n### The regular way\n\nYou need at least Java 17 to run the application.\n\nCreate an `application.yaml` file with the following content.\nReplace `username`, `password` and `bridge-mqtt.url`, etc. (don't change the `app_secret_salt`).\n\n```yaml\nusername: user   # your roborock account username (email address)\npassword: secret # your roborock account password\nroborock-mqtt:\n  nonce_generation_salt: ThisIsASecret # just a random string for entropy\n  endpoint: aAbBz0                     # 6 char string to use as an identifier\nbridge-mqtt:\n  url: tcp://localhost:1883            # connection url to your mqtt broker (use ssl:// for ssl)\n  # If you don't use anonymous access to the broker, also set these\n  # username: username\n  # password: secret\n  client_id: mqtt-bridge-service       # how the client appears to your broker\n  base_topic: mqtt-bridge              # everything th service does will be below this topic string\n```\n\nStart the application with:\n\n```shell\njava -jar file.jar\n```\n\n## How to use\n\nWhat you'll get:\n\n| topic                                                | description                                                                                                         |\n|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|\n| `home/\u003chomeId\u003e`                                      | All devices and routines are associated to a room. This topic contains the home name and the id.                    |\n| `home/\u003chomeId\u003e/rooms`                                | Homes have rooms. This topic contains a list of the defined rooms.                                                  |\n| `home/\u003chomeId\u003e/routine/\u003croutineId\u003e`                  | Routines are predefined cleanup tasks (i.e. first vacuum, the mop room A). Routines can be executed with `/action`. |\n| `home/\u003chomeId\u003e/device/\u003cdeviceId\u003e`                    | This topic contains basic information of the device and is the parent various property topics.                      |\n| `home/\u003chomeId\u003e/device/\u003cdeviceId\u003e/\u003cproperty\u003e`         | Topics associated with properties of the device. e.g. current state, remaining battery charge, map data, ...        |\n| `home/\u003chomeId\u003e/device/\u003cdeviceId\u003e/\u003cproperty\u003e/options` | Send an empty body to  this topic to get a list of possible values for the property                                 |\n\nList of some of the available properties:\n\n- map\n- path\n- virtual_walls\n- robot_position\n- charger_position\n- state\n- battery\n- ...\n\n### Commands\n\nCommands are topics which will invoke certain functionality on the bridge.\nEach command is a prefix that immediately follows the path to the resource the command should be invoked upon.\n\n**Example:**\nIf you with to perform a `get` command on a home node, you would publish a message on\ntopic `\u003cbase-topic\u003e/home/12345/get`\n\nCurrently available commands:\n\n| postfix   | description                                                |\n|-----------|------------------------------------------------------------|\n| `/get`    | request data from remote servers                           |\n| `/action` | invoke action (e.g. return to dock, start cleanup routine) |\n\n#### What can you request with get?\n\n| target | body    | description                                                                                                                  |\n|--------|---------|------------------------------------------------------------------------------------------------------------------------------|\n| home   | empty   | update home and devices via rest (some device states not included) \u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/get`          |\n| device | `state` | request update of all states via mqtt \u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/get` with body `state` |\n| device | `map`   | request update of map data via mqtt \u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/get` with body `map`     |\n| device | `consumables`   | request update of consumables data via mqtt \u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/get` with body `consumables`     |\n\n#### What can you do with actions?\n\n| target  | body                                                                                                     | description                                                                                                                                                                                                                                                                                                                                                                                                                   |\n|---------|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| routine | empty                                                                                                    | Start the cleanup routine \u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/routine/34544/action`                                                                                                                                                                                                                                                                                                                                   |\n| device  | `home`                                                                                                   | Send device back to base station\u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `home`                                                                                                                                                                                                                                                                                                   |\n| device  | `{\"action\": \"segments\", \"clean_mop\": int?, \"clean_order_mode\": int?, \"repeat\": int?, \"segments\": int[]}` | Clean selected segments / rooms. Possible values are the mqttRoomIds for segments and 0 or 1 for the other values (to be verified)\u003cbr/\u003e **Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `{\"action\": \"segments\", \"segments\": [18,19,20]}`                                                                                                                                                       |\n| device  | `{\"action\": \"clean_mode\", \"fan_power\": int,\"mop_mode\": int, \"water_box_mode\": int}`                      | Set cleanup options. Possible property values can be found in the Interpreter for your robot e.g. [S8 Pro Ultra, MOP_MODE_UNKNOWN, FAN_POWER_123, WATER_BOX_124](./src/main/kotlin/de/konqi/roborockbridge/bridge/interpreter/S8UltraInterpreter.kt). \u003cbr/\u003e**Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `{\"action\": \"clean_mode\", \"fan_power\": 103,\"mop_mode\": 300, \"water_box_mode\": 202}` |\n| device  | `{\"action\": \"clean_mode\", \"fan_power\": string,\"mop_mode\": string, \"water_box_mode\": string}`             | Set cleanup options via string values (see next section to find out allowed values). \u003cbr/\u003e**Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `{\"action\": \"clean_mode\", \"fan_power\": \"max\",\"mop_mode\": \"deep\", \"water_box_mode\": \"off\"}`                                                                                                                                                           |\n| device  | `start` or `{\"action\": \"start\", \"clean_mop\": 1}`                                                         | Start / Resume current cleanup task. \u003cbr/\u003e**Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `start`                                                                                                                                                                                                                                                                                              |\n| device  | `pause`                                                                                                  | Pause current cleanup task. \u003cbr/\u003e**Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/action` with payload `pause`                                                                                                                                                                                                                                                                                                       |\n\n#### What values are allowed for which property\n\nIf you want to know which values are allowed for which property you can ask the bridge for it.\nSend a message to `home/\u003chomeId\u003e/device/\u003cdeviceId\u003e/\u003cproperty\u003e/options` with an empty body (important).\nThe bridge will reply on the same topic with a map of values and their meaning.\nIf there is no interpreter for your device available or the interpreter has no information about possible values it\nwon't reply.\n\n**Example:** `\u003cbase-topic\u003e/home/12345/device/asjnkd978732/fan_power/options`\n\n## Something is wrong\n\nTry resetting the authentication by deleting the auth.json file.\n\n## Short excursion on RR's APIs \u003csmall style=\"font-size: 0.5em;\"\u003e(completely optional read)\u003c/small\u003e\n\nSadly RR does not provide a public interface (i.e. APIs) for developers to create their own solutions.\nSome people smarter than me started to decompile RR's apps and reverse engineered a lot of the protocol.\nToday, with a little help by a couple of extracted secrets and a bit of mitm traffic sniffing, we can see what the\nofficial app does and recreate some of it.\n\nA few things you should know about the communication between the app and roborock servers (even if it's only to\nunderstand some of the errors this application might produce) are:\n\n- There are a couple of REST APIs that are used for\n    - Authentication (login api), is where you log in and get a set of credentials for other operations\n    - Home (home api), is where you get information about a home, which is the root node where everything else is\n      assigned to\n    - Interaction with devices (user api), requests available devices and their status, also allows starting predefined\n      cleanups\n- There also is an MQTT connection. This is used for\n    - IPC request/responses. Used for live updates of the robot status (e.g. idle/cleaning/drying/charging)\n    - There are also \"special\" IPC requests that request the map of your place as seen by the robot\n\nThis application hides all the different ways of communication and provides a single way of communication with your\ndevice via mqtt.\nIF you already have a mqtt broker running for things like zigbee2mqtt, this service should be right up your alley.\nHowever, if you have never heard of mqtt, and you have no idea what it is, you may want to continue RR's app.\n\n## Todo-List\n\n| Status | What                                                         |\n|:------:|--------------------------------------------------------------|\n|   ✅    | Use request memory to determine avg request to response time |\n|   ✅    | Create \"idle mode\"                                           |\n|   ✅    | Disconnect roborock mqtt when idle, reconnect on activity    |\n|   ❌    | ~~Detect routine finished to send bridge into idle mode~~    |\n|   ✅    | poll frequent updates during active phase                    | \n|   ✅️   | Room cleaning                                                |\n|   ✅    | Set Cleanup modes                                            |\n|   ✅    | Verify room cleaning parameters                              |\n|   ✅    | Pause \u0026 Resume (e.g. to pause when certain area is entered)  |\n|   📝   | Verify Pause \u0026 Resume                                        |\n|   ✅    | Detect Device MQTT unreachable and stop polling              |\n|   ✅    | Fix POC ui after renaming room property names                |\n|   ✅    | Add room cleaning parameters to POC ui                       |\n|   📝   | Find out how to get status of dock (probably not much to do) |\n|   📝   | Allow resetting consumables (set on properties)              |\n|   📝   | Start / Stop drying at base                                  |\n|   📝   | trigger mop cleanup?                                         |\n|   ✅    | create way to ask about possible prop values and meaning     |\n|   📝   | Selected area cleaning (via mqtt? tricky!)                   |\n\n## Help reverse engineering the protocol\n\n[Instructions on breaking and entering the protocol](./HOWTO_MITM.md)\n\nI only own an S8 Ultra, and I have no idea how the protocol varies between models.\nTheoretically you should be able to use this service for other robots as well, if not, you can help by adding the\nfunctionality for it.\n\nMost likely you will have to create a `SchemaValueInterpreter` for your robot, which should be a simple copy \u0026 paste \u0026\nadapt (you might even find the data you need in some other services that do something similar).\nIn case the application doesn't work at all for you, bigger changes might be necessary.\nYou can help by figuring out what these changes are on the protocol level by following the instruction behind the link\nabove.\n\nFeel free to\n\n- open a pull request for\n    - compatibility patches\n    - bugfixes\n    - new features / improvements\n- report issues\n\n## Other ways to support\n\nIf you have no idea how to code, but really want to use this application, you can sponsor me an additional roborock\nrobot or lend me yours for a while.\nThe actual extraction of what I need shouldn't take long.\nI cannot give any guarantees to how long it might take to make the required adjustments to the application.\nContact me if interested.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonqi%2Froborock-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonqi%2Froborock-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonqi%2Froborock-bridge/lists"}