rtl_433_stats v2.3.0

Catalog and analyze transmissions from devices recorded in rtl_433 JSON logs

Function

rtl_433_stats catalogs and characterizes ISM-band devices in your neighborhood using data from the JSON log file generated by rtl_433. It processes rtl_433 JSON log files to:

• read the recorded packet information from the log file(s),
• catalog all devices recorded in the log(s),
• count the packets and consolidate redundant packets into individual transmissions,
• summarize the statistics about packet signal-to-noise ratios (SNR) and radio frequencies (Freq), the gap times between transmissions (ITGT), and the packets per transmission (PPT).

The observed devices, as recorded in the JSON file in temporal order, are cataloged in alphabetical order in a summary table. The summary includes a count of the number of packets and de-duplicated transmissions seen for that device and basic statistics for each device of the signal-to-noise-ratios, transmission frequency, inter-transmission-gap-time (in seconds), and packets-per-transmission. The statistics include:

• mean,
• std deviation,
• min value seen, and
• max value seen.

Sample output looks like this:

rtl_433_stats: 
	Analyze rtl_433 JSON logs to catalog the devices seen and to characterize
	statistically their signal-to-noise ratio (SNR), radio frequency (Freq),
	times between transmissions (ITGT), and packets per transmission (PPT).

Processing ISM messages recorded by rtl_433 from file xaa.json
Including SNR Stats
Including ITGT Stats
Including Freq Stats
Excluding TPMS devices

Processed 20000 Packets as 6952 De-Duplicated Transmissions in  0.116 sec 
Packets dated from Thu 2022-06-09 07:08:27 to Thu 2022-06-09 19:46:16

                                                  Signal-to-Noise                 Frequency (MHz)             Inter-Transmission Gap Time (sec)    Packets per Transmit 
                                              ________________________   ___________________________________  _________________________________    _____________________
Device model/channel/id         #Pkts #Xmits  Mean ±   𝜎    Min    Max   Mean    ±   𝜎          Min      Max    Mean  ±     𝜎      Min      Max    Mean ±   𝜎   Min  Max
Acurite-01185M/0/0                  4      4   9.6 ±  4.9   6.4   16.9   433.911 ±  0.017   433.902  433.936   3678.7 ± 2812.7   434.0   5425.0     1.0 ±  0.0    1    1
Acurite-606TX//134                858    858   8.4 ±  2.1   5.5   20.0   433.901 ±  0.009   433.863  433.962     53.0 ±  139.2    30.0   2573.0     1.0 ±  0.0    1    1
Acurite-609TXC//194              8006   1357  19.3 ±  0.5  12.3   21.2   433.931 ±  0.002   433.922  433.950     33.5 ±    0.7    33.0     49.0     5.9 ±  0.4    2    6
Acurite-Tower/A/11524            8203   2753  19.2 ±  0.5  13.2   20.8   433.950 ±  0.002   433.926  433.955     16.5 ±    2.5    15.0     33.0     3.0 ±  0.2    1    3
LaCrosse-TX141Bv3/1/253           597    348   8.4 ±  1.3   5.7   19.2   433.904 ±  0.003   433.863  433.945    109.9 ±  338.9    31.0   4216.0     1.7 ±  0.5    1    2
LaCrosse-TX141THBv2/0/168        1536    838   9.6 ±  1.1   6.0   19.2   433.961 ±  0.004   433.862  433.966     54.2 ±   14.7    49.0    150.0     1.8 ±  0.4    1    2
Markisol/0/0                       39     39  19.1 ±  1.2  12.3   20.2   433.932 ±  0.002   433.928  433.936   1053.5 ± 1532.1    33.0   6633.0     1.0 ±  0.0    1    1
Markisol/0/256                     20     20  19.3 ±  0.4  18.5   20.2   433.931 ±  0.002   433.927  433.936   2108.7 ± 3625.7    33.0  14070.0     1.0 ±  0.0    1    1
Markisol/1/0                       36     36  19.2 ±  0.5  17.6   20.0   433.931 ±  0.002   433.927  433.934   1009.8 ± 1550.0    67.0   6801.0     1.0 ±  0.0    1    1
Prologue-TH/2/203                 699    699  11.6 ±  1.3   7.2   19.5   433.864 ±  0.008   433.859  433.943     64.9 ±   32.7    52.0    477.0     1.0 ±  0.0    1    1

Use

Issue the command rtl_433_stats -i <JSON filename> to generate the report. Note that the input file specification may include wildcards and/or compressed files (.gz or .bz2). Use -i with no file specification for stdin.

Issue the command rtl_433_stats -h to see command-line options:

usage: rtl_433_stats [-h] [-i [FILE ...]] [-o {SNR,ITGT,Freq,PPT} [{SNR,ITGT,Freq,PPT} ...]] [-x NOISE] [-w WINDOW] [-T] [-v]

	Analyze rtl_433 JSON logs to catalog the devices seen and to characterize
	statistically their signal-to-noise ratio (SNR), times between
	transmissions (ITGT),tradio frequency (Freq), and packets per transmission (PPT).

options:
  -h, --help            show this help message and exit
  -i [FILE ...], --input [FILE ...]
                        Path to JSON log files to read in; can be .gz; can be wildcard; blank if <stdin>
  -o {SNR,ITGT,Freq,PPT} [{SNR,ITGT,Freq,PPT} ...], --omit {SNR,ITGT,Freq,PPT} [{SNR,ITGT,Freq,PPT} ...]
  -x NOISE, --exclude_noise NOISE
                        Exclude device records with fewer than 'NOISE' packets seen
  -w WINDOW, --xmt_window WINDOW
                        Max time in sec for a packet group to be considered as one transmission (default: None)
  -T, --include_TPMS    include tire pressure monitors in catalog (default: False)
  -v, --version         show program's version number and exit

