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.
| Tag | Required | Value |
|---|---|---|
ground_station_id | yes | A ground station in your network config. |
ground_antenna_id | yes | An antenna of that ground station. |
satellite_id | yes | A satellite in your network config. |
radio_id | no | A 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_id | no | The 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
| Field | Type | Notes |
|---|---|---|
azimuth_deg | float | |
elevation_deg | float | |
tracking_error_az_deg | float | |
tracking_error_el_deg | float | |
track_mode | string | |
range_m | float | One-way. |
range_rate_m_s | float | |
carrier_locked | boolean | |
subcarrier_locked | boolean | |
symbol_locked | boolean | |
frame_locked | boolean | |
c_n0_dbhz | float | |
es_n0_db | float | |
rx_power_dbm | float | |
frequency_ghz | float | Carrier centre frequency. |
carrier_offset_hz | float | |
frames_delivered | integer | Cumulative since the pass started. |
frames_good | integer | Cumulative since the pass started. |
uplink_status | string | |
modcod | string | The carrier's current MODCOD as the modem names it, such as QPSK 1/4. |
tx_power_dbm | float | |
ber | float | Bit errors over bits in the reporting interval, not a cumulative count. |
per | float | Packet errors over packets in the reporting interval, not a cumulative count. |
system_noise_temp_k | float | System noise temperature in kelvin. |
noise_power_dbm | float | Noise power in a fixed bandwidth. |
noise_diode_on | boolean | Calibration diode state. |
bytes_delivered | integer | A flown pass's bytes delivered, 0 or more. A whole float such as 5.0 is also accepted. |
contact_status | string | A flown pass's outcome: ok, failed or missed. |
los_utc | string | A 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.
| Mistake | Result |
|---|---|
| An id tag is missing | The agent drops the line. |
| An id isn't in your network config, or the antenna belongs to another ground station | The platform rejects that record and writes the rest of the batch. |
| A field isn't on the list | The 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 type | The platform rejects that record and writes the rest of the batch. |
A pass outcome field has a bad value, such as an unknown contact_status | On 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 yet | Nothing 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.