Configuration

After an Ndigo5G device has been initialized (see Initialization), it must be configured before it can acquire data.

To configure an Ndigo5G device:

The following example shows a basic configuration of an already initialized Ndigo5G device using the default configuration parameters. A complete coding example can be found on github.com/cronologic-de/ndigo5g_babel or in Code example.

int status;

// get a default set of configuration parameters
ndigo_configuration config;
status = ndigo_get_default_configuration(device, &config);
if (status != NDIGO_OK) { /* handle error */ }

// optionally modify config

// configure the device
status = ndigo_configure(device, &config);
if (status != NDIGO_OK) { /* handle error */ }
int ndigo_get_default_configuration(ndigo_device *device, ndigo_configuration *config)

Copies the default configuration to the specified config pointer.

Parameters:

  • device – [in] Pointer to the device from which to get the information.

  • config – [out] Pointer to a structure in which to store the configuration values.

Returns:

A status code.

int ndigo_configure(ndigo_device *device, ndigo_configuration *config)

Configures Ndigo device.

The config information is copied so that it can be changed after the call of ndigo_configure without corrupting the current configuration of the device.

Parameters:

  • device – [in] Pointer to the device from which to get the information.

  • config – [out] Pointer to the configuration structure.

Returns:

A status code.

int ndigo_get_current_configuration(ndigo_device *device, ndigo_configuration *config)

Copies the current configuration to the specified config pointer.

Parameters:

  • device – [in] Pointer to the device from which to get the information.

  • config – [out] Pointer to a structure in which to store the configuration values.

Returns:

A status code.

int ndigo_set_board_id(ndigo_device *device, int board_id)

Overwrite the board ID.

The board ID can be changed after initialization of the card. If cronotools are used, the board ID changes have to be done before the initialization of cronotools.

Parameters:

  • device – [in] A pointer to the device.

  • board_id – [in] New board ID.

Returns:

A status code.

typedef short (*lut_func)(int channel, float x)

Maps a value between 0 and 1 to a 16-bit output value.

The mapping has to be monotonous.

The mapping can be used, e.g., for custom INL, offset and gain correction that cover user frontend electronics. It can also invert the signal or correct the effect of logarithmic input amplifiers, etc.

The LUT is applied on the board, thus using it does not cause any additional CPU load.

In the mode NDIGO_OUTPUT_MODE_CUSTOM_INL the on-board INL correction table is applied before the user function, while NDIGO_OUTPUT_MODE_CUSTOM does not perform the INL correction.

In order to use the user lookup table functionality, ndigo_configuration::custom_lut must be set to a pointer of the user’s LUT function.

struct ndigo_configuration

Contains all configurable settings.

The struct should be first populated using ndigo_get_default_configuration(), or if the Ndigo5G has already been previously configured, using ndigo_get_current_configuration().

Afterwards, user-specific changes can be applied.

An initialized Ndigo5G device can then be configured using ndigo_configure().

Public Members

int size

The number of bytes occupied by the structure.

int version

Version number of the struct used by the API.

int reserved1

Reserved for internal usage. Do not change.

int adc_mode

ADC mode.

Must be one of the following:

NDIGO_ADC_MODE_ABCD 0

4-channel mode at sample rate 1.25GHz.

NDIGO_ADC_MODE_AC 4

2-channel mode at sample rate 2.5GHz.

NDIGO_ADC_MODE_BC 5

2-channel mode at sample rate 2.5GHz.

NDIGO_ADC_MODE_AD 6

2-channel mode at sample rate 2.5GHz.

NDIGO_ADC_MODE_BD 7

2-channel mode at sample rate 2.5GHz.

NDIGO_ADC_MODE_A 8

Single channel mode at sample rate 5GHz.

NDIGO_ADC_MODE_B 9

Single channel mode at sample rate 5GHz.

NDIGO_ADC_MODE_C 10

Single channel mode at sample rate 5GHz.

NDIGO_ADC_MODE_D 11

Single channel mode at sample rate 5GHz.

NDIGO_ADC_MODE_AAAA 12

Single channel mode at sample rate 1.25GHz.

NDIGO_ADC_MODE_BBBB 13

Single channel mode at sample rate 1.25GHz.

NDIGO_ADC_MODE_CCCC 14

Single channel mode at sample rate 1.25GHz.

NDIGO_ADC_MODE_DDDD 15

Single channel mode at sample rate 1.25GHz.

double bandwidth

Minimum bandwidth in Hz.

Set to the minimum bandwidth required for the application.

