go-roborock

go-roborock

A typed Go client for Roborock cloud accounts, MQTT vacuum controls, Dyad/Zeo A01 settings, and camera signaling. The reusable client has request-scoped credentials; explicit sessions own device connections.

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.

Supported operations

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.

A command acknowledgement establishes RPC acceptance, not completed movement or cleaning. Observe status 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.

A01 write success means MQTT publication. 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.

Supported contracts are implementation-derived from pinned Python Roborock and the existing Go baseline, with synthetic offline verification. They are not an official vendor specification or a claim of complete Python parity. B01/L01 connections, local transport, map decoding, and WebRTC media decoding are outside this release. See guides and generated reference and CLI.

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