From 6a31e4f7f9627395461b46e3b4daa15cfa0b7975 Mon Sep 17 00:00:00 2001
From: "Christian W. Zuckschwerdt" <christian@zuckschwerdt.org>
Date: Sat, 8 Jan 2022 11:54:05 +0100
Subject: [PATCH] docs: Add minor example notes
---
docs/ANALYZE.md | 1 +
docs/IQ_FORMATS.md | 2 ++
examples/rtl_433_custom.py | 20 ++++++++++++++++++--
include/bitbuffer.h | 11 ++++++++++-
4 files changed, 31 insertions(+), 3 deletions(-)
diff --git a/docs/ANALYZE.md b/docs/ANALYZE.md
index e637d104..345c6025 100644
--- a/docs/ANALYZE.md
+++ b/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
diff --git a/docs/IQ_FORMATS.md b/docs/IQ_FORMATS.md
index 503aa68a..621c6918 100644
--- a/docs/IQ_FORMATS.md
+++ b/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.
:::
diff --git a/examples/rtl_433_custom.py b/examples/rtl_433_custom.py
index b9e8afcf..07c0d785 100755
--- a/examples/rtl_433_custom.py
+++ b/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
diff --git a/include/bitbuffer.h b/include/bitbuffer.h
index 7318c387..cff68d07 100644
--- a/include/bitbuffer.h
+++ b/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.