RFXtrx433 - Access your Remote USB transceiver plugged to an OpenWRT device

Contents[Hide]

dropcap rfxtrx433If you are involved in some domotic project, you must know RFXtrx433E. This fantastic USB 433.92MHz Transceiver enables your domotic server to talk to most of 433MHz device on the market. But it has a maximum range of 20-30 meters in a typical indoor configuration. So, like your WiFi router, it should be placed in the middle of your home. As there is a big chance that your server won't be located in the middle of your home and as this device is USB connected, you are in trouble.

An elegant and efficient option is to plug the RFXtrx433E to any network device properly located and to create a network bridge between this device and your domotic server. This network connected device could be a raspberry pi, but best would be to directly use any of your home WiFi device running OpenWRT.

This guide explains how to use any WiFi device (router, access point or repeater) with a free USB plug as a bridge between your RFXtrx433E USB plug and your domotic server. The only pre requisite is to run OpenWRT on that device so that it runs a full Linux kernel. Hopefully, a lot of wifi device can be flashed with openwrt.

This setup has been designed and tested on a TP-Link TL-WDR4900v1 router and a Debian 8 server. It has also been tested on a GL-AR150 Mini router with Openwrt pre-installed. But it should be easily adapted to any other OpenWRT flashable device and a domotic server running any modern Linux distribution.

1. Basic principle

The principle of this setup is quite simple.

When a RFXtrx433E USB 433 MHz Transceiver is connected to a Linux box like an OpenWRT appliance (router, access point, …), it is seen as a serial device. So during connexion process, a local serial port /dev/tty… is created on the appliance.

To allow a remote domotic server to use this serial port, it must be tunneled thru your LAN with the help of ser2net on the client side and socat on the domotic server side.

With this setup, the domotic server is seeing distant RFXtrx433E as a local serial port, where whole serial trafic is carried by your LAN thanks to the OpenWRT box.

rfxtrx433e over lan

2. OpenWRT Appliance Setup

Any OpenWRT device (router, access point, …) can be setup to act as a serial USB relay, as long as it has a free USB port.

On an OpenWRT box, complete setup implies to follow few steps :

  1. Replace original firmware with OpenWRT
  2. Install all needed packages
  3. Define time zone to properly synchronise with your domotic server
  4. Install a hotplug USB device detection script.
    This script will be in charge of starting the USB to LAN relay as soon as a RFXtrx433E has been detected on a USB port.
  5. Force USB device detection during boot process.
    This is needed because of a procd bug.

Once all these steps have been followed, your Wifi device will natively act as a USB to LAN relay as soon as :

  • you boot it with a RFXtrx433 connected
  • you connect a RFXtrx433 to one of its USB port

Everything will be handled automatically.

2.1. Flash OpenWRT

As explained earlier, your appliance (router, wifi access point, repeater, …) should run OpenWRT to be able to relay a USB connected RFXtrx433E over the LAN.

As it is not the purpose of this guide and as OpenWRT installation is very well documented for a huge number of devices, I won't explain this step.

You just need to follow carefully OpenWRT guides.

2.2. Install packages

To prepare your OpenWRT device to share a USB connected RFXtrx433E over the LAN, you need to install few basic packages :

  • usbutils (provides lsusb command)
  • kmod-usb-serial & kmod-usb-serial-ftdi (kernel drivers for USB serial devices)
  • ser2net (main tool to publish serial device over the LAN)
  • nano (text editor)
  • wget (to retrieve script from Github)

All these packages can be installed with opkg OpenWRT package manager.

Before any package installation, you should update opkg package list as it is not persistent over reboot.

 

OpenWRT console
# opkg update
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/base/Packages.gz.
Updated list of available packages in /var/opkg-lists/barrier_breaker_base.
...
# opkg install usbutils
Installing usbutils (007-1) to root...
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/base/usbutils_007-1_mpc85xx.ipk.
...
Configuring usbutils.
# opkg install kmod-usb-serial kmod-usb-serial-ftdi
Installing kmod-usb-serial (3.10.49-1) to root...
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/base/kmod-usb-serial_3.10.49-1_mpc85xx.ipk.
...
Configuring kmod-usb-serial-ftdi.
# opkg install ser2net
Installing ser2net (2.9.1-1) to root...
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/oldpackages/ser2net_2.9.1-1_mpc85xx.ipk.
Configuring ser2net.
# opkg install nano
Installing nano (2.3.6-1) to root...
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/packages/nano_2.3.6-1_mpc85xx.ipk.
...
Configuring nano.
# opkg install wget
Installing wget (1.16-1) to root...
Downloading http://downloads.openwrt.org/barrier_breaker/14.07/mpc85xx/generic/packages/packages/wget_1.16-1_mpc85xx.ipk.
...
Configuring wget.

