README.md

   1 rtl_433
   2 =======
   3
   4 rtl_433 turns your Realtek RTL2832 based DVB dongle into a 433.92MHz generic data receiver
   5
   6 How to add support for unsupported sensors
   7 ------------------------------------------
   8
   9 Read the Test Data section at the bottom.
  10
  11
  12 Installation instructions:
  13 --------------------------
  14
  15 Compiling rtl_433 requires [rtl-sdr](http://sdr.osmocom.org/trac/wiki/rtl-sdr) to be installed.
  16
  17 Depending on your system, you may also need to install the following libraries:
  18
  19     sudo apt-get install libtool libusb-1.0.0-dev librtlsdr-dev rtl-sdr
  20
  21 Installation using cmake:
  22
  23     cd rtl_433/
  24     mkdir build
  25     cd build
  26     cmake ../
  27     make
  28     make install
  29
  30 Installation using autoconf:
  31
  32     cd rtl_433/
  33     autoreconf --install
  34     ./configure
  35     make
  36     make install
  37
  38 The final 'make install' step should be run as a user with appropriate permissions - if in doubt, 'sudo' it.
  39
  40
  41 Running:
  42 --------
  43
  44     rtl_433 -h
  45
  46 ```
  47 Usage:  = Tuner options =
  48         [-d <RTL-SDR USB device index>] (default: 0)
  49         [-g <gain>] (default: 0 for auto)
  50         [-f <frequency>] [-f...] Receive frequency(s) (default: 433920000 Hz)
  51         [-p <ppm_error] Correct rtl-sdr tuner frequency offset error (default: 0)
  52         [-s <sample rate>] Set sample rate (default: 250000 Hz)
  53         [-S] Force sync output (default: async)
  54         = Demodulator options =
  55         [-R <device>] Enable only the specified device decoding protocol (can be used multiple times)
  56         [-G] Enable all device protocols, included those disabled by default
  57         [-l <level>] Change detection level used to determine pulses [0-16384] (0 = auto) (default: 0)
  58         [-z <value>] Override short value in data decoder
  59         [-x <value>] Override long value in data decoder
  60         [-n <value>] Specify number of samples to take (each sample is 2 bytes: 1 each of I & Q)
  61         = Analyze/Debug options =
  62         [-a] Analyze mode. Print a textual description of the signal. Disables decoding
  63         [-A] Pulse Analyzer. Enable pulse analyzis and decode attempt
  64         [-I] Include only: 0 = all (default), 1 = unknown devices, 2 = known devices
  65         [-D] Print debug info on event (repeat for more info)
  66         [-q] Quiet mode, suppress non-data messages
  67         [-W] Overwrite mode, disable checks to prevent files from being overwritten
  68         = File I/O options =
  69         [-t] Test signal auto save. Use it together with analyze mode (-a -t). Creates one file per signal
  70                  Note: Saves raw I/Q samples (uint8 pcm, 2 channel). Preferred mode for generating test files
  71         [-r <filename>] Read data from input file instead of a receiver
  72         [-m <mode>] Data file mode for input / output file (default: 0)
  73                  0 = Raw I/Q samples (uint8, 2 channel)
  74                  1 = AM demodulated samples (int16 pcm, 1 channel)
  75                  2 = FM demodulated samples (int16) (experimental)
  76                  3 = Raw I/Q samples (cf32, 2 channel)
  77                  Note: If output file is specified, input will always be I/Q
  78         [-F] kv|json|csv Produce decoded output in given format. Not yet supported by all drivers.
  79         [-C] native|si|customary Convert units in decoded output.
  80         [-T] specify number of seconds to run
  81         [-U] Print timestamps in UTC (this may also be accomplished by invocation with TZ environment variable set).
  82         [<filename>] Save data stream to output file (a '-' dumps samples to stdout)
  83
  84 Supported device protocols:
  85     [01]* Silvercrest Remote Control
  86     [02]  Rubicson Temperature Sensor
  87     [03]  Prologue Temperature Sensor
  88     [04]  Waveman Switch Transmitter
  89     [05]* Steffen Switch Transmitter
  90     [06]* ELV EM 1000
  91     [07]* ELV WS 2000
  92     [08]  LaCrosse TX Temperature / Humidity Sensor
  93     [09]* Template decoder
  94     [10]* Acurite 896 Rain Gauge
  95     [11]  Acurite 609TXC Temperature and Humidity Sensor
  96     [12]  Oregon Scientific Weather Sensor
  97     [13]  Mebus 433
  98     [14]* Intertechno 433
  99     [15]  KlikAanKlikUit Wireless Switch
 100     [16]  AlectoV1 Weather Sensor (Alecto WS3500 WS4500 Ventus W155/W044 Oregon)
 101     [17]* Cardin S466-TX2
 102     [18]  Fine Offset Electronics, WH2 Temperature/Humidity Sensor
 103     [19]  Nexus Temperature & Humidity Sensor
 104     [20]  Ambient Weather Temperature Sensor
 105     [21]  Calibeur RF-104 Sensor
 106     [22]* X10 RF
 107     [23]* DSC Security Contact
 108     [24]* Brennenstuhl RCS 2044
 109     [25]* GT-WT-02 Sensor
 110     [26]  Danfoss CFR Thermostat
 111     [27]* Energy Count 3000 (868.3 MHz)
 112     [28]* Valeo Car Key
 113     [29]  Chuango Security Technology
 114     [30]  Generic Remote SC226x EV1527
 115     [31]  TFA-Twin-Plus-30.3049 and Ea2 BL999
 116     [32]  Fine Offset Electronics WH1080/WH3080 Weather Station
 117     [33]  WT450
 118     [34]  LaCrosse WS-2310 Weather Station
 119     [35]  Esperanza EWS
 120     [36]* Efergy e2 classic
 121     [37]* Inovalley kw9015b rain and Temperature weather station
 122     [38]  Generic temperature sensor 1
 123     [39]* Acurite 592TXR Temp/Humidity, 5n1 Weather Station, 6045 Lightning
 124     [40]* Acurite 986 Refrigerator / Freezer Thermometer
 125     [41]  HIDEKI TS04 Temperature, Humidity, Wind and Rain Sensor
 126     [42]  Watchman Sonic / Apollo Ultrasonic / Beckett Rocket oil tank monitor
 127     [43]  CurrentCost Current Sensor
 128     [44]  emonTx OpenEnergyMonitor
 129     [45]  HT680 Remote control
 130     [46]  S3318P Temperature & Humidity Sensor
 131     [47]  Akhan 100F14 remote keyless entry
 132     [48]  Quhwa
 133     [49]  OSv1 Temperature Sensor
 134     [50]  Proove
 135     [51]  Bresser Thermo-/Hygro-Sensor 3CH
 136     [52]  Springfield Temperature and Soil Moisture
 137     [53]  Oregon Scientific SL109H Remote Thermal Hygro Sensor
 138     [54]  Acurite 606TX Temperature Sensor
 139     [55]  TFA pool temperature sensor
 140     [56]  Kedsum Temperature & Humidity Sensor
 141     [57]  blyss DC5-UK-WH (433.92 MHz)
 142     [58]  Steelmate TPMS
 143     [59]  Schraeder TPMS
 144     [60]* LightwaveRF
 145     [61]  Elro DB286A Doorbell
 146     [62]  Efergy Optical
 147     [63]  Honda Car Key
 148     [64]* Template decoder
 149     [65]  Fine Offset Electronics, XC0400
 150     [66]  Radiohead ASK
 151     [67]  Kerui PIR Sensor
 152     [68]  Fine Offset WH1050 Weather Station
 153     [69]  Honeywell Door/Window Sensor
 154     [70]  Maverick ET-732/733 BBQ Sensor
 155     [71]* RF-tech
 156     [72]  LaCrosse TX141TH-Bv2 sensor
 157     [73]  Acurite 00275rm,00276rm Temp/Humidity with optional probe
 158     [74]  LaCrosse TX35DTH-IT Temperature sensor
 159     [75]  LaCrosse TX29IT Temperature sensor
 160     [76]  Fine Offset Electronics, WH25 Temperature/Humidity/Pressure Sensor
 161     [77]  Fine Offset Electronics, WH0530 Temperature/Rain Sensor
 162
 163 * Disabled by default, use -R n or -G
 164 ```
 165
 166
 167 Examples:
 168
 169 | Command | Description
 170 |---------|------------
 171 | `rtl_433 -G` | Default receive mode, attempt to decode all known devices
 172 | `rtl_433 -p NN -R 1 -R 9 -R 36 -R 40` | Typical usage: Enable device decoders for desired devices. Correct rtl-sdr tuning error (ppm offset).
 173 | `rtl_433 -a` | Will run in analyze mode and you will get a text description of the received signal.
 174 | `rtl_433 -A` | Enable pulse analyzer. Summarizes the timings of pulses, gaps, and periods. Can be used in either the normal decode mode, or analyze mode.
 175 | `rtl_433 -a -t` | Will run in analyze mode and save a test file per detected signal (gfile###.data). Format is uint8, 2 channels.
 176 | `rtl_433 -r file_name` | Play back a saved data file.
 177 | `rtl_433 file_name` | Will save everything received from the rtl-sdr during the session into a single file. The saves file may become quite large depending on how long rtl_433 is left running. Note: saving signals into individual files wint `rtl_433 -a -t` is preferred.
 178 | `rtl_433 -F json -U | 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 `tests/mqtt_rtl_433_test.py`.
 179
 180 This software is mostly useable for developers right now.
 181
 182
 183 Supporting Additional Devices and Test Data
 184 -------------------------------------------
 185
 186 Note: Not all device protocol decoders are enabled by default. When testing to see if your device
 187 is decoded by rtl_433, use `-G` to enable all device protocols.
 188
 189 The first step in decoding new devices is to record the signals using `-a -t`. The signals will be
 190 stored individually in files named gfileNNN.data that can be played back with `rtl_433 -r gfileNNN.data`.
 191
 192 These files are vital for understanding the signal format as well as the message data.  Use both analyzers
 193 `-a` and `-A` to look at the recorded signal and determine the pulse characteristics, e.g. `rtl_433 -r gfileNNN.data -a -A`.
 194
 195 Make sure you have recorded a proper set of test signals representing different conditions together
 196 with any and all information about the values that the signal should represent. For example, make a
 197 note of what temperature and/or humidity is the signal encoding. Ideally, capture a range of data
 198 values, such a different temperatures, to make it easy to spot what part of the message is changing.
 199
 200 Add the data files, a text file describing the captured signals, pictures of the device and/or
 201 a link the manufacturer's page (ideally with specifications) to the rtl_433_tests
 202 github repository. Follow the existing structure as best as possible and send a pull request.
 203
 204 https://github.com/merbanan/rtl_433_tests
 205
 206 Please don't open a new github issue for device support or request decoding help from others
 207 until you've added test signals and the description to the repository.
 208
 209 The rtl_433_test repository is also used to help test that changes to rtl_433 haven't caused any regressions.
 210
 211 Google Group
 212 ------------
 213
 214 Join the Google group, rtl_433, for more information about rtl_433:
 215 https://groups.google.com/forum/#!forum/rtl_433
 216
 217
 218 Troubleshooting
 219 ---------------
 220
 221 If you see this error:
 222
 223     Kernel driver is active, or device is claimed by second instance of librtlsdr.
 224     In the first case, please either detach or blacklist the kernel module
 225     (dvb_usb_rtl28xxu), or enable automatic detaching at compile time.
 226
 227 then
 228
 229     sudo rmmod dvb_usb_rtl28xxu rtl2832
 230