Skip to content

Habitat Upload Format

Jump to bottom
Mark Jessop edited this page Jan 5, 2021 · 6 revisions

radiosonde_auto_rx uploads radiosonde telemetry to the Habitat balloon tracking database in a very specific format, allowing it to be parsed and displayed on the HabHub tracker (if filtering is disabled) and SondeHub tracker maps. This page provides information on the formats used, and some notes on how various parameters are dealt with.

If developers of other radiosonde decoding software wish to contribute telemetry to the Habitat database, please follow the following conventions to ensure consistency of data.

Uploaded Sentence Format

$$<callsign>,<frame>,HH:MM:SS,<latitude>,<longitude>,<altitude>,<vel_h>,<temp>,<humidity>,<comment>*CRC16\n

As an example:

$$RS_S1130529,7106,00:50:00,-34.84254,138.58820,7273,13.0,-15.4,95.0,RS41-SG S1130529 401.501 MHz BT 08:09:02 2.5V*33AD\n

To see some real-time examples of the telemetry sentences being fed into the Habitat database, the parser logtail can be used. There are usually radiosondes active at all times of the day.

Callsign/ID (<callsign>)

All radiosonde telemetry callsigns must be prefixed with RS_ - this triggers an override in the Habitat parser, switching to a fixed parser (document ID: 8c36ab528b16cb3adf00b7e07a228854) for radiosonde telemetry and reducing load on the database.

Examples of valid callsigns:

  • RS41: RS_S1130529
  • DFM: RS_DFM-19052023
  • LMS6: RS_LMS6-7392300
  • M10: RS_M10-001-2-12321

Frame Number (<frame>)

An integer frame number, which should ideally be unique throughout the entire flight. However, as long as the combination of frame number and time (next field) are unique, the Habitat DB will handle it.

Time (HH:MM:SS)

The time reported by the sonde. For most (all?) sondes this is UTC time, not GPS time.

Position (<lat>, <lon>)

Latitude and Longitude are reported in decimal degrees, to 5 decimal places.

Altitude (<alt>)

Altitude is reported in metres (in whatever datum is provided by the sonde), as an integer.

Horizontal Speed (<vel_h>)

Speed-over-ground, as reported by the sonde, in m/s to one decimal place.

Temperature (<temp>)

Temperature, in degrees celsius, to one decimal place. If no temperature data is available, a value of -273.0 should be used.

Humidity (<humidity>)

Relative Humidity (%), to one decimal place. If no Humidity data is available, a value of -1.0 should be used.

Comment Field

The comment field is currently used to add in extra information that doesn't fit in the rest of the sentence. This currently includes:

  • Radiosonde Sub-Type (e.g. RS41-SGP) and Serial number.
  • Sonde Transmit Frequency
  • Burst Timer Status (RS41 Only)
  • Battery Voltage

Examples:

  • RS41-SG S3450794 402.000 MHz
  • RS41-SG S1130529 401.500 MHz BT 07:57:08 2.6V

The comment field does not need to have exactly the same content from each uploading client. The first message that is received by habitat for a given frame number and time will be displayed.

Checksum

A CRC16-CCITT Checksum, calculated over all bytes between the $$ and * (not including these). Presented in the string as hexadecimal. An example of it's calculation is available here: https://github.com/projecthorus/radiosonde_auto_rx/blob/master/auto_rx/autorx/habitat.py#L33

Uploading to the Habitat Database

A worked example of uploading a telemetry sentence to the Habitat DB, including error handling, is available here: https://github.com/projecthorus/radiosonde_auto_rx/blob/master/auto_rx/autorx/habitat.py#L523

Uploads should not be performed at intervals faster than 30 seconds. The suggested approach is to upload the most recent telemetry sentence for each observed sonde on 30 second boundaries.

Uploads should be performed via the sondehub proxy ( https://habitat.sondehub.org/ ). This ensures that uploads are appropriately rate limited, and also provides the opportunity to block uploads from incompatible software versions, to avoid mapping issues. The software version is provided to the proxy in the User Agent parameter when uploading.

If you are planning on uploading to the Habitat database, please contact us so we can add your software version to the allowed list.

Uploading Station Positions

The Habitat database allows users to upload their station position for display on the map. These appear as green antenna-tower icons, and display the stations callsign, radio, and antenna information when clicked on. Station icons 'age-out' from the map ~24 hours after uploading.

Uploading station position information is slightly more involved than upload telemetry, as it requires 'initialising' the listeners callsign, then providing a position update. This can be also be used to add 'moving listeners' (chase cars!) to the map by appending _chase to the callsign, and setting a chase field in the uploaded data to True.

The function in auto_rx that performs the station position upload is here: https://github.com/projecthorus/radiosonde_auto_rx/blob/master/auto_rx/autorx/habitat.py#L337 It is recommended that stations re-upload their position every ~6 hours, to stay on the map.

Marking Sondes as Recovered

We have made use of the station position icon to allow sonde chasers (running chasemapper) to 'drop' an antenna icon at the sondes landing position, informing other tracker users that a radiosonde has recently been recovered. The 'station' callsign is set to S1234567 recovered by VK5QI, and a custom message can be inserted in the 'radio' field. The code that performs this in chasemapper is available here: https://github.com/projecthorus/chasemapper/blob/master/horusmapper.py#L628

Clone this wiki locally