Editing SimTX API/Packets/TxUpdate

{{SimTX API navigation}}
{{SimTX packet
| name = TxUpdate
| frame = ClientFrame
| field = 14
| member = tx_update
| direction = c2s
| session = [[SimTX API/Transmitter session|Transmitter]]
| roles = <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>, after [[SimTX API/Packets/TxAccept|TxAccept]].
| permission = None
| reply = [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]]
| group = transmitter
| file = session.proto
}}
'''TxUpdate''' changes transmitter settings while the station is on air, without reconnecting. Every field except <code>request_id</code> is <code>optional</code>; send only the fields that change. The server answers each TxUpdate with a [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]].

== Definition ==
<syntaxhighlight lang="protobuf">
message TxUpdate {
  int64 request_id = 1;
  optional double frequency_hz = 2;
  optional float power_watts = 3;
  optional float bandwidth_hz = 4;
  optional float audio_low_cut_hz = 5;
  optional float final_drive_db = 6;
  optional float pa_headroom_db = 7;
  optional float audio_compression_db = 8;
  optional float audio_gain = 9;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Chosen by the client; echoed in the [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]]. Use a new value for each update.
|-
| 2 || <code>frequency_hz</code> || <code>optional double</code> || Live field <code>FREQUENCY</code>. 1,000 Hz to 3 GHz; at most one frequency change per second.
|-
| 3 || <code>power_watts</code> || <code>optional float</code> || Live field <code>POWER</code>. ≥ 0; reduced to at most 1,000,000 W and to the PA cap.
|-
| 4 || <code>bandwidth_hz</code> || <code>optional float</code> || Live field <code>BANDWIDTH</code>. 10 Hz to 10 MHz.
|-
| 5 || <code>audio_low_cut_hz</code> || <code>optional float</code> || Live field <code>LOW_CUT</code>. ≥ 0; values above 5,000 Hz are reduced to 5,000 Hz.
|-
| 6 || <code>final_drive_db</code> || <code>optional float</code> || Live field <code>FINAL_DRIVE</code>. Clamped to −40 to 40.
|-
| 7 || <code>pa_headroom_db</code> || <code>optional float</code> || Live field <code>PA_HEADROOM</code>. Clamped to 0 to 40.
|-
| 8 || <code>audio_compression_db</code> || <code>optional float</code> || Live field <code>AUDIO_COMPRESSION</code>. Clamped to 0 to 40.
|-
| 9 || <code>audio_gain</code> || <code>optional float</code> || Live field <code>AUDIO_GAIN</code>. Clamped to 0 to 100.
|}

== Rate limits ==
* If any update was applied less than 250 ms earlier, every field of the update is refused.
* A frequency change is refused if the previous frequency change was less than 1 second earlier.
* Refused fields are reported in the ack with <code>accepted = false</code>. They are not queued; send them again later.
* Changing the modulation, sample rate, source, site or antenna needs a new session. Antenna pointing changes use [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]].

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

'''<code>tx_update</code>''' (client to server, 19 bytes):

<syntaxhighlight lang="text">
12                            frame length 18
72 10                         tx_update (TxUpdate), 16 bytes
  08 07                       request_id = 7
  11 00 00 00 20 A6 E9 5A 41  frequency_hz = 7055000.5
  1D 00 00 48 42              power_watts = 50
</syntaxhighlight>

'''<code>tx_update_audio_gain</code>''' (client to server, 10 bytes):

<syntaxhighlight lang="text">
09                frame length 9
72 07             tx_update (TxUpdate), 7 bytes
  08 08           request_id = 8
  4D 00 00 40 3F  audio_gain = 0.75
</syntaxhighlight>

== See also ==
* [[SimTX API/Transmitter session#Live updates|Live updates]]
* [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]]

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