How to Include RFLink Radio Home Automation Devices at Home Assistant (HASS)

27 June 2017
No Comments
6 minutes

Home Assistant integrates natively the support of radio home appliances compatible with the Open Source RFLink gateway. In the previous tutorial, we saw how to include connected objects developed using the MySensors v2 library. The inclusion of radio devices using the RFLink gateway is a bit different. The technical documentation lacks details regarding the addition of devices to the groups.

RFLink gateway and hardware used for the tutorial

RFLink is an open source project that allows to realize a gateway between a home automation software and home automation devices that communicate by radio waves. This is a very economical alternative to the commercial RFXCom gateway. The RFLink project is capable of managing several 315MHz, 433MHz, 868MHz, 915MHz and 2.4GHz radio frequencies. Follow this guide to make your home radio gateway for less than €15.

For this tutorial, we will use two smoke detectors Chacon 34126 which communicate in 433MHz. They are found quite easily in DIY stores or online merchants.

Warning. Check that the radio frequency used by the device is authorized in your country before buying.

Configuring the Gateway in Home Assistant

Like MySensors, RFLink is natively supported by Home Assistant. Open the configuration.yaml file. If you installed Home Assistant in a virtual environment (recommended), run this command

sudo nano /home/homeassistant/.homeassistant/configuration.yaml

Otherwise, the file is located in the user folder

sudo nano /home/UTILISATEUR/.homeassistant/configuration.yaml

The first thing to do is to set up an RFLink Hub. The complete documentation is here. Two lines are enough

rflink:
  port: /dev/serial/by-id/usb-id01234

To find the USB port on which the gateway is connected, first connect the Arduino Mega to your computer or the Raspberry Pi. Then, in the Terminal, run the following commands to list the connected devices.

cd /dev/serial/by-id
ls
usb-Arduino__www.arduino.cc__Arduino_Mega_2560_85430353631351209040-if00

Other optional parameters can complete the configuration if necessary:

host: in case the gateway is accessible from another TCP / IP station. Follow this tutorial that explains how to do with ser2net
wait_for_ask: waits for confirmation of the execution of the previous command before sending the next command. This is the default active mode. It is slower but also more reliable
ignore_devices: it is possible to ignore radio devices. The command supports the joker (*)
reconnect_interval: waiting time in seconds between two attempts to reconnect

Warning. Home assistant crash if RFLink Gateway Is Not Connected at Startup

Enable Logger

During the debugging, it is necessary to activate the recording of the messages by the integrated logger. Create a new logger section if it does not already exist. It is possible to retrieve the radio messages as well as the messages exchanged with the gateway.

logger:
  default: error
  logs:
    rflink: debug
    homeassistant.components.rflink: debug

The logger accepts several levels of severity. The debug mode is suitable in most cases:

critical
fatal
error
warning
warn
info
debug
notset

Restart HASS

Save the file (CTRL + X then Y) and then restart Home Assistant. I recommend you restart the service from the interface by going to the Configuration panel for example or by executing this command from the Terminal.

sudo systemctl restart home-assistant@homeassistant

Follow the launch to verify that HASS is properly connected to the gateway with this command

sudo journalctl -fu home-assistant@homeassistant

You can also view the log by opening the home-assistant.log file that is in the same directory as the configuration files. here is an example

