RFLink


The rflink integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] supports devices that use RFLink gateway firmware, for example, the Nodo RFLink Gateway. RFLink Gateway is an Arduino Mega firmware that allows two-way communication with a multitude of RF wireless devices using cheap hardware (Arduino + transceiver).

The 433 MHz spectrum is used by many manufacturers mostly using their own protocol/standard and includes devices like: light switches, blinds, weather stations, alarms and various other sensors.

RFLink Gateway supports a number of RF frequencies, using a wide range of low-cost hardware. Their website provides details for various RF transmitters, receivers and transceiver modules for 433MHz, 868MHz and 2.4 GHz.

Note: Versions later than R44 add support for Ikea Ansluta, Philips Living Colors Gen1 and MySensors devices.

A complete list of devices supported by RFLink can be found here.

This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is tested with the following hardware/software:

  • Nodo RFLink Gateway V1.4/RFLink R46

Configuration

To enable RFLink in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.[Learn more] file. After changing the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.[Learn more] file, restart Home Assistant to apply the changes. To view the changes, go to Settings > Devices & services > Entities.

# Example configuration.yaml entry
rflink:
  port: /dev/serial/by-id/usb-id01234

Configuration Variables

port string Required

The path to RFLink USB/serial device or TCP port in TCP mode.

host string (Optional)

Switches to TCP mode, connects to host instead of to USB/serial.

wait_for_ack boolean (Optional, default: true)

Wait for RFLink to acknowledge commands sent before sending new command (slower but more reliable).

ignore_devices list | string (Optional)

List of device id’s to ignore. Supports wildcards (*, ?).

reconnect_interval integer (Optional, default: 10)

Time in seconds between reconnect attempts.

tcp_keepalive_idle_timer integer (Optional, default: 3600)

Time in seconds to wait since last data packet was seen before a TCP KEEPALIVE is sent. Value of 0 will disable this feature.

Full example

# Example configuration.yaml entry
rflink:
  port: /dev/serial/by-id/usb-id01234
  wait_for_ack: false
  ignore_devices:
    - newkaku_000001_01
    - digitech_*

TCP mode

TCP mode allows you to connect to an RFLink device over a TCP/IP network. This is useful if placing the RFLink device next to the HA server is not optimal or desired (eg: bad reception).

The following command can be used to expose the USB/serial interface over TCP on a different host (Linux). The arguments are separated by spaces, further info on all arguments can be found for example on the Debian manpages.

  • /dev/ttyACM0,b57600,rawer specifies the device location, a b57600 57600 baud rate, and rawer causes socat to ignore control sequences sent via the port (for example, it makes socat pass all information ‘rawest form’, rather than picking up control characters such as control-C which would close socat).
  • TCP-LISTEN:1234,reuseaddr,range=192.168.0.0/16 listens on IPV4 on the specified port (1234, change as suits your needs), the details behind the reuseaddr option are fairly complex but it allows faster reconnects from the client (Home Assistant) in case of connection drops. An important security option is range=192.168.0.0/16, which specifies that socat should only accept connections from a certain range of IP addresses - the /16 subnet mask specifies a range from 192.168.0.0 to 192.168.255.255. Change this as required for your LAN network.
socat /dev/ttyACM0,b57600,rawer TCP-LISTEN:1234,reuseaddr,range=192.168.0.0/16

Other methods of exposing the serial interface over TCP are possible (eg: ESP8266 or using Arduino Wifi shield). Essentially the serial stream should be directly mapped to the TCP stream.

Tested with Wifi serial bridge esp-link V2.2.3 running on a NodeMCU (ESP8266 Wifi module) with ESP8266 TXD0 (pin D10) and RXD0 (pin D9) connected to Arduino MEGA 2560 RX (Pin 2) and TX (Pin 3) respectively.

Due to different logic levels, a voltage level shifter is required between the 3.3V NodeMCU and 5V Arduino MEGA 2560 pins. The BSS138 bidirectional logic level converter has been tested for serial pins and the link is recommended for the CC2500 transceiver (used for IKEA Ansluta and Philips Living Colors)

