SimTX API/Packets/ReceiverRetune

ReceiverRetune

Frame	ClientFrame, field 11
Member	receiver_retune
Direction	Client → server
Session	Receiver
Roles	ROLE_RECEIVER, after the start.
Permission	None
Answered by	SessionStatus UPDATED when request_id is nonzero
Answers
Defined in	session.proto

ReceiverRetune moves a running receiver to a new centre frequency without reconnecting.

Definition

message ReceiverRetune {
  double center_frequency_hz = 1;
  int64 request_id = 2;
}

Fields

#	Field	Type	Description
1	center_frequency_hz	double	New centre frequency in Hz. Finite and ≥ 0.
2	request_id	int64	Nonzero: the server confirms with SessionStatus UPDATED (UPDATE_REASON_RETUNE) 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 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 request_id, the server sends SessionStatus UPDATED with update_reason = UPDATE_REASON_RETUNE, the same request_id and the new frequency_hz once the stream runs on the new frequency. 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 Error INVALID_REQUEST.

Examples

Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

receiver_retune (client to server, 14 bytes):

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

session_status_updated_retune (server to client, 36 bytes):

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)

See also

• Retuning