Mastering Shelly Products with Home Assistant: A Comprehensive Guide

Two of the things I most often write about are Shelly products and Home Assistant, with good reason. Shelly makes my favorite smart home devices, including smart relays, plugs, bulbs, and buttons. I use these devices every day. Home Assistant is the uber-powerful home automation controller that allows me to integrate all of the smart devices in my home into a cohesive, proactive, and reactive smart home machine. Part of what I love about Shelly and Home Assistant is that they work so well together. This article will comprehensively cover how to get these two ecosystems to work together.

If you’ve ever wanted to use a Shelly product with Home Assistant, weren’t sure where to start, were having problems, or just needed some inspiration, you’re in the right place.

Overview of Shelly products

Let’s start with a brief overview of the products Shelly provides. They have a suite of smart devices that are primarily Wi-Fi, but some have Bluetooth capabilities and others have Z-wave support instead of Wi-Fi.

Shelly’s products support industry standard protocols like MQTT and REST, which allow them to be integrated within most if not all, smart home ecosystems. These protocols allow for local control – meaning you can control these devices and keep the data on your local home network, which has many benefits.

That said, they also can work via the cloud. Shelly’s cloud allows for direct integration with voice assistants like Alexa and Google Assistant. Shelly’s app and cloud service can also function as its own smart home automation controller. It allows to you control multiple Shelly devices from anywhere and combine their actions into automation scenes.

Shelly makes a wide range of smart home devices. They are perhaps best known for their powerful and reliable smart Wi-Fi relays, which was my introduction to Shelly products. Belying their power, these relays are diminutive and can be used in all kinds of situations. I use them as light switches, gas fireplace controllers, garage door openers, and more.

As I mentioned before, Shelly makes more than relays. The table below isn’t meant to be exhaustive but is illustrative of Shelly’s product line. Most products are Wi-Fi capable. I’ve noted additional capabilities below

Shelly Product Types

Another way to look at the products and their diversity is by learning just how much of your smart home you can build with Shelly products.

Overview of Home Assistant

Home Assistant has been my smart home hub of choice for over 5 years. It has grown and improved with each release and it is the perfect smart home hub for me. I’ve used it to integrate with many smart home ecosystems and create all kinds of wonderful automations. But, what exactly is Home Assistant, and what makes it great?

Home Assistant is a powerful, open-source home automation platform designed to centralize control of various smart devices within your home. It offers robust customization, allowing users to create tailored automations that enhance convenience, security, and energy efficiency.

It’s compatible with most smart home products you’ll encounter. This allows it to provide a unified interface to manage them all. Although much of the configuration and automations can be created in the user interface, its flexibility extends to advanced users through YAML configuration, as well as integration with third-party services like Google Home and Amazon Alexa for voice control.

It has a focus on local control and privacy. Home Assistant ensures your smart home operates reliably and securely without reliance on cloud services.

Integrating Shelly products using the official Home Assistant integration

If you use both Home Assistant and Shelly, or if you are considering one and using the other, you’re going to want to integrate the two to make the most of both of them. Now that we’ve covered what Shelly and Home Assistant are let’s get to how to integrate these wonderful products.

Install Home Assistant first

Assuming you already own some Shelly products, you’ll need to have a working Home Assistant setup. Home Assistant can be installed in many ways. Their installation documentation walks you through your options, but I’ll summarize them here in case it helps.

1. Home Assistant Green – This is by far your easiest option. It is from the makers of Home Assistant and comes with Home Assistant pre-installed. All you have to do is go through the setup process. This is as official as it gets.
2. Home Assistant Yellow – If Home Assistant Green is all put together for you and plug and play, then Home Assistant Yellow is like the Lego version of that. You start with a base kit, add pieces (e.g., RAM, hard drive), and then is time to play. You have a few more options on particular capabilities you may want.
3. DIY Install — You can install Home Assistant on your own hardware. A Raspberry Pi will do, but so will other hardware, and I’ve made a list of good options for you.

Integrate Shelly products with Home Assistant

Integrating Shelly products with the official Home Assistant integration is a snap. There are a couple of nuances to pay attention to, and I’ll point them out here.

Step 1: Get the Shelly device on your network

