Sonoff RF Bridge – How To Setup with Home Assistant

The Sonoff RF Bridge is a great little device for sending and receiving RF signals when used with Home Assistant. There are many different types of RF enabled devices/entities such as strip lighting (or holiday lights), and also some RF-enabled sensors such as the motion detection sensor that we’re going to use in this tutorial.

In this tutorial, I will be configuring the Sonoff RF Bridge for use with Home Assistant (current version as of the writing of this article is v2021.6.2). This article assumes that you already have Home Assistant up and running and working properly. In addition to setting up the RF Bridge, we will also be configuring the bridge to work with an RF LED strip light and RF motion sensor. We’ll ultimately end up with some automations and scripts that turn on the LED strip lights with the motion sensor, but this is just an example – you could do the same thing by using the RF Motion Sensor to turn on some Hue lights, or toggle a fan on and off as you enter a room – you’re only limited by your imagination!

Products Used in this Tutorial

Sonoff RF Bridge ($15.99): https://geni.us/KGFSJ
Sonoff PIR Motion Sensor ($17.19): https://geni.us/fc3EC5
RF Strip lights: https://geni.us/mzG1xGq
(any RF-controlled lights will work – these are just an example)

Raspberry Pi kit for running Home Assistant: https://geni.us/uBklg

Prerequisites

• Sonoff RF Bridge
• Sonoff PIR Motion sensor
• Any RF lighting / strip lights / holiday lights
• An Apple or Android smartphone
• Home Assistant server installed and operational
• Home Assistant should have HACS (Home Assistant Community Store) installed
• Home Assistant should have some sort of file editor installed (or you can use Samba)

Install the eWeLink app to your smartphone

The Sonoff RF Bridge and related equipment works in conjunction with the eWeLink app for Apple or Android. You can search for ‘eWeLink’ in either the Apple App store or the Google Play store to find and install it.

Apple App store: https://apps.apple.com/us/app/ewelink-smart-home/id1035163158
Google Play store: https://play.google.com/store/apps/details?id=com.coolkit&hl=en_US&gl=US

Once the app has been installed, you will be asked to create a login. Remember your login email and password! We will be using these later in the tutorial.

Adopt the RF Bridge into eWeLink

Once you have your eWeLink app working, plug in the Sonoff RF Bridge so that it powers up. When it is ready for adoption, you will see 2 short blinks followed by a long blink. This is the ‘ready’ code. If you let it sit too long (300 seconds), it will stop blinking – to get it to blink again, simply either unplug/re-plug the power, or stick a paperclip into the ‘reset’ hole at the back of the device (next to where the power plugs in) for 10 seconds.

Before you add the device, you’re also going to want to ensure that your phone is on the correct wireless network for your IoT devices. If you have a separate IoT network, connect to it now before adoption so that the RF Bridge ends up in the correct network.

Click the + sign at the bottom of the eWeLink dashboard to add a new device, and then choose Quick Pairing.

Then select ‘Add one device.’

On the next screen, select your WiFi network and enter in the password – click Next.

Place your phone near the RF Bridge, and you should see it start to adopt. Mine took about 20 seconds, and then I received the ‘Device added successfully’ screen. Give your device a useful name (you can change this later) and then click ‘Done’ and you will get a notice that your device is connecting to WiFi and it may take a few mins to get online.

Once the RF Bridge is online, the LED on the top side of the RF Bridge will be solid blue, and it will show up in the eWeLink dashboard.

Add LED Strip Lights to RF Bridge

Moving right along! Now that we have our RF Bridge showing up in the eWeLink dashboard, it’s time to add our first device. In my case, I’m using an LED strip light that came with an RF remote control. First, click on the RF Bridge in the eWeLink dashboard.

Next click ‘Add.’

Since our remote control has both an ON and OFF button (plus a bunch of other buttons we’re not going to use in this tutorial), we’ll want to select ‘2-button’ and then click ‘Save.’

