Editing SimTX API/Tracking and pointing

{{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, 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"
! 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.
  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>). A reconnecting client uses it to keep the antenna where the user left it.
* 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.
* 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.

== 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 ==
The rotator of a steerable antenna turns at finite speed. The simulation uses its actual heading, not the commanded one.
* '''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.
* '''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°.
* '''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.
* '''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 as the antenna pattern says.

== 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. Doppler shifts of moving stations are always simulated, whether or not a session corrects for them.

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