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
- Variables
- type Client
- func (c *Client) AccountID() string
- func (c *Client) Close() error
- func (c *Client) Device(serial string) *Device
- func (c *Client) Devices() map[string]*Device
- func (c *Client) DynamicAction(ctx context.Context, payload any) ([]byte, error)
- func (c *Client) EnergyUsage(ctx context.Context, dev *Device, start, end time.Time) (*EnergyUsage, error)
- func (c *Client) Refresh(ctx context.Context) error
- func (c *Client) SetAway(ctx context.Context, dev *Device, on bool) error
- func (c *Client) SetMode(ctx context.Context, dev *Device, m Mode) error
- func (c *Client) SetSetpoint(ctx context.Context, dev *Device, degF int) error
- func (c *Client) Subscribe() <-chan Event
- func (c *Client) WaterUsage(ctx context.Context, dev *Device, start, end time.Time) (*WaterUsage, error)
- type Config
- type Device
- func (d *Device) AlertCount() int
- func (d *Device) Away() bool
- func (d *Device) Connected() bool
- func (d *Device) DeviceID() string
- func (d *Device) Enabled() bool
- func (d *Device) FriendlyName() string
- func (d *Device) GenericType() string
- func (d *Device) HotWaterAvailability() int
- func (d *Device) Mode() Mode
- func (d *Device) Raw() map[string]json.RawMessage
- func (d *Device) Running() bool
- func (d *Device) RunningState() string
- func (d *Device) SerialNumber() string
- func (d *Device) Setpoint() int
- func (d *Device) SetpointLimits() (min, max int)
- func (d *Device) SupportedModes() []Mode
- func (d *Device) SupportsAway() bool
- func (d *Device) SupportsModes() bool
- func (d *Device) SupportsOnOff() bool
- func (d *Device) Type() DeviceType
- func (d *Device) WiFiSignal() int
- type DeviceType
- type EnergyUsage
- type Event
- type EventKind
- type Mode
- type UsagePoint
- type WaterUsage
Constants ¶
const Version = "0.1.1"
Version is the semantic version of this library and CLI. Bump with github.com/kevinburke/bump_version.
Variables ¶
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 ¶
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) Devices ¶
Devices returns a snapshot of currently-known devices, keyed by serial number.
func (*Client) DynamicAction ¶
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 ¶
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) SetMode ¶
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 ¶
SetSetpoint sets the water-temperature setpoint. The value is checked against the unit's reported limits before sending.
func (*Client) Subscribe ¶
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 ¶
AlertCount returns the @ALERTCOUNT field (number of active alerts).
func (*Device) Connected ¶
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 ¶
DeviceID is the opaque device name Rheem uses on MQTT topics. Stable for the life of the unit.
func (*Device) Enabled ¶
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 ¶
FriendlyName returns @NAME.value if present, else the device ID.
func (*Device) GenericType ¶
GenericType returns the @TYPE string (e.g. "heatpumpWaterHeater", "gasWaterHeater", "tanklessWaterHeater").
func (*Device) HotWaterAvailability ¶
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 ¶
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 ¶
Running reports whether the heater is actively heating right now, based on the @RUNNING string being non-empty.
func (*Device) RunningState ¶
RunningState returns the raw @RUNNING string (often a status label like "Heat Pump On" or "").
func (*Device) SerialNumber ¶
SerialNumber returns the unit's serial.
func (*Device) Setpoint ¶
Setpoint returns the configured water temperature setpoint, or 0 if the unit doesn't expose one.
func (*Device) SetpointLimits ¶
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 ¶
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 ¶
SupportsAway reports whether the unit accepts away-mode commands.
func (*Device) SupportsModes ¶
SupportsModes reports whether the unit exposes an @MODE datapoint.
func (*Device) SupportsOnOff ¶
SupportsOnOff reports whether the unit exposes an @ENABLED datapoint (used by units that have no mode list — they just have on/off).
func (*Device) WiFiSignal ¶
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 ¶
Event is delivered on the channel returned by Subscribe. For EventStateChange, Device points at the device whose state changed.
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 )
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. |