Clanker: Remove development history and server internals

2026-10-24T17:16:37Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 13:		Line 13:
	\| file = session.proto		\| file = session.proto
	}}		}}
	'''SessionStatus''' is the server's account of a receiver or transmitter session: once when the start is accepted (<code>BOUND</code>), on every change the session survives (<code>UPDATED</code>), and when it is refused or stopped (<code>REJECTED</code>, <code>ENDED</code>). <code>REJECTED</code> and <code>ENDED</code> are the only refusal and kick signal for receivers and transmitters alike~~; v24's TxReject and TxKick are gone~~.		'''SessionStatus''' is the server's account of a receiver or transmitter session: once when the start is accepted (<code>BOUND</code>), on every change the session survives (<code>UPDATED</code>), and when it is refused or stopped (<code>REJECTED</code>, <code>ENDED</code>). <code>REJECTED</code> and <code>ENDED</code> are the only refusal and kick signal for receivers and transmitters alike.

	The page [[SimTX API/Session status\|Session status]] describes the life cycle in detail.		The page [[SimTX API/Session status\|Session status]] describes the life cycle in detail.
Line 96:		Line 96:
	* <code>BOUND</code> and <code>UPDATED</code> describe the session as the server now runs it. <code>frequency_hz</code>, <code>tracking</code> and <code>pointing</code> are always the current values.		* <code>BOUND</code> and <code>UPDATED</code> describe the session as the server now runs it. <code>frequency_hz</code>, <code>tracking</code> and <code>pointing</code> are always the current values.
	* <code>station</code> is set on every <code>BOUND</code> of a station-bound session. On <code>UPDATED</code> it is set only when the station changed (<code>STATION_EDIT</code>, <code>ORBIT_CHANGE</code>, <code>DEORBIT_SCHEDULED</code>) and then replaces the client's copy as a whole. Unset means unchanged.		* <code>station</code> is set on every <code>BOUND</code> of a station-bound session. On <code>UPDATED</code> it is set only when the station changed (<code>STATION_EDIT</code>, <code>ORBIT_CHANGE</code>, <code>DEORBIT_SCHEDULED</code>) and then replaces the client's copy as a whole. Unset means unchanged.
	* Servers send station changes as <code>UPDATED</code> only to clients whose hello carried <code>protocol_revision</code> ≥ 1. ~~Older~~ clients get <code>ENDED</code> instead.		* Servers send station changes as <code>UPDATED</code> only to clients whose hello carried <code>protocol_revision</code> ≥ 1. Other clients get <code>ENDED</code> instead.
	* <code>REJECTED</code> and <code>ENDED</code> carry <code>code</code> and <code>reason</code>; the connection closes after them.		* <code>REJECTED</code> and <code>ENDED</code> carry <code>code</code> and <code>reason</code>; the connection closes after them.
	* Statuses arrive in order on one connection. A client that does not know an <code>update_reason</code> applies the snapshot fields.		* Statuses arrive in order on one connection. A client that does not know an <code>update_reason</code> applies the snapshot fields.

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>session_status_bound_satellite</code>''' (server to client, 373 bytes):		'''<code>session_status_bound_satellite</code>''' (server to client, 373 bytes):

Clanker: Protocol v25 reference

2026-10-24T16:27:54Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = SessionStatus
| frame = ServerFrame
| field = 10
| member = session_status
| direction = s2c
| session = [[SimTX API/Receiver session|Receiver]], [[SimTX API/Transmitter session|transmitter]]
| roles = <code>ROLE_RECEIVER</code>, <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>.
| permission = None
| answers = [[SimTX API/Packets/ReceiverStart|ReceiverStart]], [[SimTX API/Packets/TransmitterStart|TransmitterStart]], [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]], [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]]
| group = session
| file = session.proto
}}
'''SessionStatus''' is the server's account of a receiver or transmitter session: once when the start is accepted (<code>BOUND</code>), on every change the session survives (<code>UPDATED</code>), and when it is refused or stopped (<code>REJECTED</code>, <code>ENDED</code>). <code>REJECTED</code> and <code>ENDED</code> are the only refusal and kick signal for receivers and transmitters alike; v24's TxReject and TxKick are gone.

The page [[SimTX API/Session status|Session status]] describes the life cycle in detail.

== Definition ==
<syntaxhighlight lang="protobuf">
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
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>state</code> || [[SimTX API/Data types#SessionState|SessionState]] || Required; never <code>UNSPECIFIED</code>.
|-
| 2 || <code>reason</code> || <code>string</code> || Human-readable reason. Set on <code>REJECTED</code> and <code>ENDED</code>.
|-
| 3 || <code>code</code> || [[SimTX API/Data types#ErrorCode|ErrorCode]] || Set on <code>REJECTED</code> and <code>ENDED</code>. <code>UNSPECIFIED</code> on an <code>ENDED</code> session that simply ended.
|-
| 4 || <code>session_id</code> || <code>bytes</code> || 16-byte per-connection session id. For a transmitter, the transmission id. Identifies the session in station lists, health reports and own-transmitter monitoring.
|-
| 5 || <code>station</code> || [[SimTX API/Data types#BoundStation|BoundStation]] || The resolved station of a station-bound session. Always set on <code>BOUND</code>; on <code>UPDATED</code> set only when the station changed, and then it replaces the client's copy as a whole. Unset for ad-hoc sessions.
|-
| 6 || <code>frequency_hz</code> || <code>double</code> || Current frequency in Hz: receiver centre frequency or transmitter carrier.
|-
| 7 || <code>tracking</code> || [[SimTX API/Data types#Tracking|Tracking]] || Current tracking. Unset: none.
|-
| 8 || <code>pointing</code> || [[SimTX API/Data types#AntennaPointing|AntennaPointing]] || Current antenna pointing. Unset: none.
|-
| 9 || <code>request_id</code> || <code>int64</code> || Echoes the <code>request_id</code> of the [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] or [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] this status confirms. 0 otherwise.
|-
| 10 || <code>update_reason</code> || [[SimTX API/Data types#UpdateReason|UpdateReason]] || <code>UPDATED</code> only: the most significant cause.
|}

== States ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>SESSION_STATE_UNSPECIFIED</code> || Never sent. Decoders refuse it.
|-
| 1 || <code>SESSION_STATE_BOUND</code> || Start accepted. <code>TxQueue</code> / <code>TxAccept</code> or <code>IqStreamDescriptor</code> follow.
|-
| 2 || <code>SESSION_STATE_REJECTED</code> || Start refused. <code>code</code> and <code>reason</code> say why; the connection closes.
|-
| 3 || <code>SESSION_STATE_ENDED</code> || Ended by the server: kick, ban, station deleted, reentry, access revoked. The connection closes.
|-
| 4 || <code>SESSION_STATE_UPDATED</code> || The session keeps running with a changed state; see <code>update_reason</code>.
|}

== Update reasons ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>UPDATE_REASON_UNSPECIFIED</code> || Not an <code>UPDATED</code> status. On an <code>UPDATED</code> status: apply the snapshot fields.
|-
| 1 || <code>UPDATE_REASON_POINTING</code> || This session's [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] was applied (<code>request_id</code>).
|-
| 2 || <code>UPDATE_REASON_TRACKING</code> || The server changed tracking, for example because the target was deleted or reentered.
|-
| 3 || <code>UPDATE_REASON_STATION_EDIT</code> || The station, its antenna or its rig was edited; revisions are bumped.
|-
| 4 || <code>UPDATE_REASON_ORBIT_CHANGE</code> || The bound satellite's elements or attitude changed.
|-
| 5 || <code>UPDATE_REASON_DEORBIT_SCHEDULED</code> || The bound satellite fired its deorbit burn; <code>station.core.deorbit</code> says when it reenters.
|-
| 6 || <code>UPDATE_REASON_RETUNE</code> || This session's [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] took effect (<code>request_id</code>).
|}

== Rules ==
* <code>BOUND</code> is sent exactly once, before [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] or [[SimTX API/Packets/TxQueue|TxQueue]] / [[SimTX API/Packets/TxAccept|TxAccept]]. Keep <code>session_id</code>: it identifies the session in station lists, health reports and own-transmitter monitoring.
* <code>BOUND</code> and <code>UPDATED</code> describe the session as the server now runs it. <code>frequency_hz</code>, <code>tracking</code> and <code>pointing</code> are always the current values.
* <code>station</code> is set on every <code>BOUND</code> of a station-bound session. On <code>UPDATED</code> it is set only when the station changed (<code>STATION_EDIT</code>, <code>ORBIT_CHANGE</code>, <code>DEORBIT_SCHEDULED</code>) and then replaces the client's copy as a whole. Unset means unchanged.
* Servers send station changes as <code>UPDATED</code> only to clients whose hello carried <code>protocol_revision</code> ≥ 1. Older clients get <code>ENDED</code> instead.
* <code>REJECTED</code> and <code>ENDED</code> carry <code>code</code> and <code>reason</code>; the connection closes after them.
* Statuses arrive in order on one connection. A client that does not know an <code>update_reason</code> applies the snapshot fields.

== Examples ==
Complete frames, including the varint length prefix, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>).

'''<code>session_status_bound_satellite</code>''' (server to client, 373 bytes):

<syntaxhighlight lang="text">
F3 02 frame length 371
52 F0 02 session_status (SessionStatus), 368 bytes
08 01 state = 1 (SESSION_STATE_BOUND)
22 10 AA AA AA AA … session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
2A 8E 02 station (BoundStation), 270 bytes
0A A8 01 core (StationCore), 168 bytes
0A 10 99 99 99 99 … station_id = 99999999-8888-4777-8666-555555555555
10 03 revision = 3
18 02 kind = 2 (STATION_KIND_SATELLITE)
22 08 53 69 6D 53 61 74 2D 31 name = "SimSat-1"
2A 05 53 53 41 54 31 callsign = "SSAT1"
32 08 6F 70 65 72 61 74 6F 72 owner_handle = "operator"
38 01 visibility = 1 (STATION_VISIBILITY_PUBLIC)
42 1B location (GeoPoint), 27 bytes
09 00 00 00 00 00 00 24 40 latitude_deg = 10.0
11 00 00 00 00 00 00 34 40 longitude_deg = 20.0
19 00 00 00 00 E0 C8 20 41 altitude_meters = 550000.0
4A 49 orbit (OrbitalElements), 73 bytes
0A 0B 73 69 6D 74 78 2D 6A 32 2D 76 31 model = "simtx-j2-v1"
10 C0 BB F2 D6 06 epoch_seconds = 1792843200
21 00 00 00 00 00 09 BB 40 semi_major_axis_km = 6921.0
29 FC A9 F1 D2 4D 62 50 3F eccentricity = 0.001
31 66 66 66 66 66 66 58 40 inclination_deg = 97.6
39 00 00 00 00 00 00 5E 40 raan_deg = 120.0
41 00 00 00 00 00 80 56 40 argument_of_perigee_deg = 90.0
49 00 00 00 00 00 00 24 40 mean_anomaly_deg = 10.0
52 0B attitude (Attitude), 11 bytes
1A 09 spin (Spin), 9 bytes
11 00 00 00 00 00 00 00 40 rate_rpm = 2.0
12 10 99 99 99 99 … antenna_id = 99999999-8888-4777-8666-444444444444
18 01 antenna_revision = 1
35 00 00 A0 40 pa_cap_watts = 5
3A 48 antenna (AntennaConfig), 72 bytes
0A 06 44 49 50 4F 4C 45 type = "DIPOLE"
15 00 00 20 41 height_meters = 10
1D 00 00 34 42 azimuth_deg = 45
25 00 00 80 3F feedline_loss_db = 1
2D 9A 99 21 41 wire_length_meters = 10.1
3A 2A pointing (AntennaPointing), 42 bytes
08 02 mount = 2 (ANTENNA_MOUNT_AZEL)
10 01 mode = 1 (POINTING_MODE_TRACK)
1D 00 00 34 43 azimuth_deg = 180
25 00 00 F0 41 elevation_deg = 30
2A 10 11 11 11 11 … target_station_id = 11111111-2222-4333-8444-555555555555
35 00 00 C0 40 azimuth_rate_deg_per_sec = 6
3D 00 00 40 40 elevation_rate_deg_per_sec = 3
31 00 00 00 60 19 EF B9 41 frequency_hz = 435100000.0
3A 14 tracking (Tracking), 20 bytes
0A 10 11 11 11 11 … target_station_id = 11111111-2222-4333-8444-555555555555
10 01 point_antenna = true
42 2A pointing (AntennaPointing), 42 bytes
08 02 mount = 2 (ANTENNA_MOUNT_AZEL)
10 01 mode = 1 (POINTING_MODE_TRACK)
1D 00 00 34 43 azimuth_deg = 180
25 00 00 F0 41 elevation_deg = 30
2A 10 11 11 11 11 … target_station_id = 11111111-2222-4333-8444-555555555555
35 00 00 C0 40 azimuth_rate_deg_per_sec = 6
3D 00 00 40 40 elevation_rate_deg_per_sec = 3
</syntaxhighlight>

'''<code>session_status_rejected</code>''' (server to client, 51 bytes):

<syntaxhighlight lang="text">
32 frame length 50
52 30 session_status (SessionStatus), 48 bytes
08 02 state = 2 (SESSION_STATE_REJECTED)
12 2A 47 61 6D 65 20 74 69 63 … reason = "Game ticket was minted for another station"
18 03 code = 3 (ERROR_CODE_FORBIDDEN)
</syntaxhighlight>

'''<code>session_status_rejected_station_required</code>''' (server to client, 56 bytes):

<syntaxhighlight lang="text">
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)
</syntaxhighlight>

'''<code>session_status_ended_kicked</code>''' (server to client, 46 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

'''<code>session_status_updated_pointing</code>''' (server to client, 104 bytes):

<syntaxhighlight lang="text">
67 frame length 103
52 65 session_status (SessionStatus), 101 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 60 19 EF B9 41 frequency_hz = 435100000.0
3A 16 tracking (Tracking), 22 bytes
0A 10 99 99 99 99 … target_station_id = 99999999-8888-4777-8666-555555555555
10 01 point_antenna = true
18 01 doppler_correct = true
42 2A pointing (AntennaPointing), 42 bytes
08 02 mount = 2 (ANTENNA_MOUNT_AZEL)
10 01 mode = 1 (POINTING_MODE_TRACK)
1D 00 00 34 43 azimuth_deg = 180
25 00 00 F0 41 elevation_deg = 30
2A 10 11 11 11 11 … target_station_id = 11111111-2222-4333-8444-555555555555
35 00 00 C0 40 azimuth_rate_deg_per_sec = 6
3D 00 00 40 40 elevation_rate_deg_per_sec = 3
48 1F request_id = 31
50 01 update_reason = 1 (UPDATE_REASON_POINTING)
</syntaxhighlight>

'''<code>session_status_updated_retune</code>''' (server to client, 36 bytes):

<syntaxhighlight lang="text">
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)
</syntaxhighlight>

'''<code>session_status_updated_station_edit</code>''' (server to client, 209 bytes):

<syntaxhighlight lang="text">
CF 01 frame length 207
52 CC 01 session_status (SessionStatus), 204 bytes
08 04 state = 4 (SESSION_STATE_UPDATED)
22 10 AA AA AA AA … session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
2A A1 01 station (BoundStation), 161 bytes
0A 4E core (StationCore), 78 bytes
0A 10 11 11 11 11 … station_id = 11111111-2222-4333-8444-555555555555
10 05 revision = 5
18 01 kind = 1 (STATION_KIND_GROUND)
22 08 42 75 64 61 70 65 73 74 name = "Budapest"
2A 05 48 41 35 47 53 callsign = "HA5GS"
32 08 6F 70 65 72 61 74 6F 72 owner_handle = "operator"
42 1B location (GeoPoint), 27 bytes
09 00 00 00 00 00 C0 47 40 latitude_deg = 47.5
11 00 00 00 00 00 00 33 40 longitude_deg = 19.0
19 00 00 00 00 00 00 5E 40 altitude_meters = 120.0
12 10 11 11 11 11 … antenna_id = 11111111-2222-4333-8444-666666666666
18 02 antenna_revision = 2
22 10 11 11 11 11 … rig_id = 11111111-2222-4333-8444-777777777777
28 03 rig_revision = 3
35 00 00 C8 42 pa_cap_watts = 100
3A 22 antenna (AntennaConfig), 34 bytes
0A 08 59 41 47 49 5F 33 45 4C type = "YAGI_3EL"
15 00 00 60 41 height_meters = 14
1D 00 00 87 43 azimuth_deg = 270
25 00 00 00 3F feedline_loss_db = 0.5
3A 07 pointing (AntennaPointing), 7 bytes
08 01 mount = 1 (ANTENNA_MOUNT_AZ)
1D 00 00 87 43 azimuth_deg = 270
31 00 00 00 00 12 D8 6A 41 frequency_hz = 14074000.0
42 07 pointing (AntennaPointing), 7 bytes
08 01 mount = 1 (ANTENNA_MOUNT_AZ)
1D 00 00 87 43 azimuth_deg = 270
50 03 update_reason = 3 (UPDATE_REASON_STATION_EDIT)
</syntaxhighlight>

'''<code>session_status_updated_deorbit_scheduled</code>''' (server to client, 301 bytes):

<syntaxhighlight lang="text">
AB 02 frame length 299
52 A8 02 session_status (SessionStatus), 296 bytes
08 04 state = 4 (SESSION_STATE_UPDATED)
22 10 AA AA AA AA … session_id = aaaaaaaa-bbbb-4ccc-8ddd-ffffffffffff
2A 86 02 station (BoundStation), 262 bytes
0A CC 01 core (StationCore), 204 bytes
0A 10 99 99 99 99 … station_id = 99999999-8888-4777-8666-555555555555
10 04 revision = 4
18 02 kind = 2 (STATION_KIND_SATELLITE)
22 08 53 69 6D 53 61 74 2D 31 name = "SimSat-1"
2A 05 53 53 41 54 31 callsign = "SSAT1"
32 08 6F 70 65 72 61 74 6F 72 owner_handle = "operator"
38 01 visibility = 1 (STATION_VISIBILITY_PUBLIC)
42 1B location (GeoPoint), 27 bytes
09 00 00 00 00 00 00 29 C0 latitude_deg = -12.5
11 00 00 00 00 00 80 40 40 longitude_deg = 33.0
19 00 00 00 00 40 06 19 41 altitude_meters = 410000.0
4A 49 orbit (OrbitalElements), 73 bytes
0A 0B 73 69 6D 74 78 2D 6A 32 2D 76 31 model = "simtx-j2-v1"
10 D0 D7 F2 D6 06 epoch_seconds = 1792846800
21 00 00 00 00 00 23 BA 40 semi_major_axis_km = 6691.0
29 22 FD F6 75 E0 9C 91 3F eccentricity = 0.0172
31 66 66 66 66 66 66 58 40 inclination_deg = 97.6
39 00 00 00 00 00 00 5E 40 raan_deg = 120.0
41 00 00 00 00 00 80 56 40 argument_of_perigee_deg = 90.0
49 00 00 00 00 00 00 69 40 mean_anomaly_deg = 200.0
52 02 attitude (Attitude), 2 bytes
0A 00 nadir (Nadir), 0 bytes
5A 2B deorbit (Deorbit), 43 bytes
08 80 C9 FC EF 96 34 burn_at_ms = 1792846800000
10 90 C6 94 F1 96 34 reentry_at_ms = 1792849290000
1A 12 reentry_point (GeoPoint), 18 bytes
09 00 00 00 00 00 20 43 C0 latitude_deg = -38.25
11 00 00 00 00 00 70 62 40 longitude_deg = 147.5
21 00 00 00 00 00 E0 4E 40 delta_v_mps = 61.75
12 10 99 99 99 99 … antenna_id = 99999999-8888-4777-8666-444444444444
18 01 antenna_revision = 1
35 00 00 A0 40 pa_cap_watts = 5
3A 1C antenna (AntennaConfig), 28 bytes
0A 06 44 49 50 4F 4C 45 type = "DIPOLE"
15 00 00 20 41 height_meters = 10
1D 00 00 34 42 azimuth_deg = 45
25 00 00 80 3F feedline_loss_db = 1
2D 9A 99 21 41 wire_length_meters = 10.1
31 00 00 00 60 19 EF B9 41 frequency_hz = 435100000.0
50 05 update_reason = 5 (UPDATE_REASON_DEORBIT_SCHEDULED)
</syntaxhighlight>

== See also ==
* [[SimTX API/Session status]]
* [[SimTX API/Stations]]
* [[SimTX API/Tracking and pointing]]

{{SimTX API navbox}}
[[Category:SimTX API]]

SimTX API/Packets/SessionStatus - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference