rheemcloud

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 19, 2026 License: MIT Imports: 19 Imported by: 0

README

rheemcloud-go

A Go client for the Rheem EcoNet cloud — the same backend the official EcoNet iOS/Android app uses to control Rheem water heaters and thermostats.

Auth and the device list go over HTTPS to rheem.clearblade.com (a ClearBlade-hosted BaaS). State updates and commands flow over MQTT/TLS to the same host on port 1884. There is no Rheem-published API; this package follows the protocol the pyeconet project reverse-engineered from Rheem's Android app.

You need a Rheem EcoNet account (the one you use to log into the app) and the heater's Wi-Fi module enrolled. Every command traverses Rheem's servers — this is not a local-control client. For local control of heat-pump water heaters without internet, see the sibling econet-go package, which targets the esphome-econet RS485 bridge.

Install

go get github.com/kevinburke/rheemcloud-go
go install github.com/kevinburke/rheemcloud-go/cmd/rheemcloud@latest

Library use

ctx := context.Background()
client, err := rheemcloud.Connect(ctx, os.Getenv("RHEEM_EMAIL"), os.Getenv("RHEEM_PASSWORD"), nil)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

for serial, dev := range client.Devices() {
    log.Printf("%s — %s, mode=%s setpoint=%d°F", serial, dev.FriendlyName(), dev.Mode(), dev.Setpoint())
}

// Subscribe to MQTT state changes:
for ev := range client.Subscribe() {
    if ev.Kind == rheemcloud.EventStateChange {
        log.Printf("%s: mode=%s running=%v", ev.Device.FriendlyName(), ev.Device.Mode(), ev.Device.Running())
    }
}

Client.Devices() returns a snapshot of known equipment keyed by serial number. Subscribe() returns a channel that delivers every state delta plus connect/disconnect events. Setpoint and mode commands publish to user/{account_id}/device/desired over MQTT — the Wi-Fi module typically applies the change within a few seconds and echoes back a new reported payload.

See the package docs for the full API.

Command-line tool

export RHEEM_EMAIL='you@example.com'
export RHEEM_PASSWORD='...'

rheemcloud login                  # verify creds, print account_id
rheemcloud devices                # list enrolled devices
rheemcloud state                  # print full state of the first water heater
rheemcloud watch                  # stream MQTT updates until ^C
rheemcloud mode heat-pump         # off | electric | energy-saving | heat-pump | high-demand | performance
rheemcloud setpoint 125           # target temperature in °F
rheemcloud away on                # enable vacation/away mode

Pass --serial SN-XXXX to target a specific unit if your account has more than one. Run rheemcloud --help for the full flag list.

