From 15637a2f2dbc30328e1fd75f38029ed1515444d3 Mon Sep 17 00:00:00 2001 From: "Christian W. Zuckschwerdt" Date: Thu, 1 Sep 2022 15:45:09 +0200 Subject: [PATCH] minor: Fix various decoder doc comments --- src/devices/ambient_weather.c | 4 +-- src/devices/brennenstuhl_rcs_2044.c | 2 +- src/devices/current_cost.c | 5 +++ src/devices/digitech_xc0324.c | 2 +- src/devices/elv.c | 6 +++- src/devices/emontx.c | 24 ++++++++------ src/devices/esa.c | 5 +++ src/devices/fineoffset.c | 51 ++++++++++++++--------------- src/devices/flex.c | 3 ++ src/devices/fs20.c | 2 +- src/devices/insteon.c | 2 +- src/devices/mebus.c | 9 +++-- src/devices/oregon_scientific.c | 10 ++++++ src/devices/radiohead_ask.c | 10 +++++- src/devices/secplus_v2.c | 4 +++ src/devices/silvercrest.c | 5 +++ src/devices/simplisafe.c | 19 ++++++++--- src/devices/ts_ft002.c | 4 +-- tests/symbolizer.py | 7 +++- 19 files changed, 120 insertions(+), 54 deletions(-) diff --git a/src/devices/ambient_weather.c b/src/devices/ambient_weather.c index 329cd59e9..545c90803 100644 --- a/src/devices/ambient_weather.c +++ b/src/devices/ambient_weather.c @@ -10,8 +10,8 @@ (at your option) any later version. */ -/* -Decode Ambient Weather F007TH, F012TH, TF 30.3208.02, SwitchDoc F016TH +/** +Decode Ambient Weather F007TH, F012TH, TF 30.3208.02, SwitchDoc F016TH. Devices supported: diff --git a/src/devices/brennenstuhl_rcs_2044.c b/src/devices/brennenstuhl_rcs_2044.c index da9b68083..599730cdf 100644 --- a/src/devices/brennenstuhl_rcs_2044.c +++ b/src/devices/brennenstuhl_rcs_2044.c @@ -9,7 +9,7 @@ (at your option) any later version. */ -/* +/** Brennenstuhl RCS 2044 remote control on 433.92MHz likely x1527. Receiver for the "RCS 2044 N Comfort Wireless Controller Set" sold under diff --git a/src/devices/current_cost.c b/src/devices/current_cost.c index cf0771118..07feacd4f 100644 --- a/src/devices/current_cost.c +++ b/src/devices/current_cost.c @@ -12,6 +12,11 @@ #include "decoder.h" +/** +CurrentCost TX, CurrentCost EnviR current sensors. + +@todo Documentation needed. +*/ static int current_cost_decode(r_device *decoder, bitbuffer_t *bitbuffer) { data_t *data; diff --git a/src/devices/digitech_xc0324.c b/src/devices/digitech_xc0324.c index acb15c607..a6b42aed4 100644 --- a/src/devices/digitech_xc0324.c +++ b/src/devices/digitech_xc0324.c @@ -8,7 +8,7 @@ the Free Software Foundation; either version 2 of the License, or (at your option) any later version. */ -/** @fn static int xc0324_callback(r_device *decoder, bitbuffer_t *bitbuffer) +/** Digitech XC-0324 device. The encoding is pulse position modulation diff --git a/src/devices/elv.c b/src/devices/elv.c index 54de5c427..ed52591e6 100644 --- a/src/devices/elv.c +++ b/src/devices/elv.c @@ -23,7 +23,11 @@ static uint16_t AD_POP(uint8_t *bb, uint8_t bits, uint8_t bit) return val; } -// based on fs20.c +/** +ELV EM 1000 decoder. + +based on fs20.c +*/ static int em1000_callback(r_device *decoder, bitbuffer_t *bitbuffer) { data_t *data; diff --git a/src/devices/emontx.c b/src/devices/emontx.c index 196dca7d2..d585142b2 100644 --- a/src/devices/emontx.c +++ b/src/devices/emontx.c @@ -24,16 +24,20 @@ struct emontx { }; #pragma pack(pop) -// This is the JeeLibs RF12 packet format as described at -// http://jeelabs.org/2011/06/09/rf12-packet-format-and-design/ -// -// The RFM69 chip misses out the zero bit at the end of the -// 0xAA 0xAA 0xAA preamble; the receivers only use it to set -// up the bit timing, and they look for the 0x2D at the start -// of the packet. So we'll do the same — except since we're -// specifically looking for emonTx packets, we can require a -// little bit more. We look for a group of 0xD2, and we -// expect the CDA bits in the header to all be zero: +/** @fn int emontx_callback(r_device *decoder, bitbuffer_t *bitbuffer) +OpenEnergyMonitor.org emonTx sensor protocol. + +This is the JeeLibs RF12 packet format as described at +http://jeelabs.org/2011/06/09/rf12-packet-format-and-design/ + +The RFM69 chip misses out the zero bit at the end of the +0xAA 0xAA 0xAA preamble; the receivers only use it to set +up the bit timing, and they look for the 0x2D at the start +of the packet. So we'll do the same — except since we're +specifically looking for emonTx packets, we can require a +little bit more. We look for a group of 0xD2, and we +expect the CDA bits in the header to all be zero: +*/ static unsigned char preamble[3] = { 0xaa, 0xaa, 0xaa }; static unsigned char pkt_hdr_inverted[3] = { 0xd2, 0x2d, 0xc0 }; static unsigned char pkt_hdr[3] = { 0x2d, 0xd2, 0x00 }; diff --git a/src/devices/esa.c b/src/devices/esa.c index 80073078f..898b2045b 100644 --- a/src/devices/esa.c +++ b/src/devices/esa.c @@ -35,6 +35,11 @@ static uint8_t decrypt_esa(uint8_t *b) return crc; } +/** +ELV Energy Counter ESA 1000/2000. + +@todo Documentation needed. +*/ static int esa_cost_callback(r_device *decoder, bitbuffer_t *bitbuffer) { data_t *data; diff --git a/src/devices/fineoffset.c b/src/devices/fineoffset.c index 105dceba5..aa5b3cb18 100644 --- a/src/devices/fineoffset.c +++ b/src/devices/fineoffset.c @@ -548,8 +548,8 @@ static int fineoffset_WH25_callback(r_device *decoder, bitbuffer_t *bitbuffer) return 1; } -/* -Fine Offset WH51, ECOWITT WH51, MISOL/1 Soil Moisture Sensor +/** +Fine Offset WH51, ECOWITT WH51, MISOL/1 Soil Moisture Sensor. Also: SwitchDoc Labs SM23 Soil Moisture Sensor. @@ -557,35 +557,34 @@ Test decoding with: rtl_433 -f 433920000 -X "n=soil_sensor,m=FSK_PCM,s=58,l=58, Data format: - 00 01 02 03 04 05 06 07 08 09 10 11 12 13 -aa aa aa 2d d4 51 00 6b 58 6e 7f 24 f8 d2 ff ff ff 3c 28 8 - FF II II II TB YY MM ZA AA XX XX XX CC SS - -Sync: aa aa aa ... -Preamble: 2d d4 -FF: Family code 0x51 (ECOWITT/FineOffset WH51) -IIIIII: ID (3 bytes) -T: Transmission period boost: highest 3 bits set to 111 on moisture change and decremented each transmission; - if T = 0 period is 70 sec, if T > 0 period is 10 sec -B: Battery voltage: lowest 5 bits are battery voltage * 10 (e.g. 0x0c = 12 = 1.2V). Transmitter works down to 0.7V (0x07) -YY: ? Fixed: 0x7f -MM: Moisture percentage 0%-100% (0x00-0x64) MM = (AD - 70) / (450 - 70) -Z: ? Fixed: leftmost 7 bit 1111 100 -AAA: 9 bit AD value MSB byte[07] & 0x01, LSB byte[08] -XXXXXX: ? Fixed: 0xff 0xff 0xff -CC: CRC of the preceding 12 bytes (Polynomial 0x31, Initial value 0x00, Input not reflected, Result not reflected) -SS: Sum of the preceding 13 bytes % 256 + 00 01 02 03 04 05 06 07 08 09 10 11 12 13 + aa aa aa 2d d4 51 00 6b 58 6e 7f 24 f8 d2 ff ff ff 3c 28 8 + FF II II II TB YY MM ZA AA XX XX XX CC SS + +- Sync: aa aa aa ... +- Preamble: 2d d4 +- FF: Family code 0x51 (ECOWITT/FineOffset WH51) +- IIIIII: ID (3 bytes) +- T: Transmission period boost: highest 3 bits set to 111 on moisture change and decremented each transmission; +- if T = 0 period is 70 sec, if T > 0 period is 10 sec +- B: Battery voltage: lowest 5 bits are battery voltage * 10 (e.g. 0x0c = 12 = 1.2V). Transmitter works down to 0.7V (0x07) +- YY: ? Fixed: 0x7f +- MM: Moisture percentage 0%-100% (0x00-0x64) MM = (AD - 70) / (450 - 70) +- Z: ? Fixed: leftmost 7 bit 1111 100 +- AAA: 9 bit AD value MSB byte[07] & 0x01, LSB byte[08] +- XXXXXX: ? Fixed: 0xff 0xff 0xff +- CC: CRC of the preceding 12 bytes (Polynomial 0x31, Initial value 0x00, Input not reflected, Result not reflected) +- SS: Sum of the preceding 13 bytes % 256 See http://www.ecowitt.com/upfile/201904/WH51%20Manual.pdf for relationship between AD and moisture % Short explanation: -Soil Moisture Percentage = (Moisture AD – 0%AD) / (100%AD – 0%AD) * 100 -0%AD = 70 -100%AD = 450 (manual states 500, but sensor internal computation are closer to 450) -If sensor-calculated moisture percentage are inaccurate at low/high values, use the AD value and the above formaula -changing 0%AD and 100%AD to cover the full scale from dry to damp +- Soil Moisture Percentage = (Moisture AD – 0%AD) / (100%AD – 0%AD) * 100 +- 0%AD = 70 +- 100%AD = 450 (manual states 500, but sensor internal computation are closer to 450) +- If sensor-calculated moisture percentage are inaccurate at low/high values, use the AD value and the above formaula + changing 0%AD and 100%AD to cover the full scale from dry to damp */ - static int fineoffset_WH51_callback(r_device *decoder, bitbuffer_t *bitbuffer) { data_t *data; diff --git a/src/devices/flex.c b/src/devices/flex.c index 8e5bce8b9..c5593142b 100644 --- a/src/devices/flex.c +++ b/src/devices/flex.c @@ -144,6 +144,9 @@ static void render_getters(data_t *data, uint8_t *bits, struct flex_params *para } } +/** +Generic flex decoder. +*/ static int flex_callback(r_device *decoder, bitbuffer_t *bitbuffer) { int i; diff --git a/src/devices/fs20.c b/src/devices/fs20.c index 9f92c1319..e82d4b989 100644 --- a/src/devices/fs20.c +++ b/src/devices/fs20.c @@ -8,7 +8,7 @@ published by the Free Software Foundation. */ -/* +/** Simple FS20 remote decoder. Frequency: use rtl_433 -f 868.35M diff --git a/src/devices/insteon.c b/src/devices/insteon.c index bbde0b095..e1d61f380 100644 --- a/src/devices/insteon.c +++ b/src/devices/insteon.c @@ -9,7 +9,7 @@ (at your option) any later version. */ -/** @fn int insteon_callback(r_device *decoder, bitbuffer_t *bitbuffer) +/** @fn int parse_insteon_pkt(r_device *decoder, bitbuffer_t *bits, unsigned int row, unsigned int start_pos) Insteon RF decoder. "Insteon is a home automation (domotics) technology that enables diff --git a/src/devices/mebus.c b/src/devices/mebus.c index da3ef4edc..b3c52e4a5 100644 --- a/src/devices/mebus.c +++ b/src/devices/mebus.c @@ -9,7 +9,12 @@ #include "decoder.h" -static int mebus433_callback(r_device *decoder, bitbuffer_t *bitbuffer) +/** +Mebus 433. + +@todo Documentation needed. +*/ +static int mebus433_decode(r_device *decoder, bitbuffer_t *bitbuffer) { bitrow_t *bb = bitbuffer->bb; int16_t temp; @@ -81,7 +86,7 @@ r_device mebus433 = { .long_width = 1600, // guessed, no samples available .gap_limit = 2400, .reset_limit = 6000, - .decode_fn = &mebus433_callback, + .decode_fn = &mebus433_decode, .disabled = 1, // add docs, tests, false positive checks and then re-enable .fields = output_fields, }; diff --git a/src/devices/oregon_scientific.c b/src/devices/oregon_scientific.c index c1de63791..c76d9d356 100644 --- a/src/devices/oregon_scientific.c +++ b/src/devices/oregon_scientific.c @@ -205,6 +205,11 @@ static int validate_os_v2_message(r_device *decoder, unsigned char *msg, int bit return 1; } +/** +Various Oregon Scientific protocols. + +@todo Documentation needed. +*/ static int oregon_scientific_v2_1_decode(r_device *decoder, bitbuffer_t *bitbuffer) { uint8_t *b = bitbuffer->bb[0]; @@ -556,6 +561,11 @@ static int oregon_scientific_v2_1_decode(r_device *decoder, bitbuffer_t *bitbuff // ceil( (335 + 11) / 8 ) #define EXPECTED_NUM_BYTES 44 +/** +Various Oregon Scientific protocols. + +@todo Documentation needed. +*/ static int oregon_scientific_v3_decode(r_device *decoder, bitbuffer_t *bitbuffer) { uint8_t *b = bitbuffer->bb[0]; diff --git a/src/devices/radiohead_ask.c b/src/devices/radiohead_ask.c index a7cd3a8c2..bcb66a1da 100644 --- a/src/devices/radiohead_ask.c +++ b/src/devices/radiohead_ask.c @@ -6,7 +6,7 @@ the Free Software Foundation; either version 2 of the License, or (at your option) any later version. */ -/** +/** @fn int radiohead_ask_callback(r_device *decoder, bitbuffer_t *bitbuffer) RadioHead ASK (generic) protocol. Default transmitter speed is 2000 bits per second, i.e. 500 us per bit. @@ -51,6 +51,9 @@ static uint8_t symbol_6to4(uint8_t symbol) return 0xFF; // Not found } +/** +Radiohead ASK parser. +*/ static int radiohead_ask_extract(r_device *decoder, bitbuffer_t *bitbuffer, uint8_t row, /*OUT*/ uint8_t *payload) { int len = bitbuffer->bits_per_row[row]; @@ -175,6 +178,11 @@ static int radiohead_ask_callback(r_device *decoder, bitbuffer_t *bitbuffer) return 1; } +/** +Sensible Living Mini-Plant Moisture Sensor. + +@todo Documentation needed. +*/ static int sensible_living_callback(r_device *decoder, bitbuffer_t *bitbuffer) { data_t *data; diff --git a/src/devices/secplus_v2.c b/src/devices/secplus_v2.c index e70802048..e1cc25701 100644 --- a/src/devices/secplus_v2.c +++ b/src/devices/secplus_v2.c @@ -237,6 +237,10 @@ static int secplus_v2_decode_v2_half(r_device *decoder, bitbuffer_t *bits, uint8 static const uint8_t _preamble[] = {0xaa, 0xaa, 0x95, 0x60}; unsigned _preamble_len = 28; +/** +Security+ 2.0 rolling code. +@sa secplus_v2_decode_v2_half() +*/ static int secplus_v2_callback(r_device *decoder, bitbuffer_t *bitbuffer) { unsigned search_index = 0; diff --git a/src/devices/silvercrest.c b/src/devices/silvercrest.c index ab5c0cb97..f3e21a92c 100644 --- a/src/devices/silvercrest.c +++ b/src/devices/silvercrest.c @@ -11,6 +11,11 @@ #include "decoder.h" +/** +Silvercrest remote decoder. + +@todo Documentation needed. +*/ static int silvercrest_callback(r_device *decoder, bitbuffer_t *bitbuffer) { uint8_t const cmd_lu_tab[16] = {2, 3, 0, 1, 4, 5, 7, 6, 0xC, 0xD, 0xF, 0xE, 8, 9, 0xB, 0xA}; diff --git a/src/devices/simplisafe.c b/src/devices/simplisafe.c index 56eb866ba..9caf0671b 100644 --- a/src/devices/simplisafe.c +++ b/src/devices/simplisafe.c @@ -10,9 +10,13 @@ License: GPL v2+ (or at your choice, any other OSI-approved Open Source license) */ -/** +/** @fn int ss_sensor_callback(r_device *decoder, bitbuffer_t *bitbuffer) Protocol of the SimpliSafe Sensors. +@sa ss_sensor_parser() +@sa ss_pinentry_parser() +@sa ss_keypad_commands() + The data is sent leveraging a PiWM Encoding where a long is 1, and a short is 0 All bytes are sent with least significant bit FIRST (1000 0111 = 0xE1) @@ -44,6 +48,9 @@ static void ss_get_id(char *id, uint8_t *b) *p = '\0'; } +/** +SimpliSafe protocol for sensors. +*/ static int ss_sensor_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row) { data_t *data; @@ -85,6 +92,9 @@ static int ss_sensor_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row) return 1; } +/** +SimpliSafe protocol for pinentry. +*/ static int ss_pinentry_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row) { data_t *data; @@ -119,6 +129,9 @@ static int ss_pinentry_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row return 1; } +/** +SimpliSafe protocol for keypad commands. +*/ static int ss_keypad_commands(r_device *decoder, bitbuffer_t *bitbuffer, int row) { data_t *data; @@ -155,10 +168,6 @@ static int ss_keypad_commands(r_device *decoder, bitbuffer_t *bitbuffer, int row return 1; } -/** -Protocol of the SimpliSafe Sensors. -@sa ss_sensor_parser() ss_pinentry_parser() ss_keypad_commands() -*/ static int ss_sensor_callback(r_device *decoder, bitbuffer_t *bitbuffer) { // Require two identical rows. diff --git a/src/devices/ts_ft002.c b/src/devices/ts_ft002.c index 749cce281..5272dc131 100644 --- a/src/devices/ts_ft002.c +++ b/src/devices/ts_ft002.c @@ -8,8 +8,8 @@ the Free Software Foundation; either version 2 of the License, or (at your option) any later version. */ -/* -TS-FT002 Wireless Ultrasonic Tank Liquid Level Meter With Temperature Sensor +/** +TS-FT002 Wireless Ultrasonic Tank Liquid Level Meter With Temperature Sensor. PPM with 500 us pulse, 464 us short gap (0), 948 us long gap (1), 1876 us packet gap, two packets per transmission. diff --git a/tests/symbolizer.py b/tests/symbolizer.py index b2dd4d5db..f82bff592 100755 --- a/tests/symbolizer.py +++ b/tests/symbolizer.py @@ -100,6 +100,9 @@ def process_source(path, name): if fName: if fName not in links: links[fName] = {"src": name, "type": "func"} + if dSee: + links[fName].update({"doc_line": dLine, "doc_see": dSee}) + dSee = None links[fName].update({"doc_line": dLine, "doc": doc}) doc = None fName = None @@ -141,6 +144,7 @@ def process_source(path, name): continue m = re.match(r'\s*/\*\*', line) if m: + fName = None captureDoc = True dLine = i + 1 doc = '' @@ -279,7 +283,8 @@ def check_symbols(symbols): if "line" not in d: err(f"::error file={d['src']}::func missing ({f})") if "doc" not in d or not d["doc"]: - #err(f"::warning file={d['src']},line={d['line']}::doc missing for {f}") + if "doc_see" not in d or not d["doc_see"]: + err(f"::warning file={d['src']},line={d['line']}::doc missing for {f}") pass if d["type"] == "model":