SimTX API - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:14:09Z

Remove development history and server internals

← Older revision		Revision as of 17:14, 24 October 2026
Line 6:		Line 6:
	* The '''game protocol''', a protobuf protocol over TLS spoken directly with a game server. Receiving, transmitting and control traffic all use it. The current version is '''25'''.		* The '''game protocol''', a protobuf protocol over TLS spoken directly with a game server. Receiving, transmitting and control traffic all use it. The current version is '''25'''.

	This reference ~~documents both as they are deployed. It does not cover the protocol that SimTX servers use among themselves, the propagation model, or administrative~~ and ~~internal endpoints~~. The ~~previous protocol~~ version is ~~archived~~ at [[SimTX API v24]]~~; servers that speak v25 refuse v24 clients~~.		This reference covers what a client sends and receives. The version 24 reference is at [[SimTX API v24]].

	== How the pieces fit ==		== How the pieces fit ==
Line 27:		Line 27:
	! If you want to... !! Read		! If you want to... !! Read
	\|-		\|-
	\| ~~See something working in five minutes~~ \|\| [[SimTX API/Quick start]]		\| Receive IQ with a minimal script \|\| [[SimTX API/Quick start]]
	\|-		\|-
	\| Receive IQ in your own SDR software \|\| [[SimTX API/Connection and handshake]], [[SimTX API/Framing]], then [[SimTX API/Receiver session]]		\| Receive IQ in your own SDR software \|\| [[SimTX API/Connection and handshake]], [[SimTX API/Framing]], then [[SimTX API/Receiver session]]
Line 44:		Line 44:
	\|-		\|-
	\| Understand why a session ended \|\| [[SimTX API/Session status]], [[SimTX API/Limits and errors]]		\| Understand why a session ended \|\| [[SimTX API/Session status]], [[SimTX API/Limits and errors]]
	\|-
	~~\| Port a v24 client \|\| [[SimTX API/Compatibility and versioning#Changes from v24\|Changes from v24]]~~
	\|}		\|}

Line 80:		Line 78:
	== Design notes ==		== Design notes ==
	* '''Protobuf frames.''' Every message is a protobuf message. On the wire each one is a varint length followed by a <code>ClientFrame</code> or <code>ServerFrame</code>, a message with a single <code>oneof</code>. The recommended approach is to generate bindings from the [[SimTX API/Schema\|.proto files]] with <code>protoc</code>. A hand-written codec needs only varints, 32- and 64-bit little-endian values and length-delimited fields; [[SimTX API/Quick start]] shows one in a few dozen lines of Python.		* '''Protobuf frames.''' Every message is a protobuf message. On the wire each one is a varint length followed by a <code>ClientFrame</code> or <code>ServerFrame</code>, a message with a single <code>oneof</code>. The recommended approach is to generate bindings from the [[SimTX API/Schema\|.proto files]] with <code>protoc</code>. A hand-written codec needs only varints, 32- and 64-bit little-endian values and length-delimited fields; [[SimTX API/Quick start]] shows one in a few dozen lines of Python.
	* '''Unknown is not an error.''' A frame whose <code>oneof</code> member a reader does not know, and a field it does not know, are skipped~~. That is how the protocol grows within version 25 without breaking existing clients~~. See [[SimTX API/Compatibility and versioning]].		* '''Unknown is not an error.''' A frame whose <code>oneof</code> member a reader does not know, and a field it does not know, are skipped. See [[SimTX API/Compatibility and versioning]].
	* '''Rejections are never silent.''' A refused hello gets a [[SimTX API/Packets/ServerHello\|ServerHello]] with a status, a refused or ended session a [[SimTX API/Packets/SessionStatus\|SessionStatus]] with an error code and a reason, and a failed request an [[SimTX API/Packets/Error\|Error]] with its <code>request_id</code>.		* '''Rejections are never silent.''' A refused hello gets a [[SimTX API/Packets/ServerHello\|ServerHello]] with a status, a refused or ended session a [[SimTX API/Packets/SessionStatus\|SessionStatus]] with an error code and a reason, and a failed request an [[SimTX API/Packets/Error\|Error]] with its <code>request_id</code>.
	* '''Real time.''' Receivers get samples at the rate of the simulation, and transmitters must send samples at the rate they declared. Neither side waits for the other. A client that falls behind loses data.		* '''Real time.''' Receivers get samples at the rate of the simulation, and transmitters must send samples at the rate they declared. Neither side waits for the other. A client that falls behind loses data.
	* '''~~Physics, not a jukebox~~.''' The IQ a receiver gets ~~is what an antenna at that location would deliver:~~ propagation, fading, Doppler, noise and interference ~~included. A station that cannot be heard is often simply out of range, below the horizon, or on the wrong side of the day-night terminator~~. See [[Propagation Basics]].		* '''Simulated reception.''' The IQ a receiver gets includes the propagation, fading, Doppler shift, noise and interference at its location and antenna. See [[Propagation Basics]].

	== Versioning ==		== Versioning ==
	The game protocol version is the integer in the 8-byte preface~~. Only a breaking change increments it~~; version 25 ~~replaced version 24, and the two are not compatible~~. ~~Within version 25, additive changes that~~ a ~~peer may need to detect increment the~~ '''protocol revision''' ~~carried in both hellos~~, and optional capabilities ~~of a deployment~~ appear in the '''feature registry'''. See [[SimTX API/Compatibility and versioning]].		The game protocol version is the integer in the 8-byte preface; the current version is 25. Both hellos carry a '''protocol revision''', and optional server capabilities appear in the '''feature registry'''. See [[SimTX API/Compatibility and versioning]].

	The account service API is versioned in its path (<code>/api/v1/</code>). New response fields may be added without a version change; clients must ignore fields they do not recognise.		The account service API is versioned in its path (<code>/api/v1/</code>). New response fields may be added without a version change; clients must ignore fields they do not recognise.