Lower bandwidth results in reduced noise. The driver will set the ADC to the minimum setting that has at least the desired bandwidth and report the selected bandwidth in ndigo_param_info::bandwidth.

The -8, -10 and -12 versions currently supports 1GHz and 3GHz bandwidth. The -8AQ version supports 2GHz, 1.5GHz, 600MHz and 500 MHz.

ndigo_bool_t reserved

Reserved for internal usage. Do not change.

ndigo_bool_t tdc_enabled

Enable capturing of TDC measurements on external digital input channel.

ndigo_bool_t tdc_fb_enabled

Enable enhanced TDC resolution.

Currently not implemented.

double analog_offset[NDIGO_CHANNEL_COUNT]

Configure DC offset values for ADC channels.

Sets the input DC offset-values to this value in Volts.

Default is 0.

Attention

After calling ndigo_init(), the ADC chip will heat up, which will slightly shift its baseline.

If you plan to measure very small pulses, wait for about 2 minutes after calling ndigo_init before you start capturing data and set the values of analog_offset only after this startup period.

double dc_offset[2]

Sets DC offset for GATE input and TRIGGER input.

The default value of -0.35V is ideal for negative NIM pulses of -0.8V.

Index 0 refers to the TRIGGER input, index 1 to the GATE input.

ndigo_trigger trigger[NDIGO_TRIGGER_COUNT + NDIGO_ADD_TRIGGER_COUNT]

Configuration of the external trigger sources.

The indices correspond to the following defines.

_PE are additional triggers that are always a positive edge trigger in hardware.

NDIGO_TRIGGER_A0 0
NDIGO_TRIGGER_A1 1
NDIGO_TRIGGER_B0 2
NDIGO_TRIGGER_B1 3
NDIGO_TRIGGER_C0 4
NDIGO_TRIGGER_C1 5
NDIGO_TRIGGER_D0 6
NDIGO_TRIGGER_D1 7
NDIGO_TRIGGER_TDC 8
NDIGO_TRIGGER_TRIGGER NDIGO_TRIGGER_TDC
NDIGO_TRIGGER_GATE 9
NDIGO_TRIGGER_BUS0 10
NDIGO_TRIGGER_BUS1 11
NDIGO_TRIGGER_BUS2 12
NDIGO_TRIGGER_BUS3 13
NDIGO_TRIGGER_AUTO 14
NDIGO_TRIGGER_ONE 15
NDIGO_TRIGGER_TDC_PE 16
NDIGO_TRIGGER_GATE_PE 17
NDIGO_TRIGGER_BUS0_PE 18
NDIGO_TRIGGER_BUS1_PE 19
NDIGO_TRIGGER_BUS2_PE 20
NDIGO_TRIGGER_BUS3_PE 21

ndigo_trigger_block trigger_block[NDIGO_CHANNEL_COUNT + 1]

Trigger settings of input ADC and timestamp channels.

This configures the trigger sources, trigger block lengths, etc, not the trigger type, which is configured by ndigo_configuration::trigger.

The number of enabled input channels depends on ndigo_configuration::adc_mode.

ndigo_gating_block gating_block[NDIGO_GATE_COUNT]

Configuration of gating blocks.

Gating blocks are used to filter ndigo_configuration::trigger_block.

ndigo_extension_block extension_block[NDIGO_EXTENSION_COUNT]

Configuration of extension blocks.

A structure describing the routing of the four digital channels of the Ndigo extension board to the trigger matrix.

int drive_bus[4]

Enables output drives.

Enables output drive for each of the four external sync lines. Each integer represents a bitmask selecting the trigger sources for that line.

The bit mapping is documented in ndigo_trigger_block::sources.

int auto_trigger_period

Configure periodicity of the auto trigger.

Works in conjunction with ndigo_configuration::auto_trigger_random_exponent.

The two parameters \( M \) = auto_trigger_period and \( N \) = auto_trigger_random_exponent result in a distance between triggers of

\( T = M + [1 \dots 2^N] - 1 \)

clock cycles.

\( 8 \leq M < 2^{32} \)

\( 0 \leq N < 32 \)

There is no enable or reset as the usage of this trigger can be configured in the channels.

To actually use this trigger, it has to be set as a trigger source in trigger_block.

See also Auto Trigger Function Generator.

int auto_trigger_random_exponent

Configure randomness of the auto trigger.

See also auto_trigger_period.

int output_mode

Defines the data representation in the output.

This influences the meaning of the values of ndigo_packet::data.

Must be one of the following:

group Output format definitions

Defines

