go-roborock

module

v0.3.0 Latest Latest Go to latest Published: Oct 8, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/portpowered/go-roborock

Links

Open Source Insights

README ¶

go-roborock

A typed Go client for Roborock cloud accounts and explicit device sessions. Credentials belong to each request; sessions own their MQTT connections. Choose operations using the discovered device family and capabilities.

Install and authenticate

go get github.com/portpowered/go-roborock

import "github.com/portpowered/go-roborock/pkg/roborock"

client, err := roborock.NewClient()
// Check err after every call. ctx must have a deadline.
login, err := client.ResolveLogin(ctx, roborock.ResolveLoginRequest{
    Email: email, ClientID: stableClientID,
})
_, err = client.RequestLoginCode(ctx, roborock.LoginCodeRequest{Login: login})
// Read the emailed code separately; reuse the same login identity.
result, err := client.LoginWithCode(ctx, roborock.LoginWithCodeRequest{Login: login, Code: code})
devices, err := client.ListDevices(ctx, roborock.AccountRequest{Auth: result.Auth})

Keep result.Auth and discovered local keys private. The caller stores credentials and explicitly logs in again when they expire. The SDK does not silently refresh tokens. Authentication guide.

The runnable discovery example reads a private AuthContext object directly from stdin: go run ./examples/basic < auth.json. This file contains the credential object itself, without the CLI export's outer auth field.

Try the CLI

go install github.com/portpowered/go-roborock/cmd/go-roborock@latest
go-roborock login
go-roborock devices list
go-roborock devices vacuum DEVICE_ID status

Login prompts for your email and emailed code, then saves your account locally. Replace DEVICE_ID with your vacuum's ID from the list. Follow the CLI guide to read maps, clean rooms, and control your vacuum.

Supported operations

Account operations use the same cloud API across families. Device operations use the selected V1, B01 Q7, B01 Q10, or A01 adapter. See device families, maps, and zone cleaning.

The following expressions are short call examples; r denotes roborock, c a client, s an opened device session, ctx a deadline-bearing context, and auth the current account credentials. Inputs such as speed, zones, and segments come from the caller's device configuration.

Account operation	Example
Resolve region	`c.ResolveLogin(ctx, r.ResolveLoginRequest{Email: email, ClientID: id})`
Request email code	`c.RequestLoginCode(ctx, r.LoginCodeRequest{Login: login})`
Exchange email code	`c.LoginWithCode(ctx, r.LoginWithCodeRequest{Login: login, Code: code})`
Legacy password login	`c.LoginWithPassword(ctx, r.LoginWithPasswordRequest{Login: login, Password: password})`
Home	`c.GetHome(ctx, r.AccountRequest{Auth: auth})`
Home room names	`c.GetHomeRooms(ctx, r.HomeRoomsRequest{Auth: auth, HomeID: home.ID})`
Shared device room names	`c.GetSharedDeviceRooms(ctx, r.SharedDeviceRoomsRequest{Auth: auth, DeviceID: d.ID})`
Home data	`c.GetHomeData(ctx, r.HomeDataRequest{Auth: auth, HomeID: home.ID, Version: r.HomeDataV3})`
Owned and shared devices	`c.ListDevices(ctx, r.AccountRequest{Auth: auth})`
Open device	`c.OpenDevice(ctx, r.OpenDeviceRequest{Auth: auth, DeviceID: d.ID, LocalKey: d.LocalKey, Protocol: d.Protocol})`

