Editing SimTX API/Stations

{{SimTX API navigation}}
A '''station''' is a persistent object owned by an account: a ground station at a fixed place, or a satellite in orbit. Stations are created and edited through the [[SimTX API/Station endpoints|account service]] and live across servers and reconnects. Receiver and transmitter sessions attach to them. This page describes the model and how a session binds to a station on the wire.

== Model ==
<syntaxhighlight lang="text">
Station  (persistent, owned by an account, global across servers)
├─ id (UUID, never changes), name, callsign, kind GROUND | SATELLITE,
│  visibility PUBLIC | UNLISTED, revision
├─ limits      maxSessions, maxTransmitters, maxReceivers
├─ placement   GROUND: latitude, longitude, altitude (editable at any time)
│              SATELLITE: orbit and attitude (sealed at launch)
├─ antennas    1 to 8 (satellites: 1 to 4); each with its own id and revision
└─ rigs        0 to 8 saved radio profiles; each with its own id and revision:
               PA cap, receiver noise figure, transmitter imperfection knobs
Session = one TCP connection = a station + an antenna (+ a rig) + per-session radio settings
</syntaxhighlight>

* Many transmitter and receiver sessions can attach to one station at once, up to its limits.
* On a satellite, a transmitter session is a downlink transmitter at the satellite's position, and a receiver session hears the uplink. See [[SimTX API/Satellites]].
* The revision of the station, and of each antenna and rig, increases with every edit.

== Station-bound and ad-hoc sessions ==
Every session start carries a [[SimTX API/Data types#SessionSite|SessionSite]]: either a [[SimTX API/Data types#StationBinding|StationBinding]] to a persistent station, or an inline [[SimTX API/Data types#AdhocStation|AdhocStation]].

{| class="wikitable"
! !! Ad hoc (<code>AdhocStation</code>) !! Station-bound (<code>StationBinding</code>)
|-
| Who || Anyone; receivers anonymously || Signed-in accounts
|-
| Ticket || None for receivers || A ticket minted for the same station, antenna and rig
|-
| Callsign, placement, antenna || Inline in the start || From the station
|-
| Receive || Always || Your stations, or anyone's PUBLIC station
|-
| Transmit || Refused with <code>STATION_REQUIRED</code>, unless <code>tx.adhoc</code> or server policy || Your stations only
|-
| Satellites || No || Yes
|-
| Rig and PA cap || Generic HF preset; the account's <code>tx.pa_limit</code> || The bound rig
|-
| Pointing and tracking || No steerable antenna || Full; see [[SimTX API/Tracking and pointing]]
|-
| In the station list || An entry of kind <code>ADHOC</code> with one session || Under the station
|}

== What the station dictates ==
A station-bound session takes from the station:
* the callsign and the placement: a fixed ground location, or the satellite's orbit and attitude;
* the antenna's geometry, mount and default pointing;
* from the bound rig: the PA cap, the receiver noise figure, and the transmitter imperfection knobs other than drive, compression, frequency offset and AM index.

The session still chooses the modulation, frequency, power up to the cap, source, sample rate, gain, bandwidth, low cut, tone and duty cycle, plus drive, compression, frequency offset and AM index, which default to the rig's values. Without a rig the generic HF preset is used and the cap is the account's <code>tx.pa_limit</code>.

The server reports what it resolved in the [[SimTX API/Data types#BoundStation|BoundStation]] of [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code>. Show the user what the station dictates from that message.

== Binding a session ==
# '''Mint a ticket''' with <code>POST /api/v1/game-tickets</code>, giving <code>stationId</code> and optionally <code>antennaId</code> and <code>rigId</code>. Without <code>antennaId</code> the station's first antenna is bound; without <code>rigId</code> its first rig, or none when it has no rigs. The response's <code>station</code> object echoes what was bound and the access level. See [[SimTX API/Game tickets]].
# '''Send the hello''' with <code>auth = AUTH_KIND_GAME_TICKET</code> and the ticket.
# '''Send the start''' with <code>site.station</code> set to a [[SimTX API/Data types#StationBinding|StationBinding]]. Copy the ids from the ticket response; an empty <code>antenna_id</code> or <code>rig_id</code> selects the station's first antenna or rig, or the one the ticket was minted for.

The server checks the binding against the ticket. The start is refused with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code>:
* <code>FORBIDDEN</code> when the station, antenna or rig differs from the ticket's, when a station-bound start arrives without a ticket for that station, when a ticket bound to a station is used with an ad-hoc site, or when a transmitter is started on a station the account does not own;
* <code>STATION_INACTIVE</code> when the station was deleted or the satellite has reentered.

Station tickets are issued only for servers that advertise the feature <code>stations.v1</code>; see [[SimTX API/Server directory]].

== Access ==
{| class="wikitable"
! Access !! Who !! Allows
|-
| <code>OWNER</code> || The account that owns the station || Transmitting and receiving.
|-
| <code>LISTENER</code> || Any other signed-in account, on a PUBLIC station || Receiving only.
|}

Transmitting through someone else's station is refused, and so is receiving through someone else's UNLISTED station; the account service refuses those tickets with <code>403 station_forbidden</code>. The access level is in the ticket response.

== Visibility ==
* '''PUBLIC''' stations appear in the [[SimTX API/Packets/StationList|station list]] with their id, owner and placement, and any signed-in account may receive through them. PUBLIC satellites also appear in the public satellite catalog (<code>GET /api/v1/satellites</code>) and in every station list, even with nobody attached.
* '''UNLISTED''' is the private default. Other accounts see an UNLISTED station only as an ad-hoc-style entry with the callsign of its live sessions; its id and placement are hidden.

Clients should default new ground stations to UNLISTED.

== Ad-hoc transmitters ==
An ad-hoc transmitter, with an inline callsign, position and antenna, is accepted only for principals that hold the <code>tx.adhoc</code> permission (service integrations) or when the server's ad-hoc policy allows it. The default policy refuses it with <code>ERROR_CODE_STATION_REQUIRED</code>. Third-party clients should transmit through a station. Ad-hoc receivers are supported without restriction.

== Edits while sessions run ==
A session keeps the snapshot of the station it was bound with. When the owner edits the station, the bound antenna or the bound rig:
* clients whose hello announced <code>protocol_revision</code> ≥ 1 receive [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> with <code>update_reason = UPDATE_REASON_STATION_EDIT</code> and the new station snapshot, and the session continues on the new values;
* other clients get <code>ENDED</code> and must reconnect.

Deleting the station, removing the bound antenna or rig, or revoking access always ends the session. See [[SimTX API/Session status]].

== Limits ==
* '''Per station:''' the owner sets <code>maxSessions</code>, <code>maxTransmitters</code> and <code>maxReceivers</code>, each clamped by the owner's <code>game.station_sessions.N</code> capability. A start over a station limit is refused with <code>LIMIT_REACHED</code>. The owner is not counted against the station's receiver limit.
* '''Per account:''' the number of stations and satellites an account may own is capped by <code>game.owned_stations.N</code> and <code>game.owned_satellites.N</code>. See [[SimTX API/Permissions#Numeric capabilities|Numeric capabilities]].
* The usual server, address and account session limits apply as well. See [[SimTX API/Limits and errors]].

== See also ==
* [[SimTX API/Station endpoints]]: creating and editing stations.
* [[SimTX API/Satellites]]
* [[SimTX API/Tracking and pointing]]

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