# Triggers

The stock Cyan/Crimson TNG product includes one user accessible trigger, with the option to upgrade your device to expose per channel triggers. The global trigger functionality is made available through the front panel TRIG SMA, and supports arbitrary Rx and Tx radio channels, with various modes of operation.

## Global (SMA) Trigger Overview

The global trigger is bi-directional and may be used to specify when to start transmitting or receiving samples, and also indicate when specific channels are transmitting or receiving data. When using the global trigger, you must specify a direction (input or output) and polarity (active high, active low), which applies across all radio channels.

Though the direction and polarity is universal, each radio channel may have a unique sensitivity (level, edge) to the global trigger. Each radio channel may have a unique global trigger sensitivity (edge, level), and trigger selection (trigger disabled, global trigger, per-channel trigger, or both). Whether a specific radio channel contributes to the global trigger is specified with the trig_sel parameter, which specifies the applicable triggers for a given radio channel.

## Global Trigger Direction and Channel Applicability

When specifying the global trigger direction as an input, an active trigger will serve to start broadcasting user provided samples over the corresponding Tx channel, or else indicate when four the receive chain should start receiving RF data and send it to the user application over the SFP+ ports. A global input trigger is simultaneously on all applicable radio channels (as specified by the trig_sel).

Selecting a global trigger output direction serves to indicate for when the Tx channel is starting to broadcast data over the air, or when the Rx channel is processing RF data and sending it to the user application. The global output trigger with an output direction is the result of OR’ing applicable radio channel triggers (as specified by trig_sel), such that the triggering of the specified condition on any channel will assert the global SMA trigger.

## Global Trigger Sensitivity

Each radio channel may be level or edge sensitive. When specifying edge sensitive triggers, it is further possible to specify the trigger width or duration as measured by number of samples at the user-specified sample rate for that that radio channel. Edge sensitive triggers also benefits from an edge-backoff that ignores further trigger transitions for a specified duration (as specified by number of samples at the user-set sample rate), which may helpful reduce ringing or bouncing on the input.

## Trigger Gating

Trigger gating is a feature that applies to Transmit channels only. When triggering the transmit channel, you may also specify where transmit channels are gated (either the output, or the DSP). When gating at the output, incoming samples are processed through various packet handlers, ensuring that the sample counts, and headers are preserved, ensuring phase coherency. In this mode, the a low trigger acts to blank the output, while the user application continues to send Cyan/Crimson TNG packets.

An alternative mode, DSP gating, allows you to gate at the DSP, in which case the sample count is paused, with samples dropped (if required), prior to the DSP. This provides a mechanism to queue up a number of samples in the buffer, and entirely control the timing and transmission of those samples through an external trigger. Though this mode is useful for burst applications, it’s use in continuous streaming would likely requires overriding the default flow control code. Speaking generally, it usually makes a lot of sense to for Cyan/Crimson TNG to be responsible for ensuring phase coherency, clocking, and triggering requirements.

## Per Channel (U.Fl) Triggers

Per Channel triggers operate similarly to the global trigger, except that there is one unique trigger per radio channel. This hardware option provides for a unique trigger to be specified, along with direction and polarity, per radio channel.

## Trigger Parameter Summary

fpga/trigger/
sma_dir
sma_pol
rx/{a,b,c,d}/trigger/
edge_sample_num
edge_backoff
sma_mode
trig_sel
ufl_dir
ufl_mode
ufl_pol
tx/{a,b,c,d}/trigger/
edge_sample_num
edge_backoff
gating
sma_mode
trig_sel
ufl_dir
ufl_mode
ufl_pol

### Trigger Parameter Descriptions

The following provides a more detailed description of all the trigger parameters.

##### sma_dir
Path state/fpga/trigger/sma_dir
Legal Values in, out
Default Value out
Description Specifies direction of Global SMA Trigger port, with respect to the FPGA.

Additional Information To export a trigger, for example, to indicate you are transmitting samples, specify the direction as output - with Cyan/Crimson TNG effectively generating a trigger on the specified event. To receive a trigger, such as when you want to specify the initial receipt of samples, set this direction to input. When the trigger is set as an input, it is AND’d across all channels. When using an output trigger, the global trigger is OR’d across all applicable channels, such that the trigger condition on any given channel will trigger it.

##### sma_pol
Path state/fpga/trigger/sma_pol
Legal Values positive, negative
Default Value positive
Description Specify Global SMA Trigger assertion state as VCC (positive) or GND (negative)

Additional Information This indicates what voltage level constitutes a logically high trigger. If the value is “positive”, then the untriggered state shall be specified with GND at the SMA, and the triggered state by VCC (active high). If the value is “negative”, then the trigger shall be reversed (active low).

NOTE: The trigger input has a fixed, weak, pull-up. The polarity is set using FPGA logic. This means that you must actively sink the trigger input to GND for proper operation during blanking periods; a floating or unconnected source will not work effectively.

Warning

EXCEEDING SPECIFIED IO LEVELS MAY RESULT IN DAMAGE OR INJURY The trigger is directly connected to the FPGA; violating the specified voltage range may damage the unit.
##### edge_sample_num
Path state/{rx,tx}/{a,b,c,d}/trigger/edge_sample_num
Legal Values 0..($2^64$-1)
Default Value 0
Description Number of samples to transmit or receive after receiving trigger. (0=continuous)
Note Only applicable when in edge mode.

