SimTX API/Tracking and pointing

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 station-bound session and a server that advertises the feature pointing.

Mounts

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

Value	Name	Meaning
0	ANTENNA_MOUNT_FIXED	No rotator. The default.
1	ANTENNA_MOUNT_AZ	Azimuth rotator. Elevation stays at the pointing's elevation.
2	ANTENNA_MOUNT_AZEL	Azimuth and elevation rotator.

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

Default pointing

A steerable antenna stores a default AntennaPointing: a mode, an azimuth and elevation, a target station for TRACK mode, and rotator slew rates. A session bound to the antenna starts with that pointing, unless its start carries an aim; SessionStatus BOUND reports it in station.antenna.pointing, and the pointing in effect in pointing.

Value	Name	Meaning
0	POINTING_MODE_FIXED	Hold the given azimuth and elevation. The default.
1	POINTING_MODE_TRACK	Follow a target station.

Tracking

Tracking says what a session follows:

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;
}

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

Set tracking in ReceiverStart or 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 aim, an AntennaAim (ReceiverStart.aim, TransmitterStart.aim). A reconnecting client uses it to keep the antenna where the user left it.

• Unset: the antenna starts at its stored heading.
• FIXED mount: ignored. AZ mount: the elevation is ignored.
• With tracking.point_antenna: 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 SessionStatus REJECTED, INVALID_REQUEST.

The pointing of SessionStatus BOUND reports the pointing in effect.

Changing pointing on air

AntennaPointingUpdate changes the pointing or tracking of a running session without reconnecting:

• mode = POINTING_MODE_FIXED with azimuth_deg and elevation_deg points the antenna at a fixed direction. An AZ mount keeps its elevation.
• mode = POINTING_MODE_TRACK with tracking follows a target.

The server confirms with SessionStatus UPDATED, update_reason = UPDATE_REASON_POINTING, the request's request_id, and the new pointing and tracking. A session that is ad hoc or whose antenna has a FIXED mount gets Error INVALID_REQUEST (Antenna pointing needs a station-bound session with a steerable mount) with the same request_id, 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 UPDATED with UPDATE_REASON_TRACKING.

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 AZ mount; 6 °/s in azimuth and 4 °/s in elevation for an AZEL 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 AntennaPointingUpdate with POINTING_MODE_FIXED turns the rotator from wherever it is at that moment: parked, mid-turn or mid-track. SessionStatus UPDATED reports the commanded heading in pointing 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 point_antenna, or switches to POINTING_MODE_TRACK 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 TRACK request are ignored.
• Slew start: while a rotator follows a target, tracking.since_epoch_seconds and since_nanos in SessionStatus BOUND and UPDATED 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 doppler_correct, 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 doppler_correct, 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.