Once you click ‘Save’ you’ll hear a little ‘beep’ from the RF Bridge. You now have 60 seconds to press a button on the RF remote – I’m going to press ON first. You should hear 2 beeps from the RF Bridge indicating that it received the ON RF signal. (You may have to press the button a few times to get it to register). After the 2 beeps, eWeLink redirects you to the RFBridge detail page, and you should now see a new ‘My Remote’ section with 2 buttons (only one of the buttons will show blue since we have only programmed one of the buttons so far):

At this point, if you turn off your LED strip light with the remote control, and then hit the blue button labeled ‘Button1’ your LED strip lights should turn on – magic!

So – we’re off to a great start, but the labels on the buttons and the new device are pretty generic. Let’s fix that.

Edit the ‘My Remote’ by clicking on the edit icon (the pencil). Change ‘My Remote’ to something more useful, and then change the button labels as well. I named mine ‘RackLED1’ and the buttons ‘ON’ and ‘OFF.’

Now that we have our remote and buttons named, let’s add the ‘OFF’ functionality to this remote. Long press the ‘OFF’ button on the remote (the grey one) and the RF Bridge will beep indicating that it’s ready to receive a signal. Then press the ‘OFF’ button on the LED strip light remote, and you will hear 2 beeps from the RF Bridge.

At this point, if you click on your RF Bridge, you will see that both buttons are blue – try ’em out! They should now work to turn on and off your LED strip light. Notice when you trigger any RF function, the 2nd LED on the RF Bridge blinks red – this means that the RF Bridge is sending that signal (it also blinks red when it receives an RF signal).

Add the PIR Motion Sensor to eWeLink

First, you’ll want to unpackage the PIR Motion sensor, add some batteries (mine takes 2xAAA batteries), and place it somewhere near the RF Bridge.

Now let’s add another device to eWeLink – the PIR Motion Sensor. From the dashboard of eWeLink, click on your RF Bridge, and then click the + (add) symbol in the bottom right.

Choose ‘Alarm’ and click ‘Save.’

The RF Bridge will give a little ‘beep’ indicating that it’s ready to receive input. Wave your hand in front of the PIR Motion Sensor, and you’ll hear 2 beeps from the RF Bridge indicating that it has been set up.

In the eWeLink app, you should now see a new item ‘My Remote’ with no buttons.

If eWeLink is being annoying and giving you an alert pop-up every time the motion sensor detects motion, you can click on the 3 dots in the upper right hand corner and then turn off Alarm Notification.

Just like with the LED strip light remote, you’ll want to give this motion sensor a meaningful name. Click the ‘edit’ button next to the ‘My Remote’ section and rename it. I’m using ‘Motion1’ as the name of my motion sensor.

That’s it for eWeLink – we’re all set up and ready to integrate into Home Assistant!

Buy Sherwood a beer – cheers!

Did this work for you so far? EXCELLENT! Love to hear that – if you appreciate this documentation, make sure you:

Install Sonoff integration via HACS

Log into Home Assistant and click on HACS. If you don’t have HACS installed (Home Assistant Community Store), you will need to install it. How to install HACS is beyond the scope of this tutorial, but if you Google search ‘How to install HACS’ you’ll find plenty of articles and videos on how to do so.

Click on HACS and then click on Integrations.

Next click the blue ‘Explore & Add Repositories’ blue button in the bottom right-hand corner.

Type ‘Sonoff’ in the search bar and then click on the ‘Sonoff LAN’ application.

Click ‘Install this Repository in HACS’ at the lower right.

Click ‘Install’ on the next screen.

Once the Sonoff LAN integration has been added via HACS, we next need to tell it to use our eWeLink credentials to download its configuration.

Once Sonoff LAN has been installed, you will need to restart Home Assistant. Click on Configuration, and then scroll down to Server Controls. Click ‘RESTART’ under ‘Server Management.’ The restart should take between 30-60 seconds to complete.

*** NOTE: The Sonoff LAN integration has many different ways to connect with eWeLink and work with your devices – we are going to use the ‘Local and Cloud mode’ since it is generally recommended for most users, however there may be situations where you want Cloud-only mode or Local-only mode. Read the Config Example section on the Sonoff LAN instructions page to figure out how to change to a different mode if you want.

