SimTX API/Session status

Every receiver and transmitter session is described to the client by SessionStatus frames: once when the server accepts the start, whenever the session changes and keeps running, and when it is refused or stopped. This page describes that life cycle. It applies to ROLE_RECEIVER, ROLE_TX_AUDIO and ROLE_TX_GENERATED; control and moderation sessions report failures with Error instead.

message SessionStatus {
  SessionState state = 1;
  string reason = 2;
  ErrorCode code = 3;
  bytes session_id = 4;          // per-connection id (the transmission id for TX)
  BoundStation station = 5;      // unset for ad-hoc sessions
  double frequency_hz = 6;
  Tracking tracking = 7;
  AntennaPointing pointing = 8;
  int64 request_id = 9;          // echoes AntennaPointingUpdate / ReceiverRetune request_id
  UpdateReason update_reason = 10;  // UPDATED only
}

Life cycle

 client                                                 server
   | -- [10] receiver_start / [12] transmitter_start --> |
   | <------------- [10] session_status  REJECTED ------- |   code + reason, then close
   |                         or                           |
   | <------------- [10] session_status  BOUND ---------- |   session_id, station, frequency
   |                    ... stream runs ...               |
   | <------------- [10] session_status  UPDATED -------- |   update_reason + current state
   | <------------- [10] session_status  UPDATED -------- |
   |                    ... stream runs ...               |
   | <------------- [10] session_status  ENDED ---------- |   code + reason, then close

State	When	Afterwards
BOUND	Once, when the start is accepted.	The stream begins: IqStreamDescriptor for a receiver, TxQueue and TxAccept for a transmitter.
REJECTED	Instead of BOUND, when the start cannot be accepted.	The connection closes.
UPDATED	Any number of times, when something about the running session changed.	The session continues.
ENDED	When the server stops a running session.	The connection closes.

REJECTED and ENDED are the only refusal and kick signal, for receivers and transmitters alike. They carry an ErrorCode in code and a human-readable reason. Show the reason to the user; branch on the code.

A session can also end without a SessionStatus, when the connection itself fails or the account's lease runs out. Treat a closed connection as the end of the session.

BOUND

BOUND describes the session as the server runs it:

• session_id: a 16-byte id for this session. For a transmitter it is the transmission id. It identifies the session in station lists, health reports and the own-transmitter monitor. Keep it.
• station: for a station-bound session, the BoundStation the server resolved: station, antenna and rig with their revisions, the effective PA cap, and the antenna as modelled. Show the user what the station dictates from it. Unset for ad-hoc sessions.
• frequency_hz, tracking, pointing: the current values. Unset tracking or pointing means none.

UPDATED

UPDATED means the session keeps running with a changed state. update_reason gives the most significant cause:

Value	Name	Meaning
0	UPDATE_REASON_UNSPECIFIED	Not an UPDATED status. On an UPDATED status: apply the snapshot fields.
1	UPDATE_REASON_POINTING	This session's AntennaPointingUpdate was applied (request_id).
2	UPDATE_REASON_TRACKING	The server changed tracking, for example because the target was deleted or reentered.
3	UPDATE_REASON_STATION_EDIT	The station, its antenna or its rig was edited; revisions are bumped.
4	UPDATE_REASON_ORBIT_CHANGE	The bound satellite's elements or attitude changed.
5	UPDATE_REASON_DEORBIT_SCHEDULED	The bound satellite fired its deorbit burn; station.core.deorbit says when it reenters.
6	UPDATE_REASON_RETUNE	This session's ReceiverRetune took effect (request_id).

Rules for applying an update:

• frequency_hz, tracking and pointing are always the current values. Replace the client's copies.
• station is set only when the station changed (STATION_EDIT, ORBIT_CHANGE, DEORBIT_SCHEDULED). It replaces the client's copy as a whole. Unset means unchanged.
• request_id is set when the update confirms the client's own request: an AntennaPointingUpdate (POINTING) or a ReceiverRetune (RETUNE).
• A reason the client does not know, or UPDATE_REASON_UNSPECIFIED, means "apply the snapshot fields".
• Statuses arrive in order on one connection, so the last one received is the current state.

Station edits and protocol revisions

A station-bound session keeps the station snapshot it was bound with. When the owner edits the station, its antenna or its rig in a way the session can follow, a server sends UPDATED with STATION_EDIT and the new snapshot, with the revisions bumped. It does this only for clients whose ClientHello carried protocol_revision ≥ 1. A client that announced no revision gets ENDED instead and must reconnect to pick up the new revision. See Protocol revisions.

Edits a session cannot follow always end it, whatever the revision: the station is deleted, its bound antenna or rig is removed, or the account loses access to it.

Satellites

A session bound to a satellite also gets UPDATED when the satellite's orbit or attitude changes (ORBIT_CHANGE) and when its owner fires the deorbit burn (DEORBIT_SCHEDULED). After DEORBIT_SCHEDULED, station.core.deorbit.reentry_at_ms says when the session will end. At that time the server ends it with ENDED and the reason Satellite burned up on reentry. See Deorbit.

When the target of a session's tracking disappears, for example because the tracked satellite reentered, the server changes the tracking and sends UPDATED with TRACKING.

REJECTED

Typical codes:

Code	Typical cause
INVALID_REQUEST	A value outside its range, no site, an unknown modulation or antenna type, an invalid NEC deck.
FORBIDDEN	A station-bound start without a ticket for that station; a binding that does not match the ticket; a ticket bound to a station used with an ad-hoc site; transmitting through someone else's station.
STATION_INACTIVE	The station was deleted, or the satellite has reentered.
STATION_REQUIRED	An ad-hoc transmitter without tx.adhoc on a server whose policy refuses ad-hoc transmitters.
LIMIT_REACHED	A server, address, account or station limit, or the wideband budget.
UNAVAILABLE	The server cannot place the session right now, for example no transmitter capacity.

ENDED

Typical causes are a moderator's kick, a ban of the client's address, the station being deleted or losing its antenna or rig, the account losing access, and a satellite's reentry. A session that simply ended may carry ERROR_CODE_UNSPECIFIED.

There is no session resumption. To continue, mint a new ticket if the connection was authenticated, and reconnect with exponential backoff. See Reconnecting.

Examples

session_status_rejected_station_required (server to client, 56 bytes):

37                                 frame length 55
52 35                              session_status (SessionStatus), 53 bytes
  08 02                            state = 2 (SESSION_STATE_REJECTED)
  12 2F 41 64 2D 68 6F 63 20 74 …  reason = "Ad-hoc transmitters are disabled on this server"
  18 09                            code = 9 (ERROR_CODE_STATION_REQUIRED)

session_status_updated_retune (server to client, 36 bytes):

23                            frame length 35
52 21                         session_status (SessionStatus), 33 bytes
  08 04                       state = 4 (SESSION_STATE_UPDATED)
  22 10 AA AA AA AA …         session_id = aaaaaaaa-bbbb-4ccc-8ddd-ffffffffffff
  31 00 00 00 00 12 D8 6A 41  frequency_hz = 14074000.0
  48 29                       request_id = 41
  50 06                       update_reason = 6 (UPDATE_REASON_RETUNE)

session_status_ended_kicked (server to client, 46 bytes):

2D                                 frame length 45
52 2B                              session_status (SessionStatus), 43 bytes
  08 03                            state = 3 (SESSION_STATE_ENDED)
  12 15 4B 69 63 6B 65 64 20 62 …  reason = "Kicked by a moderator"
  22 10 AA AA AA AA …              session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee

More examples, including a satellite BOUND with its station snapshot, are on the SessionStatus page.