Guides

Integrations

Shelly talks to more than its own app - locally through Home Assistant and MQTT, or through the cloud with Google and Alexa. Which path works depends on the generation.

Shelly Smart Control isn't the only way in to your devices. Depending on generation, they can also be reached locally - through Home Assistant, MQTT, Matter or KNX - or through the cloud, as with Google Home and Amazon Alexa.

Which integration is possible is, as in the rest of this documentation, a question of generation. If you're unsure, start with Which generation do you have?.

Quick overview

Home Assistant

Home Assistant has a built-in Shelly integration: Settings → Devices & services → Add integration → Shelly. Devices on the same network are usually found automatically.

Communication goes directly to the device - not through Shelly's cloud. Gen2+ uses the same RPC interface documented across shelly-api-docs.shelly.cloud, while Gen1 talks over CoIoT, Shelly's older local protocol. For Gen1, CoIoT has to be enabled in the device's advanced settings, and for battery-powered Gen1 devices it's recommended to set unicast to the Home Assistant server's IP and port 5683 instead of broadcast.

This is where most people who want more than the app offers end up - custom automations, statistics, integration with other equipment. The price is that you have to run your own Home Assistant instance.

MQTT

Gen2+ (Plus, Pro, Gen3, Gen4) has a built-in MQTT component, documented on shelly-api-docs.shelly.cloud. You point the device at your own broker (MQTT.SetConfig, or the equivalent setting in the app or web interface), the device connects, and exposes the same RPC methods that HTTP and WebSocket do - both status updates and control.

Gen1 also supports MQTT, but with an older, simpler topic scheme under /shellies/.... Two things worth knowing if you end up there anyway: enabling MQTT on a Gen1 device disables its connection to Shelly's cloud, and Gen1 doesn't support encrypted (TLS) MQTT connections.

MQTT is the way in if you're building your own system - Node-RED, openHAB, a custom script - and don't want or need Home Assistant or the Shelly app in between.

Matter

Matter is the standard that connects the device locally to Apple Home, Google Home and Alexa, without going through Shelly's cloud. Which devices support it is a question of generation - see the table in Which generation do you have?: in short, all Gen4, plus some Gen3 devices from firmware 1.6.0 onward.

Choosing Matter for a Gen4 device also means choosing away from Zigbee mode - see the section on that further down.

Google Home and Amazon Alexa

Unlike Home Assistant, MQTT, Matter and KNX, this path goes through the cloud. Shelly's own support is unambiguous on this point: a cloud connection is required for the Alexa, Google Home and SmartThings integrations to work at all.

• Alexa: enable the "Shelly Cloud" skill in the Alexa app, log in at home.shelly.cloud when redirected, then say "Alexa, discover devices".
• Google Home: Settings → Works with Google → search for "Shelly Smart Home".

The device has to exist in your Shelly account with cloud connection enabled - local control alone isn't enough for this path.

Cloud API vs. local API

shelly-api-docs.shelly.cloud is split into several separate documentation sets, and it's easy to mix them up:

• Gen1 Device API - the device's own HTTP API and CoIoT, documented separately from Gen2+.
• Gen2+ Device API - RPC methods reached over HTTP, WebSocket, BLE or MQTT depending on what you connect over. Same methods regardless of transport.
• Cloud Control API - for users who already have a Shelly account. You generate an authorization key in your account settings and control your own devices through Shelly's cloud instead of locally. Limited to one call per second.
• Integrator API - a cloud-to-cloud integration aimed at businesses/partners connecting their own cloud services to Shelly's, not something an individual user normally sets up themselves.

The point worth taking away: anything that talks directly to the device - Home Assistant, MQTT, your own HTTP calls against the local RPC interface - needs no Shelly cloud at all. The cloud only enters the picture when you want to reach the device from outside your network, or when the integration itself (like Alexa and Google Home above) is built to go through the cloud.

KNX

KNX is the integration Shelly documents most thoroughly themselves in their knowledge base - dedicated KNX pages, use cases, and a description of how a Shelly Pro 1 or Shelly Pro 1PM can substitute for a channel in an existing KNX switch actuator.

KNXnet/IP is built into:

• The Pro line (Gen2) - your DIN-rail device in the distribution board.
• Gen3 and later - several models (including 1, 1L, 2L, 2PM, Mini variants, Shutter, Dimmer and Plug S variants).

The minimum requirement is firmware 1.4.0, but some newer models require higher (1.5.0, 1.6.0 or 1.7.0) - check your specific model before planning an installation. Regular Shelly Plus devices (Gen2) are explicitly not supported.

Over KNXnet/IP you can control and read status for on/off outputs, control roller shutters/awnings/venetian blinds (including slat angle for venetian blinds) with position feedback, and report electrical measurements into the KNX system.

The Zigbee trap, again

The same thing that applies in Which generation do you have? applies here: switch a Gen4 device to Zigbee mode, and it stops working in Shelly Smart Control. That's not a bug to troubleshoot - see also Troubleshooting - it's a consequence of the choice. The device is then handled entirely by your Zigbee hub's own app, and what you can do with it there depends on the hub, not on Shelly.