SimTX API/Packets/SessionStatus
| Frame | ServerFrame, field 10
|
|---|---|
| Member | session_status
|
| Direction | Server → client |
| Session | Receiver, transmitter |
| Roles | ROLE_RECEIVER, ROLE_TX_AUDIO, ROLE_TX_GENERATED.
|
| Permission | None |
| Answers | ReceiverStart, TransmitterStart, AntennaPointingUpdate, ReceiverRetune |
| Defined in | session.proto
|
SessionStatus is the server's account of a receiver or transmitter session: once when the start is accepted (BOUND), on every change the session survives (UPDATED), and when it is refused or stopped (REJECTED, ENDED). REJECTED and ENDED are the only refusal and kick signal for receivers and transmitters alike; v24's TxReject and TxKick are gone.
The page Session status describes the life cycle in detail.
Definition
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
}
Fields
| # | Field | Type | Description |
|---|---|---|---|
| 1 | state |
SessionState | Required; never UNSPECIFIED.
|
| 2 | reason |
string |
Human-readable reason. Set on REJECTED and ENDED.
|
| 3 | code |
ErrorCode | Set on REJECTED and ENDED. UNSPECIFIED on an ENDED session that simply ended.
|
| 4 | session_id |
bytes |
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 | station |
BoundStation | The resolved station of a station-bound session. Always set on BOUND; on UPDATED set only when the station changed, and then it replaces the client's copy as a whole. Unset for ad-hoc sessions.
|
| 6 | frequency_hz |
double |
Current frequency in Hz: receiver centre frequency or transmitter carrier. |
| 7 | tracking |
Tracking | Current tracking. Unset: none. |
| 8 | pointing |
AntennaPointing | Current antenna pointing. Unset: none. |
| 9 | request_id |
int64 |
Echoes the request_id of the AntennaPointingUpdate or ReceiverRetune this status confirms. 0 otherwise.
|
| 10 | update_reason |
UpdateReason | UPDATED only: the most significant cause.
|
States
| Value | Name | Meaning |
|---|---|---|
| 0 | SESSION_STATE_UNSPECIFIED |
Never sent. Decoders refuse it. |
| 1 | SESSION_STATE_BOUND |
Start accepted. TxQueue / TxAccept or IqStreamDescriptor follow.
|
| 2 | SESSION_STATE_REJECTED |
Start refused. code and reason say why; the connection closes.
|
| 3 | SESSION_STATE_ENDED |
Ended by the server: kick, ban, station deleted, reentry, access revoked. The connection closes. |
| 4 | SESSION_STATE_UPDATED |
The session keeps running with a changed state; see update_reason.
|
Update reasons
| 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
BOUNDis sent exactly once, before IqStreamDescriptor or TxQueue / TxAccept. Keepsession_id: it identifies the session in station lists, health reports and own-transmitter monitoring.BOUNDandUPDATEDdescribe the session as the server now runs it.frequency_hz,trackingandpointingare always the current values.stationis set on everyBOUNDof a station-bound session. OnUPDATEDit is set only when the station changed (STATION_EDIT,ORBIT_CHANGE,DEORBIT_SCHEDULED) and then replaces the client's copy as a whole. Unset means unchanged.- Servers send station changes as
UPDATEDonly to clients whose hello carriedprotocol_revision≥ 1. Older clients getENDEDinstead. REJECTEDandENDEDcarrycodeandreason; the connection closes after them.- Statuses arrive in order on one connection. A client that does not know an
update_reasonapplies the snapshot fields.
Examples
Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).
session_status_bound_satellite (server to client, 373 bytes):
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
session_status_rejected (server to client, 51 bytes):
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)
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_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
session_status_updated_pointing (server to client, 104 bytes):
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)
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_updated_station_edit (server to client, 209 bytes):
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)
session_status_updated_deorbit_scheduled (server to client, 301 bytes):
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)