Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====rtl_433: Software Defined Radio Plugin=====

The rtl_433 plugin makes use of the excellent [[https://github.com/merbanan/rtl_433|rtl_433]] software to control a Software Defined Radio to receive many different wireless devices on many different frequencies. Virtually all devices listed as supported on their github page can also be received in XTension though some work better than others. Some of the highly customized devices may require specific handling code in Xtension to work properly and if you find one that does not please let me know and I will prioritize getting that specifically supported for you. Note that an SDR radio is receive only. There is no way to use one to send signals or to attempt to control the devices. At this moment the reception of temperature and other sensors works very well but the reception of 433mhz buttons or remote controls works somewhat less well. Reception of some smart meter readings in the 912mhz band also works but may miss transmissions due to limitations of bandwidth as they hop frequencies. There will be a rtlamr plugin in the next release that will fix at least some of those problems.

Due to the huge scope of devices to be supported and tested, this plugin is still a work in progress and should be considered in a beta state at the moment.

This plugin does not require the installing of any additional software on your mac and includes a recent build of rtl_433 for the mac. You can connect to any reasonable number of radios on a single machine but that will require manually setting the USB Serial number of the device. The rtl_eeprom program is also included in the distribution, see the documentation for doing that further down the page.

====Supported Hardware:====
As of this moment I can say that any SDR device that is supported by the rtl-sdr software will also work with this plugin. It should also support the more expensive SoapySDR supported radios like the HackRF and others but these are entirely untested and may require additional command line arguments so you should know how to use them with their supplied software before trying to attach them to XTension.

The different kinds if radios all have different connection methods and antenna requirements. Many are SMA but others are different and will require adaptors to get to a decent antenna. 

I recommend supporting the RTL-SDR folks by purchasing one of [[https://www.rtl-sdr.com/buy-rtl-sdr-dvb-t-dongles/|their radios here]] While I have had success with other brands my initial impression is that these are superior in reception quality to many others I have experimented with.

====XTension Configuration:====

As long as you only have one radio connected to the Mac in question the install is very simple. If you wish to connect more than one SDR to the Mac then it is necessary to use the “rtl_eeprom” application to give each one a unique serial number. This application is included in the XTension plugin but running it has to be done from the command line. See the specific section below on how to do that.

{{:current:rtl_433_settings.png?500 |}}

**Connection Type:** You can connect to a radio connected directly to your Mac, in which case select “Local USB” or to a raspberry pi or other Mac or Linux device remotely with the software instsalled. In that case select “Remote Via SSH” from this popup. There is much more setup to do on the remote Pi or device if you wish to use this, see the section below for more information.\\
\\
If you’re using a local connection the following “Remote” labeled entries are ignored.\\


**Remote Address:** If connecting to a remote Raspberry pi please fill in it’s IP address or DNS name and port in this line.

**Remote rtl_433 Path:** The path to the application as installed on the remote device. Defaults to the default install location on a raspberry pi. Unless you changed this there is no need to change it.

**Remote SSH User:** The user name you wish to run the remote command as. This requires that you do a shared key exchange between the Mac and the remote device, see the second below for more info.


**SDR USB Serial Number:** If you have only a single radio connected to the Mac you can leave this blank. If you have more than one on a single machine you must use the rtl_eeprom utility that is included in the plugin to write a unique number to each radio. See the section below for more info.

**Frequency:** for 433 devices leave this set to the default of 433.920MHz. If you wish to look for devices on a different frequency enter it here in the format described on the rtl_433 wiki pages.

**Advanced Additional Command Line Arguments:** If you wish to pass other parameters to the rtl_433 property to do things like control the bandwidth or to enable or disable specific decoders beyond the default you can enter them here. Any info entered here will be appended to the end of the command line as XTension executes the rtl_433 app. See the rtl_433 wiki pages for more information on what is possible.

**Units:** The units section lets you select how the data from rtl_433 will be converted to your local preferences for display. If you select anything other than the default output from rtl_433 the units will be converted before putting into an XTension unit value.

====Raspberry Pi As Remote Host:====
It is possible to use a raspberry pi as a remote host for the radio. This can take quite a bit of CPU effort on the part of the pi so you should not plan to use a Pi Zero or older pi device. Any Pi 3B+ or later device will work fine and it runs excellently on a Pi4. You should plan to have a pi4 if you wish to host mutliple radios on it.

The connection to the Pi is via an SSH connection and no password is saved in XTension thus you must arranged for a shared SSH key between the two machines so no password is necessary to connect between them. If you have never done this before on your mac you must create an ssh key on the Mac via the terminal command:

<code>
ssh-keygen -t rsa
</code>

This creates a key on your Mac that can then be shared with the remote machines so no password will be needed to run the command later. The next step is to copy that key to the remote machine or pi via the ssh-copy-id command like this:

<code>
ssh-copy-id pi@thePiAddressOrName.local
</code>

if you are using a different user than the default of “pi” then replace the “pi@“ in the command above with the new user name and the at sign. Once that completes you should test the success by trying to ssh into the remote machine. It should no longer ask you for a password and if that works then you’re good to continue to the next step.

====Installing rtl_433 on the Pi====
Note that this step is NOT necessary if you’re running a local radio on your Mac. A properly compiled version of the app is included in the plugin.

===Install Git===
If you haven’t already please make sure git is installed on the pi. You can verify it by issuing the command “git --version” if the command returns a value then you can skip to the next step. If not then please perform a “sudo apt install git” and wait for that to complete.

===Install Other Prerequisits:===
The following packages are needed to complete the install:
<code>
sudo apt install cmake libusb-1.0-0-dev build-essential autoconf libtool pkg-config
</code>

===Install rtl-sdr:===
As of this writing the instructions for installing RTL-SDR are:
<code>
git clone git://git.osmocom.org/rtl-sdr.git
cd rtl-sdr
mkdir build
cd build
cmake -DINSTALL_UDEV_RULES=ON ..
make
sudo make install
sudo ldconfig
</code>

===Install rtl_433:===
As of this writing the instructions for installing rtl_433 are:
<code>
git clone https://github.com/merbanan/rtl_433
cd rtl_433
mkdir build
cd build
cmake ..
make
sudo make install
</code>

===Multiple Radios:===
If you wish to use more than one SDR on your Mac or Raspberry Pi you need to use the included utility to write unique serial numbers to them. They seem to all ship with the serial number set to 0000001 or something similar.

On the Pi the rtl_eeprom utility should be in your path after the above installs. On the Mac it is included with the plugin. You can find that by control clicking on XTension in the Finder and selecting “Show Package Contents” open the Contents folder and then the Resources folder and then the Plugins folder and finally the rtl_433 folder. Open a terminal window and type “cd “ and then drag that folder into the terminal window to enter the path and press return to change to it.

Run the “rtl_eeprom” program from there and use it to write a new serial number to the radio. Do this for each radio and then enter the same number into the SDR Serial Number field in the setup window for that interface above.


====Summary So Far====
The app works very well to receive oregon scientific and other temperature/humidity sensors from various manufacturers. I have yet to find a similar device that isn’t supported actually. It works less well for 433 mhz remotes and buttons. We will shortly ahve other better options for receiving those. It can also be used to receive some smart meter transmissions. It works less well than the upcoming rtlamr plugin for that as it makes the bandwidth too small to pick up all the transmissions as they do freequency hopping. It may work for some if you set the frequency to 912600155 and having the appropriate antenna attached. 

====History:====
  * The 0.1 beta version of the plugin was first added to XTension version 9.4.40 in May of 2021
  * v0.2 was included in Xtension 9.4.41. It fixed the omission of the “Register” device type that would have caused units using it to stop receiving updates once they were edited. It added specific special case support for the Honeywell WST232 devices.