Editing SimTX API/Packets/AntennaPointingUpdate

{{SimTX API navigation}}
{{SimTX packet
| name = AntennaPointingUpdate
| frame = ClientFrame
| field = 16
| member = pointing
| direction = c2s
| session = [[SimTX API/Receiver session|Receiver]], [[SimTX API/Transmitter session|transmitter]]
| roles = Station-bound <code>ROLE_RECEIVER</code>, <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>.
| permission = None
| reply = [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> or [[SimTX API/Packets/Error|Error]]
| group = session
| file = session.proto
}}
'''AntennaPointingUpdate''' steers the antenna of a running station-bound session, or changes its tracking and Doppler correction, without reconnecting. It needs the server feature <code>pointing</code>.

== Definition ==
<syntaxhighlight lang="protobuf">
message AntennaPointingUpdate {
  int64 request_id = 1;
  PointingMode mode = 2;
  float azimuth_deg = 3;
  float elevation_deg = 4;
  Tracking tracking = 5;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Chosen by the client; echoed by the [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> or the [[SimTX API/Packets/Error|Error]] that answers it.
|-
| 2 || <code>mode</code> || [[SimTX API/Data types#PointingMode|PointingMode]] || <code>POINTING_MODE_FIXED</code>: point at <code>azimuth_deg</code> / <code>elevation_deg</code>. <code>POINTING_MODE_TRACK</code>: follow <code>tracking</code>.
|-
| 3 || <code>azimuth_deg</code> || <code>float</code> || <code>FIXED</code> mode: azimuth in degrees from true north through east.
|-
| 4 || <code>elevation_deg</code> || <code>float</code> || <code>FIXED</code> mode: elevation in degrees. Ignored by an <code>AZ</code> mount.
|-
| 5 || <code>tracking</code> || [[SimTX API/Data types#Tracking|Tracking]] || <code>TRACK</code> mode: the target, rotator and Doppler settings. Also accepted in <code>FIXED</code> mode to switch Doppler correction on or off.
|}

== Behaviour ==
* <code>POINTING_MODE_FIXED</code> points the antenna at <code>azimuth_deg</code> / <code>elevation_deg</code>. <code>POINTING_MODE_TRACK</code> follows <code>tracking.target_station_id</code>.
* <code>elevation_deg</code> must be −90 to 90 and both angles finite.
* Steering needs a station-bound session whose antenna has an <code>AZ</code> or <code>AZEL</code> mount. An <code>AZ</code> mount keeps its elevation. Otherwise the request is answered with [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code> (<i>Antenna pointing needs a station-bound session with a steerable mount</i>) and the session continues.
* Success is confirmed by [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> with <code>update_reason = UPDATE_REASON_POINTING</code>, the request's <code>request_id</code> and the new <code>pointing</code> and <code>tracking</code>.
* <code>UPDATED</code> reports the commanded pointing at once. The rotator turns there at its rates from wherever it is at that moment, and its actual heading is what the propagation uses. Repeating the current heading does not restart the turn. See [[SimTX API/Tracking and pointing#Rotators|Rotators]].
* The change applies to this session only. The station's stored default pointing is unchanged.

== See also ==
* [[SimTX API/Tracking and pointing]]
* [[SimTX API/Packets/SessionStatus|SessionStatus]]

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