First things first, you need to get your Shelly device set up. The easiest method is to use the Shelly Smart Control app to set up the devices. The app will walk you through setting up your device, which will include getting the device on your Wi-Fi network.

You can also do it using a mobile device and web browser. The process is mostly the same regardless of the Shelly device, but the interfaces may be different depending on the generation of the Shelly device. This method isn’t quite as straightforward as the app so I’ll give some brief instructions below.

Connect to the Shelly’s Internal Web Server

Upon supplying Shelly devices with power they will broadcast a Wi-Fi access point network for you to connect to. It is usually in the form of ShellyDeviceType-XXXXXXXX. It won’t require a password.

After connecting your mobile device to the Shelly’s access point, point your mobile device’s web browser to the Shelly universal default web address — 192.168.33.1. You’ll be presented with a web interface that will differ a bit if you use a Gen 1 or a later-generation device as seen below:

Connect the Shelly to your Wi-Fi network

• For Gen 1 devices go to Internet & Security->Wi-Fi Mode - Client and enter your Wi-Fi credentials, select “Connect the Shelly device to an existing WiFi Network” and click “Save“
• For later gen devices to go Settings->Wi-Fi and select your Wi-Fi network and enter its password. Click “Enable” and then click “Save settings“

At this point, your Shelly device will be connected to your Wi-Fi network. You can find its IP address by checking your router and/or Wi-Fi access point settings.

For later-generation Shelly devices you may want to also make sure the access point is turned off. You can do this by going to Settings->Access Point and uncheck the “Enable” and click “Save settings.“

Further configuration for Gen 1 Devices

As specified in the Home Assistant Shelly integration documentation, generation 1 Shelly devices need to use the CoIoT protocol. Battery-powered devices won’t work properly without this step.

You can configure this in the Shelly device web interface by going to Internet & Security > ADVANCED - DEVELOPER SETTINGS, and checking the “enable CoIoT box and then putting in the IP address for your Home Assistant installation with port :5683 and click “Save” as seen below:

Further configuration for later-generation battery-powered devices

Also specified in that same documentation is some additional configuration for later-generation Shelly devices. You need to enable to RPC protocol for battery-powered devices. To do this, go to your Shelly device’s web interface. Then navigate to Settings >> Connectivity >> Outbound WebSocket and check the box “Enable.” Under server enter the following address: ws:// + Home_Assistant_local_ip_address:Port + /api/shelly/ws like below. Make sure to hit “Save settings.“

Step 2: Adding the Shelly device to Home Assistant

In most cases, your Home Assistant installation will automatically discover your Shelly device once it is on your network and it will look like this in the Home Assistant interface:

You can either follow the notifications or navigate in Home Assistant to Settings->Devices & Services-> Integrations where you will see the screen with the “Configure” button above. Press that button and you will see a screen similar to below:

Click the “Submit” button at the bottom right of that screen and you’ll be presented with a screen similar to below indicating the device is setup!

You are ready to start using the device in Home Assistant at this point! You should now have a device screen similar to below, depending on what Shelly device you just integrated with Home Assistant (this one is for a smart plug).

If for some reason your Shelly device is not automatically detected in Home Assistant you can add it manually. In Home Assistant, navigate to Settings->Devices & Services-> Integrations and then click on the “+ ADD INTEGRATION” button at the bottom right of the screen. Search for and select the Shelly integration as seen below:

Then you’ll need to simply enter your Shelly device’s IP address and setup will proceed as specified above.

Important things to note:

• Battery-powered devices may need to be activated to access their web interface and configuration.
• Make sure the Wi-Fi network you add your device to can reach your Home Assistant installation (be wary of adding to guest networks or other networks with isolations)
• At the time of this writing, Shelly devices primarily work on 2.4 GHz networks.
• If you add a password to your Shelly interface before integrating the device with Home Assistant, you’ll need to know that password to set up the integration. If you add a password after setting up the Home Assistant integration you’ll need to reconfigure the Home Assistant integration to use that password or it may stop working.
• I recommend keeping your firmware up-to-date on Shelly products (well, any IoT device). A good time to check your firmware is right after you get the device on your network. You can upgrade the firmware through your Shelly web interface. Also Home Assistant will notify you that the firmware needs to be updated, and you can update it directly from Home Assistant.

