This page describes the configuration settings within station.cfg.example, which must be copied to station.cfg and edited prior to first run of the auto_rx.py script. The comments within station.cfg are fairly self-explanatory, but this page provides further expansion on a few of the settings.
Important Settings
These settings should be adjusted prior to first-run:
-
[search_params] -> max_freq / min_freq- The upper and lower search bounds, in MHz. Set these to your local radiosonde band.- Australia: 400 - 403 MHz (Most sondes are on either 400.5, 401.5 or 402.5 MHz)
- Europe: 400 - 406 MHz
- US: Some areas use the 400.05 - 406 MHz band, others are still using the 1680 MHz band (which uses channels of 1676, 1678, 1680 and 1682 MHz). You can find what sondes are in use using this map.
-
[sdr_1] -> ppm- This sets the frequency error (in parts-per-million - ppm) of your RTLSDR. You can determine the ppm offset via a number of methods, such as kalibrate-rtl (if you have GSM signals nearby) or using LTE-Cell-Scanner, if you only have LTE around (i.e. Australia). The RTLSDR v3 SDR dongles are usually good enough without any correction (so just leave it at 0).
NOTE: Setting the PPM is fairly important for this application. Pretty much all radiosondes transmit on 10 kHz frequency steps, so the scanning code takes advantage of this and quantises detected peaks to the nearest 10 kHz step. If the receiver is off-frequency (due to bad ppm), it can result in poor receive performance, and potentially no decode.
RTLSDR Settings
[sdr_1] -> bias- Setting this to True will enable the bias-tee found on the 'v3' RTLSDR Dongles, which can be used to power a preamplifier up the coax.[sdr_1] -> gain- If using a preamplifier, it's recommended to dial back the gain on the RTLSDR unit itself to avoid overload. Use thertl_testutility to find out what gain settings your RTLSDR supports and experiment.[sdr_1] -> device_idx- If you want to use a particular RTLSDR, you can enter the device ID or serial number in here. Otherwise, leave this at 0.
Use of multiple RTLSDRs
To use multiple RTLSDRs to enable tracking of multiple sondes, we need a way of distinguishing individual RTLSDRs. To do this, we use the rtl_eeprom utility to set the serial numbers of the RTLSDRs to unique values.
For example, to set the serial number of a connected RTLSDR (with only one RTLSDR connected!!) to SDR00002, you would run:
$ rtl_eeprom -s SDR00002
Note that the serial number can use any ASCII characters!
Once you have set the serial numbers on your RTLSDRs, set the [sdr]->sdr_quantity field as appropriate, and set the [sdr_1]/[sdr_2]/etc->device_idx fields to the serial numbers. The ppm, gain and bias settings are set individually for each configured RTLSDR.
WARNING: If running multiple RTLSDRs, do not use serial numbers 0, 1, or '00000001'. The rtl utilities will sometimes try and interpret the serial as an index. This can lead to rtl_test getting confused and trying to test incorrect SDRs, leading to odd behaviour. It is strongly suggested you use serial numbers with non-numerical characters 'SDR00002', 'SDR00003', etc, to ensure the serial numbers are truly unique.
WARNING: Running multiple RTLSDRs directly off a Raspberry Pi's USB ports can lead to serious instability of the Pi's USB bus due to brownouts. Use an external powered USB hub if you're going to run multiple RTLSDRs.
White / Black / Grey-lists of Frequencies
Frequencies can be added to one of three lists, with the following behaviour:
- Whitelist (
[search_params] -> whitelist) - Search for radiosondes on only these supplied frequencies. Used where you are sure what frequency the radiosonde will be on every launch, and don't want to have to scan. - Blacklist (
[search_params] -> blacklist) - Remove any of the frequencies from the detected peak list. Useful for removing known spurs (i.e. 403.2 MHz on the R820T tuner) from the scan list. - Greylist (
[search_params] -> greylist) - Add the supplied frequencies to the top of the detected peak list. Use this where you are fairly sure you know what frequency the radiosonde will be on, but still want to search on other frequencies anyway.
Station Location
The [station] block defines the lat/lon/alt of your station. This is used to centre the map on the web interface, help filter out corrupt positions from RS92s and DFMs (which are known to jump all over the map), and also defines your station location for the Habitat and APRS-IS uploaders (more on those below).
Both the station_lat and station_lon fields are in decimal degrees.
You can also set your station location via a GPSD server, by setting gpsd_enabled to True, and defining gpsd_host and gpsd_port.
Uploading to the SondeHub Tracker
Uploading positions to the SondeHub High-Altitude Balloon tracker gives the benefit of getting live predictions of the balloon's flight path, and is highly recommended! (.. and is enabled by default!) We used to upload to the Habitat database, but this has been deprecated in 1.5.2 to avoid overloading it. References to habitat in the configuration file settings are for legacy reasons and will be changed in the next major release.
You should adjust the following parameters:
[habitat] -> uploader_callsign- Your callsign, which will show up in the 'received via' section on the tracker.[habitat] -> uploader_antenna- A description of your receiving station.
If you want your receive station to show up on the map, set your station's latitude/longitude in the [station] block, and set [habitat] -> upload_listener_position to True.
Uploading to APRS-IS
auto_rx can upload sonde positions into APRS-IS, which are then viewable on sites like aprs.fi, or radiosondy.info. To use APRS-IS you need an amateur radio licence.
APRS-IS output is enabled through the following settings:
[aprs] -> aprs_enabled- Set this toTrue[aprs] -> upload_rate- How often to upload positions to APRS (in seconds). Uploading more often than every 30 seconds is discouraged.[aprs] -> aprs_user- Your amateur radio callsign. You can add an optional 'SSID' on the end, i.e. N0CALL-4[aprs] -> aprs_pass- Your APRS-IS passcode (a 5-digit number, which you can generate here)[aprs] -> aprs_custom_comment- What goes in the comment field of the APRS beacon. The following data fields can be included, and will be auto-replaced with the actual data:<freq>- The sonde's TX frequency, i.e.400.500 MHz<type>- The model of the radiosonde, i.e. RS92 or RS41-SG<id>- The serial number of the radiosonde.<vel_v>- The current vertical velocity of the radiosonde (i.e. -5.1 m/s)<temp>- External temperature, reported by the radiosonde.<humidity>- Relative Humidity, reported by the radiosonde. (RS41 and iMet-4 sondes)<pressure>- Atmospheric Pressure, reported by the radiosonde. (RS41-SGP and iMet-4 sondes)<batt>- Reported battery voltage. (RS41, DFM, iMet
The default (compatible with what radiosondy.info expects), is: Clb=<vel_v> t=<temp> h=<humidity> p=<pressure> <freq> Type=<type> Radiosonde
The auto_rx version number is automatically appended to the end of the comment field.
If you wish to upload your station location, you can do so by setting station_beacon_enabled to True (you will also need to set your station lat/lon as mentioned above).
E-Mail Notifications
An e-mail notification can be sent when a new sonde is detected. A SMTP server must be configured and from/to addresses must be set. Refer to the documentation within the configuration file. Note that your email provider may only accept SSL or TLS connections on a specific port.
Once you have configured these settings, you can test that notification is working correctly by running:
$ cd ~/radiosonde_auto_rx/auto_rx/
$ python3 -m autorx.email_notification
Users running auto_rx using Docker will need to gain a shell within the docker image:
$ docker exec -it radiosonde_auto_rx /bin/bash
Then run:
$ python3 -m autorx.email_notification
Sending Payload data to ChaseMapper / OziPlotter
Payload position information can be emitted into the local network in two formats:
- 'Horus UDP' messages, which are essentially JSON blobs emitted via UDP broadcast, and
- 'OziMux' messages, which are essentially lines of CSV containing TELEMETRY,time,lat,lon,alt - also send via UDP broadcast.
These messages provide an easy way for other applications to capture 'live' radiosonde telemetry data. Examples include:
- ChaseMapper - Project Horus's browser-based offline mapping system.
- OziPlotter - Project Horus's legacy Windows-based offline mapping system.
Horus UDP 'Payload Summary' Output
auto_rx will emit 'Payload Summary' messages on UDP port 55673 by default. Information on the format of these packets is available here.
ChaseMapper is configured to listen for these packets by default, so auto_rx and ChaseMapper should 'just work'.
There is also a 'worked example' of a Python receiver for these packets available here.
OziMux Packets
Payload position information can be sent into Project Horus's offline balloon tracker 'OziPlotter', by setting the following parameters:
[oziplotter] -> ozi_enabled- Set this toTrue[oziplotter] -> ozi_port- Set this to 8942 if sending data directly into the OziPlotter application, or leave it at 55681 if sending data via OziMux. Refer to the OziPlotter documentation for more information on configuring OziPlotter, and to the Horus Utils documentation if running the full 'Horus Ground Station' software stack.
Telemetry is sent to the supplied hostname and port (UDP), in the basic CSV format: TELEMETRY,HH:MM:SS,latitude,longitude,altitude\n, so it should be fairly easy to adapt other mapping applications to accept and plot this data.
Note that this format does not send callsign information, and so should not be used if multiple sondes will be received simultaneously (i.e. in a multi-SDR setup).
Controlling an Azimuth/Elevation Rotator via rotctld
auto_rx is able to send position update commands to an instance of Hamlib's rotctld, which supports a very large number of commercial rotator protocols.
Running rotctld
On a Debian/Raspbian system, Hamlib can be installed using the command:
$ sudo apt-get install libhamlib-utils
A rotctld daemon can then be started by using the command:
$ rotctld -m <model> -r /dev/ttyUSB0 -s 9600
Where <model> is the model ID for your rotator (run rotctld -l to see a list of rotators), and the serial port and baud rate are adjusted as appropriate. As an example, to communicate an Alfa-Spid Rot2Prog, I use the command:
$ rotctld -m 901 -r /dev/ttyUSB0 -s 600
You can make rotctld run in the background by appending a & to the end of the command.
Configuring auto_rx's rotator settings
For the rotator control to work, the following settings need to be updated:
[location] -> station_lat / station_lon / station_alt- These need to be set as appropriate so auto_rx can calculate where to point.[rotator] -> enable_rotator- Set toTrue[rotator] -> rotator_hostname- Set to the hostname or IP address of the machine where rotctld is running.[rotator] -> rotator_port- Set to the TCP port of the machine where rotctld is running. The default for rotctld is 4533.[rotator] -> rotation_threshold- Set a movement threshold in degrees. The rotator will only be moved when the new target position differs from the current position by this threshold.
The rotator can be commanded to turn to a 'home' azimuth/elevation when scanning starts, by setting:
[rotator] -> rotator_homing_enabled- Set toTrue[rotator] -> rotator_home_azimuth / rotator_home_elevation- Set to the 'home' azimuth, i.e. the direction of your local radiosonde launch site.
The rotator position is updated every 30 seconds by default. This can be changed with the [upload] -> upload_rate setting.
Starting rotctld on boot
There are a few ways rotctld can be started on boot, but a simple way is just making use of /etc/rc.local.
Make a script named start_rotator.sh in your home directory containing:
#!/usr/bin/env bash
rotctld -m <model> -r /dev/ttyUSB0 -s 9600
(replacing the model, serial port, and baud rate above as appropriate)
Make the script executable by running: chmod +x start_rotator.sh.
If not already available, install the screen utility with: sudo apt-get install screen
Now, edit /etc/rc.local as root (e.g. sudo nano /etc/rc.local) and add the following line at the bottom:
su - pi -c "screen -dm -S rotator /home/pi/start_rotator.sh"
If you are not running as the pi user, you will need to change pi in the line above. After a reboot this should start up. To access the screen session, run screen -r rotator from a terminal. To detach from the screen session, hold down Ctrl-a, release, then press d.