SimTX API/Packets/ReceiverStart - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:16:33Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 19:		Line 19:
	message ReceiverStart {		message ReceiverStart {
	reserved 2;		reserved 2;
	~~reserved "station", "adhoc";~~
	SessionSite site = 1;		SessionSite site = 1;
	double center_frequency_hz = 3;		double center_frequency_hz = 3;
Line 61:		Line 60:
	\|}		\|}

	~~Reserved, never reused: field~~ number 2 ~~and the names <code>station</code>, <code>adhoc</code>~~.		Field number 2 is reserved; do not use it.

	== Negotiation ==		== Negotiation ==
Line 71:		Line 70:
	\| Sample rate \|\| Requests up to 2,400,000 are narrowband and clamped to 24,000 to 2,400,000. Requests above are wideband: min(request, 32,000,000).		\| Sample rate \|\| Requests up to 2,400,000 are narrowband and clamped to 24,000 to 2,400,000. Requests above are wideband: min(request, 32,000,000).
	\|-		\|-
	\| Block size \|\| Narrowband: clamped to 1,024 to min(1,200,000, rate × ''T''), where ''T'' is 40 ms on ~~the public clustered deployment and~~ 0.5 s ~~on a stand-alone server~~. Wideband: always 16,384.		\| Block size \|\| Narrowband: clamped to 1,024 to min(1,200,000, rate × ''T''), where ''T'' is a server setting: 40 ms on <code>argon.simtx.net</code>, 0.5 s by default. Wideband: always 16,384.
	\|-		\|-
	\| Bandwidth \|\| max(50, min(request, max(24,000, rate))).		\| Bandwidth \|\| max(50, min(request, max(24,000, rate))).
