X-Git-Url: https://git.rvb.name/rtl-433.git/blobdiff_plain/ca13278b24eb61443559bcb61e64627fba3d8823..6d15c6f967221af825cf84e3ed12b96c763b127b:/README.md diff --git a/README.md b/README.md index dd180f6..b79587a 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,21 @@ rtl_433 rtl_433 turns your Realtek RTL2832 based DVB dongle into a 433.92MHz generic data receiver +How to add support for unsupported sensors +------------------------------------------ + +Read the Test Data section at the bottom. + + Installation instructions: -------------------------- Compiling rtl_433 requires [rtl-sdr](http://sdr.osmocom.org/trac/wiki/rtl-sdr) to be installed. +Depending on your system, you may also need to install the following libraries: + + sudo apt-get install libtool libusb-1.0.0-dev librtlsdr-dev rtl-sdr + Installation using cmake: cd rtl_433/ @@ -15,15 +25,17 @@ Installation using cmake: cd build cmake ../ make - make install + make install Installation using autoconf: cd rtl_433/ autoreconf --install - ./configure - make - make install + ./configure + make + make install + +The final 'make install' step should be run as a user with appropriate permissions - if in doubt, 'sudo' it. Running: @@ -31,47 +43,188 @@ Running: rtl_433 -h - Usage: [-d device_index (default: 0)] - [-g gain (default: 0 for auto)] - [-a analyze mode, print a textual description of the signal] - [-l change the detection level used to determine pulses (0-32000) default 10000] - [-f change the receive frequency, default is 433.92MHz] - [-S force sync output (default: async)] - [-r read data from file instead of from a receiver] - filename (a '-' dumps samples to stdout) +``` +Usage: = Tuner options = + [-d ] (default: 0) + [-g ] (default: 0 for auto) + [-f ] [-f...] Receive frequency(s) (default: 433920000 Hz) + [-p ] Set sample rate (default: 250000 Hz) + [-S] Force sync output (default: async) + = Demodulator options = + [-R ] Enable only the specified device decoding protocol (can be used multiple times) + [-G] Enable all device protocols, included those disabled by default + [-l ] Change detection level used to determine pulses [0-16384] (0 = auto) (default: 0) + [-z ] Override short value in data decoder + [-x ] Override long value in data decoder + [-n ] Specify number of samples to take (each sample is 2 bytes: 1 each of I & Q) + = Analyze/Debug options = + [-a] Analyze mode. Print a textual description of the signal. Disables decoding + [-A] Pulse Analyzer. Enable pulse analyzis and decode attempt + [-I] Include only: 0 = all (default), 1 = unknown devices, 2 = known devices + [-D] Print debug info on event (repeat for more info) + [-q] Quiet mode, suppress non-data messages + [-W] Overwrite mode, disable checks to prevent files from being overwritten + = File I/O options = + [-t] Test signal auto save. Use it together with analyze mode (-a -t). Creates one file per signal + Note: Saves raw I/Q samples (uint8 pcm, 2 channel). Preferred mode for generating test files + [-r ] Read data from input file instead of a receiver + [-m ] Data file mode for input / output file (default: 0) + 0 = Raw I/Q samples (uint8, 2 channel) + 1 = AM demodulated samples (int16 pcm, 1 channel) + 2 = FM demodulated samples (int16) (experimental) + 3 = Raw I/Q samples (cf32, 2 channel) + Note: If output file is specified, input will always be I/Q + [-F] kv|json|csv Produce decoded output in given format. Not yet supported by all drivers. + [-C] native|si|customary Convert units in decoded output. + [-T] specify number of seconds to run + [-U] Print timestamps in UTC (this may also be accomplished by invocation with TZ environment variable set). + [] Save data stream to output file (a '-' dumps samples to stdout) + +Supported device protocols: + [01]* Silvercrest Remote Control + [02] Rubicson Temperature Sensor + [03] Prologue Temperature Sensor + [04] Waveman Switch Transmitter + [05]* Steffen Switch Transmitter + [06]* ELV EM 1000 + [07]* ELV WS 2000 + [08] LaCrosse TX Temperature / Humidity Sensor + [09]* Template decoder + [10]* Acurite 896 Rain Gauge + [11] Acurite 609TXC Temperature and Humidity Sensor + [12] Oregon Scientific Weather Sensor + [13] Mebus 433 + [14]* Intertechno 433 + [15] KlikAanKlikUit Wireless Switch + [16] AlectoV1 Weather Sensor (Alecto WS3500 WS4500 Ventus W155/W044 Oregon) + [17]* Cardin S466-TX2 + [18] Fine Offset Electronics, WH2 Temperature/Humidity Sensor + [19] Nexus Temperature & Humidity Sensor + [20] Ambient Weather Temperature Sensor + [21] Calibeur RF-104 Sensor + [22]* X10 RF + [23]* DSC Security Contact + [24]* Brennenstuhl RCS 2044 + [25]* GT-WT-02 Sensor + [26] Danfoss CFR Thermostat + [27]* Energy Count 3000 (868.3 MHz) + [28]* Valeo Car Key + [29] Chuango Security Technology + [30] Generic Remote SC226x EV1527 + [31] TFA-Twin-Plus-30.3049 and Ea2 BL999 + [32] Fine Offset Electronics WH1080/WH3080 Weather Station + [33] WT450 + [34] LaCrosse WS-2310 Weather Station + [35] Esperanza EWS + [36]* Efergy e2 classic + [37]* Inovalley kw9015b rain and Temperature weather station + [38] Generic temperature sensor 1 + [39]* Acurite 592TXR Temp/Humidity, 5n1 Weather Station, 6045 Lightning + [40]* Acurite 986 Refrigerator / Freezer Thermometer + [41] HIDEKI TS04 Temperature, Humidity, Wind and Rain Sensor + [42] Watchman Sonic / Apollo Ultrasonic / Beckett Rocket oil tank monitor + [43] CurrentCost Current Sensor + [44] emonTx OpenEnergyMonitor + [45] HT680 Remote control + [46] S3318P Temperature & Humidity Sensor + [47] Akhan 100F14 remote keyless entry + [48] Quhwa + [49] OSv1 Temperature Sensor + [50] Proove + [51] Bresser Thermo-/Hygro-Sensor 3CH + [52] Springfield Temperature and Soil Moisture + [53] Oregon Scientific SL109H Remote Thermal Hygro Sensor + [54] Acurite 606TX Temperature Sensor + [55] TFA pool temperature sensor + [56] Kedsum Temperature & Humidity Sensor + [57] blyss DC5-UK-WH (433.92 MHz) + [58] Steelmate TPMS + [59] Schraeder TPMS + [60]* LightwaveRF + [61] Elro DB286A Doorbell + [62] Efergy Optical + [63] Honda Car Key + [64]* Template decoder + [65] Fine Offset Electronics, XC0400 + [66] Radiohead ASK + [67] Kerui PIR Sensor + [68] Fine Offset WH1050 Weather Station + [69] Honeywell Door/Window Sensor + [70] Maverick ET-732/733 BBQ Sensor + [71]* RF-tech + [72] LaCrosse TX141TH-Bv2 sensor + [73] Acurite 00275rm,00276rm Temp/Humidity with optional probe + [74] LaCrosse TX35DTH-IT Temperature sensor + [75] LaCrosse TX29IT Temperature sensor + [76] Fine Offset Electronics, WH25 Temperature/Humidity/Pressure Sensor + [77] Fine Offset Electronics, WH0530 Temperature/Rain Sensor + +* Disabled by default, use -R n or -G +``` Examples: | Command | Description |---------|------------ -| `rtl_433 -a` | will run in analyze mode and you will get a text log of the received signal. -| `rtl_433 -a file_name` | will save the demodulated signal in a file. The format of the file is 48kHz 16 bit samples. -| `rtl_433` | will run the software in receive mode. Some sensor data can be receviced. +| `rtl_433 -G` | Default receive mode, attempt to decode all known devices +| `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). +| `rtl_433 -a` | Will run in analyze mode and you will get a text description of the received signal. +| `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. +| `rtl_433 -a -t` | Will run in analyze mode and save a test file per detected signal (gfile###.data). Format is uint8, 2 channels. +| `rtl_433 -r file_name` | Play back a saved data file. +| `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. +| `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`. This software is mostly useable for developers right now. -Supported Devices ------------------ - - Rubicson Temperature Sensor - Silvercrest Remote Control - ELV EM 1000 - ELV WS 2000 - Waveman Switch Transmitter - Steffen Switch Transmitter - Acurite 5n1 Weather Station - Acurite Temperature and Humidity Sensor - Acurite 896 Rain Gauge - LaCrosse TX Temperature / Humidity Sensor - Oregon Scientific Weather Sensor - KlikAanKlikUit Wireless Switch - AlectoV1 Weather Sensor - Intertechno 433 - Mebus 433 + +Supporting Additional Devices and Test Data +------------------------------------------- + +Note: Not all device protocol decoders are enabled by default. When testing to see if your device +is decoded by rtl_433, use `-G` to enable all device protocols. + +The first step in decoding new devices is to record the signals using `-a -t`. The signals will be +stored individually in files named gfileNNN.data that can be played back with `rtl_433 -r gfileNNN.data`. + +These files are vital for understanding the signal format as well as the message data. Use both analyzers +`-a` and `-A` to look at the recorded signal and determine the pulse characteristics, e.g. `rtl_433 -r gfileNNN.data -a -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. 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 dvb_usb_rtl28xxu rtl2832 +