Other methods of integrating Shelly products with Home Assistant

The native Home Assistant Shelly integration is likely all you’ll ever need as it is fully-featured and well-maintained. However, I’ll mention a couple of other integration options you may hear about or run into.

• MQTT — Back in the old days (a few years for tech) an official Home Assistant Shelly integration didn’t exist. Shelly supports MQTT, and that’s what I initially used to integrate a Shelly 1 and a Shelly RGBW2 LED controller, and a couple of them are still implemented that way. You can learn more about how I set up MQTT with Home Assistant here.
• ShellyforHASS — The most important thing you need to know about this method is that it is discontinued and unmaintained. You may still see references to it and find it in the Home Assistant Community Store (HACS) but you shouldn’t use it. The official Home Assistant integration has replaced it.
• Z-Wave — Shelly now produces Z-Wave devices and of course Home Assistant supports Z-Wave. Shelly Z-Wave devices are handled by Home Assistant’s Z-Wave integration like other Z-Wave devices, so I won’t go into details of how that works here. However, you can learn more about how Home Assistant’s Z-Wave integration has worked for me here.

Important note: MQTT and Cloud

• For some Shelly devices, you can’t have cloud capabilities and MQTT enabled at the same time.

Creating automations in Home Assistant

Automations are the key to making a smart home… well… smart. Smart home controllers centralize where you can manually and remotely control devices. However, their true power comes in allowing you to create activities that happen automatically based on inputs and conditions. Shouldn’t your exterior smart deadbolts lock when you arm your alarm away? Shouldn’t your nighttime exterior lights turn on when it gets dark, and off at sunrise on their own? That’s where writing automations comes in.

The simplest way to create automations in Home Assistant is to use the automation builder which works with Shelly and any other devices in Home Assistant. Let’s walk through making a simple automation that turns a light on at dark.

Editor’s note: This section just scratches the surface of automations. Look at the resources at the end of this article for more in-depth information about creating automations.

Example: Turning on the patio light at night

Let’s say I have a Shelly relay that controls my patio light switch (I really do have this). What I want is an automation that turns it on at sunset each night.

1. Go to Settings > Automations & scenes and make sure you are on the “Automation” tab. If you’ve created automations before you’ll see them all here.
2. Click the “+ CREATE AUTOMATION” button at the bottom right of the screen and select “Create new automation.”
3. At this point, you need to think about your automation. What will be the trigger (what makes this automation run) and then what will it do when it runs (the action)? In our case, the trigger will be when it is sunset, and what it will do is turn the patio light on.
4. Click on “+ ADD TRIGGER.” There are tons of trigger options, since we are looking for sunset let’s just search for sun.

Select “Sun” and then you’ll get some options. We want the lights to come on about 15 minutes before sunset. So, select “Sunset” as the event and put in -15 minutes as the offset as seen below:

5. We don’t need to worry about conditions for this automation so we can get right to the action. Under the “Then do” section click on “+ ADD ACTION.” Search for “service” and then select “Call service” as the action. In the window that appears, type in “light” for the service and then select “Light: Turn on.” Then click on the “+ Choose entity ” and choose the entity that represents my patio light which. I could select more lights here if I wanted to, or even create more actions, but let’s keep this simple:

Then you simply select save and name the automation. At 15 minutes before sunset, my patio light will turn on!

Creating Automations using YAML

You can write automations in a computer language called YAML in two ways. One is to edit automations in YAML via the UI. Go to Settings > Automations & scenes and make sure you are on the “Automation” tab. Select an automation and then click the three dots menu at the top right and choose “Edit in YAML.”

Another way is to write them from scratch and put them in your configuration.yaml file. Let’s take a look at what the YAML code would look like for the automation we created in the UI:

automation:
  - alias: 'Turn on Patio Light 15 Minutes Before Sunset'
    trigger:
      - platform: sun
        event: sunset
        offset: '-00:15:00'
    action:
      - service: light.turn_on
        target:
          entity_id: light.patio_light
    mode: single

Creating basic Home Assistant dashboards

Creating custom dashboards in Home Assistant is a powerful way to visualize and control your smart home setup. Dashboards provide a user-friendly interface where you can monitor the status of your devices, execute automations, and receive important notifications at a glance. In this section, we’ll show you the basics of creating a Home Assistant dashboard.