Once the server has restarted, use your file editor to edit the config/configuration.yaml file. Add the following to the bottom of that file:

# Sonoff RF Bridge / eWeLink application
sonoff:
  username: your@email.com
  password: your eWeLink password
  reload: always # update device list every time HA starts

*** NOTE: Home Assistant configuration files are in YAML format, which means they are extremely picky about spacing and indentation. In the case above where you see some of the lines indented, those are indented by 2 spaces. Refer to the Sonoff LAN instructions page for exact spacing of configuration items.

And – if you ever run into a situation where it *seems* like your automations, scripts, or integrations should be working, but they’re not – double and triple-check the spacing and indentation in YAML…it’s the likely culprit.

*** NOTE: You can download all examples used in this documentation on our github page here: https://github.com/chriscrosstalk/sonoffrfbridge

Replace the username and password with your eWeLink credentials. The line that says ‘reload: always’ is optional – this basically means that each time Home Assistant restarts, you are also pulling down the eWeLink configuration. Once you’re past the initial setup of your RF devices, you can comment out or delete that line. You will want to have it in there if you add any more RF bridges to eWeLink though.

We will need to restart Home Assistant again, but before we do – since we made changes to one of the YAML files, let’s click the ‘Check Configuration’ button first to make sure our config is valid. If you don’t receive any errors, you’re clear to restart HA.

Now that HA has been restarted, if you go to Configuration –> Entities, and then search for ‘sonoff’ you should see your RF Bridge show up – make note of the Entity ID as we will be using this in our scripts and automations.

Create an RF Automation

OK, so great…we’re done right? HELL NO! We’re just getting started…we have the RF Bridge in Home Assistant, but now we need to make it do stuff.

The first thing we’re going to do is create an automation that will pop a notification in Home Assistant any time the RF Bridge does something. This way, we’ll know the ‘commands’ and names of our devices so that we can use them in automations.

Use your file editor to edit the config/automations.yaml file. Copy and paste this into the bottom of that file:

- id: '1621138990255'
  alias: Sonoff RF Receive
  trigger:
    platform: event
    event_type: sonoff.remote
  action:
    service: persistent_notification.create
    data_template:
      title: Sonoff RF Receive
      message: |-
        Name: {{ trigger.event.data.name }} 
        Command: {{ trigger.event.data.command }} 
        Time: {{ trigger.event.data.ts }}

Again – be very careful about the spacing for the YAML entry. So – just what exactly are we doing here? Well – it’s pretty simple. First, we’re giving this automation a random ID (make sure the 13 digit number doesn’t overlap with any of your existing automations) so that we can control this automation from within the Configuration –> Automations section of Home Assistant.

*** NOTE: You can download all examples used in this documentation on our github page here: https://github.com/chriscrosstalk/sonoffrfbridge

Then, the automation has two parts – the trigger, and the action. The trigger in this case is any event of type ‘sonoff.remote.’ That means basically “anytime ANYTHING happens with this sonoff.remote event type, do the following action.”

The ‘action’ that we’re doing is creating a notification in Home Assistant titled ‘Sonoff RF Receive’ with a message body that will tell us the device name that created the event, the command that it is associated with (more on this later), and the time/date of the event.

In order to try this out, we’ll need to restart Home Assistant again. Or, in this case, since we just modified the automation.yaml file, we should be able to just reload our automations by going to Configuration –> Server Controls and then clicking on ‘Automations’ under YAML configuration reloading. If you don’t see ‘Automations’ in that section, then just do a full restart of HA like we have done previously.

Click ‘Check Configuration’ first to ensure that your YAML is properly formatted, and then restart HA or just the Automations YAML file.

Let’s test it out! If you now click on Configuration –> Automations in Home Assistant, you should see a new automation titled ‘Sonoff RF Receive.’ (Make sure that it is enabled). If you now wave your hand in front of the motion sensor, you will see a yellow circle show up near ‘Notifications’ in the bottom left-hand menu. Every time the motion sensor detects motion, it will pop a notification.

