SimTX API/Stations

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

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

• 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 SessionSite: either a StationBinding to a persistent station, or an inline AdhocStation.

	Ad hoc (AdhocStation)	Station-bound (StationBinding)
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 STATION_REQUIRED, unless tx.adhoc or server policy	Your stations only
Satellites	No	Yes
Rig and PA cap	Generic HF preset; the account's tx.pa_limit	The bound rig
Pointing and tracking	No steerable antenna	Full; see SimTX API/Tracking and pointing
In the station list	An entry of kind ADHOC 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 tx.pa_limit.

The server reports what it resolved in the BoundStation of SessionStatus BOUND. Show the user what the station dictates from that message.

Binding a session

1. Mint a ticket with POST /api/v1/game-tickets, giving stationId and optionally antennaId and rigId. Without antennaId the station's first antenna is bound; without rigId its first rig, or none when it has no rigs. The response's station object echoes what was bound and the access level. See SimTX API/Game tickets.
2. Send the hello with auth = AUTH_KIND_GAME_TICKET and the ticket.
3. Send the start with site.station set to a StationBinding. Copy the ids from the ticket response; an empty antenna_id or rig_id 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 SessionStatus REJECTED:

• FORBIDDEN 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;
• STATION_INACTIVE when the station was deleted or the satellite has reentered.

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

Access

Access	Who	Allows
OWNER	The account that owns the station	Transmitting and receiving.
LISTENER	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 403 station_forbidden. The access level is in the ticket response.

Visibility

• PUBLIC stations appear in the 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 (GET /api/v1/satellites) 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 tx.adhoc permission (service integrations) or when the server's ad-hoc policy allows it. The default policy refuses it with ERROR_CODE_STATION_REQUIRED. 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 protocol_revision ≥ 1 receive SessionStatus UPDATED with update_reason = UPDATE_REASON_STATION_EDIT and the new station snapshot, and the session continues on the new values;
• other clients get ENDED 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 maxSessions, maxTransmitters and maxReceivers, each clamped by the owner's game.station_sessions.N capability. A start over a station limit is refused with LIMIT_REACHED. 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 game.owned_stations.N and game.owned_satellites.N. See 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