SimTX API/Packets/ClientHello

ClientHello

Frame	ClientFrame, field 1
Member	hello
Direction	Client → server
Session	All roles
Roles	All roles. Always the first frame.
Permission	Depends on the role
Answered by	ServerHello
Answers
Defined in	frames.proto

ClientHello opens every game connection. It names the role of the session, carries the game ticket of an authenticated connection, identifies the client software, and states which optional features and protocol revision the client implements. It is the first frame the client sends, immediately after the 8-byte preface.

Definition

message ClientHello {
  Role role = 1;
  AuthKind auth = 2;
  string credential = 3;        // stx_gt1_… game ticket; empty when anonymous
  string client_name = 4;       // e.g. "SimTX Transmitter"
  string client_version = 5;
  repeated string features = 6;  // client feature registry (see the top of this file)
  int32 protocol_revision = 7;    // highest protocol revision this client implements
}

Fields

#	Field	Type	Description
1	role	Role	Session role. Required; ROLE_UNSPECIFIED or an unknown value is refused.
2	auth	AuthKind	AUTH_KIND_ANONYMOUS (0) or AUTH_KIND_GAME_TICKET (1).
3	credential	string	The stx_gt1_ game ticket when auth is GAME_TICKET. Must be empty when anonymous: an anonymous hello with a credential is refused. At most 512 characters. Never an access or personal credential.
4	client_name	string	Name of the client software, for example Example SDR Client. Shown to operators.
5	client_version	string	Version of the client software.
6	features	repeated string	Optional behaviours the client understands, from the feature registry. Servers ignore names they do not know.
7	protocol_revision	int32	Highest protocol revision the client implements. Send 1, the released v25. 0 (unset): the server leaves out the revision-gated behaviours.

Rules

• Send it within 5 seconds of connecting through the public gateway (15 seconds on a direct server connection), together with the preface.
• The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.
• The role cannot change later on the same connection.
• credential carries the ticket when auth is AUTH_KIND_GAME_TICKET. An anonymous hello must leave it empty; one that carries a credential is refused, so a forgotten auth never silently drops a ticket. A ticket is valid for one connection, 60 seconds, one server and one role. See Game tickets.
• Send features: "stations.v1" if the client handles station-bound sessions and BoundStation, and protocol_revision: 1 if it handles SessionStatus UPDATED with update_reason and station snapshots. See Compatibility and versioning.

Roles

Value	Name	Meaning
0	ROLE_UNSPECIFIED	Refused.
1	ROLE_RECEIVER	Receiver: an IQ stream. Anonymous for ad-hoc sites; a receiver ticket for station-bound ones.
2	ROLE_TX_AUDIO	Transmitter whose samples the client streams. Ticket tx-audio, permission game.transmit.
3	ROLE_TX_GENERATED	Transmitter whose source the server generates. Ticket tx-generated, permission game.transmit.
4	ROLE_CONTROL	Control: station list, maps, health, catalog, ephemeris, passes, own-transmitter monitor. Anonymous, or ticket control.
5	ROLE_MODERATION	Moderation. Ticket moderation, permission moderation.manage.

Examples

Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

hello_anonymous_receiver (client to server, 37 bytes):

24                                           frame length 36
0A 22                                        hello (ClientHello), 34 bytes
  08 01                                      role = 1 (ROLE_RECEIVER)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 30 2E 30                    client_version = "25.0.0"
  32 08 70 6F 69 6E 74 69 6E 67              features = "pointing"

hello_ticket_tx_audio (client to server, 50 bytes):

31                                 frame length 49
0A 2F                              hello (ClientHello), 47 bytes
  08 02                            role = 2 (ROLE_TX_AUDIO)
  10 01                            auth = 1 (AUTH_KIND_GAME_TICKET)
  1A 0E 73 74 78 5F 67 74 31 5F …  credential = "stx_gt1_golden"
  22 11 53 69 6D 54 58 20 54 72 …  client_name = "SimTX Transmitter"
  2A 06 32 35 2E 30 2E 30          client_version = "25.0.0"

hello_revision_1_control (client to server, 29 bytes):

1C                                           frame length 28
0A 1A                                        hello (ClientHello), 26 bytes
  08 04                                      role = 4 (ROLE_CONTROL)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 31 2E 30                    client_version = "25.1.0"
  38 01                                      protocol_revision = 1

See also

• SimTX API/Connection and handshake
• SimTX API/Game tickets
• SimTX API/Compatibility and versioning