Let’s take a closer look at those notifications by clicking on ‘Notifications.’

Here we can see some notifications already stacking up. Every time the motion sensor senses motion, a notification event is generated.

Side note – you’ll probably want to turn this off after a while…it’s excellent for troubleshooting and debugging, but can get quite annoying to see 1000 unnecessary notifications in Home Assistant.

The title of the notification is ‘Sonoff RF Receive’ which comes from the ‘alias’ variable in our automation YAML. Then we’re displaying ‘Name,’ which is the name of the RF motion device in eWeLink, as well as ‘Command,’ which is basically the unique ID of the sensor or element in eWeLink. We are able to call up other scripts and automations using either the Name or the Command, which we will see when we create some automations shortly.

The Command variable is automatically assigned by eWeLink, and starts from 0. So, since we added our RF LED strip light remote control ON button first, that became Command 0. Then the OFF button was Command 1, and finally the RF Motion Sensor was the 3rd device that we added to eWeLink, so it became Command 2.

While we’re looking at our notifications, let’s now press the ON and OFF buttons from our LED strip light remote control:

We can now see the name as well as the command code for each of those button presses.

Create some scripts and buttons

Great – so what can we actually do with this information now? Let’s start by creating scripts for turning our lights on and off. Copy and paste the following into the bottom of your config/scripts.yaml file:

send_rf_button1:
  alias: Send RF Button1
  sequence:
  - service: remote.send_command
    data:
      entity_id: remote.sonoff_1001108bb1
      command: 0
  mode: single
  icon: hass:lightbulb
send_rf_button2:
  alias: Send RF Button2
  sequence:
  - service: remote.send_command
    data:
      entity_id: remote.sonoff_1001108bb1
      command: 1
  mode: single
  icon: hass:lightbulb

What exactly are we doing here? First, we’re creating two different scripts called ‘send_rf_button1’ and ‘send_rf_button2.’ We are then using the ‘remote.send_command’ service to send a command to our entity, which is ‘remote.sonoff_1001108bb1’ (the Sonoff RF bridge). The Command that we’re sending is command 0 to turn on our LED strip light, and command 1 to turn it off.

If you don’t know your Sonoff bridge entity ID, you can always look it up by going to Configuration –> Entities, and then search for ‘sonoff’ – it should pop up for you.

Once you have put this code into your scripts.yaml file, we’ll need to reload Home Assistant (or also just reloading the scripts should work). Once reloaded, go to Configuration –> Scripts, and you should see your new script items!

Try ’em out! They should work to turn the LED strip light on and off when you click the ‘Play’ button to the left of the light bulb. That light bulb by the way came from the ‘icon’ variable in the script that you copied and pasted. You can change that if you like.

What can we do with these scripts? Well – one of the easiest things to do would be to add a button to a dashboard. Open a dashboard that you want to edit – in my case, I’m going to edit my ‘Office’ dashboard that controls stuff here in my home office.

First I will click the 3 dots in the upper right-hand corner of the dashboard and select ‘Edit Dashboard.’ Then I will click the blue ‘ADD CARD’ button in the bottom right. The way that you add buttons can be done many different ways, but I am going to use a horizontal stack to create an ON and OFF button card.

Add the first button by clicking on Button. For the Entity ID, search for the script that you created. The name of my script was ‘send_rf_button1.’ You can give the button a friendly name like ‘LED Lights ON.’ Your button card should now look like this:

Next, click the ‘+’ (plus) icon near the middle of that page to add a 2nd button to the horizontal stack. Repeat the same process you used with the first button, but choose the script for turning the LED light OFF instead. Once complete, click ‘SAVE.’

On your dashboard, you should now have two buttons next to each other – one for turning ON the LED strip light, and one for turning OFF the LED strip light. Try ’em out!

Create a motion sensing automation

OK – so now it’s time to tie everything together. We have the motion sensor detecting motion in Home Assistant, and we now have two scripts for turning lights on and off. But what if you wanted those lights to come on with the RF motion sensor? Let’s do that next.

The first thing we need to do is tell Home Assistant what type of device our motion sensor is – it’s a motion sensor of course! But HA doesn’t know that by default.

