Reference · built on requestConnectorEnergy, EV & distributed resources

Shelly Gen2+ Device API

Switch state, power, and energy from Shelly Gen2+ relays, plugs, and meters over the local RPC API on HTTP, WebSocket, and MQTT.

Request accessPricing ↗

About

Shelly Gen2+ (Shelly-NG) devices are relays, plugs, and energy meters from Shelly Group with a local JSON-RPC 2.0 API. Each device is built from components such as Switch, EM, EMData, Webhook, and MQTT, and each component answers GetStatus, GetConfig, and SetConfig. The same RPC runs over HTTP at /rpc, over WebSocket, over MQTT to a broker the device connects out to, and over UDP if you enable it. The device sends NotifyStatus and NotifyEvent frames when values change, and the three-phase meters keep energy blocks in flash.

Through Fibric, an operator reads apower and aenergy per switch or per phase, notices loads that stay on, and proposes Switch.Set on or off for your approval. Each command runs once and leaves a receipt: what changed, why, and how to undo it.

This is a reference listing. It documents what Fibric would read from Shelly Gen2+ Device API and what it could propose, based on the vendor's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

Inputs

  • Switch output, apower, voltage, current, pf, freq, and aenergy totals with by_minute values through Switch.GetStatus
  • Per-phase a_current, a_voltage, a_act_power, a_aprt_power, a_pf, and a_freq, plus total_act_power, through EM.GetStatus on three-phase meters
  • Stored energy blocks at 60 to 3600 second periods through EMData.GetRecords and EMData.GetData, or as CSV at /emdata/<id>/data.csv
  • NotifyStatus and NotifyEvent frames over WebSocket, and on <topic_prefix>/events/rpc over MQTT, as values change
  • switch.on, switch.off, and switch.active_power_change events posted by the Webhook component to URLs you set
  • Online state on <topic_prefix>/online and errors such as overtemp, overpower, overvoltage, and undervoltage in Switch status

Proposed actions

  • Target capability: propose Switch.Set with id, on, and an optional toggle_after in seconds, or Switch.Toggle
  • Target capability: propose Switch.SetConfig changes such as auto_off, power_limit, or initial_state
  • Target capability: propose Webhook.Create so a device posts its own events to a URL you choose, with a condition and repeat_period
  • Target capability: propose on, off, or toggle published to <topic_prefix>/command/switch:0 over MQTT

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Shed a load at the peak

    apower per switch shows what is drawing now. When site demand nears the threshold you set, the operator proposes Switch.Set off on the loads you marked sheddable, and Switch.Set on when the window closes.

    With Peak Demand

  • Catch what was left on overnight

    Switch status after closing time shows outputs still on. The operator proposes Switch.Set off for each one, or an auto_off in Switch.SetConfig so it does not recur.

    With Schedule Leak, After-Hours Audit

  • Watch power factor per phase

    a_pf, b_pf, and c_pf from EM.GetStatus are logged through the day. When one phase sags, the operator proposes which circuit to inspect and attaches the readings.

    With Power Factor

  • Move a load into the cheap window

    With a tariff schedule beside it, the operator proposes Switch.Set on with toggle_after so a heater or charger runs inside the window and stops on its own.

    With Price Shift

Requirements

  • Shelly Gen2+ devices reachable on your network by IP address or mDNS name, or an MQTT broker they connect out to
  • The admin password for each device, or a decision to leave authentication off on a trusted network segment
  • For MQTT over TLS, a CA the device can validate through ssl_ca, or ssl_ca set to * to skip validation
  • For notifications, a WebSocket client that sends at least one request frame with a valid src, or an MQTT subscriber
Authentication
Digest authentication per RFC 7616 with SHA-256, username admin and a password set through Shelly.SetAuth; it protects HTTP and WebSocket, not MQTT or outbound WebSocket.

Limits

  • A device allows at most 6 simultaneous non-persistent RPC channels; many readers should share an MQTT broker instead
  • HTTP has no keepalive and carries no notifications; NotifyStatus arrives only over WebSocket, MQTT, or UDP
  • Webhooks: 20 per device, 10 on battery devices, 5 URLs each, 300 characters per URL, and no self-signed certificates
  • Traffic over MQTT and outbound WebSocket is not covered by the device password

Access and pricing

Reference listing. Fibric builds the connector under a managed deployment when you request it. Your quote covers the build, capabilities, usage, and support.

Request Shelly Gen2+ Device API ↗

Questions and answers

Which transports does a Shelly Gen2+ device speak?
HTTP: POST /rpc with a full frame, or GET or POST /rpc/<method name>. WebSocket at ws://<shelly.addr>/rpc. MQTT: requests on <shelly-id>/rpc, notifications on <shelly-id>/events/rpc. UDP RPC to a configured peer and port, off by default.
How do I get power readings without polling?
Keep a WebSocket open and read NotifyStatus frames, or set rpc_ntf on the MQTT component so the device publishes them to <topic_prefix>/events/rpc. status_ntf adds full component status on <topic_prefix>/status/<component:id>. A webhook on switch.active_power_change posts apower to your URL.
Does a meter keep history on the device?
Three-phase meters do, through the EMData component. Energy is aggregated into blocks of 60, 300, 900, 1800, or 3600 seconds and saved to flash. EMData.GetRecords lists the saved intervals, EMData.GetData returns them, and /emdata/<id>/data.csv exports them with ts and end_ts.
Ask about Shelly Gen2+ Device API

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This connector listing is developed, published, and supported by Fibric. It describes integration with Shelly Gen2+ Device API through published interfaces. Third-party names and logos identify the systems an integration connects to; they are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy