Shelly (Shelly v0.1.0)

Copy Markdown View Source

Shelly smart-device client for Elixir — cloud APIs, real-time events, and component-aware status parsing across every hardware generation.

Extracted from NordSwitch, where it drives a live fleet spanning Gen2 (Plus 1PM), Pro (Pro 3) and Gen4 hardware.

The pieces

  • Shelly.OAuth — "connect your Shelly account" authorization-code flow; yields a long-lived token and the account's cloud server.
  • Shelly.Account — token-authorized account API: list all devices (names, models, channels), whole-account status in one call, relay control. The recommended path — no auth keys.
  • Shelly.CloudV2 — auth-key API: bulk status (≤10 devices), switch/cover/light control, toggle_after watchdog.
  • Shelly.CloudV1 — the deprecated legacy API, kept as a fallback.
  • Shelly.Events — real-time websocket per account with a handler callback (status changes, online transitions).
  • Shelly.Status — one parser for every payload shape: Gen2/3/4 RPC components (switch/cover/light/CCT/RGB(W)/PM1/EM/EM1, flood, smoke, presence, temperature/humidity sensors, voltmeter, devicepower) and Gen1 arrays (relays with Watt-minute counters, lights, rollers, emeters, battery sensors). Reports component and metered so a relay without power metering is never mistaken for one drawing 0 W.
  • Shelly.RateGate — per-account request pacing (the cloud 429s beyond ~1 req/s/account); add it to your supervision tree.

Quick start (OAuth path)

# 1. In your supervision tree:
children = [Shelly.RateGate]

# 2. Send the user to Shelly's login:
Shelly.OAuth.authorize_url("https://myapp.example/oauth/callback")

# 3. In your callback:
{:ok, grant} = Shelly.OAuth.exchange_code(code)
account = Shelly.OAuth.to_account(grant)

# 4. Devices + live data:
{:ok, devices} = Shelly.Account.list_devices(account)
{:ok, statuses} = Shelly.Account.all_statuses(account)

parsed = Shelly.Account.parse_status(statuses["0cdc7ef76644"], 0)
# => %{on: true, watts: 2.4, component: "switch", metered: true, ...}

# 5. Control:
:ok = Shelly.Account.set_switch(account, "0cdc7ef76644", 0, false)

Field notes baked into this library

  • Cloud rate limit is ~1 request/second/account and it will 429 concurrent bursts — hence Shelly.RateGate.
  • Gen1 relay energy counters count Watt-minutes; Gen1 emeters count real Wh. Shelly.Status converts appropriately.
  • Websocket events can be partial deltas — always guard with Shelly.Status.has_component?/2 before parsing.
  • The v1 API is deprecated by Shelly; v2 accepts the same auth key.
  • OAuth tokens are long-lived and die on password change; treat expiry as possible anyway and reconnect on auth failures.