go-roborock

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.

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.

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 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.