Skip to content

RS Auto_RX JSON Formats

Jump to bottom
Mark Jessop edited this page Mar 3, 2023 · 15 revisions

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 -s option.
  • rs41mod, which accepts the soft-symbols (--softin -i) calculates PTU data (pressure/temp/humidity, via the --ptu2 flag), 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 stdin
  • 48000 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.
Clone this wiki locally