Editing SimTX API/Packets/TxUpdateAck

{{SimTX API navigation}}
{{SimTX packet
| name = TxUpdateAck
| frame = ServerFrame
| field = 18
| member = tx_update_ack
| direction = s2c
| session = [[SimTX API/Transmitter session|Transmitter]]
| roles = <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>.
| permission = None
| answers = [[SimTX API/Packets/TxUpdate|TxUpdate]]
| group = transmitter
| file = session.proto
}}
'''TxUpdateAck''' reports the outcome of a [[SimTX API/Packets/TxUpdate|TxUpdate]], one result per field that was set.

== Definition ==
<syntaxhighlight lang="protobuf">
message TxUpdateAck {
  message Result {
    TxLiveField field = 1;
    bool accepted = 2;
    double applied_value = 3;
  }
  int64 request_id = 1;
  repeated Result results = 2;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || The update's <code>request_id</code>.
|-
| 2 || <code>results</code> || <code>repeated</code> [[#TxUpdateAckResult|Result]] || One result per field of the update.
|}

<span id="TxUpdateAckResult"></span>
=== Result ===
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>field</code> || [[SimTX API/Data types#TxLiveField|TxLiveField]] || The live field. <code>TX_LIVE_FIELD_UNSPECIFIED</code> or an unknown value names a field this client does not know; ignore that result.
|-
| 2 || <code>accepted</code> || <code>bool</code> || True if the value was applied or was already in effect.
|-
| 3 || <code>applied_value</code> || <code>double</code> || The value now in effect, after clamping and the PA cap. For a refused field, the current unchanged value.
|}

== Live fields ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>TX_LIVE_FIELD_UNSPECIFIED</code> || In a TxUpdateAck result, like an unknown value: a field this client does not know. Ignore that result.
|-
| 1 || <code>TX_LIVE_FIELD_FREQUENCY</code> || <code>frequency_hz</code>
|-
| 2 || <code>TX_LIVE_FIELD_POWER</code> || <code>power_watts</code>
|-
| 3 || <code>TX_LIVE_FIELD_BANDWIDTH</code> || <code>bandwidth_hz</code>
|-
| 4 || <code>TX_LIVE_FIELD_LOW_CUT</code> || <code>audio_low_cut_hz</code>
|-
| 5 || <code>TX_LIVE_FIELD_FINAL_DRIVE</code> || <code>final_drive_db</code>
|-
| 6 || <code>TX_LIVE_FIELD_PA_HEADROOM</code> || <code>pa_headroom_db</code>
|-
| 7 || <code>TX_LIVE_FIELD_AUDIO_COMPRESSION</code> || <code>audio_compression_db</code>
|-
| 8 || <code>TX_LIVE_FIELD_AUDIO_GAIN</code> || <code>audio_gain</code>
|}

== Interpreting results ==
{| class="wikitable"
! Situation !! <code>accepted</code> !! <code>applied_value</code>
|-
| Applied || true || The value now in effect, after clamping and the PA cap.
|-
| Value already in effect || true || The current value.
|-
| Refused (out of range or too soon) || false || The current, unchanged value.
|}

Always update the user interface from <code>applied_value</code>, not from the value that was requested. A power request of 1,500 W with a 400 W PA cap is accepted with <code>applied_value = 400</code>. A server that does not know a field ignores it and returns no result for it.

== Example ==
Complete frames, including the varint length prefix.

'''<code>tx_update_ack</code>''' (server to client, 34 bytes):

<syntaxhighlight lang="text">
21                              frame length 33
92 01 1E                        tx_update_ack (TxUpdateAck), 30 bytes
  08 07                         request_id = 7
  12 0D                         results (Result), 13 bytes
    08 01                       field = 1 (TX_LIVE_FIELD_FREQUENCY)
    10 01                       accepted = true
    19 00 00 00 20 A6 E9 5A 41  applied_value = 7055000.5
  12 0B                         results (Result), 11 bytes
    08 02                       field = 2 (TX_LIVE_FIELD_POWER)
    19 00 00 00 00 00 00 39 40  applied_value = 25.0
</syntaxhighlight>

== See also ==
* [[SimTX API/Packets/TxUpdate|TxUpdate]]

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