SimTX API/Tracking and pointing - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:14:28Z

Remove development history and server internals

← Older revision		Revision as of 17:14, 24 October 2026
Line 38:		Line 38:
	// Simulation time at which the rotator began slewing toward this target (point_antenna only; both 0 =		// Simulation time at which the rotator began slewing toward this target (point_antenna only; both 0 =
	// not known). Servers set it in SessionStatus; with the antenna's slew rate it gives the rotator position.		// not known). Servers set it in SessionStatus; with the antenna's slew rate it gives the rotator position.
	// Ignored in a client's start or AntennaPointingUpdate~~, except in a start that a SimTX gateway replays~~		// Ignored in a client's start or AntennaPointingUpdate.
	~~// when it moves a session to another server, so the moved session keeps its slew~~.
	int64 since_epoch_seconds = 4;		int64 since_epoch_seconds = 4;
	int32 since_nanos = 5;		int32 since_nanos = 5;
Line 52:		Line 51:

	== Start pointing ==		== Start pointing ==
	A start can say where the antenna points at the beginning of the session with <code>aim</code>, an [[SimTX API/Data types#AntennaAim\|AntennaAim]] (<code>ReceiverStart.aim</code>, <code>TransmitterStart.aim</code>). ~~It is meant for a~~ client ~~that reconnects and wants~~ the antenna ~~to stay~~ where the user left it~~, instead of swinging back from the stored heading~~.		A start can say where the antenna points at the beginning of the session with <code>aim</code>, an [[SimTX API/Data types#AntennaAim\|AntennaAim]] (<code>ReceiverStart.aim</code>, <code>TransmitterStart.aim</code>). A reconnecting client uses it to keep the antenna where the user left it.
	* Unset: the antenna starts at its stored heading.		* Unset: the antenna starts at its stored heading.
	* <code>FIXED</code> mount: ignored. <code>AZ</code> mount: the elevation is ignored.		* <code>FIXED</code> mount: ignored. <code>AZ</code> mount: the elevation is ignored.
Line 87:		Line 86:
	* '''Transmitters:''' with <code>doppler_correct</code>, the carrier is pre-corrected for the uplink Doppler at emission time, so the signal arrives on frequency at the satellite.		* '''Transmitters:''' with <code>doppler_correct</code>, the carrier is pre-corrected for the uplink Doppler at emission time, so the signal arrives on frequency at the satellite.

	The correction is geometric. The small ionospheric Doppler (below about 2 Hz at 70 cm) remains~~, as it does with real tracking software~~. Doppler shifts of moving stations are always simulated, whether or not a session corrects for them.		The correction is geometric. The small ionospheric Doppler (below about 2 Hz at 70 cm) remains. Doppler shifts of moving stations are always simulated, whether or not a session corrects for them.

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

Clanker: Reconcile with the frozen v25 schema

2026-10-24T16:52:24Z

Reconcile with the frozen v25 schema

← Older revision		Revision as of 16:52, 24 October 2026
Line 18:		Line 18:

	== Default pointing ==		== Default pointing ==
	A steerable antenna stores a default [[SimTX API/Data types#AntennaPointing\|AntennaPointing]]: a mode, an azimuth and elevation, a target station for <code>TRACK</code> mode, and rotator slew rates. A session bound to the antenna starts with that pointing; [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>BOUND</code> reports it in <code>station.antenna.pointing</code>, and the pointing in effect in <code>pointing</code>.		A steerable antenna stores a default [[SimTX API/Data types#AntennaPointing\|AntennaPointing]]: a mode, an azimuth and elevation, a target station for <code>TRACK</code> mode, and rotator slew rates. A session bound to the antenna starts with that pointing, unless its start carries an <code>aim</code>; [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>BOUND</code> reports it in <code>station.antenna.pointing</code>, and the pointing in effect in <code>pointing</code>.

	{\| class="wikitable"		{\| class="wikitable"
Line 52:		Line 52:

	== Start pointing ==		== Start pointing ==
	A start can say where the antenna points at the beginning of the session with <code>aim</code>, an [[SimTX API/Data types#AntennaAim\|AntennaAim]] (<code>ReceiverStart.aim</code>, <code>TransmitterStart.aim</code>). It is meant for a client that reconnects and wants the antenna to stay where the user left it, instead of ~~returning to~~ the stored heading.		A start can say where the antenna points at the beginning of the session with <code>aim</code>, an [[SimTX API/Data types#AntennaAim\|AntennaAim]] (<code>ReceiverStart.aim</code>, <code>TransmitterStart.aim</code>). It is meant for a client that reconnects and wants the antenna to stay where the user left it, instead of swinging back from the stored heading.
	* Unset: the antenna starts at its stored heading.		* Unset: the antenna starts at its stored heading.
	* <code>FIXED</code> mount: ignored. <code>AZ</code> mount: the elevation is ignored.		* <code>FIXED</code> mount: ignored. <code>AZ</code> mount: the elevation is ignored.
	* With <code>tracking.point_antenna</code>: the aim is the rotator's position at the start, and the rotator slews from there towards the target ~~at its slew rate~~.		* With <code>tracking.point_antenna</code>: the aim is the rotator's position at the start, and the rotator slews from there towards the target.
	* The values are checked like an AntennaPointingUpdate: finite numbers, elevation −90 to 90; the azimuth is normalised to 0 to 360.		* Otherwise the session binds already pointed there, without a turn.
			* The values are checked like an AntennaPointingUpdate: finite numbers, elevation −90 to 90; the azimuth is normalised to 0 to 360. Out-of-range values refuse the start with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>REJECTED</code>, <code>INVALID_REQUEST</code>.

	The <code>pointing</code> of [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>BOUND</code> reports the pointing in effect. While a rotator follows a target, the server also reports in <code>tracking.since_epoch_seconds</code> and <code>since_nanos</code> when it began slewing towards it, which together with the slew rate gives the rotator's position.		The <code>pointing</code> of [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>BOUND</code> reports the pointing in effect.

	== Changing pointing on air ==		== Changing pointing on air ==
Line 70:		Line 71:

	== Rotators ==		== Rotators ==
	~~Rotators move~~ at finite speed, ~~so a tracking antenna lags a fast satellite:~~		The rotator of a steerable antenna turns at finite speed. The simulation uses its actual heading, not the commanded one.
	* '''~~Slew rates~~''' come from the antenna's pointing. 0 selects the defaults: ~~6 °/s in azimuth and 4~~ °/s ~~in elevation~~ for <code>~~AZEL~~</code>~~, 3~~ °/s in azimuth for <code>AZ</code>.		* '''Rates''' come from the antenna's pointing, each axis on its own. 0 selects the defaults: 3 °/s for an <code>AZ</code> mount; 6 °/s in azimuth and 4 °/s in elevation for an <code>AZEL</code> mount.
	* '''~~Range~~:''' azimuth 0 to 360° with the ~~end~~ stop at north~~; elevation~~ 0 to 90°~~, or 0 to 180° on mounts that can flip over the zenith~~.		* '''Stops:''' the azimuth stays within 0 to 360°, with the stop at north. A turn never crosses north, so a turn from 350° to 10° goes the long way round. Elevation is 0 to 90°.
	* '''~~Trajectory~~:''' ~~for each pass~~ the rotator ~~starts~~ from ~~its park position (~~the pointing'~~s azimuth and elevation) 60 seconds before acquisition~~, or ~~when tracking was switched on~~, and ~~steps every 0.25 s towards~~ the target~~'s true direction~~ within its rate limits. The azimuth ~~unwrap~~, and ~~whether~~ to ~~flip~~, ~~are chosen for~~ the ~~whole pass in advance~~, so the rotator ~~never runs into its end stop mid-pass~~.		* '''Fixed headings:''' an [[SimTX API/Packets/AntennaPointingUpdate\|AntennaPointingUpdate]] with <code>POINTING_MODE_FIXED</code> turns the rotator from wherever it is at that moment: parked, mid-turn or mid-track. [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>UPDATED</code> reports the commanded heading in <code>pointing</code> at once; a client that draws the rotator animates the turn from the rates. Repeating the current heading does not restart the turn.
	* '''Lag:''' on a 500 km overhead pass a 6 °/s rotator falls up to 16° behind just after closest approach ~~(32° at~~ 3 °/s~~); a pass with a 30° maximum elevation is tracked~~ to ~~within 0.01°~~.		* '''Tracking:''' a session that starts with <code>point_antenna</code>, or switches to <code>POINTING_MODE_TRACK</code> or to a new target, starts slewing at that moment from where the rotator is, and then follows the target within its rate limits. The azimuth and elevation of a <code>TRACK</code> request are ignored.
			* '''Slew start:''' while a rotator follows a target, <code>tracking.since_epoch_seconds</code> and <code>since_nanos</code> in SessionStatus <code>BOUND</code> and <code>UPDATED</code> give the simulation time at which it began slewing towards the target. With the rates they give the rotator's position for display. Clients leave these fields unset in their own requests; servers ignore them there.
			* '''Paths:''' the actual heading applies to every propagation path: HF skywave and groundwave, VHF and UHF terrestrial paths, Earth-space links and the sky-noise beam. While the rotator turns, the server re-plans the link about once a second until the rotator arrives.
			* '''Lag:''' a tracking rotator lags a fast satellite. On a 500 km overhead pass a 6 °/s rotator falls up to 16° behind just after closest approach, and a 3 °/s rotator up to 32°.

	The pointing error reduces the antenna gain towards the target ~~exactly~~ as the antenna pattern says~~, which is what a real station experiences~~.		The pointing error reduces the antenna gain towards the target as the antenna pattern says.

	== Doppler correction ==		== Doppler correction ==

Clanker: Protocol v25 reference

2026-10-24T16:26:39Z

Protocol v25 reference

New page

{{SimTX API navigation}}
Station antennas can be steerable: an antenna on an azimuth or azimuth-elevation rotator can be pointed at a fixed direction or made to follow a moving target, usually a satellite. Independently, a session can correct its frequency for the target's Doppler shift. This page describes both. They need a [[SimTX API/Stations|station-bound]] session and a server that advertises the feature <code>pointing</code>.

== Mounts ==
Each antenna of a station has a mount, stored with the antenna in the account service:

{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ANTENNA_MOUNT_FIXED</code> || No rotator. The default.
|-
| 1 || <code>ANTENNA_MOUNT_AZ</code> || Azimuth rotator. Elevation stays at the pointing's elevation.
|-
| 2 || <code>ANTENNA_MOUNT_AZEL</code> || Azimuth and elevation rotator.
|}

A <code>FIXED</code> antenna radiates where its type and <code>azimuth_deg</code> put it, over the ground, as in [[Antenna System]]. Steerable antennas (<code>AZ</code>, <code>AZEL</code>) are solved in free space, rotated to their current pointing, and given a ground reflection for their height. The circularly polarised types <code>CROSSED_YAGI</code> and <code>HELIX</code> are meant for steerable ground stations.

== Default pointing ==
A steerable antenna stores a default [[SimTX API/Data types#AntennaPointing|AntennaPointing]]: a mode, an azimuth and elevation, a target station for <code>TRACK</code> mode, and rotator slew rates. A session bound to the antenna starts with that pointing; [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code> reports it in <code>station.antenna.pointing</code>, and the pointing in effect in <code>pointing</code>.

{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>POINTING_MODE_FIXED</code> || Hold the given azimuth and elevation. The default.
|-
| 1 || <code>POINTING_MODE_TRACK</code> || Follow a target station.
|}

== Tracking ==
[[SimTX API/Data types#Tracking|Tracking]] says what a session follows:

<syntaxhighlight lang="protobuf">
message Tracking {
bytes target_station_id = 1;
bool point_antenna = 2; // drive the antenna's rotator toward the target
bool doppler_correct = 3; // RX: shift tuning by the target's Doppler; TX: pre-correct so it arrives on frequency
// Simulation time at which the rotator began slewing toward this target (point_antenna only; both 0 =
// not known). Servers set it in SessionStatus; with the antenna's slew rate it gives the rotator position.
// Ignored in a client's start or AntennaPointingUpdate, except in a start that a SimTX gateway replays
// when it moves a session to another server, so the moved session keeps its slew.
int64 since_epoch_seconds = 4;
int32 since_nanos = 5;
}
</syntaxhighlight>

* <code>target_station_id</code>: the station to follow, usually a satellite from the satellite catalog.
* <code>point_antenna</code>: drive the antenna's rotator towards the target. Needs an <code>AZ</code> or <code>AZEL</code> mount.
* <code>doppler_correct</code>: correct the session's frequency for the target's Doppler shift.

Set <code>tracking</code> in [[SimTX API/Packets/ReceiverStart|ReceiverStart]] or [[SimTX API/Packets/TransmitterStart|TransmitterStart]] to follow a target from the start.

== Start pointing ==
A start can say where the antenna points at the beginning of the session with <code>aim</code>, an [[SimTX API/Data types#AntennaAim|AntennaAim]] (<code>ReceiverStart.aim</code>, <code>TransmitterStart.aim</code>). It is meant for a client that reconnects and wants the antenna to stay where the user left it, instead of returning to the stored heading.
* Unset: the antenna starts at its stored heading.
* <code>FIXED</code> mount: ignored. <code>AZ</code> mount: the elevation is ignored.
* With <code>tracking.point_antenna</code>: the aim is the rotator's position at the start, and the rotator slews from there towards the target at its slew rate.
* The values are checked like an AntennaPointingUpdate: finite numbers, elevation −90 to 90; the azimuth is normalised to 0 to 360.

The <code>pointing</code> of [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code> reports the pointing in effect. While a rotator follows a target, the server also reports in <code>tracking.since_epoch_seconds</code> and <code>since_nanos</code> when it began slewing towards it, which together with the slew rate gives the rotator's position.

== Changing pointing on air ==
[[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] changes the pointing or tracking of a running session without reconnecting:
* <code>mode = POINTING_MODE_FIXED</code> with <code>azimuth_deg</code> and <code>elevation_deg</code> points the antenna at a fixed direction. An <code>AZ</code> mount keeps its elevation.
* <code>mode = POINTING_MODE_TRACK</code> with <code>tracking</code> follows a target.

The server confirms with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code>, <code>update_reason = UPDATE_REASON_POINTING</code>, the request's <code>request_id</code>, and the new <code>pointing</code> and <code>tracking</code>. A session that is ad hoc or whose antenna has a <code>FIXED</code> mount gets [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code> (''Antenna pointing needs a station-bound session with a steerable mount'') with the same <code>request_id</code>, and continues unchanged.

The update applies to this session only; the antenna's stored default is not changed. When a tracked target disappears, for example because a satellite reentered, the server changes the tracking itself and sends <code>UPDATED</code> with <code>UPDATE_REASON_TRACKING</code>.

== Rotators ==
Rotators move at finite speed, so a tracking antenna lags a fast satellite:
* '''Slew rates''' come from the antenna's pointing. 0 selects the defaults: 6 °/s in azimuth and 4 °/s in elevation for <code>AZEL</code>, 3 °/s in azimuth for <code>AZ</code>.
* '''Range:''' azimuth 0 to 360° with the end stop at north; elevation 0 to 90°, or 0 to 180° on mounts that can flip over the zenith.
* '''Trajectory:''' for each pass the rotator starts from its park position (the pointing's azimuth and elevation) 60 seconds before acquisition, or when tracking was switched on, and steps every 0.25 s towards the target's true direction within its rate limits. The azimuth unwrap, and whether to flip, are chosen for the whole pass in advance, so the rotator never runs into its end stop mid-pass.
* '''Lag:''' on a 500 km overhead pass a 6 °/s rotator falls up to 16° behind just after closest approach (32° at 3 °/s); a pass with a 30° maximum elevation is tracked to within 0.01°.

The pointing error reduces the antenna gain towards the target exactly as the antenna pattern says, which is what a real station experiences.

== Doppler correction ==
A satellite's signal is shifted by up to a few kilohertz at VHF and UHF during a pass, depending on its speed towards or away from the station.
* '''Receivers:''' with <code>doppler_correct</code>, the receiver's tuning is shifted by the target's downlink Doppler at the receiver's centre frequency, so the satellite's signal stays at a fixed offset in the IQ passband.
* '''Transmitters:''' with <code>doppler_correct</code>, the carrier is pre-corrected for the uplink Doppler at emission time, so the signal arrives on frequency at the satellite.

The correction is geometric. The small ionospheric Doppler (below about 2 Hz at 70 cm) remains, as it does with real tracking software. Doppler shifts of moving stations are always simulated, whether or not a session corrects for them.

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