Editing SimTX API/Packets/TxTelemetry

{{SimTX API navigation}}
{{SimTX packet
| name = TxTelemetry
| frame = ServerFrame
| field = 17
| member = tx_telemetry
| direction = s2c
| session = [[SimTX API/Transmitter session|Transmitter]]
| roles = <code>ROLE_TX_AUDIO</code>, <code>ROLE_TX_GENERATED</code>.
| permission = None
| group = transmitter
| file = session.proto
}}
'''TxTelemetry''' reports the state of a transmitter on air: power at each point of the chain, standing-wave ratio, amplifier compression and temperature, and the server's playout buffer. The server sends it about every 50 ms from [[SimTX API/Packets/TxAccept|TxAccept]] until the session ends.

== Definition ==
<syntaxhighlight lang="protobuf">
message TxTelemetry {
  int64 sequence = 1;
  int64 server_time_ms = 2;
  double actual_frequency_hz = 3;
  float requested_power_watts = 4;
  float forward_power_watts = 5;
  float delivered_power_watts = 6;
  float reflected_power_watts = 7;
  float vswr = 8;
  float mismatch_loss_db = 9;
  float transformer_loss_db = 10;
  float foldback_loss_db = 11;
  float alc_db = 12;
  float buffer_seconds = 13;
  float finals_temperature_c = 14;
  float thermal_foldback_db = 15;
  float pa_compression_db = 16;
  float pa_heat_watts = 17;
  float pa_efficiency_percent = 18;
  bool pa_thermal_fault_active = 19;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>sequence</code> || <code>int64</code> || Increments with each telemetry frame. Telemetry is coalesced, so values may be skipped.
|-
| 2 || <code>server_time_ms</code> || <code>int64</code> || Server wall clock, Unix ms.
|-
| 3 || <code>actual_frequency_hz</code> || <code>double</code> || Frequency on air in Hz: the requested frequency plus the frequency offset.
|-
| 4 || <code>requested_power_watts</code> || <code>float</code> || Power requested, after the PA cap.
|-
| 5 || <code>forward_power_watts</code> || <code>float</code> || Power leaving the amplifier towards the antenna.
|-
| 6 || <code>delivered_power_watts</code> || <code>float</code> || Power accepted by the antenna.
|-
| 7 || <code>reflected_power_watts</code> || <code>float</code> || Power reflected by the mismatch.
|-
| 8 || <code>vswr</code> || <code>float</code> || Voltage standing-wave ratio at the feed point.
|-
| 9 || <code>mismatch_loss_db</code> || <code>float</code> || Loss due to the mismatch, dB.
|-
| 10 || <code>transformer_loss_db</code> || <code>float</code> || Loss in the matching transformer, dB.
|-
| 11 || <code>foldback_loss_db</code> || <code>float</code> || Power reduction by SWR protection, dB.
|-
| 12 || <code>alc_db</code> || <code>float</code> || Automatic level control reduction, dB.
|-
| 13 || <code>buffer_seconds</code> || <code>float</code> || Samples waiting in the server's playout buffer, seconds.
|-
| 14 || <code>finals_temperature_c</code> || <code>float</code> || Temperature of the final amplifier, °C.
|-
| 15 || <code>thermal_foldback_db</code> || <code>float</code> || Power reduction by thermal protection, dB.
|-
| 16 || <code>pa_compression_db</code> || <code>float</code> || Amplifier gain compression, dB.
|-
| 17 || <code>pa_heat_watts</code> || <code>float</code> || Heat dissipated in the amplifier, W.
|-
| 18 || <code>pa_efficiency_percent</code> || <code>float</code> || Amplifier efficiency, percent.
|-
| 19 || <code>pa_thermal_fault_active</code> || <code>bool</code> || True while the amplifier is in thermal fault.
|}

== Usage ==
* '''Pacing:''' <code>buffer_seconds</code> is the most useful field for a streaming client. Keep it above zero (otherwise listeners hear gaps) and below about two seconds (otherwise latency grows and input may be discarded).
* '''Antenna match:''' a high <code>vswr</code> with large <code>reflected_power_watts</code> and <code>foldback_loss_db</code> means the antenna is not resonant on the frequency. See [[SWR and Transmitter Protection]].
* '''Heat:''' <code>finals_temperature_c</code>, <code>thermal_foldback_db</code> and <code>pa_thermal_fault_active</code> follow the amplifier model in [[Power Amplifier Behaviour]].
* Telemetry is coalesced. A slow reader gets the most recent values rather than a backlog; <code>sequence</code> may skip.
* Keep reading. A client that does not read for 5 seconds is disconnected.

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

'''<code>tx_telemetry</code>''' (server to client, 90 bytes):

<syntaxhighlight lang="text">
59                            frame length 89
8A 01 56                      tx_telemetry (TxTelemetry), 86 bytes
  08 2A                       sequence = 42
  10 FA 95 83 B9 97 34        server_time_ms = 1793000000250
  19 00 00 00 00 34 FC 5A 41  actual_frequency_hz = 7074000.0
  25 00 00 C8 42              requested_power_watts = 100
  2D 00 00 C4 42              forward_power_watts = 98
  35 00 00 C1 42              delivered_power_watts = 96.5
  3D 00 00 C0 3F              reflected_power_watts = 1.5
  45 66 66 A6 3F              vswr = 1.3
  4D 29 5C 8F 3D              mismatch_loss_db = 0.07
  55 CD CC 4C 3E              transformer_loss_db = 0.2
  65 00 00 80 BF              alc_db = -1
  6D 00 00 80 3E              buffer_seconds = 0.25
  75 00 00 34 42              finals_temperature_c = 45
  85 01 9A 99 99 3F           pa_compression_db = 1.2
  8D 01 00 00 F0 41           pa_heat_watts = 30
  95 01 00 00 7A 42           pa_efficiency_percent = 62.5
</syntaxhighlight>

== See also ==
* [[SWR and Transmitter Protection]]
* [[Power Amplifier Behaviour]]

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