Editing SimTX API/Packets/SessionStatus

{{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.

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. 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.
* 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.

'''<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]]