docs: Add minor example notes

docs/ANALYZE.md

@@ -32,6 +32,7 @@ Do not plug the receiver directly in a USB port, avoid noise and use a short usb
 Note the frequency, pick a frequency a little off, e.g 50k above or below.
 Then grab the signal with rtl_433, e.g. `rtl_433 -f 433.92M -S unknown`
 Visually verify the samples in https://triq.net/iqs
+
 ::: tip
 The modes for the sample grabber are
 - `-S all`: grab all frames found

docs/IQ_FORMATS.md

@@ -9,6 +9,7 @@ I/Q stands for "In-phase / Quadrature", the raw data format used by SDR receiver
 A sample consists of an I and Q value, each commonly of 8, 12, or 16-bit. This is called "interleaved" in audio or video data.
 
 The data can be processed similar to a two-channel audio signal, although at a much higher sample rate.
+
 ::: tip
 Common sample rates with RTL-SDR receivers are 250 kHz and 1024 kHz, also 1 MHz (1000 kHz).
 :::
@@ -66,6 +67,7 @@ There are also formats for demodulated but "raw" amplitude or frequency,
 e.g. `.am.s16`, `.fm.s16` similar to the above formats but with only one "channel".
 
 The SigRok `.sr` format is a Zip and combines multiple files for easy viewing with SigRok Pulseview.
+
 ::: tip
 Install SigRok Pulseview and write a SigRok file. The overwrite option (uppercase `-W`) will automatically open Pulseview.
 :::

examples/rtl_433_custom.py

@@ -9,6 +9,9 @@ from __future__ import print_function
 import socket
 import json
 
+# You can run rtl_433 and this script on different machines,
+# start rtl_433 with `-F syslog:YOURTARGETIP:1433`, and change
+# to `UDP_IP = "0.0.0.0"` (listen to the whole network) below.
 UDP_IP = "127.0.0.1"
 UDP_PORT = 1433
 
@@ -24,24 +27,36 @@ def parse_syslog(line):
 
 
 def rtl_433_listen():
-    """Try to extract the payload from a syslog line."""
+    """Listen to all messages in a loop forever."""
+    # Open a UDP socket
     sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    # Bind the UDP socket to a listening address
     sock.bind((UDP_IP, UDP_PORT))
 
+    # Loop forever
     while True:
+        # Receive a message
         line, addr = sock.recvfrom(1024)
 
         try:
+            # Parse the message format
             line = parse_syslog(line)
+            # Decode the message as JSON
             data = json.loads(line)
 
-            # change for your custom handling below, this is a simple example
+            #
+            # Change for your custom handling below, this is a simple example
+            #
             label = data["model"]
             if "channel" in data:
                 label += ".CH" + str(data["channel"])
             elif "id" in data:
                 label += ".ID" + str(data["id"])
 
+            # E.g. match `model` and `id` to a descriptive name.
+            if data["model"] == "LaCrosse-TX" and data["id"] == 123:
+                label = "Living Room"
+
             if "battery_ok" in data:
                 if data["battery_ok"] == 0:
                     print(label + ' Battery empty!')
@@ -52,6 +67,7 @@ def rtl_433_listen():
             if "humidity" in data:
                 print(label + ' Humidity ', data["humidity"])
 
+            # Ignore unknown message data and continue
         except KeyError:
             pass
 

include/bitbuffer.h

@@ -78,7 +78,16 @@ void bitrow_print(uint8_t const *bitrow, unsigned bit_len);
 void bitrow_debug(uint8_t const *bitrow, unsigned bit_len);
 
 /// Print the content of a bit row (byte buffer) to a string buffer.
-/// The output is always null-terminated, unless size is 0.
+///
+/// Write at most @p size - 1 characters,
+/// the output is always null-terminated, unless size is 0.
+///
+/// @param bitrow the row of bytes to print
+/// @param bit_len the number of bits in @p bitrow to print
+/// @param str an output string buffer of sufficient size
+/// @param size the size of @p str
+///
+/// @return the number of characters printed (not including the trailing `\0`).
 int bitrow_snprint(uint8_t const *bitrow, unsigned bit_len, char *str, unsigned size);
 
 /// Parse a string into a bitbuffer.