search

merbanan / rtl_433

Program to decode radio transmissions from devices on the ISM bands (and other frequencies)
GNU General Public License v2.0
6.14k stars 1.33k forks source link

Not all parameters are sufficiently documented in help / manpage / rtl_433.example.conf #1784

Open drws opened 3 years ago

drws commented 3 years ago

There are two help-related issues regarding parameters' descriptions and their default values. First of all the related documentation is scattered between help, manpage and/or rtl_433.example.conf. Parameter descriptions are more or less in-sync between these documentation sources, but there are notable differences, some of which are stated below in examples.

The second issue is that some of the rtl_433 parameters' default settings are not clearly stated in any documentation source. Below I've listed a few examples that stand out the most.

Parameter duration Manpage states that the input is in seconds and some other time formats. It fails to mention the default value (run indefinitely) or its numerical value. Example configuration file implies the default value is 0, but it doesn't clearly specify and explain it. It also fails to mention anything regarding input format(s).

Parameter hop_interval The fact that this parameter is used only when multiple frequencies are set is emphasized only in the example configuration file, but not in the main help / manpage.

Parameter sample_rate The main help fails to mention only a handful of possible values such as in the example configuration file. Default value is exemplary stated in both cases.

Parameter gain Manpage fails to mention the numerical value of 0 for auto-setting, while the example configuration file efficiently explains everything with (default: 0 for auto).

Parameter convert Help/manual page does not specify the default setting convert native (which probably means convert no).

Parameter group pulse_detect The default values are missing from the manpage and only implied in example configuration files. Default behaviour unambiguitiy is additionaly confusing in cases of pulse_detect autolevel and pulse_detect squelch. Are they used by default or not?

These are the cases that stand out the most but all in all, there is lot of important information missing in help/man page and this tool practically relies on documenting input parameters in the example configuration file. This can be an issue if these documentation sources are not at least included/autosynced/linked somehow.

zuckschwerdt commented 3 years ago

Thanks for taking the time to document this in detail! The man page and example conf should be a copy of the help. So we need to enhance the help, then improve the copy.

drws commented 3 years ago

I've also noticed that default sample rate is still 250kHz in documentation and the question about the new default for pulse detection mode also arises. The sample configuration file implies it is -Y auto, while it might possibly be -Y minmax. How does auto work anyway?

zuckschwerdt commented 3 years ago

When adding a center freq above 800MHz the sample rate is set to 1MS/s https://github.com/merbanan/rtl_433/blob/master/src/rtl_433.c#L833-L837

If I remember correctly that oversampling is a workaround to allow some GFSK which is mainly found at 868M. If we manage to improve the demod it could be reversed.

gdt commented 1 year ago

I am guessing this is still valid, so not asking submitter to reverify.

gdt commented 1 year ago

I dropped the documentation label; this is simply a valid bug report against existing docs.