2.3. Set Time Zone

As your router will interact with another server, it is important to get a properly synchronized clock.

By default, OpenWRT is configured with its own NTP servers. So it is only needed to set your proper timezone.

With nano editor, update /etc/config/system to match your timezone (all recognized time zones are available from https://wiki.openwrt.org/doc/uci/system#time_zones) :

/etc/config/system
config system
option hostname OpenWrt
option timezone CET-1CEST,M3.5.0,M10.5.0/3
...

2.4. First RFXtrx433E Connection

It is now time to connect your RFXtrx433E to a USB port on your OpenWRT box.

You should detect it as a USB device :

OpenWRT console
# lsusb
...
Bus 001 Device 003: ID 0403:6001 Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC
# dmesg
...
[49972.710152] usb 1-1.1: new full-speed USB device number 3 using fsl-ehci

Your RFXtrx433E has been detected with :

  • Vendor ID : 0403
  • Device ID : 6001

It will need a reboot to load newly installed modules and to fully detect RFXtrx433E as /dev/tty device. This will be done later.

2.5. Ser2Net Configuration

It is now time to setup a specific /etc/rfxtrx433.conf configuration file that will provide ser2net all informations to publish your RFXtrx433 as a serial device over your LAN.

RFXtrx433E default serial parameters are :

  • 38400 bauds
  • 1 stop bit
  • 8 data bits
  • no parity control
  • no connexion timeout

To be fully predictive and use a generic configuration file, RFXtrx433 will always :

  • be mounted as a serial device thru /dev/ttyRFXtrx433 symlink
  • be published on TCP port 1001

/etc/rfxtrx433.conf
# /etc/rfxtrx433.conf
1001:raw:0:/dev/ttyRFXtrx433:38400 NONE 1STOPBIT 8DATABITS

This standard configuration file can be installed from my GitHub repository :

OpenWRT console
# wget --no-check-certificate -O /etc/rfxtrx433.conf https://raw.githubusercontent.com/NicolasBernaerts/openwrt-scripts/master/RFXtrx433/rfxtrx433.conf

2.6. USB Hotplug Script

Next step is to setup hotplug service to handle all needed commands during RFXtrx433E connexion & disconnexion.

hotplug service is provided by openWRT as a replacement of udev and is in charge of managing devices that can be dynamically attached to and removed from the system while running. It can be extended with some scripts to handle specific devices.

We will create a hotplug script in charge of :

  • publishing a newly connected RFXtrx433 device
  • unpublishing it when disconnected

When a RFXtrx433 is plugged, following operations should be performed :

  1. retrieve TTY device where RFXtrx433 is mounted
  2. create the generic TTY symlink /dev/ttyRFXtrx433 to this device
  3. start ser2net service with RFXtrx433 configuration

When unplugged, following operations should be performed :

  1. remove TTY device lock file (created under /var/lock/LCK..ttyRFXtrx433)
  2. kill ser2net process
  3. remove /dev/ttyRFXtrx433 generic symlink

These operations will be handled by /etc/hotplug.d/usb/99-rfxtrx433 script.

/etc/hotplug.d/usb/99-rfxtrx433
#!/bin/sh
# /etc/hotplug.d/usb/99-rfxtrx433
# hotplug script called for RFXtrx433E USB Transceiver

# RFXtrx433E Vendor and Device ID
RFXTRX_VENDOR_ID="403"
RFXTRX_DEVICE_ID="6001"

# configuration
SYMLINK="ttyRFXtrx433"
CONFIG="/etc/rfxtrx433.conf"

# read product vendor and device ID
PRODUCT_VENDOR_ID=$(echo $PRODUCT | cut -d'/' -f1)
PRODUCT_DEVICE_ID=$(echo $PRODUCT | cut -d'/' -f2)

# if device is a RFXtrx433E
if [ "$PRODUCT_VENDOR_ID" = "$RFXTRX_VENDOR_ID" -a "$PRODUCT_VENDOR_ID" = "$RFXTRX_VENDOR_ID" -a "$INTERFACE" != "" ]
then

  # get USB port
  USB_PORT=$(echo $DEVICENAME | cut -d':' -f1)

  # get TTY device
  USB_TTY=$(ls /sys/$DEVPATH | grep tty)

  # deal according to insertion or removal
  case "$ACTION" in

    # connexion
    add)
      # get TTY device
      USB_TTY=$(ls /sys/$DEVPATH | grep tty)
 
      # log detection
      logger "RFXtrx433 : Insertion on USB port $USB_PORT, connection on /dev/$USB_TTY"

      # create symlink to newly created TTY
      ln -s /dev/$USB_TTY /dev/$SYMLINK

      # commands to launch service
      ser2net -c $CONFIG

      # log service start
      logger "RFXtrx433 : Symlink created for /dev/$USB_TTY and ser2net service started"
      ;;

    # removal
    remove)
      # remove device lock file
      rm -f "/var/lock/LCK..$SYMLINK"
 
      # get ser2net process ID
      PID=$(ps | grep -v "grep" | grep "$CONFIG" | xargs | cut -d' ' -f1)
 
      # kill ser2net process
      kill $PID

      # remove symlink
      rm -f /dev/$SYMLINK

      # log service stop
      logger "RFXtrx433 : Service ser2net stopped and symlink /dev/$SYMLINK removed"
      ;;

  esac