V1 vacuum operation	Example
Status	`s.GetStatus(ctx, r.EmptyRequest{})`
Consumables	`s.GetConsumables(ctx, r.EmptyRequest{})`
Cleaning summary	`s.GetCleaningSummary(ctx, r.EmptyRequest{})`
Cleaning records	`s.GetCleanRecord(ctx, r.CleanRecordRequest{RecordId: recordID})`
DND schedule	`s.GetDND(ctx, r.EmptyRequest{})`
Start, stop, pause	`s.StartCleaning(ctx, r.EmptyRequest{})`; `s.StopCleaning(ctx, r.EmptyRequest{})`; `s.PauseCleaning(ctx, r.EmptyRequest{})`
Return to dock, spot clean	`s.ReturnToDock(ctx, r.EmptyRequest{})`; `s.SpotClean(ctx, r.EmptyRequest{})`
Dust collection	`s.StartDustCollection(ctx, r.EmptyRequest{})`; `s.StopDustCollection(ctx, r.EmptyRequest{})`
Mop washing	`s.StartMopWashing(ctx, r.EmptyRequest{})`; `s.StopMopWashing(ctx, r.EmptyRequest{})`
Fan, water, mop mode	`s.SetFanSpeed(ctx, r.SetFanSpeedRequest{Speed: speed})`; `s.SetWaterMode(ctx, r.SetWaterModeRequest{Mode: water})`; `s.SetMopMode(ctx, r.SetMopModeRequest{Mode: mop})`; switch the whole mode with `s.SetCleanMotorMode(ctx, r.SetCleanMotorModeRequest{FanSpeed: speed, WaterMode: water, MopMode: &mop})`
Configure, disable DND	`s.SetDND(ctx, r.SetDNDRequest{StartHour: 22, EndHour: 8})`; `s.DisableDND(ctx, r.EmptyRequest{})`
Zones, segments (family-dependent)	`s.CleanZones(ctx, r.CleanZonesRequest{Zones: zones})`; `s.CleanSegments(ctx, r.CleanSegmentsRequest{Segments: segments, Repeats: 1})`
Remote control lifecycle	`s.RCStart(ctx, r.EmptyRequest{})`; `s.RCStop(ctx, r.EmptyRequest{})`; `s.RCEnd(ctx, r.EmptyRequest{})`
Remote movement	`s.RCMove(ctx, r.RCMoveRequest{Velocity: 0.1, Duration: 500, Sequence: 1})`
Session lifetime and close	`<-s.Done()`; `s.Err()`; `s.Close()`

V1 and Q7 acknowledgements establish RPC acceptance, not completed movement or cleaning. Q10 cleaning success establishes MQTT publication only. Observe V1 status or the B01 device/app after an acknowledgement; do not automatically retry uncertain movement. Mode values depend on the model and remain forward compatible. Vacuum guide and remote control guide.

Maps and room operation	Example
SDK capabilities	`s.GetCapabilities(ctx, r.EmptyRequest{})`
Current map	`s.GetMap(ctx, r.GetMapRequest{})`
Saved maps	`s.ListMaps(ctx, r.EmptyRequest{})`
Q7 saved-map content	`s.GetMap(ctx, r.GetMapRequest{MapID: mapID})`
Device room IDs	`s.GetRooms(ctx, r.EmptyRequest{})`
Q10 trace observation	`s.GetMapTrace(ctx, r.EmptyRequest{})`
World point to pixel	`r.MapToPixel(grid, point)`
Pixel point to world	`r.PixelToMap(grid, point)`
Pixel rectangle to world	`r.PixelRectangleToMap(grid, rectangle)`
V1 active-map selection	`s.SelectMap(ctx, r.SelectMapRequest{MapID: mapID})`

V1, Q7, and Q10 support map reads and room cleaning. Rectangle cleaning supports V1 and Q10; Q10 accepts one rectangle aligned to 5 mm. B01 general status, dock, settings, remote-control, and camera operations remain unsupported. Map reads do not initiate cleaning or change the active floor. Map IDs are opaque strings; choose cleaning IDs and coordinates from the active map. The map guide explains coordinate frames and missing geometry.

A01 and camera operation	Example
Dyad state	`s.GetDyadState(ctx, r.GetDyadStateRequest{Properties: dyadProperties})`
Zeo state	`s.GetZeoState(ctx, r.GetZeoStateRequest{Properties: zeoProperties})`
Dyad settings	`s.SetDyadSettings(ctx, dyadSettings)` where `dyadSettings` is `r.SetDyadSettingsRequest`
Zeo settings	`s.SetZeoSettings(ctx, zeoSettings)` where `zeoSettings` is `r.SetZeoSettingsRequest`
Start Zeo cycle	`s.StartZeo(ctx, r.StartZeoRequest{Mode: mode, Program: program})`
Open camera	`s.OpenCamera(ctx, r.OpenCameraRequest{PatternPassword: pattern, SdpOffer: offer})`
Camera description	`camera.Description()`
Send, get ICE	`camera.SendICE(ctx, r.SendICERequest{Candidate: candidate})`; `camera.GetICE(ctx, r.EmptyRequest{})`
Camera lifetime and close	`<-camera.Done()`; `camera.Close()`

A01 write success means MQTT publication. Camera signaling currently uses V1. Camera sessions own preview signaling; the caller's WebRTC stack owns media. See A01 and camera.

