Editing SimTX API/Packets/ReceiverRetune

{{SimTX API navigation}}
{{SimTX packet
| name = ReceiverRetune
| frame = ClientFrame
| field = 11
| member = receiver_retune
| direction = c2s
| session = [[SimTX API/Receiver session|Receiver]]
| roles = <code>ROLE_RECEIVER</code>, after the start.
| permission = None
| reply = [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> when <code>request_id</code> is nonzero
| group = receiver
| file = session.proto
}}
'''ReceiverRetune''' moves a running receiver to a new centre frequency without reconnecting.

== Definition ==
<syntaxhighlight lang="protobuf">
message ReceiverRetune {
  double center_frequency_hz = 1;
  int64 request_id = 2;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>center_frequency_hz</code> || <code>double</code> || New centre frequency in Hz. Finite and ≥ 0.
|-
| 2 || <code>request_id</code> || <code>int64</code> || Nonzero: the server confirms with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> (<code>UPDATE_REASON_RETUNE</code>) echoing it once the stream runs on the new frequency. 0: no confirmation.
|}

== Behaviour ==
* Sample rate, block size, bandwidth and sample format stay the same. No new [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] is sent.
* The new frequency takes effect after a settling time of about 120 ms. Retunes received during that time are coalesced; only the latest is applied. A retune superseded before it took effect gets no confirmation of its own.
* With a nonzero <code>request_id</code>, the server sends [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> with <code>update_reason = UPDATE_REASON_RETUNE</code>, the same <code>request_id</code> and the new <code>frequency_hz</code> once the stream runs on the new frequency. [[SimTX API/Packets/IqBlock|IqBlock]] sequence numbers continue across the retune.
* Expect a short gap or transient around the change.
* A negative or non-finite frequency is refused with [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code>.

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

'''<code>receiver_retune</code>''' (client to server, 14 bytes):

<syntaxhighlight lang="text">
0D                            frame length 13
5A 0B                         receiver_retune (ReceiverRetune), 11 bytes
  09 00 00 00 00 12 D8 6A 41  center_frequency_hz = 14074000.0
  10 29                       request_id = 41
</syntaxhighlight>

'''<code>session_status_updated_retune</code>''' (server to client, 36 bytes):

<syntaxhighlight lang="text">
23                            frame length 35
52 21                         session_status (SessionStatus), 33 bytes
  08 04                       state = 4 (SESSION_STATE_UPDATED)
  22 10 AA AA AA AA …         session_id = aaaaaaaa-bbbb-4ccc-8ddd-ffffffffffff
  31 00 00 00 00 12 D8 6A 41  frequency_hz = 14074000.0
  48 29                       request_id = 41
  50 06                       update_reason = 6 (UPDATE_REASON_RETUNE)
</syntaxhighlight>

== See also ==
* [[SimTX API/Receiver session#Retuning|Retuning]]

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