Additional Information A 64-bit unsigned integer, representing the number of samples (based on the user specified sample rate after decimation), to collect and send to the host PC, on receipt of a trigger. A value of 0 indicates to immediately start sending samples indefinitely (no count is used). The number of samples to transmit corresponds to the number of samples provided by the user at the user specified sample-rate.

##### edge_backoff
Path state/{rx,tx}/{a,b,c,d}/trigger/edge_backoff
Legal Values 0..($2^31$-1)
Default Value 0
Description Timeout after trigger to debounce or reduce ringing.
Note Only applicable when in edge mode.

Additional Information A 32-bit unsigned integer, representing the duration, as measured in intervals of 162.5MHz, to ignore further transitions of the trigger. This may be used to reduce ringing or bouncing.

##### sma_mode
Path state/{rx,tx}/{a,b,c,d}/trigger/sma_mode
Legal Values edge, level
Default Value level
Description Trigger mode associated with TRIG SMA port.

Additional Information This specifies whether the SMA trigger should be edge or level sensitive. A level sensitive trigger is asserted on the leading edge of an input, and remains asserted for as long as the level remains high. On Rx radio channels, the trigger gates at the interface of the converter device, prior to decimation. On Tx radio channels, the gating property modifies the gate to operate on either the interface between the interpolation stages and the interpolate, similar to a blanking signal, or between where the user provided data is passed to the internal DSP interpolation stages. Edge sensitive trigger behaviour is further specified by the edge_sample_num and edge_backoff properties.

##### trig_sel
Path state/{rx,tx}/{a,b,c,d}/trigger/trig_sel
Legal Values {0..3}
Default Value 3
Description Select what triggers are applicable to the channel.

Additional Information Specifies whether the channel should contribute, or respond, to the specified triggers. This has the following values;

0 Not Triggered (Global Trigger disabled, Per-Channel U.Fl channel trigger disabled)

1 Global SMA trigger only (Per Channel U.Fl disabled)

2 Per Channel U.Fl only (Global SMA trigger disabled)

3 All Triggers on (Global SMA trigger and U.Fl Per Channel trigger enabled)

##### gating
Path state/tx/{a,b,c,d}/trigger/gating
Legal Values output, dsp
Default Value output
Description Specify gating mode for Tx triggers only.
Notes Tx only trigger option.

Additional Information This indicates where, in the Tx chain, samples are gated. The default option, output gating, means that samples are processed through the UHD and VITA packet handler, and interpolated. After interpolation, if the trigger is not active, the interpolated samples are discarded, and the zero valued samples are sent to the DAC. This ensures that VITA sample count and headers may be used to ensure phase coherency.

When using dsp gating, the UHD sample count is paused, and samples discarded prior to the dsp. This provides a mechanism to queue up a number of samples in the buffer, and entirely control the timing and transmission of those samples through an external trigger. _NB: Continuous operation in this mode would likely require end users to override the default flow control handler. For phase coherent, users must also ensure phase coherency. In most cases, it makes a lot more sense for Cyan/Crimson TNG to be responsible for phase coherency and clocking requirements.

##### ufl_mode
Path state/{rx,tx}/{a,b,c,d}/trigger/ufl_mode
Legal Values edge, level
Default Value level
Description Trigger mode associated with U.Fl channel trigger ports.

Additional Information This specifies whether the U.Fl per channel triggers should be edge or level sensitive, and operates identically to the sma_mode property, except that trigger behaviour is specific and exclusive to the specified radio channel.

##### ufl_dir
Path state/{rx,tx}/{a,b,c,d}/trigger/ufl_dir
Legal Values in, out
Default Value out
Description Specifies direction of Per Channel U.Fl Trigger port, with respect to the FPGA.

Additional Information This property works similarly to the sma_dir property, except it is channel specific. To export a trigger, for example, to indicate you are transmitting samples, specify the direction as output - with (Cyan/Crimson TNG) effectively generating a generating a trigger on the specified event. To receive a trigger, such as when you want to specify the initial receipt of samples, set this direction to input. Unlike the Global SMA trigger, the behaviour of this trigger is exclusive to its associated radio channel.

##### ufl_pol
Path state/{rx,tx}/{a,b,c,d}/trigger/ufl_pol
Legal Values positive, negative
Default Value positive
Description Per Channel U.Fl trigger assertion state as VCC (positive) or GND (negative)

Additional Information This indicates what voltage level constitutes a logically high trigger. If the value is “positive”, then the untriggered state shall be specified with GND at the SMA, and the triggered state by VCC (active high). If the value is “negative”, then the trigger shall be reversed (active low).

NOTE: The trigger input has a fixed, weak, pull-up. The polarity is set using FPGA logic. This means that you must actively sink the trigger input to GND for proper operation during blanking periods; a floating or unconnected source will not work effectively.

Warning

EXCEEDING SPECIFIED IO LEVELS MAY RESULT IN DAMAGE OR INJURY The trigger is directly connected to the FPGA; violating the specified voltage range may result in damage or injury.

### Trigger Configuration

Trigger behaviour may be configured on the website, through UHD, or directly through the file system.

#### Website

The universal global trigger properties (direction and polarity) may be configured from the configuration page through the website. Radio chain specific behaviour may be configured from the channel web page, under the Trigger Settings header.

#### SSH

You can directly set the trigger behaviour through the Cyan/Crimson TNG state tree. The state tree is located in /var/crimson/state. The relative path to one of the specified properties is specified above.

#### UHD

You may also get and set selected properties through UHD. Example code demonstrating this functionality is available in the UHD repository. In this mode, you can configure various paths, including trigger settings.