rf-ctrl - A command-line tool to control 433MHz OOK based devices

Synopsis

rf-ctrl is a command line tool allowing to control wireless plugs and chimes that use a 433MHz OOK modulation. The OOK modulation (ON/OFF Keying) allows to transmit binary data on a particular frequency by enabling or disabling the transmitter oscillator. I will call these states High and Low.

A big part of the wireless plugs that can be found on the market uses this modulation with a carrier frequency of 433.92MHz, and almost all of them follow the same frame pattern regarding the transmitted data:

a starting marker : High to Low transition with particular High and Low durations
the actual binary data : 0 and 1 bits are coded using High to Low transitions, with different High and Low timings
an ending marker : High to Low transition with particular High and Low durations

This frame is then repeated a specific number of times. Some protocols are based on High to Low transitions, while some others use Low to High transitions.

rf-ctrl uses a frontend/backend logic allowing to generate the proper frame for a particular protocol on one side, and to use a particular 433MHz enabled hardware to send it on the other side. This means that adding a new transmitter driver will allow all the supported protocols to be used out of the box.

Build instruction

As usual:

$ make

Take a look at the Makefile to see the variables that can be used (for instance CROSS_COMPILE).

OpenWrt support

In order to build rf-ctrl as an OpenWrt package and/or add it to an OpenWrt firmware build:

checkout an OpenWrt build tree (only tested on Barrier Breaker 14.07 so far)
create the openwrt/package/utils/rf-ctrl sub-folder and place OpenWrt/Makefile in it
create the openwrt/package/utils/rf-ctrl/src sub-folder and place all the files from the rf-ctrl root folder in it

Now, if you run $ make menuconfig from the openwrt root folder, you should see an rf-ctrl entry in the Utilities sub-menu !

Currently supported protocols and transmitters

The supported transmitters are:

HE853 : the ELRO/Home Easy USB dongle
OOK-GPIO : any 1$ 433MHz transmitters connected to a GPIO (ook-gpio kernel driver required)
SYSFS-GPIO : any 1$ 433MHz transmitters connected to a GPIO (using the standard SYSFS GPIO interface)

The supported protocols are:

DI-O
Home Easy (not tested because I don't have one)
Idk (Chinese wireless chime that is probably sold under different brands)
OTAX (found in a the French Conforama store)
Auchan (found in the French Auchan store, and probably sold under different brands)
Auchan2 (also found in the French Auchan store, and probably sold under different brands)
Sumtech (not sure were it can be found, it is a pure chinese product like Idk)
Blyss (found in french Castorama store)
Somfy (RTS 433,42 MHz only)

Usage

Turning off the DI-O device number 3 paired to the remote ID 424242:

$ sudo ./rf-ctrl -p dio -r 424242 -d 3 -c off

Starting a fast RF scan on every OTAX devices, sending the 'on' command:

$ sudo ./rf-ctrl -p otax -c on -s -n 1

License

rf-ctrl is distributed under the GPLv2 license. See the LICENSE file for more information.

Miscellaneous

Thanks to r10r and his he853-remote project. It saved me a lot of time when I implemented the HE853 USB dongle driver and the Home Easy protocol. So far, rf-ctrl has been successfully tested on a regular Linux PC, a TP-Link TL-WR703N router running OpenWrt, and a Raspberry Pi. Check out my Home-RF project for a simple Web-UI that uses rf-ctrl.

Fell free to visit my blog, and/or send me a mail !

jcrona / rf-ctrl