fi

You can retrieve the script and install it from my GitHub repository :

OpenWRT console
# mkdir -p /etc/hotplug.d/usb
# wget --no-check-certificate -O /etc/hotplug.d/usb/99-rfxtrx433 https://raw.githubusercontent.com/NicolasBernaerts/openwrt-scripts/master/RFXtrx433/99-rfxtrx433
# chmod +x /etc/hotplug.d/usb/99-rfxtrx433

You just need to adjust Vendor ID and Device ID at the beginning of the script according to what lsusb command has detected earlier.

2.7. Device Detection during Boot

Last step is to configure RFXtrx433E detection during coldboot.

Because of a procd bug, hotplug scripts are not called during boot process, even if USB devices are detected.

Simplest way to correct it, is to force disconnection and reconnection of all USB devices at the end of the boot process.

This is done by adding a very simple command in /etc/rc.local script.

/etc/rc.local
# Put your custom commands here that should be executed once
# the system init finished. By default this file does nothing.

# force USB devices detection at boot (procd bug)
echo "1" > /sys/bus/usb/devices/usb1/bConfigurationValue

exit 0

A readymade /etc/rc.local including this command can be downloaded from my GitHub repository :

OpenWRT console
# wget --no-check-certificate -O /etc/rc.local https://raw.githubusercontent.com/NicolasBernaerts/openwrt-scripts/master/RFXtrx433/rc.local
# chmod +x /etc/rc.local

2.8. Reboot OpenWRT Box

You can now reboot your OpenWRT box.

OpenWRT console
# reboot

After boot, if you login thru SSH, you should see your RFXtrx433 detected as a serial device mounted under /dev/ttyRFXtrx433 and ser2net process should be running.

OpenWRT console
# dmesg
...
[ 10.756674] usbcore: registered new interface driver ftdi_sio
[ 10.762695] usbserial: USB Serial support registered for FTDI USB Serial Device
[ 10.770187] ftdi_sio 1-1.1:1.0: FTDI USB Serial Device converter detected
[ 10.788250] usb 1-1.1: Detected FT232RL
[ 10.792117] usb 1-1.1: Number of endpoints 2
[ 10.796389] usb 1-1.1: Endpoint 1 MaxPacketSize 16384
[ 10.801443] usb 1-1.1: Endpoint 2 MaxPacketSize 16384
[ 10.806495] usb 1-1.1: Setting MaxPacketSize 64
[ 10.836485] usb 1-1.1: FTDI USB Serial Device converter now attached to ttyUSB0
...
# ls -l /dev | grep "USB"
lrwxrwxrwx 1 root root 12 Feb 19 00:08 ttyRFXtrx433 -> /dev/ttyUSB0
crw-r--r-- 1 root root 188, 0 Feb 19 09:26 ttyUSB0
# ps
...
3120 root 836 S ser2net -c /etc/rfxtrx433.conf
...

As soon as you unplug the RFXtrx433, /dev/ttyRFXtrx433 device and ser2net process should be removed.

They should be revived as soon as you plug it back.