NDIGO_OUTPUT_MODE_SIGNED16 0

Output in signed16 integer format.

Raw ADC values are scaled and INL corrected to a range of -32768 to 32767.

NDIGO_OUTPUT_MODE_RAW 1

Return the native ADC range.

Ranges from NDIGO_RAW_VALUE_MIN to NDIGO_RAW_VALUE_MAX.

NDIGO_OUTPUT_MODE_CUSTOM 2

Custom output mode.

Requires that lut_func is set to an appropriate function pointer.

Requires configuration of ndigo_configuration::custom_lut.

NDIGO_OUTPUT_MODE_CUSTOM_INL 3

Custom output mode which applies a custom LUT correction.

Requires that lut_func is set to an appropriate function pointer.

Requires configuration of ndigo_configuration::custom_lut.

lut_func custom_lut

Custom mapping from raw ADC value to output value.

If the ndigo_configuration::output_mode is set to NDIGO_OUTPUT_MODE_CUSTOM or NDIGO_OUTPUT_MODE_CUSTOM_INL this function is used for mapping from ADC value to output value. The driver will call this function with a value from -1 to +1 and the function must return the corresponding signed 16 bit value that the board should return for an input voltage relative to the full scale range.

struct ndigo_trigger

Struct containing trigger settings.

Used by ndigo_configuration::trigger.

Public Members

short threshold

Threshold of both triggers units.

Valid values depend on output mode:

ndigo_bool_t edge

Enable edge trigger functionality.

If true, operate as an edge trigger.

If false, operate as a level trigger.

An edge trigger triggers as soon as its set threshold is crossed by the signal. Thus the roots in reference to the threshold are recorded.

A level trigger triggers as long as the signal is above (or below) the set threshold. Therefore, the trigger gives the sign of the signal in reference to the threshold.

For trigger indices NDIGO_TRIGGER_AUTO and NDIGO_TRIGGER_ONE this is ignored.

For trigger indices NDIGO_TRIGGER_TDC_PE to NDIGO_TRIGGER_BUS3_PE this must be set.

ndigo_bool_t rising

Configure rising or falling edge trigger functionality.

If true (false)

struct ndigo_trigger_block

Configuration of a trigger block.

Used by ndigo_configuration::trigger_block.

Public Members

ndigo_bool_t enabled

Activates triggers on this channel.

ndigo_bool_t force_led

Activates LED on input even if trigger block is not enabled.

Required for LED activity in Multi/SingleShot mode.

ndigo_bool_t retrigger

Enable retriggering.

If a new trigger condition occurs while the postcursor is acquired the packet is extended by starting a new postcursor. Otherwise the new trigger is ignored and the packet ends after the precursor of the first trigger.

The retrigger setting is ignored for the timestamp channel.

ndigo_bool_t reserved1

Reserved. Defaults to false. Do not change.

ndigo_bool_t reserved2

Reserved. Defaults to false. Do not change.

int multi_shot_count

Number of packets created in single shot mode before packet generation stops.

Maximum is NDIGO_MAX_MULTISHOT.

NDIGO_MAX_MULTISHOT 65535

Maximum ndigo_trigger_block::multi_shot_count.

int precursor

Precursor in multiples of the device main clock period (3.2ns).

It is the amount of data preceding a trigger that is captured.

The precursor setting is ignored for the TDC channel.

The maximum allowed value is NDIGO_MAX_PRECURSOR.

NDIGO_MAX_PRECURSOR 25

Maximum of ndigo_trigger_block::precursor.

int length

Length in multiples of the device main clock period (3.2ns).

It corresponds to the total amount of data that is recorded in addition to the trigger window. precursor determines how many of these are ahead of the trigger and how many are appended after the trigger.

In edge trigger mode (see ndigo_trigger::edge), the trigger window is always one main clock cycle wide.

In level trigger mode it is as long as the trigger condition is fulfilled.

The length setting is ignored for the TDC channel.

int sources

A bitmask with a bit set for all trigger sources that can trigger this channel.

The bits correspond to the following defines, where the _PE defines are always triggered by a positive edge in the hardware.

Defaults to a bitmask triggering the current channel.