The steps to create a dashboard are as follows:

1. Go to Settings -> Dashboard. Most likely you’ll want to select the option to create a dashboard from scratch.
   • You’ll then be asked to give the dashboard a name and an icon. You can also decide if you want the dashboard to be visible in the sidebar and if you only want admin users to view it.
2. Open your new dashboard and at the top right of the screen select the pencil icon to edit your dashboard.
   • Here you can change the name of your dashboard and create different “views” or tabs. These tabs can be named and can have different layouts (view types). I recommend using the “Sections” layout for most tabs. It is more flexible and easier to reconfigure than the other types.
3. At this point you can add cards that allow you to control and view devices and entities on your dashboard.
4. You can also position these cards how you want on each dashboard.

Editor’s note: One of the best ways to become more proficient at building Home Assistant dashboards is to use their dashboard demo editor. There you can play with many dashboard options without fear of messing anything up.

Home Assistant dashboards are extremely powerful and very customizable. To go over all the options would require a series of articles. This section is just intended to introduce you to them.

Voice assistant integration (via Home Assistant)

Integrating Shelly devices with Google Assistant and Alexa via Home Assistant is best done through Nabu Casa, which is Home Assistant’s official cloud solution and integration. Before I discuss this any further, I want to note that this service isn’t free. They offer a free 31-day trial, but you can learn more about their very affordable pricing here. I pay for this service willingly for two primary reasons:

1. It supports Home Assistant development.
2. It securely enables voice assistant integration, remote access to my Home Assistant controller, and multiple text-to-speech options.

Alright, let’s get to how to set up voice assistant access through Nabu Casa.

Editor’s Note: If you want to learn how to integrate with Siri voice control see the Integration with Apple HomeKit section later in this article.

Step 1: Enable Home Assistant Cloud

The official instructions for doing this are detailed here, but I’ll summarize for completeness hear.

1. After you’ve signed up for Nabu Casa head over to your Home Assistant interface and go to Settings -> Home Assistant Cloud.
2. Sign in to your Nabu Casa account
3. That’s it!

Step 2: Enable voice assistant(s)

Instructions for Alexa are here, and instructions for Google Assistant are here, but I’ll summarize both here for completeness.

For Alexa:

1. In Home Assistant, go to Settings -> Voice Assistants, and enable Alexa
2. On the “Expose” tab, expose at least one entity to Alexa. You can do this by clicking on an entity and selecting Amazon Alexa.
3. Go into your Alexa app and activate the “Home Assistant Smart Home” skill.
4. Tell Alexa to discover new devices (i.e., tell Alexa “Alexa, discover new devices”).
5. You’re done!

For Google Assistant:

1. In Home Assistant, go to Settings -> Voice Assistants, and enable Google Assistant
2. On the “Expose” tab, expose at least one entity to Google. You can do this by clicking on an entity and selecting Google Assistant.
3. Activate the “Home Assistant Smart Home” skill.
   • If you have a Google/Nest Home device use the Google Home app. Select the plus icon in the upper left corner, and then “Set up device”, and “Works with Google.” Then search for Home Assistant Cloud by Nabu Casa and add it.
   • If you only have a mobile phone, launch Google Assistant, and select the three dots menu. Under Settings, you’ll find Home Control, and from there you can add Home Assistant Cloud by Nabu Casa using the Add devices option.
4. You’re done!

Important note: Naming devices for voice assistants

It is important to use clear and distinct entity names when you use voice assistants. Try to give your devices simple and easy-to-remember names that don’t sound like the names of other devices that you control via voice. The more devices you control by voice the more difficult this becomes, but it also becomes increasingly important.

Voice assistant integration (via Shelly Smart Control App)

If you don’t want to pay for Nabu Casa or are only interested in voice control for Shelly devices, you can simply use their app to integrate with voice assistants. You’ll need to add all of your Shelly devices to the app first.

Google Assistant integration