Clanker: Protocol v25 reference

2026-10-24T16:33:10Z

Protocol v25 reference

← Older revision		Revision as of 16:33, 24 October 2026
Line 1:		Line 1:
	#~~REDIRECT~~ [[SimTX API ~~v24~~]]		{{SimTX API navigation}}
			The '''SimTX API''' is the set of public interfaces that third-party software uses to work with SimTX. With it, a program can receive the simulated radio spectrum as raw IQ samples, put its own transmitter on the air, manage persistent stations and launch satellites, read the list of stations, request coverage and weather maps, satellite ephemerides and pass predictions, and publish packages to the extension catalog, all without the official SimTX applications.

			The API has two parts:
			* The '''[[SimTX API/Account service\|account service]]''', an HTTPS JSON API at <code>auth.simtx.net</code>. It signs users in, manages stations and satellites, lists game servers and issues single-use game tickets.
			* The '''game protocol''', a protobuf protocol over TLS spoken directly with a game server. Receiving, transmitting and control traffic all use it. The current version is '''25'''.

			This reference documents both as they are deployed. It does not cover the protocol that SimTX servers use among themselves, the propagation model, or administrative and internal endpoints. The previous protocol version is archived at [[SimTX API v24]]; servers that speak v25 refuse v24 clients.

			== How the pieces fit ==
			<syntaxhighlight lang="text">
			HTTPS + JSON TLS + protobuf (v25)
			client ────────────────────────▶ auth.simtx.net client ────────────────────────▶ game server
			1. device login → credentials 5. preface + ClientHello (role, ticket)
			2. GET /api/v1/stations → your stations 6. ReceiverStart or TransmitterStart
			3. GET /api/v1/servers → host and port 7. IQ in, samples out, or control traffic
			4. POST /api/v1/game-tickets → one-shot ticket
			</syntaxhighlight>

			* '''Receiving needs no account.''' An ad-hoc receiver, which brings its own callsign, position and antenna, and the control role accept anonymous connections. Such a client skips steps 1 to 4 and needs only a host and port.
			* '''Transmitting needs an account and a station.''' A transmitter is bound to one of the account's persistent [[SimTX API/Stations\|stations]]. It needs the <code>game.transmit</code> [[SimTX API/Permissions\|permission]] and a fresh [[SimTX API/Game tickets\|game ticket]] for every connection.
			* '''Station-bound reception''' works on the account's own stations and on any PUBLIC station of another account, including [[SimTX API/Satellites\|satellites]].
			* '''One TCP connection is one session.''' A client that wants two receivers, or a receiver and a transmitter, opens two connections.

			== Where to start ==
			{\| class="wikitable"
			! If you want to... !! Read
			\|-
			\| See something working in five minutes \|\| [[SimTX API/Quick start]]
			\|-
			\| Receive IQ in your own SDR software \|\| [[SimTX API/Connection and handshake]], [[SimTX API/Framing]], then [[SimTX API/Receiver session]]
			\|-
			\| Transmit from your own software \|\| [[SimTX API/Device login]], [[SimTX API/Stations]], [[SimTX API/Game tickets]], then [[SimTX API/Transmitter session]]
			\|-
			\| Create stations or launch a satellite \|\| [[SimTX API/Station endpoints]], [[SimTX API/Satellites]]
			\|-
			\| Track a satellite and correct Doppler \|\| [[SimTX API/Tracking and pointing]]
			\|-
			\| Show a station list or map \|\| [[SimTX API/Control session]]
			\|-
			\| Publish extensions from a script \|\| [[SimTX API/Extension catalog protocol]]
			\|-
			\| Look up one message \|\| [[SimTX API/Packet list]]
			\|-
			\| Understand why a session ended \|\| [[SimTX API/Session status]], [[SimTX API/Limits and errors]]
			\|-
			\| Port a v24 client \|\| [[SimTX API/Compatibility and versioning#Changes from v24\|Changes from v24]]
			\|}

			== Reference pages ==
			=== Account service ===
			* [[SimTX API/Account service]]: base URL, authentication, credential formats, errors and rate limits.
			* [[SimTX API/Device login]]: signing a user in from a desktop or command-line program.
			* [[SimTX API/Server directory]]: discovering game servers and their features.
			* [[SimTX API/Station endpoints]]: creating and editing stations, launching and deorbiting satellites.
			* [[SimTX API/Game tickets]]: exchanging a credential for a one-shot game server ticket, optionally bound to a station.
			* [[SimTX API/Permissions]]: scopes, permission identifiers and numeric capabilities.
			* [[SimTX API/Public endpoints]]: status, public satellites, profiles, releases and network test.

			=== Game protocol ===
			* [[SimTX API/Connection and handshake]]: TLS, the preface, the hello, roles and hello results.
			* [[SimTX API/Framing]]: length-delimited frames, size limits and skipping unknown frames.
			* [[SimTX API/Data types]]: protobuf types, conventions and shared messages.
			* [[SimTX API/Session status]]: how receiver and transmitter sessions are bound, updated, refused and ended.
			* [[SimTX API/Receiver session]]: requesting a receiver and decoding IQ.
			* [[SimTX API/Transmitter session]]: admission, streaming samples, live updates and telemetry.
			* [[SimTX API/Control session]]: station list, banners, health, coverage and weather maps, ephemerides, passes, monitoring.
			* [[SimTX API/Extension catalog protocol]]: listing, fetching, uploading and deleting catalog entries.
			* [[SimTX API/Moderation session]]: moderator tools. Not usable without moderator permission.
			* [[SimTX API/Limits and errors]]: the error model, session limits, rate limits and timeouts.
			* [[SimTX API/Compatibility and versioning]]: protocol revisions, the feature registry and what may change.
			* [[SimTX API/Packet list]]: every frame member in both directions.
			* [[SimTX API/Schema]]: the <code>.proto</code> files.

			=== Stations and satellites ===
			* [[SimTX API/Stations]]: persistent stations, station-bound and ad-hoc sessions, what the station dictates.
			* [[SimTX API/Satellites]]: user-launched satellites, the orbit model, ephemerides, passes and deorbiting.
			* [[SimTX API/Tracking and pointing]]: steerable antennas, rotators and Doppler correction.

			== Design notes ==
			* '''Protobuf frames.''' Every message is a protobuf message. On the wire each one is a varint length followed by a <code>ClientFrame</code> or <code>ServerFrame</code>, a message with a single <code>oneof</code>. The recommended approach is to generate bindings from the [[SimTX API/Schema\|.proto files]] with <code>protoc</code>. A hand-written codec needs only varints, 32- and 64-bit little-endian values and length-delimited fields; [[SimTX API/Quick start]] shows one in a few dozen lines of Python.
			* '''Unknown is not an error.''' A frame whose <code>oneof</code> member a reader does not know, and a field it does not know, are skipped. That is how the protocol grows within version 25 without breaking existing clients. See [[SimTX API/Compatibility and versioning]].
			* '''Rejections are never silent.''' A refused hello gets a [[SimTX API/Packets/ServerHello\|ServerHello]] with a status, a refused or ended session a [[SimTX API/Packets/SessionStatus\|SessionStatus]] with an error code and a reason, and a failed request an [[SimTX API/Packets/Error\|Error]] with its <code>request_id</code>.
			* '''Real time.''' Receivers get samples at the rate of the simulation, and transmitters must send samples at the rate they declared. Neither side waits for the other. A client that falls behind loses data.
			* '''Physics, not a jukebox.''' The IQ a receiver gets is what an antenna at that location would deliver: propagation, fading, Doppler, noise and interference included. A station that cannot be heard is often simply out of range, below the horizon, or on the wrong side of the day-night terminator. See [[Propagation Basics]].

			== Versioning ==
			The game protocol version is the integer in the 8-byte preface. Only a breaking change increments it; version 25 replaced version 24, and the two are not compatible. Within version 25, additive changes that a peer may need to detect increment the '''protocol revision''' carried in both hellos, and optional capabilities of a deployment appear in the '''feature registry'''. See [[SimTX API/Compatibility and versioning]].

			The account service API is versioned in its path (<code>/api/v1/</code>). New response fields may be added without a version change; clients must ignore fields they do not recognise.

			== Terms of use ==
			SimTX is a shared simulation with other people listening. Software built on this API is subject to the same rules as the official applications. Keep request rates within the documented limits, identify your software honestly in <code>clientName</code> during [[SimTX API/Device login\|device login]] and in <code>ClientHello.client_name</code>, and do not use the API to disrupt other users.

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

Clanker: Clanker moved page SimTX API to SimTX API v24: Archive the v24 protocol reference

2026-10-24T16:11:21Z

Clanker moved page SimTX API to SimTX API v24: Archive the v24 protocol reference

New page

#REDIRECT [[SimTX API v24]]