pymacon

Secure async REST and WebSocket client for the Macon Heat Pump Controller. It is the transport library used by the Macon Home Assistant integration.

Each MaconClient owns the credential, pinned certificate, ordered state, reconnect loop, and reconciliation state for exactly one controller. Multiple controllers therefore remain fully isolated.

Install

pip install pymacon

Usage

from pymacon import MaconClient

client = MaconClient(
    "192.168.1.21",
    token,
    certificate_fingerprint,
    # arctic-* is retained because it is the firmware wire-format ID.
    device_id="arctic-001122334455",
)
client.subscribe(handle_snapshot)
client.subscribe_status(handle_status)
await client.start()

Call await client.stop() when unloading the owning config entry. Sessions passed into the constructor remain owned by the caller; sessions created by the client are closed automatically.

Control methods acknowledge that a command was accepted, but they never optimistically mutate local state. Subscribe to snapshots to observe the controller's reported state:

await client.async_set_cooling_setpoint(12)
await client.async_set_power(False)

Only controls advertised by client.capabilities should be called. The firmware rejects unavailable, unsafe, or unsupported operations.

Controller health (uptime, reset reason, brownout/panic/watchdog counts, Wi-Fi drop and RS485 bus counters) is polled separately from the heat-pump state when client.capabilities.diagnostics is true. Every health field is optional. diagnostics.events carries the controller's newest problem events (Wi-Fi and network outages, crashes and resets) as ControllerEvents; use event.key to tell new ones from ones already seen. A restart names the current boot so a late retry cannot reboot the controller twice:

diagnostics = await client.async_fetch_diagnostics()
if client.capabilities.restart:
    await client.async_restart()

Development

python -m pip install -e ".[tests]"
pytest
ruff check src tests
mypy src