Stability caveats

  • The Rheem cloud API is undocumented and unsupported. Endpoints, field names, or auth flow can change at any time — pyeconet has occasionally needed updates after Rheem-side changes.
  • Some fields (notably @SIGNAL, @RUNNING) only arrive on MQTT, not in the initial REST device dump. Give a state call ~1s after Connect (the CLI's state subcommand does this for you) or call Subscribe() and wait for the first event.
  • Mode label normalization follows pyeconet's by_string, which is forgiving but not exhaustive — if your unit returns an unrecognized label, Mode() returns ModeUnknown and SetMode for that label won't work. Open an issue with the raw label and we'll add it.

License

MIT

Documentation

Overview

Package rheemcloud is a Go client for the Rheem EcoNet cloud service — the same backend the EcoNet mobile app talks to.

Auth and the initial device list go over HTTPS to rheem.clearblade.com (a ClearBlade-hosted Backend-as-a-Service). State updates and commands go over MQTT/TLS to the same host on port 1884. There is no Rheem- published API; this package follows the protocol the open-source pyeconet library reverse-engineered from the Android app.

You will need a Rheem EcoNet account (the one used by the iOS/Android app) and the heater's Wi-Fi module connected to your network. All commands traverse Rheem's servers; this is not a local-only client. For local control without internet, see the sibling econet-go package (which targets the esphome-econet RS485 bridge instead).

The Client is long-lived. After Connect returns it maintains the MQTT session in the background and reconnects on drop. The context passed to Connect bounds the session setup only — REST auth, REST device list, and MQTT handshake — not the lifetime of the Client. Call Close to shut down the background session.

Methods that touch the network (commands, usage queries, Refresh, DynamicAction) each accept their own context.Context for per-operation timeouts and cancellation.

Index

Constants

View Source
const Version = "0.1.1"

Version is the semantic version of this library and CLI. Bump with github.com/kevinburke/bump_version.

Variables

View Source
var (
	// ErrInvalidCredentials is returned by Connect when Rheem rejects the
	// email/password pair.
	ErrInvalidCredentials = errors.New("rheemcloud: invalid credentials")
	// ErrClosed is returned by commands issued after Close.
	ErrClosed = errors.New("rheemcloud: client closed")
	// ErrNoDevice is returned when a command references an unknown
	// device.
	ErrNoDevice = errors.New("rheemcloud: device not found")
	// ErrModeUnsupported is returned by SetMode when the unit doesn't
	// expose the requested mode.
	ErrModeUnsupported = errors.New("rheemcloud: mode not supported by this unit")
	// ErrSetpointOutOfRange is returned by SetSetpoint when the value
	// is outside the unit's reported range.
	ErrSetpointOutOfRange = errors.New("rheemcloud: setpoint out of range")
)

Errors returned by Client methods.

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a long-lived authenticated EcoNet session.

func Connect

func Connect(ctx context.Context, email, password string, cfg *Config) (*Client, error)

Connect establishes a full EcoNet session: it authenticates with the REST API, fetches the device list, and opens the MQTT subscription for state updates. Returns a ready-to-use Client.

ctx bounds setup only — the initial REST auth, REST device list, and MQTT handshake. Once Connect returns successfully, the Client is independent of ctx; its background MQTT session reconnects on drop until Close is called. To bound the client's lifetime, defer Close.

func (*Client) AccountID

func (c *Client) AccountID() string

AccountID returns the authenticated user's account ID.

func (*Client) Close

func (c *Client) Close() error

Close disconnects MQTT and releases subscriber channels.

func (*Client) Device

func (c *Client) Device(serial string) *Device

Device looks up a single device by serial number.

func (*Client) Devices

func (c *Client) Devices() map[string]*Device

Devices returns a snapshot of currently-known devices, keyed by serial number.

func (*Client) DynamicAction

func (c *Client) DynamicAction(ctx context.Context, payload any) ([]byte, error)

DynamicAction is the low-level escape hatch: it POSTs an arbitrary payload to /code/{systemKey}/dynamicAction and returns the raw response JSON. The shape of both request and response varies by action — see pyeconet or sniff the EcoNet app for examples. Useful for exploring undocumented actions like waterheaterHealthView.

func (*Client) EnergyUsage

func (c *Client) EnergyUsage(ctx context.Context, dev *Device, start, end time.Time) (*EnergyUsage, error)

EnergyUsage queries the cloud for the device's hourly energy usage over the supplied window. Pass zero start/end to default to "today 00:00:00.999" through "today 23:59:59.999" in the local timezone, matching pyeconet's defaults.

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context) error

Refresh re-fetches the device list from REST and merges into the in-memory state. Useful if a unit was added or replaced.

func (*Client) SetAway

func (c *Client) SetAway(ctx context.Context, dev *Device, on bool) error

SetAway toggles vacation/away mode on units that support it.

func (*Client) SetMode

func (c *Client) SetMode(ctx context.Context, dev *Device, m Mode) error

SetMode changes the operating mode of a water heater. The unit must advertise the requested mode in its SupportedModes list (or accept the equivalent @ENABLED toggle for ModeOff). Blocks until the publish is acked by the broker, ctx expires, or the client is closed; observe Subscribe to confirm the unit reported the new state.

func (*Client) SetSetpoint

func (c *Client) SetSetpoint(ctx context.Context, dev *Device, degF int) error

SetSetpoint sets the water-temperature setpoint. The value is checked against the unit's reported limits before sending.

func (*Client) Subscribe

func (c *Client) Subscribe() <-chan Event

Subscribe returns a channel of events. The channel is buffered; if a consumer falls behind, oldest events are dropped (logged).