In practice and for log files recorded over long periods, the log file may contain records for devices seen only sporadically: tire pressure monitor systems, security systems, automobile remotes, etc. These may make the report long and difficult to read. Some options help customize the reports:

• By default, tire pressure monitoring systems (TPMS) are excluded from reports: use -T to include them.
• All other devices recorded in the log file(s) are included in the report by default. Use the -x n option to exclude from the report any device with less than n transmissions in the logs (typically n=10 to 100 seem to be most useful).
• The default report with all four characteristics is fairly wide. It can be narrowed by omitting one or more of the characteristics with the -o option followed by SNR, ITGT, Freq, and/or PPT to specify which reports to omit.
• By default, packets broadcast by a single device within a 2-second window are considered to be one transmission. The -w n option, n in seconds, can be used to change that window, affecting the ITGT and PPT reports.

If you've configured logrotate to compress and archive your rtl_433 log files, you can process the .gz log files directly with the file specification to rtl_433_stats, and you can select just a set of files with wildcards. For example, specify -i /var/log/rtl_433/rtl_433.json-202303*.gz to generate a report for just March, 2023.

Operational Details

rtl_433_stats reads the JSON log file created by rtl_433 (recommend to stop rtl_433 so that the JSON log file is closed for processing). Each line of the JSON file represents one packet, and the values of signal-to-noise-ratio (SNR) and transmission frequency for each packet are included in the overall summary for each individual device. Devices are identified by a key string composed from information from the JSON records. The identifier has the form model/channel/id, where the individual components are the values taken from the JSON record.

The observed devices, as recorded in the JSON file in temporal order, are cataloged in alphabetical order in a summary table along with a count of the number of packets and de-duplicated transmissions seen for that device and with basic statistics:

• mean,
• std deviation,
• min value seen, and
• max value seen

for these device characteristics:

• signal-to-noise ratio over all packets (SNR),
• radio frequency of transmissions (Freq) over all packets from that device,
• inter-transmission gap times (ITGT): the time in seconds between successive transmissions by that device, and
• the number of packets per transmission (PPT).

Note

The frequency reported is that associated with the JSON field "freq". For devices that report more than one frequency, the field labeled "freq1" is used.

A command-line option allows the de-selection of any or all of these characteristics (default is to report all four).

A device "transmission" represents one observation but may contain 1 to 6 or more "packets". Transmissions are frequently initiated by remote sensor devices at approximately 15-second, 30-second, or 60-second intervals. These are simplex communication devices -- the remote device sends data and receives no acknowledgement from the receiver that it has received the data. In high-traffic neighborhoods, the signals from the various devices may interfere with each other. Sending redundant packets increases the probability that a receiving device will successfully receive at least one packet in the transmission. rtl_433_stats builds a catalog of devices as it processes the file; it updates statistics for SNR and frequency as it processes individual packets; and it groups packets into individual transmissions based on the time between packets (default is 2 sec for receipt of all packets for an individual transmission) and updates transmission statistics.

While processing the JSON log files, rtl_433_stats monitors the "battery_ok" and "status" flags for each device (if present in the packets) and prints an alert that there has been a change in condition in the remote device. Generally a 1-->0 change in "battery_ok" indicates a low voltage on the battery and suggests that the battery should be changed. The values of "status" vary by device and are generally not well documented, but the program notes them for you in case further investigation is justified.

Installation

1. Use git to clone the distribution from Github, clone https://github.com/hdtodd/rtl_433_stats
2. Connect to the download directory
3. Type ./rtl_433_stats -i xaa.json and compare its output with the file xaa-output.rpt to ensure that it is functioning correctly.

After verifying that ./rtl_433_statsis functioning correctly with test data, you may want to configure your rtl_433 config file to record data from your own RTL_SDR dongle. For example, add something like the following to your rtl_433.conf file:

output json:/var/log/rtl_433/rtl_433.json

(and create and assign ownership to /var/log/rtl_433/ if necessary) and then restart rtl_433.

Known Issues

The first packet from a device during a transmission interval (individually or as the first in a transmission packet) may have a distorted SNR because of a high auto-gain on the receiving RTL_SDR dongle. Some devices issue just one packet per transmission and others issue 3-6. No fix anticipated.

Other Tools

The tools directory contains two Python scripts that may be useful for extracting records from the JSON log files for more detailed analysis:

• rtl_xtract_json extracts from a JSON log file all records for one or more specific devices into a separate file. Devices are identified by the "model/channel/id" keyword identifier in the rtl_433_stats report.
• rtl_json_csv extracts from a JSON log file and into CSV format the values of fields specified on the command line. The output is labeled with the "model/channel/id" identifier. A header line identifying the extracted fields prefaces the data to allow easy importing into spreadsheet programs.

A reduced-functionality version of rtl_433_stats is available as a C-language version in the directory c-version as the program snr. That program produces the same statistics as the Python version. It does not have the options for selecting records to be processed but does have the ability to select JSON records by date-time.

Release History

Version	Date	Changes
V2.3.0	2026.06	Python code: reorder statistics columns as SNR, freq, ITGT, PPT; eliminate redundant data columns in report; use prior xmit time rather than prior pkt time for de-duping. C code: complete the statistics by adding columns for frequency, ITGT, and PPT; add noise, de-duping threshhold, and TPMS options; format output to match Python output.
V2.2.1	2026.06	For devices reporting multiple frequencies that don't present a field labeled "freq", use the value associated with "freq1" as the frequency value.
V2.2.0	2024.08	Add support for both ISO and Unix Epoch time stamps in the JSON log file
V2.1	2023.04	Complete documentation and full version
V1.0	2022.05	First operational version.

Author

David Todd, hdtodd@gmail.com; http://github.com/hdtodd/