Line 84:		Line 83:

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>receiver_start_adhoc</code>''' (client to server, 100 bytes):		'''<code>receiver_start_adhoc</code>''' (client to server, 100 bytes):

Clanker: Reconcile with the frozen v25 schema

2026-10-24T16:54:22Z

Reconcile with the frozen v25 schema

← Older revision		Revision as of 16:54, 24 October 2026
Line 19:		Line 19:
	message ReceiverStart {		message ReceiverStart {
	reserved 2;		reserved 2;
			reserved "station", "adhoc";
	SessionSite site = 1;		SessionSite site = 1;
	double center_frequency_hz = 3;		double center_frequency_hz = 3;
Line 60:		Line 61:
	\|}		\|}

	~~Field~~ number 2 ~~is reserved~~ and ~~never reused~~.		Reserved, never reused: field number 2 and the names <code>station</code>, <code>adhoc</code>.

	== Negotiation ==		== Negotiation ==
Line 77:		Line 78:
	== Validation ==		== Validation ==
	A start that cannot be accepted is answered with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>REJECTED</code>, a [[SimTX API/Data types#ErrorCode\|ErrorCode]] and a reason, and the connection closes:		A start that cannot be accepted is answered with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>REJECTED</code>, a [[SimTX API/Data types#ErrorCode\|ErrorCode]] and a reason, and the connection closes:
	* <code>INVALID_REQUEST</code>: no site, a latitude outside ±90°, a longitude outside ±180°, a negative or non-finite frequency or noise figure, a non-positive bandwidth, sample rate or block size, an empty callsign, an unknown antenna type or an invalid NEC deck.		* <code>INVALID_REQUEST</code>: no site, a latitude outside ±90°, a longitude outside ±180°, a negative or non-finite frequency or noise figure, a non-positive bandwidth, sample rate or block size, an empty callsign, an unknown antenna type, an invalid NEC deck, or an <code>aim</code> with a non-finite angle or an elevation outside ±90°.
	* <code>FORBIDDEN</code>: a station-bound start without a ticket for that station, a binding that does not match the ticket, or a ticket bound to a station used with an ad-hoc site.		* <code>FORBIDDEN</code>: a station-bound start without a ticket for that station, a binding that does not match the ticket, or a ticket bound to a station used with an ad-hoc site.
	* <code>STATION_INACTIVE</code>: the station was deleted, or the satellite has reentered.		* <code>STATION_INACTIVE</code>: the station was deleted, or the satellite has reentered.

Clanker: Protocol v25 reference

2026-10-24T16:27:50Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = ReceiverStart
| frame = ClientFrame
| field = 10
| member = receiver_start
| direction = c2s
| session = [[SimTX API/Receiver session|Receiver]]
| roles = <code>ROLE_RECEIVER</code>. Once, right after the hello.
| permission = None for an ad-hoc site. A station-bound site needs a <code>receiver</code> ticket for that station.
| reply = [[SimTX API/Packets/SessionStatus|SessionStatus]], then [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]]
| group = receiver
| file = session.proto
}}
'''ReceiverStart''' starts a [[SimTX API/Receiver session|receiver session]]. It places the receiver, either at one of the account's persistent stations or at an inline ad-hoc site, and states the frequency, bandwidth, sample rate, block size and sample format the client would like. The client sends it once, immediately after an accepted [[SimTX API/Packets/ServerHello|ServerHello]].

== Definition ==
<syntaxhighlight lang="protobuf">
message ReceiverStart {
reserved 2;
SessionSite site = 1;
double center_frequency_hz = 3;
float bandwidth_hz = 4;
int32 sample_rate = 5;
int32 chunk_samples = 6;
optional float noise_figure_db = 7; // default: rig value, else 6 dB
bool timestamped = 8; // IqBlocks carry first-sample timestamps
string solo_transmitter_id = 9; // moderator monitor feature
Tracking tracking = 10;
SampleFormat sample_format = 11;
AntennaAim aim = 12; // start pointing; absent = the antenna's stored heading
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>site</code> || [[SimTX API/Data types#SessionSite|SessionSite]] || Where the receiver is: a [[SimTX API/Data types#StationBinding|StationBinding]] or an [[SimTX API/Data types#AdhocStation|AdhocStation]]. Exactly one member must be set.
|-
| 3 || <code>center_frequency_hz</code> || <code>double</code> || Centre frequency in Hz. Finite and ≥ 0.
|-
| 4 || <code>bandwidth_hz</code> || <code>float</code> || Requested filter bandwidth in Hz. Finite and > 0. Effective value: max(50, min(request, max(24,000, sample rate))).
|-
| 5 || <code>sample_rate</code> || <code>int32</code> || Requested sample rate in complex samples per second, > 0. See [[SimTX API/Receiver session#Negotiation|Negotiation]].
|-
| 6 || <code>chunk_samples</code> || <code>int32</code> || Requested complex samples per [[SimTX API/Packets/IqBlock|IqBlock]], > 0. The server decides; see [[SimTX API/Receiver session#Negotiation|Negotiation]].
|-
| 7 || <code>noise_figure_db</code> || <code>optional float</code> || Receiver noise figure in dB, finite and ≥ 0. Unset: the bound rig's noise figure, otherwise 6 dB. 3 to 8 dB is typical.
|-
| 8 || <code>timestamped</code> || <code>bool</code> || True: every [[SimTX API/Packets/IqBlock|IqBlock]] carries the UTC instant of its first sample. Works with or without an account.
|-
| 9 || <code>solo_transmitter_id</code> || <code>string</code> || Moderator feature. Leave empty. A non-empty value needs <code>monitor.any</code>.
|-
| 10 || <code>tracking</code> || [[SimTX API/Data types#Tracking|Tracking]] || Track a target from the start. See [[SimTX API/Tracking and pointing|Tracking and pointing]].
|-
| 11 || <code>sample_format</code> || [[SimTX API/Data types#SampleFormat|SampleFormat]] || <code>SAMPLE_FORMAT_INT16</code> (0, default) or <code>SAMPLE_FORMAT_INT8</code> (1).
|-
| 12 || <code>aim</code> || [[SimTX API/Data types#AntennaAim|AntennaAim]] || Where the antenna points when the session starts, for example to reconnect already pointed at a manual heading. Unset: the antenna's stored heading. See [[SimTX API/Tracking and pointing#Start pointing|Start pointing]].
|}

Field number 2 is reserved and never reused.

== Negotiation ==
The server adjusts the request and reports the result in [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]]:

{| class="wikitable"
! Value !! Rule
|-
| Sample rate || Requests up to 2,400,000 are narrowband and clamped to 24,000 to 2,400,000. Requests above are wideband: min(request, 32,000,000).
|-
| Block size || Narrowband: clamped to 1,024 to min(1,200,000, rate × ''T''), where ''T'' is 40 ms on the public clustered deployment and 0.5 s on a stand-alone server. Wideband: always 16,384.
|-
| Bandwidth || max(50, min(request, max(24,000, rate))).
|}

== Validation ==
A start that cannot be accepted is answered with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code>, a [[SimTX API/Data types#ErrorCode|ErrorCode]] and a reason, and the connection closes:
* <code>INVALID_REQUEST</code>: no site, a latitude outside ±90°, a longitude outside ±180°, a negative or non-finite frequency or noise figure, a non-positive bandwidth, sample rate or block size, an empty callsign, an unknown antenna type or an invalid NEC deck.
* <code>FORBIDDEN</code>: a station-bound start without a ticket for that station, a binding that does not match the ticket, or a ticket bound to a station used with an ad-hoc site.
* <code>STATION_INACTIVE</code>: the station was deleted, or the satellite has reentered.
* <code>LIMIT_REACHED</code>: server, per-address, account or station receiver limits, or the wideband budget.

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

'''<code>receiver_start_adhoc</code>''' (client to server, 100 bytes):

<syntaxhighlight lang="text">
63 frame length 99
52 61 receiver_start (ReceiverStart), 97 bytes
0A 45 site (SessionSite), 69 bytes
12 43 adhoc (AdhocStation), 67 bytes
0A 06 4E 30 43 41 4C 4C callsign = "N0CALL"
12 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
1A 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
19 00 00 00 00 34 FC 5A 41 center_frequency_hz = 7074000.0
25 00 80 3B 46 bandwidth_hz = 12000
28 80 F7 02 sample_rate = 48000
30 80 20 chunk_samples = 4096
3D 00 00 D0 40 noise_figure_db = 6.5
</syntaxhighlight>

'''<code>receiver_start_station_timestamped</code>''' (client to server, 88 bytes):

<syntaxhighlight lang="text">
57 frame length 87
52 55 receiver_start (ReceiverStart), 85 bytes
0A 26 site (SessionSite), 38 bytes
0A 24 station (StationBinding), 36 bytes
0A 10 11 11 11 11 … station_id = 11111111-2222-4333-8444-555555555555
12 10 11 11 11 11 … antenna_id = 11111111-2222-4333-8444-666666666666
19 00 00 00 08 12 D8 6A 41 center_frequency_hz = 14074000.25
25 00 80 BB 46 bandwidth_hz = 24000
28 80 EE 05 sample_rate = 96000
30 80 40 chunk_samples = 8192
40 01 timestamped = true
52 14 tracking (Tracking), 20 bytes
0A 10 99 99 99 99 … target_station_id = 99999999-8888-4777-8666-555555555555
18 01 doppler_correct = true
</syntaxhighlight>

== See also ==
* [[SimTX API/Receiver session]]
* [[SimTX API/Stations]]
* [[SimTX API/Quick start]]

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