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

• 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). 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.
• 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 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 pointing of SessionStatus BOUND reports the pointing in effect. While a rotator follows a target, the server also reports in tracking.since_epoch_seconds and since_nanos when it began slewing towards it, which together with the slew rate gives the rotator's position.

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

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 AZEL, 3 °/s in azimuth for AZ.
• 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 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, as it does with real tracking software. Doppler shifts of moving stations are always simulated, whether or not a session corrects for them.