Skip to main content

Publish telemetry

Write one line per sample to the local socket. Each line names a ground station, one of its antennas, and the satellite it is tracking, then carries any fields from the list below. Send fields at whatever rate you have them; a record does not need every field.

link,ground_station_id=GS-001,ground_antenna_id=GS-001-ANT-1,satellite_id=SAT-9 elevation_deg=22.8,c_n0_dbhz=71.4,carrier_locked=true 1785528000000000000

Ids​

The ids are tags and must match your topology config, where ground stations, antennas, and satellites are defined. Positions and orbits come from there too (orbits from each satellite's NORAD ID or TLE), so they aren't telemetry.

TagRequiredValue
ground_station_idyesA ground station in your network config.
ground_antenna_idyesAn antenna of that ground station.
satellite_idyesA satellite in your network config.
radio_idnoA radio of that satellite in your network config. Name it when one satellite has two carriers measured at the same instant, and send it on all of a link's records or on none: a link with both is two series.
contact_idnoThe contact (pass), 1 to 128 characters.

Ids are 1 to 64 letters, digits, ., _, or -. The measurement name (link) is required by line protocol and ignored after that, as is any other tag.

Fields​

FieldTypeNotes
azimuth_degfloat
elevation_degfloat
tracking_error_az_degfloat
tracking_error_el_degfloat
track_modestring
range_mfloatOne-way.
range_rate_m_sfloat
carrier_lockedboolean
subcarrier_lockedboolean
symbol_lockedboolean
frame_lockedboolean
c_n0_dbhzfloat
es_n0_dbfloat
rx_power_dbmfloat
frequency_ghzfloatCarrier centre frequency.
carrier_offset_hzfloat
frames_deliveredintegerCumulative since the pass started.
frames_goodintegerCumulative since the pass started.
uplink_statusstring
modcodstringThe carrier's current MODCOD as the modem names it, such as QPSK 1/4.
tx_power_dbmfloat
berfloatBit errors over bits in the reporting interval, not a cumulative count.
perfloatPacket errors over packets in the reporting interval, not a cumulative count.
system_noise_temp_kfloatSystem noise temperature in kelvin.
noise_power_dbmfloatNoise power in a fixed bandwidth.
noise_diode_onbooleanCalibration diode state.
bytes_deliveredintegerA flown pass's bytes delivered, 0 or more. A whole float such as 5.0 is also accepted.
contact_statusstringA flown pass's outcome: ok, failed or missed.
los_utcstringA flown pass's end, ISO 8601 with a UTC offset, after the record's time.

Write 22.8 for a float, 4820i for an integer, true for a boolean, and "program" for a string. An integer is accepted where a float is expected, but not the other way round, and 1/0 is not a boolean.

The timestamp is Unix nanoseconds. Omit it to use the time the agent receives the line.

Try it​

emit encodes one record and writes it to the socket:

constellation-agent emit \
--ground-station-id GS-001 \
--ground-antenna-id GS-001-ANT-1 \
--satellite-id SAT-9 \
--field elevation_deg=22.8 \
--field carrier_locked=true

Add --print to see the encoded line without sending it, or pipe JSON to emit --json:

echo '{"ground_station_id": "GS-001", "ground_antenna_id": "GS-001-ANT-1", "satellite_id": "SAT-9",
"fields": {"elevation_deg": 22.8, "carrier_locked": true}}' | constellation-agent emit --json

From an application​

Keep one connection open and write lines as samples arrive. Don't run emit per sample.

import socket, time

path = open("/etc/constellation/socket.env").read().split("=", 1)[1].strip() # CONSTELLATION_SOCKET_PATH
ids = "ground_station_id=GS-001,ground_antenna_id=GS-001-ANT-1,satellite_id=SAT-9"

with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
s.connect(path)
while True:
s.sendall(f"link,{ids} elevation_deg=22.8,c_n0_dbhz=71.4 {time.time_ns()}\n".encode())
time.sleep(1)

Reconnect with backoff when the connection closes: the agent restarts on upgrade. A completed write means the agent received the bytes, not that the platform stored them. Escaping and framing rules are in the protocol reference.

Rejections​

The platform checks each record on its own: it writes every record that passes and reports the rest, so a mistake costs only the records it is in.

MistakeResult
An id tag is missingThe agent drops the line.
An id isn't in your network config, or the antenna belongs to another ground stationThe platform rejects that record and writes the rest of the batch.
A field isn't on the listThe platform drops the field and writes the rest of the record. A record left with no field on the list is rejected.
A field has the wrong typeThe platform rejects that record and writes the rest of the batch.
A pass outcome field has a bad value, such as an unknown contact_statusOn gRPC egress the platform rejects that record and writes the rest of the batch. On HTTP egress the whole request is refused, as below.
You have no network config yetNothing can be written. On gRPC egress the agent holds the batch and retries it until you upload one; on HTTP egress every batch is refused and dropped.

The agent never resends a batch the platform answered: that would write its accepted records twice. On the default gRPC egress, sudo constellation-agent logs shows each partial write with its counts and first five rejections. On HTTP egress the rejections are in the API's response, which is not logged, and a record that breaks the record schema, such as a malformed id, a contact_id over 128 characters or a bad pass outcome field, refuses the whole request with 422.

Next: Verify it.