View source for Synchronizing USRP Events Using Timed Commands in UHD

==Application Note Number==
'''AN-TC'''

==Revision History==
{| class="wikitable"
!Date
!Author
!Details
|-
|style="text-align:center;"| 2020-02-10   
|style="text-align:center;"| Sam Reiter
|style="text-align:center;"| Initial creation
|}

==Abstract==
This AN discusses Timed Commands in UHD. We will explore usecases, theory of operation, and examples of timed command use in UHD 3.x.

==Timed Commands: Overview and Usecases==
*A 
*B
*C
*D
*E
*F
*G
*H
*I
*J

==Clocking and Timekeeping in the USRP==

In this section, we will cover several key topics relating to USRP synchronization and the use of timed commands in UHD.

===CHDR Packet Types and Structure===

CHDR or "Compressed Header" packets are a derivative of the VITA 49 (VRT) protocol. While the CHDR protocol is proprietary to USRP devices, mapping to and from VITA-49 is a trivial task. All packet routing in b2xx and "Gen 3" USRPs uses the CHDR protocol. 

There are 4 types of packets used in the USRP:
*Data 
*Flow Control
*Command 
*Command Response

The type of packet is determined by the state of bits 63 and 62 in the CHDR header. See [https://files.ettus.com/manual/page_rtp.html UHD Manual: Radio Transport Protocols] for more information on CHDR structure. 

[[File:packet breakdown.png|1400px|center]]



All of these packet types have a single bit (61) used to denote whether an optional timestamp is included. If present, a timestamp is a 64-bit value representing an absolute time value. In this application note, we’re concerned with the use and functionality of command packets with a timestamp present, also known as “Timed Commands”.

===Command Queue===
The command queue is a FIFO for all commands that are sent to an RFNoC block. The command queue FIFO is not to be confused with the data FIFOs used to buffer data between blocks (pictured in Figure **###**).  Every command queue maintains a sense of time. The mechanism for acquiring this sense of time is different between the Radio Core and other RFNoC blocks and will be explored later in this Application Note. When commands enter the command queue, their timestamp is compared against the queue's sense of time and the commands are executed when Queue Time >= Command Time. Commands without timestamps are executed immediately when they're at the front of the queue. Command queues in RFNoC do not support on the fly reordering, meaning a command at the front of the queue will block subsequent commands from executing even if their timestamp has passed. An overflow of the command queue will result in a system halt and often requires a physical reset of the FPGA. 

Every RFNoC block, including the Radio Core, includes 1 command queue per port (there's generally 1 port per data stream). The depth of this command queue varies from device-to device is determined at FPGA compilation time based on user settings and available resources.

===PPS (Pulse Per Second)===

PPS is a signal used by USRPs for time synchronization. With a shared PPS, the sense of time can be aligned across several USRPs, allowing for the synchronization of timed command execution on an arbitrary number of radio channels. Within the context of a USRP, a PPS signal is expected to have the following properties:

*1Hz
*TTL Signal Levels
*25% duity cycle

A USRP's PPS can be derived from a GPSDO automatically, from an externally supplied PPS signal, or via internal PPS synthesis (not supported in legacy USRPs).

A PPS trigger is used to coordinate time alignment events across multiple devices. For example, the USRPs internal sense of time (the <code>vita_time</code> counter) can be synchronously set/reset across multiple USRPs via UHD API calls such as 

 set_time_next_pps

 set_time_unknown_pps

Ettus Research recommends the [https://www.ettus.com/all-products/octoclock/ Octoclock] for distribution of PPS and 10MHz REF signals across multiple devices, and the [https://www.ettus.com/all-products/octoclock-g/ Octoclock-G] for this functionality as well as tight alignment with GPS time. For further information on PPS and other common reference signals, see the [https://files.ettus.com/manual/page_sync.html UHD Manual: Device Synchronization].

===Radio Core Block Timing===

The Radio Core is the heart of the USRP's functionality. The radio core is responsible for controlling all TX and RX daughterboard components (synthesizer, signalpath, gain and attenuation elements, etc.), GPIO, setting up data streaming to/from DACs and ADCs, and related error handling. 

[[File:rfnoc with ubx.png|1200px|center]]

In addition to the functionality listed above, the Radio Core is also responsible for maintaining the USRP's sense of absolute time. This absolute time value is stored as a 64-bit counter called the "VITA time" or <code>vita_time</code> in UHD. The <code>vita_time</code> counter is incremented off of the FPGA's base clock and local to the Radio Core USRP, meaning that other RFNoC blocks can not reference this counter value directly. This sense of absolute time is a subtle yet important difference between the Radio Core and other RFNoC blocks, which can also execute timed commands but do so based on the timestamps (and IQ rate) of packets which pass through these blocks.

===General RFNoC Block Timing===
The next case to cover is the handling of timed commands within a "General" RFNoC block. The Digital Down Converter (DDC) and Digital Up Converter (DUC) are two default RFNoC blocks that would be considered general RFNoC blocks. These blocks are responsible for performing digital frequency shifts of IQ data that is passed through them. Precise execution of these frequency shifts are essential to phase coherent operation of the USRP.

RFNoC blocks like the DDC and DUC are reliant on the timestamp of packets (and the IQ rate of the radio) to derive a sense of time. In the case of the receive chain, samples that are digitized by an ADC are then packaged into a CHDR Packet by the Radio Core (with an included absolute timestamp) and are then passed downstream to the DDC. The DDC will read the timestamp of the incoming CHDR packet, extract the IQ samples, and apply any queued frequency shift at the specified time in the stream. To get sample-precise data manipulation, the DDC can interpolate timestamps for each IQ sample by incrementing its sense of time by <code>1/samp_rate</code> for each IQ sample. 

With this method, a USRP can begin RX'ing data at absolute time <code>t0</code>, tune it's LO at an absolute time of <code>t1</code>, and then apply a frequency shift in the DDC at the point in data corresponding to <code>t1</code>, resulting in a physical and digital frequency change that begin on the exact same sample.

The reverse process holds true for the transmit chain. One often overlooked difference is that the host must pass along at least 1 sample with a timestamp included. Without this timestamped packet, the DUC can not derive a sense of time and therefore will never execute timed commands that are in its queue. This will either result in a command queue overflow or a "No Response Packet" runtime error from <code>ctrl_iface.cpp</code>.

===Miscellaneous Timed Command Notes===

====Types of timed commands====
* Most timed commands are

====Timed commands on AD93xx-based devices====


===Summary===

==USRP Time Sources==

===Internal PPS===

===External PPS===

===GPSDO===

==UHD API for Timed Commands==

===Overview of Relevant Methods===

===Timed Commands vs. Stream Commands with time_spec (remove this?)===

===Commands that can be timed===

===Time Resolution of Timed Commands===

==Example: Using Timed Commands to Phase Align Channels==

==Example: Using Timed Commands to Control GPIO==

[[Category:Application Notes]]