1. Download the Shelly Smart Control application from your app store and add your Shelly devices if you haven’t already.
2. Open the Google Home application. Go to “Settings” and then select “Works with Google“. In the “Search” field type: “Shelly Smart Home” and click on it. Google will open the “my.shelly.cloud” – login page.
3. Once you log in to your account, the verification linking process will start.
4. When the linking process is done, all available devices will be displayed on the screen. Press “Done”
5. All your Google Home-enabled devices will be ready to control your Shelly devices.

Amazon Alexa integration

1. Download the Shelly Smart Control application from your app store and add your Shelly devices if you haven’t already.
2. Open your Alexa app and go to the skills tab.
3. Then in the search field, type “Shelly Smart Control”, click on it, and press “Enable to use”.
4. When the “Enable to use” button is clicked, Alexa opens the “my.shelly.cloud” – login page.
5. Log in to your account and the “Discovery device” process will start. You will see an “Alexa is looking for devices” message.
6. When the “Discover devices” process ends, you will see a message with information on how many new devices have been found. Then, all your Alexa-enabled devices will be ready to control your Shelly devices.

Integration with Apple HomeKit

If you want iOS control of your Shelly devices and you use Home Assistant then you are in luck! The HomeKit Bridge integration was built just for this. It allows you to make the Home Assistant entities you select available in Apple HomeKit, and thus they can be controlled by Siri and Apple’s Home app even if they don’t have native HomeKit support.

The setup is simple. First, make sure you’ve added your Shelly devices to Home Assistant. In Home Assistant, navigate to Settings->Devices & Services-> Integrations and then click on the “+ ADD INTEGRATION” button at the bottom right of the screen. Search the “HomeKit” integration. Initially, it will show you the choice of Apple:

Click on “Apple” and select the HomeKit Bridge integration (not the HomeKit Device) as seen below:

You will then see a screen with a dropdown that allows you to select the Home Assistant entities your HomeKit set up will see by domain. Select any domain that has devices you want controllable via HomeKit.

After you click submit you’ll be presented with a new card displaying a pairing QR code and PIN code, which you can also find via the Home Assistant notifications (bell icon) in the UI. You then open up the Apple Home app, select “Add Accessory” and scan the QR code or enter the PIN code. Follow the steps in the app and then your Home Assistant devices will be available through Apple’s Home and Siri.

Important things to note:

• If you move your Home Assistant installation to a different machine and want to retain your HomeKit pairing you’ll want to make sure you copy over the .storage/homekit.* file inside your Home Assistant configuration directory. Make sure to stop Home Assistant before you copy this file.
• The HomeKit Accessory Protocol only allows for 150 unique devices, or “accessories.” If you have more than this you’ll want to create multiple bridges and split your devices between bridges.

Troubleshooting and tips

Most of the tips are somewhere in this guide. However, it is a long guide! Here are a few things that come up over and over again for users.

• If you have a battery-operated Shelly device that isn’t updating in Home Assistant, make sure you’ve enabled CoIoT if it is a Gen 1 device or configured RPC if it is a later-generation device. Instructions are above.
• When integrating with voice assistants be sure to use distinct and simple names for your devices to avoid confusion.
• As you update Home Assistant, sometimes things change and/or need to be reconfigured. Be sure to read through the release notes before upgrading to avoid surprises.
• You can upgrade Shelly device firmware through Home Assistant. Home Assistant will notify you when this needs to happen. You can also check the Shelly devices for new firmware updates by logging into their web interface.
• If you add a password to protect the web interface of a Shelly device after it is added to Home Assistant and it stops working in Home Assistant, you may need to delete and re-add the Shelly device so the integration can ask for the password.

Additional resources

I used a myriad of resources to put this article together, and I’ve produced many Shelly articles in the past. Here is a listing of Home Assistant and Shelly resources that may be of interest to you:

Select HomeTechHacker Shelly articles:

Additional Shelly resources:

Select HomeTechHacker Home Assistant articles:

Additional Home Assistant resources:

Other resources:

Final thoughts

By mastering the integration of Shelly devices with Home Assistant, you unlock a world of possibilities for your smart home. With the flexibility of Home Assistant and the versatility of Shelly products, you can create a seamless, reliable, and highly personalized smart home experience. Keep experimenting, customizing, and expanding your setup to continue optimizing your living space.

At HomeTechHacker we aim to make home tech simple and help you make the most of your home technology. We hope this guide helps you take a big step in that direction.