func (*Client) WaterUsage

func (c *Client) WaterUsage(ctx context.Context, dev *Device, start, end time.Time) (*WaterUsage, error)

WaterUsage queries the cloud for the device's hourly water usage. Same windowing semantics as EnergyUsage. Returns ErrNotSupported (via the typed error) if the unit doesn't track water consumption.

type Config

type Config struct {
	// UserAgent overrides the User-Agent header on REST calls.
	UserAgent string
	// HTTPTimeout bounds individual REST calls. Defaults to 15s.
	HTTPTimeout time.Duration
	// Logger handles reconnect/error logging. Defaults to slog.Default().
	Logger *slog.Logger
	// HTTPClient lets callers inject a custom http.Client (e.g. for
	// tests). If nil a new client with HTTPTimeout is created.
	HTTPClient *http.Client
}

Config holds optional knobs.

type Device

type Device struct {

	// LastUpdated is the time we last applied an incoming MQTT update
	// or refresh. Zero before the first event.
	LastUpdated time.Time
	// contains filtered or unexported fields
}

Device represents a single piece of Rheem equipment associated with the logged-in account. Currently water heaters are the only fully- supported type; thermostat support is stubbed.

func (*Device) AlertCount

func (d *Device) AlertCount() int

AlertCount returns the @ALERTCOUNT field (number of active alerts).

func (*Device) Away

func (d *Device) Away() bool

Away reports whether away mode is currently active.

func (*Device) Connected

func (d *Device) Connected() bool

Connected reports whether the unit is talking to Rheem's cloud. Returns true if @CONNECTED is absent (older units don't include it and are assumed connected).

func (*Device) DeviceID

func (d *Device) DeviceID() string

DeviceID is the opaque device name Rheem uses on MQTT topics. Stable for the life of the unit.

func (*Device) Enabled

func (d *Device) Enabled() bool

Enabled reports whether the unit's master on/off datapoint is on. For mode-supporting units, it returns false if the active mode is "OFF".

func (*Device) FriendlyName

func (d *Device) FriendlyName() string

FriendlyName returns @NAME.value if present, else the device ID.

func (*Device) GenericType

func (d *Device) GenericType() string

GenericType returns the @TYPE string (e.g. "heatpumpWaterHeater", "gasWaterHeater", "tanklessWaterHeater").

func (*Device) HotWaterAvailability

func (d *Device) HotWaterAvailability() int

HotWaterAvailability returns the unit's "how much hot water is left" estimate, mapped to 0/33/66/100 like pyeconet does. Returns -1 if the unit doesn't report this field.

func (*Device) Mode

func (d *Device) Mode() Mode

Mode returns the current operating mode. ModeOff is reported if the unit supports on/off and @ENABLED is 0.

func (*Device) Raw

func (d *Device) Raw() map[string]json.RawMessage

Raw returns the device's full raw JSON document — every field the REST + MQTT protocol has surfaced so far, including the "@..." datapoints (mode, setpoint, alerts, etc.) and the bare-string metadata fields (serial_number, device_name, device_type, etc.). The result is a snapshot; subsequent MQTT updates won't affect it.

func (*Device) Running

func (d *Device) Running() bool

Running reports whether the heater is actively heating right now, based on the @RUNNING string being non-empty.

func (*Device) RunningState

func (d *Device) RunningState() string

RunningState returns the raw @RUNNING string (often a status label like "Heat Pump On" or "").

func (*Device) SerialNumber

func (d *Device) SerialNumber() string

SerialNumber returns the unit's serial.

func (*Device) Setpoint

func (d *Device) Setpoint() int

Setpoint returns the configured water temperature setpoint, or 0 if the unit doesn't expose one.

func (*Device) SetpointLimits

func (d *Device) SetpointLimits() (min, max int)

SetpointLimits returns the min and max setpoint values from the device's reported constraints. Returns 0,0 if no constraints are reported.

func (*Device) SupportedModes

func (d *Device) SupportedModes() []Mode

SupportedModes returns the operating modes this unit advertises. The order matches the unit's enumText, so SetMode can look up the right index. ModeOff is appended when the unit also supports @ENABLED.