NDIGO_TRIGGER_SOURCE_NONE 0x00000000
NDIGO_TRIGGER_SOURCE_A0 0x00000001
NDIGO_TRIGGER_SOURCE_A1 0x00000002
NDIGO_TRIGGER_SOURCE_B0 0x00000004
NDIGO_TRIGGER_SOURCE_B1 0x00000008
NDIGO_TRIGGER_SOURCE_C0 0x00000010
NDIGO_TRIGGER_SOURCE_C1 0x00000020
NDIGO_TRIGGER_SOURCE_D0 0x00000040
NDIGO_TRIGGER_SOURCE_D1 0x00000080
NDIGO_TRIGGER_SOURCE_TDC 0x00000100
NDIGO_TRIGGER_SOURCE_GATE 0x00000200
NDIGO_TRIGGER_SOURCE_BUS0 0x00000400
NDIGO_TRIGGER_SOURCE_BUS1 0x00000800
NDIGO_TRIGGER_SOURCE_BUS2 0x00001000
NDIGO_TRIGGER_SOURCE_BUS3 0x00002000
NDIGO_TRIGGER_SOURCE_AUTO 0x00004000
NDIGO_TRIGGER_SOURCE_ONE 0x00008000
NDIGO_TRIGGER_SOURCE_TDC_PE 0x01000000
NDIGO_TRIGGER_SOURCE_GATE_PE 0x02000000
NDIGO_TRIGGER_SOURCE_BUS0_PE 0x04000000
NDIGO_TRIGGER_SOURCE_BUS1_PE 0x08000000
NDIGO_TRIGGER_SOURCE_BUS2_PE 0x10000000
NDIGO_TRIGGER_SOURCE_BUS3_PE 0x20000000

int gates

A bitmask with a bit set for all gates controlling this channel.

The bits correspond to the following defines.

Defaults to NDIGO_TRIGGER_GATE_NONE.

NDIGO_TRIGGER_GATE_NONE 0x0000
NDIGO_TRIGGER_GATE_0 0x0001
NDIGO_TRIGGER_GATE_1 0x0002
NDIGO_TRIGGER_GATE_2 0x0004
NDIGO_TRIGGER_GATE_3 0x0008

double minimum_free_packets

Number of packets that need to fit into the onboard FIFO.

This parameter sets how many packets are supposed to fit into the on-board FIFO before a new packet is recorded after the FIFO was full. That is, a certain amount of free space in the FIFO is demanded before a new packet is written after the FIFO was full.

As a measure for the packet length the gate length (configured by ndigo_gating_block::start and ndigo_gating_block::stop) is used.

The onboard algorithm checks the free FIFO space only in case the FIFO is full. Therefore, if this number is 1.0 or more at least every second packet in the host buffer is guaranteed to have the full length set by the gate length parameters.

In many cases smaller values will also result in full length packets. But below a certain value multiple packets that are cut off at the end will appear.

struct ndigo_gating_block

Contains settings of the gating blocks.

Used by ndigo_configuration::gating_block.

Public Members

ndigo_bool_t negate

Invert output polarity.

Defaults to false.

ndigo_bool_t retrigger

Enable retrigger functionality.

If retriggering is enabled, the timer is reset to the value of the start parameter whenever the input signal is set while waiting to reach the stop time.

Defaults to false.

ndigo_bool_t extend

Currently not implemented. Do not use.

Defaults to true. If set, a gate is created with the set timing from the first occurrence of the input trigger even for short gates. If not set, the input signal must persist for the gate to be created.

ndigo_bool_t reserved1

Defaults to false. Do not change.

int start

The time from the first input signal seen in the idle state until the gating output is set.

start needs to be >=0 and <2^16.

start must be set to a value <= stop.

In multiples of 3.2ns.

int stop

The number of samples from leaving the idle state until the gating output is reset.

If retriggering is enabled the timer is reset to the value of the start parameter whenever the input signal is set while waiting to reach the stop time.

stop needs to be >=0 and <2^16.

In multiples of 3.2ns.

int sources

A bitmask with a bit set for all trigger sources that can trigger this gating block.

The bits correspond to the same defines listed in ndigo_trigger_block::sources.

The gating blocks cannot use the digital trigger as as a source, that is, bitmasks NDIGO_TRIGGER_SOURCE_TDC_PE to NDIGO_TRIGGER_SOURCE_BUS3_PE

struct ndigo_extension_block

Configures the optional extension board.

This structure configures the merging of the inputs from the synchronization bus and the optional extension board.

Used by ndigo_configuration::extension_block.

Public Members

ndigo_bool_t enable

Enables routing of digital signal from the Ndigo extension board.

The signals are routed to the corresponding BUSx trigger unit.

ndigo_bool_t ignore_cable

Control signal routing.

If true, only the signal from Ndigo extension board is used.

If false, input signal and BUS signal are read before routing to the according BUSx trigger unit.