## File: README.md # rtl_433 rtl_433 (despite the name) is a generic data receiver, mainly for the 433.92 MHz, 868 MHz (SRD), 315 MHz, 345 MHz, and 915 MHz ISM bands. The official source code is in the https://github.com/merbanan/rtl_433/ repository. See also [a list of software that works with rtl_433](https://github.com/merbanan/rtl_433/wiki/Built-with-rtl_433!) in the wiki. For more documentation and related projects, particularly those that help with rtl_433 development, see the https://triq.org/ site. It works with [RTL-SDR](https://github.com/osmocom/rtl-sdr/) and/or [SoapySDR](https://github.com/pothosware/SoapySDR/). Actively tested and supported are Realtek RTL2832 based DVB dongles (using RTL-SDR) and LimeSDR ([LimeSDR USB](https://www.crowdsupply.com/lime-micro/limesdr) and [LimeSDR mini](https://www.crowdsupply.com/lime-micro/limesdr-mini) engineering samples kindly provided by [MyriadRf](https://myriadrf.org/)), PlutoSDR, HackRF One (using SoapySDR drivers), as well as SoapyRemote. ## Building rtl_433 is written in portable C (C99 standard) and known to compile on Linux (also embedded), FreeBSD, MacOS, and Windows systems. Older compilers and toolchains are supported as a key-goal. Low resource consumption and very few dependencies allow rtl_433 to run on embedded hardware. Most common 32-bit and 64-bit CPU architectures like amd64, arm64, armhf, i386, ppc64el, riscv64, s390x and others are well supported. See [BUILDING.md](docs/BUILDING.md) ## Installation Linux (Debian, Ubuntu): `sudo apt install rtl-433`. For other distributions see [repology](https://repology.org/project/rtl-433/versions) or [pkgs.org](https://pkgs.org/download/rtl-433). FreeBSD: `pkg install rtl-433`. MacOS: `brew install rtl_433`. Docker images with rtl_433 are available [on the github page of hertzg](https://github.com/hertzg/rtl_433_docker). ## How to add support for unsupported sensors See [CONTRIBUTING.md](./docs/CONTRIBUTING.md). ## Running rtl_433 -h ``` /* Detailed source-code truncated for AI context efficiency. */ ``` Some examples: | Command | Description |---------|------------ | `rtl_433` | Default receive mode, use the first device found, listen at 433.92 MHz at 250k sample rate. | `rtl_433 -C si` | Default receive mode, also convert units to metric system. | `rtl_433 -f 868M -s 1024k` | Listen at 868 MHz and 1024k sample rate. | `rtl_433 -M hires -M level` | Report microsecond accurate timestamps and add reception levels (depending on gain). | `rtl_433 -R 1 -R 8 -R 43` | Enable only specific decoders for desired devices. | `rtl_433 -R -216 -R 216` | Enable all default decoders plus a decoder disabled by default (216). | `rtl_433 -A` | Enable pulse analyzer. Summarizes the timings of pulses, gaps, and periods. Can be used with `-R 0` to disable decoders. | `rtl_433 -S all -T 120` | Save all detected signals (`g###_###M_###k.cu8`). Run for 2 minutes. | `rtl_433 -K FILE -r file_name` | Read a saved data file instead of receiving live data. Tag output with filenames. | `rtl_433 -F json -M utc \| mosquitto_pub -t home/rtl_433 -l` | Will pipe the output to network as JSON formatted MQTT messages. A test MQTT client can be found in `examples/mqtt_rtl_433_test_client.py`. | `rtl_433 -f 433.53M -f 434.02M -H 15` | Will poll two frequencies with 15 seconds hop interval. ## Security Please note: We aim to make `rtl_433` safe to use, but it should not be assumed secure. There is no reason to e.g. run with `sudo`, we do read and write files without any checks. The output is literally pulled from thin air, it's not to be trusted. If you feed downstream systems with data make sure edge cases are checked and handled. Network inputs and outputs are for use in a trusted local network, will contain unfiltered data, and might overload the recipient (know that e.g. the MQTT output can be controlled by anyone with a radio sender). ## Google Group Join the Google group, rtl_433, for more information about rtl_433: https://groups.google.com/forum/#!forum/rtl_433 ## Troubleshooting If you see this error: Kernel driver is active, or device is claimed by second instance of librtlsdr. In the first case, please either detach or blacklist the kernel module (dvb_usb_rtl28xxu), or enable automatic detaching at compile time. then sudo rmmod rtl2832_sdr dvb_usb_rtl28xxu rtl2832 or add blacklist dvb_usb_rtl28xxu to /etc/modprobe.d/blacklist.conf ## Releases Version numbering scheme used is year.month. We try to keep the API compatible between releases but focus is on maintainablity. --- ## File: docs/ANALYZE.md # Capture and analyze devices ## TL;DR Capture sample data with `-S unknown`. Note down the expected measurement values from a read-out or head unit. Check the spectrogram by dropping samples on https://triq.org/pdv/ (it should [look "busy" like this](https://triq.org/pdv/#/honeywell/2Gig-DW10/g001_344.975M_250k.cu8)) Try analyzing each sample with `rtl_433 -A gfile.cu8` to see if there is some real data. Use the analyzer hints to create a plausible `-X` decoder and demod the data codes. Then upload some zipped samples to an issue and post a description and tabled codes and values per sample file. ## Verify a transmission rtl_433 processes radio data in multiple stages. You can follow the stages and verify the data at each point. First a radio data packet is found and framed. Get on overview of the band. Check if the transmission is visible and in the expected frequency range. Use CubicSDR, Gqrx, SigDigger, SDR#, SDRangel or similar SDR UIs to verify you receice a signal. If you have the SDR receiver on a headless machine try `rtl_tcp` to transport data to a GUI. :::tip A quick substitute for an SDR UI is to record a sample, e.g. `-w file_433.92M_250k.cu8 -T 60` (adjust for the actual frequency and sample rate). Now drop that .cu8 sample file on https://triq.org/pdv/ to visually inspect the spectrogram (a sideways view of the common SDR waterfalls). ::: :::warning Do not plug the receiver directly in a USB port, avoid noise and use a short USB cable. ::: ## Grab a sample Note the frequency, pick a frequency a little off, e.g 50k above or below. Then grab the signal with rtl_433, e.g. `rtl_433 -f 433.92M -S unknown` Visually verify the samples in https://triq.org/pdv :::tip The modes for the sample grabber are - `-S all`: grab all frames found - `-S unknown`: grab frames that are not decoded by any decoder - `-S known`: grab frames successfully decoded by some decoder ::: The band covered is equal to the sample rate. At the default `433.92M` and `250k` sample rate that's `433.67 MHz` to `434.17 MHz`. For the `868M` default sample rate of `1024k` that's `867.5 MHz` to `868.5 MHz`. For the `868M` it's like good to pick `868.3M` for a band of `867.8 MHz` to `868.8 MHz`. To get a clean signal remove the receiver antenna and place the device at 10cm to the receiver, that mostly isolates the transmissions. ## Analyze the data packet Then next stage is demodulation of OOK or FSK data. A run of pulse/gap (OOK) or mark/space (FSK) timings is generated by the demod. Run `rtl_433 -A SAMPLE.cu8` to get an overview of the timings, or `rtl_433 -w OOK:- SAMPLE.cu8` to see the raw data. Write the pulses to a file with `rtl_433 -w SAMPLE.ook SAMPLE.cu8` and visualize the file with https://triq.org/pdv :::warning You need to give the sample rate if it's not 250k, look at the file name, e.g. use `rtl_433 -s 1000k -A SAMPLE_1000k.cu8` ::: For advanced analysis you can also try out SigRok's Pulseview with `rtl_433 -W out.sr SAMPLE.cu8`. Be sure to also try with higher sensitivity: `-Y autolevel -Y magest -M noise -M level` Try different sample rates, for 433M try `-s 1024k`, for 868M try `-s 250k` or `-s 2048k`. Try different demods, for 433M try `-Y minmax`, for 868M try `-Y classic`. ## Build a flex decoder Now build a flex decoder to slice the data into bits. Use the suggestion or make a guess based on the analyzed pulse data on the coding. ## Document data codes The last stage is the protocol decoding from the bit data. Build a table of codes and the expected sensor values to identify where the bytes are and what is contained. Preferably put the codes and annotations in a [BitBench](https://triq.org/bitbench). ## Example commands - capture samples not decoded by rtl_433 `rtl_433 -S unknown` - capture samples of every received frame `rtl_433 -S all` - analyze a capture to get an overview of the timings `rtl_433 -A SAMPLE.cu8` - show the raw data pulse data from a captured sample `rtl_433 -w OOK:- SAMPLE.cu8` - convert pulse data from a capture to OOK file `rtl_433 -w SAMPLE.ook SAMPLE.cu8` - try to read codes from a captured sample `rtl_433 -X '...' SAMPLE.cu8` - open a captured sample in SigRok Pulseview `rtl_433 -W SAMPLE.sr SAMPLE.cu8` --- ## File: docs/BINARY_BUILDS.md # Binary Builds First check to see if your distribution already has a recent enough version packaged for you. E.g. check [Repology](https://repology.org/project/rtl-433/versions) for a quick overview. We currently provide 18 [binary builds](https://github.com/merbanan/rtl_433/releases) for different OS, Platform, Version and Features. This is intended to quickly test out `rtl_433` or update to the newest version. Due to library dependencies and versions we can't guarantee our binaries to work (safe to try though, the worst is a "executable not supported" or "library is missing" message). Let us know in [with a comment](https://github.com/merbanan/rtl_433/issues/2859) if a binary unexpectedly does work or does not work. OS and Platform: - Windows: x32 and x64 - MacOS: x86_64/Intel and arm64/M1 - Linux: x86_64/amd64, arm64 (Raspberry Pi OS 64-bit), and armhf (Raspberry Pi OS 64-bit) Version (only Linux): - Variant for OpenSSL 1.1: Ubuntu 20.04 focal, Debian 11 Bullseye, Raspberry Pi OS Legacy - Variant for OpenSSL 3: Ubuntu 22.04 jammy, Debian 12 Bookworm, Raspberry Pi OS Features: - with only rtlsdr - with rtlsdr and SoapySDR ## Choosing a binary Without SoapySDR: - `rtl_433-rtlsdr-MacOS-arm64.zip`: MacOS-14 for arm64/M1 - `rtl_433-rtlsdr-MacOS-x86_64.zip`: MacOS-12 for x86_64/Intel - `rtl_433-rtlsdr-openssl11-Linux-amd64.zip`: Linux for x86_64/amd64 with OpenSSL 1.1 - `rtl_433-rtlsdr-openssl11-Linux-arm64.zip`: Linux for aarch64/arm64 with OpenSSL 1.1 - `rtl_433-rtlsdr-openssl11-Linux-armhf.zip`: Linux for armhf with OpenSSL 1.1 - `rtl_433-rtlsdr-openssl3-Linux-amd64.zip`: Linux for x86_64/amd64 with OpenSSL 3 - `rtl_433-rtlsdr-openssl3-Linux-arm64.zip`: Linux for aarch64/arm64 with OpenSSL 3 - `rtl_433-rtlsdr-openssl3-Linux-armhf.zip`: Linux for armhf with OpenSSL 3 With SoapySDR: - `rtl_433-soapysdr-MacOS-arm64.zip`: MacOS-arm64 - `rtl_433-soapysdr-MacOS-x86_64.zip`: MacOS-x86_64 - `rtl_433-soapysdr-openssl11-Linux-amd64.zip`: Linux for x86_64/amd64 with OpenSSL 1.1 - `rtl_433-soapysdr-openssl11-Linux-arm64.zip`: Linux for aarch64/arm64 with OpenSSL 1.1 - `rtl_433-soapysdr-openssl11-Linux-armhf.zip`: Linux for armhf with OpenSSL 1.1 - `rtl_433-soapysdr-openssl3-Linux-amd64.zip`: Linux for x86_64/amd64 with OpenSSL 3 - `rtl_433-soapysdr-openssl3-Linux-arm64.zip`: Linux for aarch64/arm64 with OpenSSL 3 - `rtl_433-soapysdr-openssl3-Linux-armhf.zip`: Linux for armhf with OpenSSL 3 ## Easy Install Easiest install would be to first install a distribution provided `rtl_433` package for the dependencies, then use one of these binaries instead. ## Install Otherwise you need to install libusb, openssl (1.1 or 3), librtlsdr, and optionally SoapySDR (plus driver modules). ### MacOS After unpacking the binary you need to clear the file attributes: ``` xattr -c rtl_433 ``` Note that `com.apple.quarantine` attributes are a useful safety feature and you should only perform this with genuine downloads from trusted sources. :::warning Note that [Homebrew](https://formulae.brew.sh/formula/librtlsdr) uses librtlsdr version 2.0 (with rtl-sdr blog v4 support) while [MacPorts](https://ports.macports.org/port/rtl-sdr/details/) uses version 0.6 but those are compatible. You'll need to update the binary to run on MacPorts: ``` install_name_tool -change @rpath/librtlsdr.2.dylib @rpath/librtlsdr.0.dylib rtl_433 ``` ::: #### MacPorts (s.a. the [MacPorts port](https://ports.macports.org/port/rtl_433/)) ``` sudo port install libusb openssl3 rtl-sdr ``` optionally add ``` sudo port install SoapySDR ``` #### HomeBrew (s.a. the [Homebrew Formula](https://formulae.brew.sh/formula/rtl_433)) ``` brew install libusb brew install openssl@3 brew install librtlsdr ``` optionally add ``` brew install soapysdr ``` ### Linux On Debian, Ubuntu, and Raspberry Pi OS (and similar Debian-based OS supporting the `apt` package manager): ``` sudo apt-get install -y rtl-sdr openssl soapysdr-tools ``` Or with out any tools, just the libs for Bullseye / Focal ``` sudo apt-get install -y librtlsdr0 libssl1.1 libsoapysdr0.7 ``` Similar for Bookworm / Jammy ``` sudo apt-get install -y librtlsdr0 libssl3 libsoapysdr0.8 ``` --- ## File: docs/BUILDING.md # Building rtl_433 rtl_433 currently supports these input types: * [RTL-SDR](http://sdr.osmocom.org/trac/wiki/rtl-sdr) (optional, recommended) * [SoapySDR](https://github.com/pothosware/SoapySDR/wiki) (optional) * files: CU8, CS16, CF32 I/Q data, U16 AM data (built-in) * rtl_tcp remote data servers (built-in) Building rtl_433 with RTL-SDR or SoapySDR support is optional but using RTL-SDR is highly recommended. The libraries and header files for RTL-SDR and/or SoapySDR should be installed beforehand. ## Nightly builds Some distributions offer nightly builds. ### openSUSE openSUSE users of at least Leap 42.3 or Tumbleweed can add the repository with daily builds: $ sudo zypper addrepo -f obs://home:mnhauke:rtl_433:nightly/rtl_433 rtl_433-nightly $ sudo zypper install rtl_433 The usual update mechanism will now keep the rtl_433 version current. ### Fedora Fedora users (38, 39 and Rawhide) can add the following copr repository to get nightly builds: $ sudo dnf copr enable tvass/rtl_433 $ sudo dnf install rtl_433 The usual update mechanism will now keep the rtl_433 version current. ## Linux / Mac OS X Depending on your system, you may need to install the following libraries. Debian: ``` sudo apt-get install libtool libusb-1.0-0-dev librtlsdr-dev rtl-sdr build-essential cmake pkg-config ``` * If you require TLS connections, also install `libssl-dev` (`sudo apt-get install libssl-dev`). Centos/Fedora/RHEL with EPEL repo using cmake: * If `dnf` doesn't exist, use `yum`. * If you require TLS connections, install `openssl-devel`. ``` sudo dnf install libtool libusb1-devel rtl-sdr-devel rtl-sdr cmake ``` Mac OS X with MacPorts: * If you require TLS connections, install `openssl` from either MacPorts or Homebrew. ``` sudo port install rtl-sdr cmake ``` Mac OS X with Homebrew: brew install rtl-sdr cmake pkg-config ### CMake Get the `rtl_433` git repository if needed: git clone https://github.com/merbanan/rtl_433.git Installation using CMake and Make (commonly available): cd rtl_433/ cmake -B build cmake --build build --target install Installation using CMake and Ninja (newer and faster): cd rtl_433/ cmake -DFORCE_COLORED_BUILD:BOOL=ON -GNinja -B build cmake --build build -j 4 cmake --build build --target install If installing to a global prefix (e.g. the default `/usr/local`) then instead run `make install` with privileges, .i.e. sudo cmake --build build --target install Use CMake with `-DENABLE_SOAPYSDR=ON` (default: `AUTO`) to require SoapySDR (e.g. with Debian needs the package `libsoapysdr-dev`), use `-DENABLE_RTLSDR=OFF` (default: `ON`) to disable RTL-SDR if needed. E.g. use: cmake -DENABLE_SOAPYSDR=ON .. :::tip If you use CMake older than 3.13 (check `cmake --version`), you need to build using e.g. `mkdir build ; cd build ; cmake .. && cmake --build .` ::: :::tip In CMake 3.6 or older the OpenSSL search seems broken, you need to use `cmake -DENABLE_OPENSSL=NO ..` ::: :::warning If you experience trouble with SoapySDR when compiling or running: you likely mixed version 0.7 and version 0.8 headers and libs. Purge all SoapySDR packages and source installation from /usr/local. Then install only from packages (version 0.7) or only from source (version 0.8). ::: ## Package maintainers To properly configure builds without relying on automatic feature detection you should set all options explicitly, e.g. cmake -DENABLE_RTLSDR=ON -DENABLE_SOAPYSDR=ON -DENABLE_OPENSSL=ON -DBUILD_DOCUMENTATION=OFF -DCMAKE_BUILD_TYPE=Release -GNinja -B build cmake --build build -j 10 DESTDIR=/tmp/destdir cmake --build build --target install ## Windows ### Visual Studio 2017 You need [PothosSDR](https://downloads.myriadrf.org/builds/PothosSDR/) installed to get RTL-SDR and SoapySDR libraries. Any recent version should work, e.g. [2021.07.25-vc16](https://downloads.myriadrf.org/builds/PothosSDR/PothosSDR-2021.07.25-vc16-x64.exe). When installing PothosSDR choose "Add PothosSDR to the system PATH for the current user". For TLS support (mqtts and influxs) you need OpenSSL installed. E.g. [install Chocolatey](https://chocolatey.org/install) then open a Command Prompt and choco install openssl Clone the project, e.g. open Visual Studio, change to "Team Explorer" > "Projects" > "Manage Connections" > "Clone" and enter `https://github.com/merbanan/rtl_433.git` If you want to change options, in the menu select "CMake" > "Change CMake Settings" > "rtl433", select e.g. "x64-Release", change e.g. "buildRoot": "${workspaceRoot}\\build", "installRoot": "${workspaceRoot}\\install", To start a build use in the menu e.g. "CMake" > "Build all" Or build at the Command Prompt without opening Visual Studio. Clone rtl_433 sources, then cd rtl_433 cmake -G "Visual Studio 15 2017 Win64" -B build cmake --build build ### MinGW-w64 You'll probably want librtlsdr and libusb. libusb has prebuilt binaries for windows, librtlsdr needs to be built (or extracted from the PothosSDR installer) #### librtlsdr taken and adapted from here: https://www.onetransistor.eu/2017/03/compile-librtlsdr-windows-mingw.html * install [MinGW-w64](https://mingw-w64.org/) and [CMake](https://cmake.org/) * it's easiest if you select the option to include CMake in your path, otherwise you'll need to do this manually * download the libusb binaries from https://sourceforge.net/projects/libusb/files/libusb-1.0/ or from https://libusb.info/ * take the latest release and then download the .7z file, the other file contains the sources (or 'windows binaries' on the .info website) * extract the archive and open the extracted folder * copy the contents of the include folder to `/include` * copy the `mingw64/dll/libusb-1.0.dll.a` file to `/lib * copy the `mingw64/dll/libusb-1.0.dll` file to `/bin` * download the source code of librtlsdr https://github.com/steve-m/librtlsdr * go into the librtlsdr folder * open CMakeLists.txt with an editor that knows unix line endings * go to `# Find build dependencies` (around line 65) and comment/remove the line with `find_package(Threads)` * add the following lines instead: ``` SET(CMAKE_THREAD_LIBS_INIT "-lpthread") SET(CMAKE_HAVE_THREADS_LIBRARY 1) SET(Threads_FOUND TRUE) ``` * go into the cmake/modules folder and open FindLibUSB.cmake with a text editor * find the lines with the following text in them ``` /usr/include/libusb-1.0 /usr/include /usr/local/include ``` * add some extra lines to point to the MinGW include folder where you extracted libusb-1.0, making it look like this * take note of the "" around the folder names, these are needed when there are spaces in the folder name * you'll need to find out the exact paths for your system ``` /usr/include/libusb-1.0 /usr/include /usr/local/include "C:/Program Files/mingw-w64/x86_64-8.1.0-posix-seh-rt_v6-rev0/mingw64/include" "C:/Program Files/mingw-w64/x86_64-8.1.0-posix-seh-rt_v6-rev0/mingw64/include/libusb-1.0" ``` * open a MinGW terminal in the librtlsdr folder * generate makefiles for MinGW: `cmake -G "MinGW Makefiles" -B build` * build the librtlsdr library: `cmake --build build` #### rtl_433 * clone the rtl_433 repository and cd into it * run `cmake -G "MinGW Makefiles" -B build` in the build directory * run cmake-gui (this is easiest) * set the source (the rtl_433 source code directory) and the build directory (one might create a build directory in the source directory) * click configure * select the grouped and advanced tickboxes * go into the librtlsdr config group * point the `LIBRTLSDR_INCLUDE_DIRS` to the include folder of the librtlsdr source * point the `LIBRTLSDR_LIBRARIES` to the `librtlsdr.dll.a` file in the /build/src folder * that's the one you've built earlier * start a MinGW terminal and run `cmake --build build` to build * when something in the tests folder doesn't build, you can disable it by commenting out `add_subdirectory(tests)` in the CMakeLists.txt file in the source folder of rtl_433 * rtl_433.exe should be built now * you need to place it in the same folder as librtlsdr.dll and libusb-1.0.dll (you should have seen both of them by now) * good luck! If your system is missing or you find these steps are outdated please PR an update or open an issue. --- ## File: docs/CONTRIBUTING.md # Contributing guidelines The rtl_433 project is built on the work of many contributors analyzing, documenting, and coding device support. We are happy to accept your contribution of yet another sensor! Please check if your contribution is following these guidelines to improve the feedback loop and decrease the burden for the maintainers. ## Adding a new decoder Decoders for new device protocols are welcome. You need to know some C and register the decoder with one line, the rest is automatic. To get started follow these steps to add a new decoder: - Clone the repo and create a feature branch. E.g. Clone in Github, checkout and then `git checkout -b feat-mydevice` - Copy some decoder as template, either one that is already close to what you need or `src/devices/new_template.c`. E.g. `cp src/devices/new_template.c src/devices/my_device.c` - Change the new decoder (at least the `r_device` name and `.disabled = 0`). E.g. change `r_device const new_template =` to `r_device const my_device =`, and `new_template_decode` to `my_device_decode`, and `.disabled = 3` to `.disabled = 0` - Edit `include/rtl_433_devices.h` E.g. add `DECL(my_device) \` - Add your files with Git (no need to commit yet) E.g. `git add src/devices/my_device.c include/rtl_433_devices.h` - Run `./maintainer_update.py` to add the CMake compile rules - Compile, add files with Git again E.g. `git add src/CMakeLists.txt` - Code and test your decoder, try to follow our code style (you can generally use clang-format). - Run `./maintainer_update.py` again for the readme files. - Review and commit your changes, push the changes then create a PR. ## Commit messages Pull-Requests (PR) will be added as squash commit and the commit message will likely be updated to follow this format. For general work, e.g. adding or changing decoders the commit messages should follow a format of [] Verb must be one of the following: - `Add`: for new additions, e.g. device support - `Fix`: for changes that don't change anything to input/output (security related or bug fixing) - `Remove`: for changes that remove behaviour (e.g. some old algorithms are cleaned up) - `Change`: for changes that modify input/output behaviour (e.g. added checksums, preambles) - `Improve`: for improvements without changes in normal output/behaviour Don't prefix general work, e.g. adding a decoder should be `Add support for TheDevice`. Other commit messages should follow the common format of : Area of work is optional and may be one of the following: - `minor`: other small changes that do not warrant a changelog entry - `build`: for build / build system / ci related work - `docs`: for documentation related work, both in code and readme/docs folder - `test`: for test related work - `deps`: for changes related to (external) dependencies (e.g. soapysdr is updated or mongoose is updated) - `examples`: for changes related to examples and scripts - `cosmetics`: for housekeeping work, code style changes ## Supporting Additional Devices and Test Data Some device protocol decoders are disabled by default. If you have one of the default-disabled devices then enable all needed device protocols with the `-R` option. This will likely produce false positives, use with caution. The first step in decoding new devices is to record the signals using `-S unknown`. The signals will be stored individually in files named g**NNN**\_**FFF**M\_**RRR**k.cu8 : | Parameter | Description |---------|------------ | **NNN** | signal grabbed number | **FFF** | frequency | **RRR** | sample rate This file can be played back with `rtl_433 -r gNNN_FFFM_RRRk.cu8`. These files are vital for understanding the signal format as well as the message data. Use the analyzer with `-A` to look at the recorded signal and determine the pulse characteristics, e.g. `rtl_433 -r gNNN_FFFM_RRRk.cu8 -A`. Make sure you have recorded a proper set of test signals representing different conditions together with any and all information about the values that the signal should represent. For example, make a note of what temperature and/or humidity is the signal encoding. Ideally, capture a range of data values, such a different temperatures, to make it easy to spot what part of the message is changing. Add the data files, a text file describing the captured signals, pictures of the device and/or a link the manufacturer's page (ideally with specifications) to the rtl_433_tests github repository. Follow the existing structure as best as possible and send a pull request. https://github.com/merbanan/rtl_433_tests Please don't open a new github issue for device support or request decoding help from others until you've added test signals and the description to the repository. The rtl_433_test repository is also used to help test that changes to rtl_433 haven't caused any regressions. ## Code style Indentation is 4 spaces. Check with `clang-format`. Indent `data_make()` nicely tabular and surround it with ``` /* clang-format off */ ... /* clang-format on */ ``` Start your file with a copyright note (indent 4 spaces) like: ``` /** @file Bresser Weather Center 5-in-1. Copyright (C) 2019 Christian W. Zuckschwerdt This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. */ ``` Name your decode function `foobar_decode`. Put documentation (markdown, no indent) before the decode function: ``` /** Bresser Weather Center 7-in-1, outdoor sensor. ...supported models etc. Data layout: IIII F TTT HH CC - I: 16 bit ID - F: 4 bit flags - T: 12 bit temperature, scale 10 - H: 8 bit humidity - C: 8 bit CRC-8, poly 0x81 Format string: ID:16h FLAGS:4h TEMP:12h HUMI:8h CRC:8h ...Decoding notes like endianness, signedness */ ``` The keys in `data_make()` need to contain - `"model"`, short unique key for this decoder - `"id", `a unique sensor ID - `"mic"`, if applicable the integrity check, e.g. `"PARITY"`, `"SUM"`, `"CRC"`, or `"DIGEST"`. See [JSON Data fields](DATA_FORMAT.md) for common keys. --- ## File: docs/DATA_FORMAT.md # JSON Data fields See also the discussion and rationale in https://github.com/merbanan/rtl_433/pull/827 ## Message Data These fields are the primary data fields containing the most basic message data and used to identify the specific device. For some devices these are the *only* fields contained in the message, as the message itself constitutes an event from this particular device model. * **time** (string) (Required) * Time stamp. String containing date and time of when the message was received. Format and timezone is dependent on current locale unless options like `-M time:unix` or `-M time:iso` and `-M time:utc` are used. * **type** (string) (Optional) * Classification of the general device type. Currently only used for `"TPMS"`. * **model** (string) (Required) * Device model. Human readable string concisely describing the device by manufacturer name and manufacturers model designation according to the following syntax: `"-"`. * It is common for devices to be sold under different brands, however the Original Equipment Manufacturer name shall be used, where possible to identify. * Avoid redundant word like "sensor", "wireless" etc. unless it is part of the manufacturers model designation. * Avoid adding device type designations like "Switch", "Temperature", "Thermostat", "Weather Station" etc. Device type can be inferred from the data content. * Avoid all non-alphanumeric characters, especially: `"/&$*#+[]()"`. * Length of *model* string should be less than 32 characters. * **subtype** (string) (Optional) * Device type or function in a common protocol. Examples are various sensors, triggers, keyfob in wireless security. * **id** (integer, rarely string) (Optional) * Device identification. Used to differentiate between devices of same *model*. Depending on device model it may be a non-volatile value programmed into the device, a volatile value that changes at each power on (or battery change), or a value configurable by user e.g. by switch or jumpers. No assumptions should be made to the id value other than it contains a unique sequence of alphanumeric characters. * Length of *id* should be less than 16 characters. * **channel** (integer, rarely string) (Optional) * Secondary device identification. For devices with more than one identification value (e.g. both an internal value and a switch). * **mic** (string) (Optional) * Message integrity check. String describing the method used for ensuring the data integrity of the message. Protocol decoders for devices without mic will be disabled by default as they are prone to excessive false positives. * Possible values: * "CRC" - Cyclic Redundancy Check. * "CHECKSUM" - Accumulated sum of data. * "PARITY" - Parity bit (odd, even, multiple) ## Common Device Data Various data fields, which are common across devices of different types. * **battery_ok** (double) (Optional) * Battery status indication as a level between 0 (empty) and 1 (full). If the sensor can only report a binary status the value shall be 1 for "OK" and 0 for "LOW". * **battery_V** (**battery_mV**) (double) (Optional) * Battery level in Volts. Should be supplemented by *battery_ok* status indication if possible. ## Sensor Data Due to the large variance in sensor types this list of common values is non-exhaustive. Additional data value fields should follow the form: `_`, where *Unit* should be in sensors native units insofar possible with no conversion. Automatic unit conversion can be performed with the `-C si` or `-C customary` option. Examples: * **temperature_C** (**temperature_F**) (double) (Optional) * Temperature from a temperature sensor in degrees Celsius (Fahrenheit). * **setpoint_C** (**setpoint_F**) (double) (Optional) * Thermal set point of a thermostat device in degrees Celsius (Fahrenheit). * **humidity** (double) (Optional) * Humidity from a hygrometer sensor in % relative humidity * **moisture** (double) (Optional) * Moisture from a soil probe in % relative saturation * **wind_dir_deg** (double) (Optional) * Wind direction from wind sensor in compass direction degrees. * **wind_avg_m_s** (**wind_avg_km_h**, **wind_avg_mi_h**) (double) (Optional) * Average wind speed from wind sensor in m/s. Averaging time is sensor dependent. * **wind_max_m_s** (**wind_max_km_h**, **wind_max_mi_h**) (double) (Optional) * Gust wind speed from wind sensor in m/s. * **rain_mm** (**rain_in**) (double) (Optional) * Rainfall from rain sensor in mm (inches) since last reset. Reset method is device dependent. * **rain_rate_mm_h** (**rain_rate_in_h**) (double) (Optional) * Rainfall rate from rain sensor in mm per hour (inches per hour). * **pressure_hPa** (**pressure_psi**) (double) (Optional) * Air pressure from barometer or Tire Pressure Monitor in hPa (psi) --- ## File: docs/HARDWARE.md # Hardware tested with rtl_433 rtl_433 is known to work with or tested with the following SDR hardware: ## RTL-SDR Actively tested and supported are Realtek RTL2832 based DVB dongles (and other similar devices supported by RTL-SDR). See also [RTL-SDR](https://github.com/osmocom/rtl-sdr/). ## SoapySDR Actively tested and supported are - [LimeSDR USB](https://www.crowdsupply.com/lime-micro/limesdr) - [LimeSDR mini](https://www.crowdsupply.com/lime-micro/limesdr-mini) - [LimeNet Micro](https://www.crowdsupply.com/lime-micro/limenet-micro) - [PlutoSDR](https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/adalm-pluto.html) - [SDRplay](https://www.sdrplay.com/) (RSP1A tested) - [HackRF One](https://greatscottgadgets.com/hackrf/) (reported, we don't have a receiver) - [SoapyRemote](https://github.com/pothosware/SoapyRemote/wiki) LimeSDR and LimeNet engineering samples were kindly provided by [MyriadRf](https://myriadrf.org/). See also [SoapySDR](https://github.com/pothosware/SoapySDR/). ## Not supported - Ultra cheap 1-bit (OOK) receivers, and antenna-on-a-raspi-pin - CC1101, and alike special purpose / non general SDR chips --- ## File: docs/INTEGRATION.md # Integration Integration of rtl_433 output into various home automation gateways. :::tip If you are a user of one these systems, please help to confirm and extend the information here. ::: ## openHAB [openHAB](https://www.openhab.org/) - open source automation software for your home See the wiki page https://github.com/merbanan/rtl_433/wiki/How-to-integrate-rtl_433-sensors-into-openHAB-via-MQTT Some help comes from https://community.openhab.org/t/rtl-433-to-mqtt/80652/3 Run rtl_433 -F "mqtt://192.168.178.42:1883,retain=0,devices=sensors/rtl_433/P[protocol]/C[channel]" This produces some topics in the broker like this: sensors/rtl_433/P25/C1/id 147 sensors/rtl_433/P25/C1/temperature_C 33.200001 sensors/rtl_433/P25/C1/rain_mm 107.699997 sensors/rtl_433/P25/C1/battery_ok 1 sensors/rtl_433/P25/C1/mic CRC You can easily set up some MQTT things then: Bridge mqtt:broker:My-MQTT "MQTT Broker" @ "RTL433" [ host="192.168.x.x", secure=false, port=1883, qos=0, retain=false, clientid="Oh2Mqtt2Thing", keep_alive_time=30000, reconnect_time=60000 ] { Thing topic RTL_433 "433MHz Empfänger" @ "RTL433" { Channels: Type number : temp "Temperatur" [ stateTopic="sensors/rtl_433/P25/C1/temperature_C" ] Type number : hum "Luftfeuchtigkeit" [ stateTopic="sensors/rtl_433/P25/C1/humidity" ] Type switch : batt "Battery schwach" [ stateTopic="sensors/rtl_433/P25/C1/battery", transformationPattern="MAP:battery.map"] } } ## Home Assistant [Home Assistant](https://www.home-assistant.io/) - Open source home automation Home Assistant has good MQTT support and can read rtl_433 event topics. Assuming rtl_433 is started with rtl_433 -C si -M time:unix:usec:utc -F mqtt you can set up temperature and humidity sensors in Home Assistant with sensor: - name: temperature_raw state_topic: "rtl_433/host/devices/Prologue-TH/5/3/+/temperature_C" platform: mqtt device_class: temperature unit_of_measurement: "°C" force_update: true expire_after: 610 - name: humidity_raw state_topic: "rtl_433/host/devices/Prologue-TH/5/3/+/humidity" platform: mqtt device_class: humidity unit_of_measurement: "%" force_update: true expire_after: 610 You may want to postprocess the received values with something like sensor: - name: temperature entity_id: sensor.temperature_raw platform: filter filters: - filter: outlier window_size: 2 radius: 3.0 See [the Home Assistant documentation](https://www.home-assistant.io/integrations/sensor.mqtt/) for more information. See also [rtl_433_mqtt_hass.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_mqtt_hass.py) MQTT Home Assistant auto discovery. ## Domoticz [Domoticz](http://www.domoticz.com/) - Home Automation System Domoticz has built-in support for reading from rtl_433 using pipes. There is also a newer plugin using MQTT: [enesbcs/pyrtl433](https://github.com/enesbcs/pyrtl433). :::warning Testing and example needed ::: ## NodeRED [NodeRED](https://nodered.org/) - Flow-based programming for the Internet of Things Node RED has built-in support for reading from MQTT and thus rtl_433 events. :::warning Example needed ::: ## Databases You likely need to filter and transform rtl_433's output before sending it to a database. It's recommended you read the JSON data and process it to your specific requirements. Some example pipes/relays for rtl_433 JSON data. Should work with Python 2 and also Python 3. The `pipe` examples read JSON output from `rtl_433` using a pipe, i.e. rtl_433 -F json ... | rtl_433_statsd_pipe.py The `relay` examples consumes the (UDP) Syslog output from rtl_433 (or a legacy plain JSON datagram). Basically run `rtl_433` with `-F syslog:127.0.0.1:1433` and the relay script as an unrelated process, i.e. rtl_433_mqtt_relay.py & rtl_433 -F syslog:127.0.0.1:1433 ### SQL An example to push data to SQL is at [Domifry/RTL_433_SQL_Connection](https://github.com/Domifry/RTL_433_SQL_Connection/), see also [#1828](https://github.com/merbanan/rtl_433/issues/1828). ### RRD See [rtl_433_rrd_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_rrd_relay.py) ### Statsd See [rtl_433_statsd_pipe.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_statsd_pipe.py) See [rtl_433_statsd_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_statsd_relay.py) ### Collectd See [rtl_433_collectd_pipe.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_collectd_pipe.py) ### Graphite See [rtl_433_graphite_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_graphite_relay.py) ### InfluxDB There is built-in support for an InfluxDB output. Specify an InfluxDB 2.0 server with e.g. rtl_433 -F "influx://localhost:9999/api/v2/write?org=&bucket=,token=" Specify an InfluxDB 1.x server with e.g. rtl_433 -F "influx://localhost:8086/write?db=&p=&u=" It is recommended to additionally use the option `-M time:unix:usec:utc` for correct timestamps in InfluxDB. If you want to filter messages before they are inserted into the InfluxDB or if you want to transform the data see [rtl_433_influxdb_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_influxdb_relay.py) for an example script. The [rtl433_influx](https://github.com/azrdev/rtl433_influx/) project allows to dump the JSON output of rtl_433 into InfluxDB. InfluxDB also comes with MQTT integration through Telegraf, see [MQTT Monitoring](https://www.influxdata.com/integration/mqtt-monitoring/) and [MQTT Consumer Input Plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/mqtt_consumer). ### MySQL TBD. ### Sqlite TBD. --- ## File: docs/IQ_FORMATS.md # Introduction to I/Q formats SDR data is exchanged and saved in different formats. There are formats for raw I/Q sample data and formats with demodulated pulse data. ## I/Q sample data formats I/Q stands for "In-phase / Quadrature", the raw data format used by SDR receivers and transmitters. A sample consists of an I and Q value, each commonly of 8, 12, or 16-bit. This is called "interleaved" in audio or video data. The data can be processed similar to a two-channel audio signal, although at a much higher sample rate. :::tip Common sample rates with RTL-SDR receivers are 250 kHz and 1024 kHz, also 1 MHz (1000 kHz). ::: The nature of an I/Q sample allows to use a bandwidth equal to the sample rate (with a purely real signal the Nyquist-Shannon sampling theorem would only allow half the bandwidth). Generally the data formats are header- (and thus metadata-)less, the used center frequency and sample rate must be transferred separately or encoded in the filename. Formats differ in sample-(bit-)width and (bit-)number format, used bit-widths are 4, 8, 12, 16, 32, and 64, bit-formats are unsigned integer, signed integer, and float: - `.cu4`: Complex (I/Q), Unsigned integer, 4-bit per value (8 bit per sample) - `.cs4`: Signed integer - `.cu8` (`.data` `.complex16u`): 8-bit per value (16 bit per sample) - `.cs8` (`.complex16s`) - `.cu12`: 12-bit per value (24 bit per sample) - `.cs12` - `.cu16`: 16-bit per value (32 bit per sample) - `.cs16` - `.cu32`: 32-bit per value (64 bit per sample) - `.cs32` - `.cu64`: 64-bit per value (128 bit per sample) - `.cs64` - `.cf32` (`.cfile` `.complex`): Float, 32-bit per value (64 bit per sample) - `.cf64`: Double Float, 64-bit per value (128 bit per sample) Also used but rarely supported are audio files containing I/Q data: - `.wav` - `.bwf`: Broadcast Wave Format The "native" format for RTL-SDR receivers is `.cu8`, for other receivers likely `.cs16`. Most receivers only sample with 12-bit per channel, using `.cs12` will be more compact although not as widely supported. The rtl_433 program supports most of these formats and allows to read, write, or convert them, e.g.: - `rtl_433 -w FILE.cu8`: write received data to sample file - `rtl_433 -w FILE.cu8 FILE.cs16`: convert sample file ## Pulse data formats Demodulated data can be stored in a readable text-format with file extension `.ook`, also `.fsk` or `.psk`. A header contains meta data about the demodulation (2-ASK / ook, 2-FSK / fsk, ...) and the extension is informational only. Each regular line in the file format contains a number for pulse duration and a number for gap duration. For FSK or PSK demodulation these are mark and space duration. There is also the `.vcd` format which can carry the same information and might be useful with traditional signal data software. It can optionally also encode more than two states, e.g. (4-FSK), this isn't used however. A very compact format is `rfraw:`, usually just one line of code. This format encodes quantized pulse/gap durations with a maximum of eight different durations. There are also formats for demodulated but "raw" amplitude or frequency, e.g. `.am.s16`, `.fm.s16` similar to the above formats but with only one "channel". The SigRok `.sr` format is a Zip and combines multiple files for easy viewing with SigRok Pulseview. :::tip Install SigRok Pulseview and write a SigRok file. The overwrite option (uppercase `-W`) will automatically open Pulseview. ::: The rtl_433 program can create all these formats from live data or sample files, e.g.: - `rtl_433 -w FILE.ook`: write received data to ook file - `rtl_433 -w FILE.ook FILE.cu8`: convert sample file to ook file ## File name meta data In addition to the file extension meta data about the center frequency and sample rate are encoded in the filename. - `433.92M` : A decimal number suffixed with `M` denotes the center frequency - `1000k` : A decimal number suffixed with `k` denotes the sample rate Each part of the filename must be separated by an underscore. Even with low frequencies or high sample rates the suffix is fixed, :::warning `433920k` is not a valid frequency specification and `1M` is not a valid sample rate specification in filenames. ::: ## File viewers All raw I/Q sample data formats and most demodulated pulse data formats can be visualized with the [triq I/Q Spectrogram and Pulsedata viewer](https://triq.org/pdv/). --- ## File: docs/LINKS.md # Links to tools and related projects ## SDR Inputs/Drivers - [RTL-SDR](https://github.com/osmocom/rtl-sdr/) - [SoapySDR](https://github.com/pothosware/SoapySDR/) ## Analysis - [SigRok](https://sigrok.org/) [PulseView](https://sigrok.org/wiki/PulseView) - [Audacity](https://www.audacityteam.org/) - [Spectrogram](http://triq.org/pdv) to visualize sample files - [BitBench](http://triq.org/bitbench) to analyze data formats ## Related projects - [ShinySDR](https://shinysdr.switchb.org/) Web remote-controllable SDR receiver application supporting multiple simultaneous hardware devices and demodulators, including rtl_433 and other decoding tools. - [HASS addon to convert rtl433 output to mqtt](https://github.com/james-fry/hassio-addons/blob/master/rtl4332mqtt/rtl2mqtt.sh) - [rtl_fl2k_433](https://github.com/winterrace2/rtl_fl2k_433) an RX/TX prototyping tool. Aims to be a comfortable, GUI-based bridge between RTL-SDR dongles on RX side and cheap FL2K dongles on TX side. Currently, the GUI is available for Win64 only. - [rtl_433 with Snap7](https://github.com/merbanan/rtl_433/issues/950) to inject weather data to industrial control system (PLC - Siemens S7-300 or compatible VIPA) coming from Weather station WH1080. - [Domoticz](https://www.domoticz.com/) rtl_433 is usable from domoticz with a quite good integration: Domoticz launch rtl_433 with no data detection (relaunch rtl_433 if so) and process csv output format. All command line arguments are usable. - [WeeWx](http://weewx.com/) the weewx-sdr driver gets data from rtl_433 and feeds it into weewx. from there the data can be combined with data from other sources, displayed using any of the many weewx skins, and/or uploaded to many different web services. the first weewx-sdr release was in 2016. S.a. https://github.com/matthewwall/weewx-sdr https://github.com/weewx/weewx/wiki#skins https://github.com/weewx/weewx/wiki#uploaders - [rtl_snr](https://github.com/hdtodd/rtl_snr): snr is a pair of equivalent C and Python programs that catalog and analyze signal-to-noise ratios from devices seen by RTL_SDR dongles and logged in JSON format by rtl_433. - [rtl_sdr driver](https://f-droid.org/en/packages/marto.rtl_tcp_andro/): rtl_sdr driver is a port of rtl_tcp to Android. See also the [source code](https://github.com/signalwareltd/rtl_tcp_andro-).