func (*Device) SupportsAway

func (d *Device) SupportsAway() bool

SupportsAway reports whether the unit accepts away-mode commands.

func (*Device) SupportsModes

func (d *Device) SupportsModes() bool

SupportsModes reports whether the unit exposes an @MODE datapoint.

func (*Device) SupportsOnOff

func (d *Device) SupportsOnOff() bool

SupportsOnOff reports whether the unit exposes an @ENABLED datapoint (used by units that have no mode list — they just have on/off).

func (*Device) Type

func (d *Device) Type() DeviceType

Type returns the device's category.

func (*Device) WiFiSignal

func (d *Device) WiFiSignal() int

WiFiSignal returns the @SIGNAL value (dB) or 0 if not yet received. The signal field only arrives via MQTT updates, not the initial REST device list — it'll be zero until the first MQTT message lands.

type DeviceType

type DeviceType int

DeviceType identifies the kind of equipment Rheem returns.

const (
	DeviceUnknown DeviceType = iota
	DeviceWaterHeater
	DeviceThermostat
)

func (DeviceType) String

func (d DeviceType) String() string

type EnergyUsage

type EnergyUsage struct {
	Today []UsagePoint
	Past  []UsagePoint
	// Total is the sum of Today's points — kWh for electric/heat-pump
	// units, kBTU for gas, per the EnergyType field.
	Total float64
	// EnergyType is the unit reported by the API — typically "KWH" or
	// "KBTU". Inferred from the human-readable "message" field.
	EnergyType string
	// Message is the human-readable summary string from Rheem (e.g.
	// "You used 1.23 kWh of energy today.").
	Message string
}

EnergyUsage reports the unit's energy consumption for a single day. Today is the default if start/end are zero. The cloud returns two series: Today (one point per hour, midnight-to-midnight in the unit's local time) and Past (a comparison series the EcoNet app overlays on the "today" chart — semantics not officially documented).

type Event

type Event struct {
	At     time.Time
	Kind   EventKind
	Device *Device
}

Event is delivered on the channel returned by Subscribe. For EventStateChange, Device points at the device whose state changed.

type EventKind

type EventKind int

EventKind labels what happened.

const (
	EventStateChange EventKind = iota
	EventConnected
	EventDisconnected
)

func (EventKind) String

func (k EventKind) String() string

type Mode

type Mode int

Mode is the operating mode of a water heater. Values match pyeconet.WaterHeaterOperationMode so labels are stable across libraries.

const (
	ModeUnknown      Mode = 99
	ModeOff          Mode = 1
	ModeElectric     Mode = 2 // matches "Electric" / "Electric Mode" / "Performance"
	ModeEnergySaving Mode = 3 // "Energy Saver" / "Energy Saving" / "Eco"
	ModeHeatPump     Mode = 4 // "Heat Pump" / "Heat Pump Only"
	ModeHighDemand   Mode = 5
	ModeGas          Mode = 6
	ModePerformance  Mode = 8
	ModeVacation     Mode = 9
)

func (Mode) String

func (m Mode) String() string

type UsagePoint

type UsagePoint struct {
	Bucket int     // hour-of-day for today's data, day-of-week for the history series
	Value  float64 // kWh, kBTU, or gallons depending on the usage type
}

UsagePoint is one bucket of historical usage data. For daily reports Hour is 0-23. For the historical-week series Rheem returns alongside the day, the same struct holds 7 days indexed 1-7 (Mon=1?) — the upstream API doesn't document the labels so consumers should treat the bucket key as an opaque integer.

type WaterUsage

type WaterUsage struct {
	Today []UsagePoint
	Past  []UsagePoint
	// Total is the sum of Today's points, in the units Rheem returns
	// (typically gallons).
	Total float64
	// Message is the human-readable summary from Rheem.
	Message string
}

WaterUsage reports the unit's water draw for a single day.

Directories

Path Synopsis
cmd
rheemcloud command
Command rheemcloud is a small CLI around the rheemcloud-go client.
Command rheemcloud is a small CLI around the rheemcloud-go client.

Jump to

Keyboard shortcuts

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