auto_rx uses rs1729's RS radiosonde decoders to decode radio telemetry, with the decoded telemetry passed into auto_rx as JSON objects, which are then interpreted. In the default use-cases, auto_rx starts up the decoders itself, and reads the JSON data from the decoder's stdout. In 'UDP mode', auto_rx listens for JSON objects via UDP packets, on port 50000.
This page attempts to describe the format of the JSON objects which are passed between the RS decoders and auto_rx. Note that this is different to the 'payload summary' JSON format emitted by auto_rx.
Overall Format Description
Telemetry is passed as JSON objects, with a range of mandatory and optional fields.
Mandatory Fields
These fields represent the bare minimum amount of data for a sonde position to be plotted on a map, enabling recovery.
| Field | Type | Description | Special Cases |
|---|---|---|---|
id |
string | Radiosonde Serial Number | iMet sondes do not provide a serial number, and so the ID field is just set to 'iMet'. auto_rx generates a serial number based on launch time and transmit frequency. DFM sondes do not regularly transmit their serial number, and so before the serial number is observed the RS decoder will output an invalid serial number (DFM-xxxxxxx), resulting in auto_rx ignoring the packet. |
frame |
int | Frame Number | The overflow point for the frame numbers varies between sonde types. Some sondes (M10/M20) do not transmit a frame number at all, and so a unix timestamp (seconds since epoch) is provided in its place. Ideally this number should be unique over the entire flight, but for some sondes this isn't always the case. |
datetime |
string | Date/Time from the sonde's GPS. Usually as YYYY-MM-DDTHH:MM:SS.SSSSSSZ format. |
auto_rx uses the dateutil parse function to decode the time, and so is fairly tolerant to variations in time format. iMet and LMS6 sondes do not transmit date, and so only time (HH:MM:SSZ) is provided. auto_rx adds on the date portion. |
lat |
float | Latitude (decimal degrees) | |
lon |
float | Longitude (decimal degrees) | |
alt |
float | Altitude (metres) | |
version |
str | Decoder software version (e.g. '1.6.0') | Used to verify the decoders have been re-built to match the current auto_rx version. |
Optional Fields
| Field | Type | Description | Default Value | Special Cases |
|---|---|---|---|---|
type |
string | Radiosonde type provided by the decoder | Based on the decoder which was started. | |
subtype |
string | If known, the specific model of radiosonde being decoded. Mainly used | None | RS41 subtypes are provided as a string (e.g. RS41-SGP), DFM subtypes are provided as a hex code, decoded here. |
temp |
float | Measured Temperature (deg C) | -273.0 | A value of -273.0 is interpreted as invalid data, and is not passed on to SondeHub. |
humidity |
float | Measured Relative Humidity (%) | -1 | A value of -1 is interpreted as invalid data, and is not passed on to SondeHub. |
pressure |
float | Measured Pressure (hPa) | -1 | A value of -1 is interpreted as invalid data, and is not passed on to SondeHub. |
vel_h |
float | Horizontal Velocity (m/s) | 0.0 | |
vel_v |
float | Vertical Velocity (m/s) | 0.0 | |
heading |
float | Heading (degrees True) | 0.0 | Note that this is the direction of travel of the sonde, not the wind direction. |
sats |
int | Number of SVs used in position solution | 0 | |
batt |
float | Battery Voltage (volts) | 0.0 | |
bt |
int | RS41 burst-timer value, in seconds | None | Counts down to 0 after burst. |
aux |
string | RS41 XDATA, provided as a hexadecimal string | ||
encrypted |
bool | Flag to indicate if incoming telemetry is encrypted (e.g. RS41-SGM) | None | If this is set to True, the current frequency is locked out for 2 hours. |
freq |
int | Centre frequency of the radiosonde signal, supplied in kHz. If supplied, this will be used instead of any frequency information auto_rx may already have. | ||
tx_frequency |
int | Frequency of the radiosonde transmission, as determined from information in the telemetry, in kHz. |
Radiosonde Types and known Subtypes
The following table shows the type codes recognised by auto_rx, and what decoder is used for each.
| Type Code | Name | Decoder | Subtypes |
|---|---|---|---|
| RS41 | Vaisala RS41 | rs41mod | RS41-SG, RS41-SGP (Pressure Sensor), RS41-SGM (Military) |
| RS92 | Vaisala RS92 | rs92mod | RS92-SGP, RS92-NGP |
| DFM | Graw DFM06/DFM09/DFM17 | dfm09mod | DFM06, DFM09, DFM17 |
| M10 | Meteomodem M10 | m10mod | |
| M20 | Meteomodem M20 | mXXmod | |
| IMET | Intermet iMet-1AB / iMet-4 | imet1rs_dft | (Note that dft_detect returns IMET4.) |
| IMET5 | Intermet Systems iMet-50/iMet-54 | imet54mod | iMet-54, iMet-50 |
| MK2LMS | Lockheed Martin Sippican LMS6 - 1680 MHz Variant | mk2mod | |
| LMS6 | Lockheed Martin Sippican LMS6 - 403 MHz Variant | lms6Xmod | LMS6-403, LMS6-403-2, LMSX-403 (possible new replacement for the LMS6) |
| MEISEI | Meisei iMS100 / RS11G | meisei100mod | IMS100, RS11G |
| MRZ | Meteo-Radiy MRZ | mp3h1mod |
auto_rx 'UDP Mode' Configuration
Warning: There have been reports that this functionality is not working correctly in v1.6.0. Fixing this is not a high priority at this time.
In this mode, auto_rx listens for JSON data in the above described format on UDP port 50000 (one JSON object per UDP packet). This is useful if you want to run the decoders separately, or experiment with running multiple decoders at once. Telemetry from many different radiosondes can be ingested by auto_rx via this interface with no issues.
Entering this mode require a few configuration adjustments, and then adjustments to how auto_rx is started.
Within your station.cfg file, you will need to set your SDR device ID to 'TCP001', e.g.:
# Individual SDR Settings.
[sdr_1]
# Device Index / Serial
# If using a single RTLSDR, set this value to 0
# If using multiple SDRs, you MUST allocate each SDR a unique serial number using rtl_eeprom
# i.e. to set the serial number of a (single) connected RTLSDR: rtl_eeprom -s 00000002
# Then set the device_idx below to 00000002, and repeat for the other [sdr_n] sections below
#
# For the special case when auto_rx is used entirely with a JSON-via-UDP input, set the below to TCP001
# This will bypass all RTLSDR checks and allow auto_rx to continue running.
device_idx = TCP001
All other settings are configured as normal.
Then, to start up auto_rx in UDP mode, run it with:
$ python3 auto_rx.py -m UDP -f 403.000
Note that the frequency value will be used when sending data off to SondeHub. Don't worry too much about it though, as this value is overridden if any incoming UDP data contains a 'freq' field (which it should).
To see how auto_rx is handling each packet, include the -v option for more verbose output.
Starting up decoders outside of auto_rx
The following provides an example of starting up a decode chain outside of auto_rx, and feeding the output data from the decoder into auto_rx via netcat:
rtl_fm -p 0 -d 0 -M raw -F9 -s 48000 -f 401488000 | \
./fsk_demod --cs16 -b 1200 -u 22800 -s 2 48000 4800 - - | \
./rs41mod --ptu2 --json --softin -i --jsn_cfq 401500000 | nc -u localhost 50000
Breaking this apart a little, we have a few commands piped together:
- rtl_fm, producing signed 16-bit IQ output (the 'raw' option), at 48 kHz sample rate, tuned 12 kHz below the expected sonde centre frequency (401.5 MHz)
- fsk_demod, configured to accept that IQ input (
--cs16), and look for a 4800 baud signal between +1200 and +22800 Hz. The demod is configured to output soft-symbols (floating point values between -1.0 and +1.0) via the-soption. - rs41mod, which accepts the soft-symbols (
--softin -i) calculates PTU data (pressure/temp/humidity, via the--ptu2flag), and outputs JSON data to stdout (--json). We also tell the decoder what the centre frequency of the incoming signal is (--jsn_cfg 401500000) so it can include this in the UDP packets.
Performing a Radiosonde Detection
To know which decoder to start up, you need to know what radiosonde type you are listening to! Sometimes you will know this in advance (e.g. scheduled launches from a known launch site), other times not so much (which is why auto_rx exists in the first place...). You can use the dft_detect utility to determine what you are listening to:
$ rtl_fm -p 0 -d 0 -M raw -F9 -s 48000 -f 401500000 |./dft_detect -t 5 --iq --bw 20 --dc - 48000 16
RS41: 0.9874 , +313.3Hz
In this example there is a RS41 within the receiver passband, with a centre frequency at ~+313 Hz. The 0.9874 number is a 'correlation score', indicating how well the detector was able to match the RS41 header to the received signal.
While the rtl_fm argument is pretty similar to what is used in the RS41 decoding example earlier, note that we have tuned to the centre frequency of the radiosonde signal, not the -12 kHz offset frequency we used to decode.
The argument to dft_detect are as follows:
-t 5- Only run the detection processes for 5 seconds. This is long enough to reliably detect any radiosonde type.--iq- Accept IQ input--bw 20- Filter the input to a 20 kHz bandwidth.--dc- Apply a DC-blocking filter to the input.-- Take input from stdin48000 16- Informs the detector that the input sample rate is 48 kHz, with 16-bit samples.
The radiosonde types detected by dft_detect are presented in the 'Radiosonde Types and known Subtypes' further above.
Other Decoder Startup Examples
The following points show some examples of starting up a decoder for different types of radiosondes. In all cases the sonde frequency is assumed to be 401.5 MHz. Append | nc -u localhost 50000 to feed data into auto_rx.
- LMS6-403:
rtl_fm -p 0 -d 0 -M raw -F9 -s 48000 -f 401488000 |./fsk_demod --cs16 -b 1200 -u 22800 -s 2 48000 4800 - - | ./lms6Xmod --json --softin --vit2 -i -r --jsn_cfq 401500000 - iMet-4:
rtl_fm -p 0 -d 0 -M fm -F9 -s 15k -f 401500000 | sox -t raw -r 15k -e s -b 16 -c 1 - -r 48000 -b 8 -t wav - highpass 20 |./imet1rs_dft --json -r --jsn_cfq 401500000- Note that this decoder requires FM-demodulated audio input, and the 'sox' utility is used to perform some audio filtering and resampling.
- DFM:
rtl_fm -p 0 -d 0 -M raw -F9 -s 50000 -f 401487500 |./fsk_demod --cs16 -b 1250 -u 23750 -s 2 50000 2500 - - | ./dfm09mod -vv --ecc --json --dist --auto --softin -i -R --jsn_cfq 401500000- Note the different sample rates used (targeting a multiple of the baud rate, in this case 2500 baud).
- M10:
rtl_fm -p 0 -d 0 -M raw -F9 -s 48080 -f 401487980 |./fsk_demod --cs16 -b 1202 -u 22838 -s -p 5 2 48080 9616 - - | ./m10mod --json --ptu -vvv --softin -i -r - M20:
rtl_fm -p 0 -d 0 -M raw -F9 -s 48000 -f 401488000 |./fsk_demod --cs16 -b 1200 -u 22800 -s -p 5 2 48000 9600 - - | ./mXXmod --json --ptu -vvv --softin -i -r
To find out what commands auto_rx uses for a particular sonde type and frequency, start up auto_rx in verbose mode, and supply the sonde type and frequency as command-line arguments, e.g.:
$ python auto_rx.py -v -m M20 -f 401.5
2021-09-17 19:26:53,098 INFO:Reading configuration file...
<snip>
dev/null |./fsk_demod --cs16 -b 1200 -u 22800 -s -p 5 --stats=5 2 48000 9600 - -
2021-09-17 19:26:59,135 DEBUG:Decoder #0 M20 401.500 - Decoder Command: ./mXXmod --json --ptu -vvv --softin -i -r 2>/dev/null
2021-09-17 19:26:59,156 INFO:Decoder #0 M20 401.500 - Starting decoder subprocess.