Telemetry Submission

gr_satellites can upload every decoded frame to online telemetry databases, so that satellite teams and the community get data from your station. This page explains how to enable submission, which servers are supported, what each one needs in the configuration file, how timestamps are produced, and how to switch submission off for test runs.

Overview

Server	SatYAML name	Satellites	Configuration needed
SatNOGS DB	(always)	All	`callsign`, `latitude`, `longitude`
FUNcube Warehouse	`FUNcube`	AO-73 (FUNcube-1), UKube-1, Nayif-1, JY1-Sat	`[FUNcube] site_id`, `auth_code`
PW-Sat2 ground station	`PWSat`	PW-Sat2	`[PW-Sat2] credentials_file`
BME telemetry server	`BME`	ATL-1, SMOG-P, SMOG-1	`[BME] user`, `password`
BME WebSocket server	`BMEWS`	MRC-100	None
Harbin Institute of Technology proxy	`HIT <port>`	BY02 (`HIT 8001`)	A locally running proxy
Any SIDS server	`SIDS <url>`	For example CELESTA, MTCUBE-2, NUSHSAT-1, PicSat, TUBIN, UVSQ-SAT	Same as SatNOGS

SatNOGS DB is added for every satellite whenever submission is enabled. The other servers are added only for satellites that list them in the telemetry_servers field of their SatYAML file.

Enabling Submission

Submission is controlled by ~/.gr_satellites/config.ini, which gr_satellites creates with this template the first time it runs:

[Groundstation]
callsign = 
latitude = 0
longitude = 0
submit_tlm = no

[FUNcube]
site_id = 
auth_code = 

[PW-Sat2]
credentials_file = 

[BME]
user = 
password =

To enable submission:

Set submit_tlm = yes.
Set your callsign.
Set latitude and longitude in decimal degrees (north and east positive).

[Groundstation]
callsign = N0CALL
latitude = 40.6
longitude = -3.7
submit_tlm = yes

Note: SatNOGS and SIDS submission is silently disabled if callsign is empty or if both latitude and longitude are 0. No warning is printed, so check these values if nothing appears in SatNOGS DB.

The full file format is described in Configuration.

Overriding with GR_SATELLITES_SUBMIT_TLM

The environment variable GR_SATELLITES_SUBMIT_TLM takes precedence over submit_tlm in the configuration file:

GR_SATELLITES_SUBMIT_TLM=0 gr_satellites FUNcube-1 --wavfile ao73.wav

Accepted values are exactly 1, yes, true, on (enable) and 0, no, false, off (disable), in lower case. Any other value, including True or YES, makes the tool crash with a Python KeyError while building the flowgraph. The repository's test.sh exports GR_SATELLITES_SUBMIT_TLM=0 so that decoding the sample recordings never submits old frames.

What Gets Submitted

Every frame produced by any deframer of the satellite is submitted, before transports and regardless of --hexdump. Frames read with --kiss_in are also submitted when submission is enabled, which you usually do not want for old data: disable it with GR_SATELLITES_SUBMIT_TLM=0.

SatNOGS DB and SIDS Servers

SatNOGS DB and custom servers both use the SIDS protocol, an HTTP protocol first developed by the ESTCube team. For each frame, gr-satellites sends a POST request to the server URL (https://db.satnogs.org/api/telemetry/ for SatNOGS) with these parameters, both in the query string and the body:

Parameter	Value
`noradID`	NORAD ID from the SatYAML file
`source`	Your callsign
`timestamp`	Reception time, UTC, ISO 8601 with milliseconds and a `Z` suffix
`frame`	The frame in upper-case hex
`locator`	`longLat`
`longitude`	Absolute value followed by `E` or `W`, e.g. `3.7W`
`latitude`	Absolute value followed by `N` or `S`, e.g. `40.6N`
`version`	`1.6.6`

Errors are printed but do not stop decoding: Error while submitting telemetry: followed by the exception, or Server error while submitting telemetry followed by the reply, URL, HTTP code and headers for non-2xx responses.

A satellite selects a custom SIDS server with an entry such as SIDS https://example.org/sids in telemetry_servers. No extra configuration is needed.

FUNcube Warehouse

Fill in site_id and auth_code in the [FUNcube] section; you get them by registering in the FUNcube Warehouse. Frames are posted to http://data.amsat-uk.org/api/data/hex/<site_id>/ as space-separated hex, with a digest parameter that is the MD5 of the hex string, a colon, and the auth code.

If either value is empty, FUNcube submission is skipped silently. On a non-200 reply the tool prints FUNcube server error while submitting telemetry with the reply and the HTTP code.

PW-Sat2

Set credentials_file in [PW-Sat2] to the path of the JSON credentials file downloaded from the "Your credentials" section of the PW-Sat2 ground station web interface (an account is needed). gr-satellites:

Loads the file and authenticates at startup. On failure it prints Could not load credentials for http://radio.pw-sat.pl or Could not authenticate to PW-Sat2 server, and every later frame prints Not uploading packet to http://radio.pw-sat.pl as we are not authenticated.
Appends a CRC-16 to each frame and uploads it, base64-encoded, with a millisecond timestamp.
Prints Packet uploaded to http://radio.pw-sat.pl with the server's reply.

Note: PW-Sat2 timestamps always use the current clock. --start_time is not applied to this server.

BME

For ATL-1, SMOG-P and SMOG-1, register an account in the BME server and enter user and password in the [BME] section. gr-satellites requests a token at startup and then posts each frame. Messages you may see:

Message	Meaning
`Wrong credentials, have you registered at...`	HTTP 401 from the token request.
`Authentication failed, error code = <n>`	Other HTTP error.
`Not uploading packet to BME, as we are not authenticated`	Authentication failed earlier.
`Packet upload failed, token might have expired!`	Upload rejected.
`Checksum error`	The server rejected a frame's checksum.

The BME server only accepts the three NORAD IDs above. The upstream documentation notes that this server is deprecated, since BME no longer uses it.

BME WebSocket

MRC-100 uses BMEWS: frames are sent over a WebSocket to wss://gnd.bme.hu:8070/send. No configuration is needed. If the connection fails at startup, the tool prints could not connect to wss://gnd.bme.hu:8070/send; disabling telemetry submission and continues decoding.

Harbin Institute of Technology Proxy

Some satellites built by the Harbin Institute of Technology use a telemetry proxy distributed with the gr-lilacsat and gr-dslwp projects. The proxy must be running on the same computer before gr_satellites starts. gr-satellites connects to 127.0.0.1 on the port given in the SatYAML entry (for example HIT 8001) and sends frames as KISS without a control byte. Station and operator details are configured in the proxy itself.

If the connection fails, the tool prints Could not connect to telemetry proxy: and Disabling telemetry submission..., and continues decoding without the proxy.

Timestamps

SatNOGS, SIDS servers and PW-Sat2 receive a reception timestamp taken from the computer's clock when the frame is decoded. For meaningful data:

keep the computer's clock synchronized (NTP),
prefer submitting from live signals,
if you must submit from a recording, use --throttle and --start_time (see Input Sources). This works for SatNOGS and SIDS, not for PW-Sat2.