3. Server Setup

Now that your OpenWRT device is fully operational, it's time to configure your Domotic server.

On the server side, we will use socat, a multi-purpose socket relay, to connect to our remote ser2net port and forward all traffic to an emulated local TTY port.

As remote port may be broken at some stage, we will setup a pooling script which will monitor the local emulated TTY port. In case this local port is not present, the monitoring process will restart socat relay.

As we may have to monitor multiple remote TTY devices, we will use a configuration file to list all remote TTY devices to be localy emulated and monitored.

3.1. Install packages

First step is to install socat on the domotic server.

Server console
# apt-get install socat

3.2. Remote TTY Script

As we want to be able to mount one or more remote RFXtrx433 as local TTY, we will declare all remote devices in a specific configuration file.

This /etc/remote-tty.conf file will list one remote RFXtrx433 per line with following characteritics :

  • IP address of remote device
  • Listening port of remote device
  • Local TTY port to create for this device

/etc/remote-tty.conf
192.168.0.15;1001;ttyUSB9
192.168.0.25;2000;ttyUSB10

Based on remote TTY devices listed in this configuration file, a server script is in charge of creating associated local TTY ports. These local ports will be created with socat, a multi-purpose socket relay.

This script is written in a way that it can be called periodically to recreate broken TTY ports. For every managed remote device, it first check if associated local TTY port is present. In case of absence, it then create the local port using a socat command.

/usr/local/bin/remote-tty
#!/bin/bash
# Remote TTY monitoring script
# Check local TTY emulation
# If broken for any reason, remount remote TTY with socat
# Remote TTY configured in /etc/remote-tty.conf
#
# Revision history :
# 18/02/2016 - V1.0 - Creation by N. Bernaerts
# 18/09/2017 - V1.1 - Allow tty device access to anybody

# configuration
TTY_CONF="/etc/remote-tty.conf"

# loop thru configuration file
while read LINE; do
  if [ "$LINE" != "" ]
  then
    # get variables
    REMOTE_IP=$(echo "$LINE" | cut -d';' -f1)
    REMOTE_PORT=$(echo "$LINE" | cut -d';' -f2)
    LOCAL_TTY=$(echo "$LINE" | cut -d';' -f3)

    # test if local TTY file is absent as a caracter file
    if [ ! -c "/dev/${LOCAL_TTY}" ]
    then
      # create tty
      socat pty,raw,echo=0,link=/dev/${LOCAL_TTY} tcp:${REMOTE_IP}:${REMOTE_PORT} &
      
      # wait for 1 second
      sleep 1

      # give 666 access right
      chmod 666 "/dev/${LOCAL_TTY}"
    fi
  fi
done < $TTY_CONF

You can install this script and a sample configuration file from my GitHub repository :

Server console
# wget -O /usr/local/sbin/remote-tty https://raw.githubusercontent.com/NicolasBernaerts/debian-scripts/master/remote-tty/remote-tty
# chmod +x /usr/local/sbin/remote-tty

As a remote device connection may fail (network cut, remote device power loss, …), this script should be called during boot and every 5 minutes to check remote devices and associated local TTY ports. In case a remote device TTY port has been lost, the script periodic calls will redeclare them.

As with every Linux box, simplest way to get periodic calls is thru crontab.

/etc/rc.local
...

# create remote tty
/usr/local/sbin/remote-tty

exit 0

Server console
# crontab -e
...
*/5 * * * * /usr/local/sbin/remote-tty

3.3. Remote Device Declaration in Domoticz

In previous example, RFXtrx433E device connected to your OpenWRT box is now localy accessible thru /dev/ttyUSB9 on your domotic server.

Any domotic application able to connect to a RFXtrx433E will see the device.

Here is and example of Domoticz declaration :

domoticz rfxtrx433 lan declaration

If everything is well configured, you should detect your domotic devices.

Here is what I get after using an unknown DIO remote :

domoticz rfxtrx433 lan detection

3.4. Enjoy

Everything is now setup for your remote RFXtrx433E to be part of your domotic system.

 

Hope it helps.

Signature Technoblog

This article is published "as is", without any warranty that it will work for your specific need.
If you think this article needs some complement, or simply if you think it saved you lots of time & trouble,
just let me know at This email address is being protected from spambots. You need JavaScript enabled to view it.. Cheers !

icon linux icon debian icon apache icon mysql icon php icon piwik icon googleplus