When re-flashing the Arduino MEGA, disconnect the ESP8266 to avoid programming difficulties.
# Example configuration.yaml entry
rflink:
  host: 192.168.0.10
  port: 1234
  tcp_keepalive_idle_timer: 600

Adding devices Automatically

In order to have your devices discovered automatically, you need to add the following to the configuration. When pressing the button on the physical remote, RFLink detects the signal and the device should be added automatically to Home Assistant.

# Example configuration.yaml entry
light:
  - platform: rflink
    automatic_add: true
sensor:
  - platform: rflink
    automatic_add: true

RFLink Switches and RFLink Binary Sensors cannot be added automatically.

The RFLink integration does not know the difference between a binary sensor, a switch and a light. Therefore all switchable devices are automatically added as light by default. However, once the ID of a switch is known, it can be used to configure it as a switch or a binary sensor type in Home Assistant, for example, to add it to a different group or configure a nice name.

Ignoring devices

The RFLink platform can be configured to completely ignore a device on a platform level. This is useful when you have neighbors which also use 433 MHz technology.

For example:

# Example configuration.yaml entry
rflink:
  port: /dev/serial/by-id/usb-id01234
  wait_for_ack: false
  ignore_devices:
    - newkaku_000001_01
    - digitech_*
    - kaku_1_*

This configuration will ignore the button 1 of the newkaku device with ID 000001, all devices of the digitech protocol and all switches of the kaku protocol device with codewheel ID 1.

Invert cover

Devices can be configure to work in inverted mode by adding option in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI.[Learn more]:

# Example configuration.yaml entry for inverted RTS cover
cover:
  - platform: rflink
    devices:
      # Rfloader created remote control which is used by Home Assistant
      RTS_0a0a0a_1:
        name: "Blind office"
        aliases: 
          - rts_0f1f2f_01 # ID of the remote control (Somfy smove in this case)
        type: inverted

This configuration uses 0a0a0a to control the inverted shutter (send UP to close and Down to open) and listen commands sent by 0f1f2f remote control.

Device support

Even though a lot of devices are supported by RFLink, not all have been tested/implemented. If you have a device supported by RFLink but not by this integration please consider testing and adding support yourself.

Device Incorrectly Identified

If you find a device is recognized differently, with different protocols or the ON OFF is swapped or detected as two ON commands, it can be overcome with the RFLink ‘RF Signal Learning’ mechanism from RFLink Rev 46 (11 March 2017). Link to further detail.

Technical Overview

  • Therflink Python module is an asyncio transport/protocol which is setup to fire a callback for every (valid/supported) packet received by the RFLink gateway.
  • This integration uses this callback to distribute ‘rflink packet events’ over Home Assistant’s event bus which can be subscribed to by entities/platform implementations.
  • The platform implementation takes care of creating new devices (if enabled) for unseen incoming packet ID’s.
  • Device entities take care of matching to the packet ID, interpreting and performing actions based on the packet contents. Common entity logic is maintained in this main component.

Debug Logging

For debugging purposes or context when investigating issues you can enable debug logging for RFLink with the following configuration snippet:

# Example configuration.yaml entry
logger:
  default: error
  logs:
    rflink: debug
    homeassistant.components.rflink: debug

This will give you output looking like this:

17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] received data: 20;00;Nod
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] received data: o RadioFrequencyLink - R
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] received data: FLink Gateway V1.1 - R45
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] received data: ;
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] got packet: 20;00;Nodo RadioFrequencyLink - RFLink Gateway V1.1 - R45;
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] decoded packet: {'firmware': 'RFLink Gateway', 'revision': '45', 'node': 'gateway', 'protocol': 'unknown', 'hardware': 'Nodo RadioFrequencyLink', 'version': '1.1'}
17-03-07 20:12:05 DEBUG (MainThread) [rflink.protocol] got event: {'version': '1.1', 'firmware': 'RFLink Gateway', 'revision': '45', 'hardware': 'Nodo RadioFrequencyLink', 'id': 'rflink'}
17-03-07 20:12:05 DEBUG (MainThread) [homeassistant.components.rflink] event of type unknown: {'version': '1.1', 'firmware': 'RFLink Gateway', 'revision': '45', 'hardware': 'Nodo RadioFrequencyLink', 'id': 'rflink'}