Open up your file editor and edit the config/configuration.yaml file. We’re going to add a few more lines to the ‘sonoff:’ section:

# Sonoff RF Bridge / eWeLink application
sonoff:
  username: your@eWeLink.email
  password: your eWeLink password
  reload: always # update device list every time HA starts
  rfbridge:
    Motion1: # sensor name in eWeLink application
      device_class: motion
      timeout: 60 # optional (default 120), timeout in seconds for auto turn off

The ‘new’ stuff that we’re adding is the line starting with ‘rfbridge:’ and everything below it. This section of code is basically saying that we’re adding a new device ‘Motion1’ (substitute this with the actual name of your RF motion sensor in eWeLink), and that that device’s class is ‘motion.’

We’re also giving the motion sensor a timeout value of 60 seconds. You can change this to whatever you want. Essentially, when motion is triggered, the motion sensor goes into an ‘on’ state, and then after the timeout period (in this case, 60 seconds), it reverts back to an ‘off’ state. Each time it detects motion, that 60 second timer is reset – so if you have this motion sensor in a room where you’re moving around a bit, it should keep the lights on until 60 seconds after you actually leave. Your mileage may vary though, and you may have to adjust the timeout setting until it works just right.

Save the configuration.yaml file and now let’s edit config/automations.yaml. Add the following two automations to the bottom of the file:

- id: '1622613626154'
  alias: RF LEDs on with motion
  description: 'RF LEDs on with motion'
  trigger:
  - platform: state
    entity_id: binary_sensor.motion1
    from: 'off'
    to: 'on'
  action:
  - service: remote.send_command
    target:
      entity_id: remote.sonoff_1001108bb1
    data:
      command: 0

- id: '16226136486155'
  alias: RF LEDs off after 30 seconds
  description: 'RF LEDs off after 30 seconds of no motion'
  trigger:
  - platform: state
    entity_id: binary_sensor.motion1
    to: 'off'
    for: '00:00:30'
  action:
  - service: remote.send_command
    target:
      entity_id: remote.sonoff_1001108bb1
    data:
      command: 1 

WOW! That is a lot to take in. What exactly is happening here? Let’s take these scripts line by line. First – the id: is a unique identifier for Home Assistant – this 14 digit number can really be anything as long as it is unique to each automation. You can just re-use the id’s that I have in my example assuming that you don’t have any other id’s of with matching digits. Having a unique ID allows you to edit and enable/disable these automations in HA’s Configuration –> Automations section.

Alias and description is basically just naming the automation. Then we have the triggers and the actions. Triggers are exactly what they sound like – basically telling HA to run this automation when X happens. For the first automation, it is a state change. We’re saying ‘when binary_sensor.motion1’s state changes from ‘off’ to ‘on’ then perform the following action. Or in other words – when we detect motion, do this.

The action that we’re doing when motion is detected is running entity RF Bridge command 0 (turn ON LED strip light).

The second automation is very similar to the first one – except in this one, we’re saying that the trigger for the automation is when the motion sensor’s ‘state’ has been OFF for 30 seconds. Remember back to when we added the motion sensor as a motion device type? We gave the motion sensor a timeout of 60 seconds – and that clock resets every time motion is detected. Now, we’re saying that once the motion sensor’s timeout of 60 seconds has occurred, wait ANOTHER 30 seconds…and then perform the action RF Bridge command 1 (turn OFF LED strip light).

So, if motion is detected, the light will turn on, and then as soon as no motion is detected for 60 seconds, we will wait 30 more seconds and then turn the light off.

You could even take this automation conditional by saying ONLY run this automation between sunset and sunrise – or in other words, turn on this light via the motion sensor only at nighttime.

Hopefully this gives you a good example of how to set up and use the Sonoff RF bridge and ancillary devices – leave any comments and questions below if you run into any issues with the documentation, or if you have use case scenarios for this stuff – I’d love to see it!

Buy Sherwood another beer!

Did everything work? If you didn’t buy me a beer before, how about now? Cheers!