Configuration and lifecycle

NewClient accepts WithBaseURL, WithHTTPClient, and WithMQTTDial functional options. The HTTP client and connection-producing MQTT dial hook allow offline transports, tracing, and proxy configuration. Injected transports must be safe for their concurrent use; an injected MQTT dialer owns transport security and must honor cancellation.

Keep the opening context alive for the whole device session. Set deadlines on individual operations and always close sessions. Classify failures with errors.As and *roborockerrors.Error; see errors and lifecycle.

Contracts follow pinned Python Roborock and the existing Go baseline, with synthetic offline verification. Hardware captures are separate compatibility evidence. The SDK does not claim official vendor specifications or complete Python parity. L01, local transport, and WebRTC media decoding remain outside scope. See guides and reference and CLI.

Contributors should read CONTRIBUTING.md, provenance, and release procedure.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api embeds the checked-in Roborock REST contracts for response validation.	Package api embeds the checked-in Roborock REST contracts for response validation.
cmd
go-roborock module
examples
basic command Command basic lists account devices without printing their encryption keys.	Command basic lists account devices without printing their encryption keys.
internal
mapmodel Package mapmodel provides primitives to interact with the openapi HTTP API.	Package mapmodel provides primitives to interact with the openapi HTTP API.
protocol Code generated by tools/generate from schema x-wire-constants; DO NOT EDIT.	Code generated by tools/generate from schema x-wire-constants; DO NOT EDIT.
schemaadapter Package schemaadapter projects canonical MQTT schemas for the existing Go model generator.	Package schemaadapter projects canonical MQTT schemas for the existing Go model generator.
pkg
dependencies/mapdata Package mapdata decodes bounded inner map payloads without network or rendering.	Package mapdata decodes bounded inner map payloads without network or rendering.
dependencies/mqtt Package mqtt implements account-bound Roborock cloud device sessions.	Package mqtt implements account-bound Roborock cloud device sessions.
dependencies/rest Package rest implements stateless Roborock cloud authentication and inventory.	Package rest implements stateless Roborock cloud authentication and inventory.
dependencymodels Package dependencymodels provides primitives to interact with the openapi HTTP API.	Package dependencymodels provides primitives to interact with the openapi HTTP API.
dependencymodels/mapproto
roborock Package roborock provides a stateless cloud client and explicit typed device sessions.	Package roborock provides a stateless cloud client and explicit typed device sessions.
roborockerrors Package roborockerrors defines failures shared by the public API and transports.	Package roborockerrors defines failures shared by the public API and transports.
tools
compatibility command Command compatibility compares the public Go API with a Git baseline.	Command compatibility compares the public Go API with a Git baseline.
contracts command Command contracts validates schema documents, production source rules and generated models.	Command contracts validates schema documents, production source rules and generated models.
coverage command Command coverage reports statement coverage for non-generated library code.	Command coverage reports statement coverage for non-generated library code.
docbundle command Command docbundle joins schemas for documentation without changing wire owners.	Command docbundle joins schemas for documentation without changing wire owners.
formatcheck command Command formatcheck checks every repository Go source without modifying files.	Command formatcheck checks every repository Go source without modifying files.
generate command Command generate reproducibly generates schema models and protocol constants.	Command generate reproducibly generates schema models and protocol constants.
generatedfiles command Command generatedfiles rejects untracked generated output in CI.	Command generatedfiles rejects untracked generated output in CI.
integrationcheck command Command integrationcheck compiles and skips the opt-in live suite without credentials.	Command integrationcheck compiles and skips the opt-in live suite without credentials.
inventory command Command inventory records schema-owned declarations and resolved production uses.	Command inventory records schema-owned declarations and resolved production uses.
modules command Command modules verifies the CLI module against the local SDK without publishing replacements.	Command modules verifies the CLI module against the local SDK without publishing replacements.
protogen command Command protogen compiles the pinned map protocol with the official Go plugin.	Command protogen compiles the pinned map protocol with the official Go plugin.
publicdocs command Command publicdocs renders schema-owned public A01 types as customer MDX.	Command publicdocs renders schema-owned public A01 types as customer MDX.
siteassets command Command siteassets adds the flat Flight payload names requested by static Next navigation.	Command siteassets adds the flat Flight payload names requested by static Next navigation.
sitelinks command Command sitelinks verifies local destinations in every rendered HTML page.	Command sitelinks verifies local destinations in every rendered HTML page.