2017-05-19 12:16:05 INFO (MainThread) [homeassistant.components.rflink] Initiating Rflink connection
2017-05-19 12:16:05 INFO (MainThread) [homeassistant.components.rflink] Connected to Rflink
2017-05-19 12:16:05 DEBUG (MainThread) [rflink.protocol] connected
2017-05-19 12:16:06 DEBUG (MainThread) [rflink.protocol] received data: 20;00;Nodo RadioFrequencyLink - RFLink Gateway V1.1 - R46;
2017-05-19 12:16:06 DEBUG (MainThread) [rflink.protocol] got packet: 20;00;Nodo RadioFrequencyLink - RFLink Gateway V1.1 - R46;
2017-05-19 12:16:06 DEBUG (MainThread) [rflink.protocol] decoded packet: {'node': 'gateway', 'firmware': 'RFLink Gateway', 'protocol': 'unknown', 'revision': '46', 'hardware': '$
2017-05-19 12:16:06 DEBUG (MainThread) [rflink.protocol] got event: {'version': '1.1', 'firmware': 'RFLink Gateway', 'id': 'rflink', 'hardware': 'Nodo RadioFrequencyLink', 'revi$
2017-05-19 12:16:06 DEBUG (MainThread) [homeassistant.components.rflink] event of type unknown: {'version': '1.1', 'firmware': 'RFLink Gateway', 'id': 'rflink', 'hardware': 'Nod$
2017-05-19 12:16:06 DEBUG (MainThread) [homeassistant.components.rflink] unhandled event of type: unknown

All is correct, you can continue

Included devices: lights, switches, sensors

Now that HASS can connect to the gateway, all you have to do is add the devices to an existing group (or a new group). Unlike MySensors, radio devices are unfortunately not listed in the status panel.

The first thing to do is to retrieve the device ID. To do this, a single means, to operate the device to send a radio signal containing its identity. Press the test or command button and open the run-time log (home-assistant.log) in the same directory as the configuration files.

Here, by pressing the Chacon Smoke Detector test button, you will retrieve all the information needed to include it in Home Assistant.

2017-05-19 15:50:17 DEBUG (MainThread) [rflink.protocol] received data: 20;01
2017-05-19 15:50:17 DEBUG (MainThread) [rflink.protocol] received data: ;Slave;Debug=01 00 00 10
2017-05-19 15:50:17 DEBUG (MainThread) [rflink.protocol] received data: 00 1;
2017-05-19 15:50:17 WARNING (MainThread) [rflink.protocol] dropping invalid data: 20;01;Slave;Debug=01 00 00 10 00 1;
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] received data: 20;02;
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] received data: FA20RF;ID=40cd71;SWITCH=
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] received data: 01;CMD=ON;SMOKEALERT=ON;
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] received data:
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] got packet: 20;02;FA20RF;ID=40cd71;SWITCH=01;CMD=ON;SMOKEALERT=ON;
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] decoded packet: {'node': 'gateway', 'command': 'on', 'protocol': 'fa20rf', 'smokealert': 'on', 'id': '40cd71', 'switch':$
2017-05-19 16:37:01 DEBUG (MainThread) [rflink.protocol] got event: {'command': 'on', 'id': 'fa20rf_40cd71_01'}

The identifier is at the got event line.

The identifier is generated automatically by HASS. It is of the form protocol_id_type.

Open the configuration file again.

sudo nano configuration.yaml

Smoke detectors are managed as switches. The inclusion of a switch type device requires no special adjustment. A switch block is added with a name (used in the group). The platform is rflink. Then we list the devices (devices) connected to this block

switch sirenes:
  platform: rflink
  devices:
    fa20rf_40cd71_01:
      name: cuisine

This is the minimum configuration required. Other parameters are available to refine the management of the devices (the complete list here):

If you need to include sensors, the configuration is a bit different. It is necessary to indicate to HASS the type of sensor used. The types of sensors supported are as follows (detailed documentation):

average_windspeed
barometric_pressure
battery
weather_forecast
doorbell_melody
command
co2_air_quality
current_phase_1
current_phase_2
current_phase_3
distance
firmware
humidity_status
humidity
hardware
kilowatt
light_intensity
meter_value
total_rain
rain_rate
revision
noise_level
temperature
uv_intensity
version
voltage
watt
windchill (?)
winddirection
windgusts
windspeed
windtemp

It is the same for lights but the type is not a mandatory parameter. Here are the types of light managed (detailed documentation):

Hybrid: send a dim command followed by ON or OFF
Switchable: switchable, a classic lamp
Dimmable: light dimmer
Toogle: state inverter. Only the ON command is sent. This control may be useful for some devices such as wall switches of the brand Livolo.

Configure the group

The hardest is done, the addition of smoke detectors in a group is very simple. For example, we will create a group that presents all the smoke detectors in the house

smoke:
  name: Détecteurs de fumées
  control: hidden
  entities:
    - switch.cuisine  
    - switch.lingerie

We can add this group in the sensor view for example

sensor_view:
  name: Capteurs
  view: yes
  icon: mdi:gauge
  entities:
    - group.smoke

Save the configuration and re-start Home Assistant from the interface or by running this command

sudo systemctl restart home-assistant@homeassistant

Here, the two smoke detectors are now integrated into Home Assistant. The display is not yet perfect. The available style overload that allows you to set the sensor type via the device_class option does not seem to work for RFLink.