Triggers

Description

Trigger functionality introduced in bladeRF FPGA v0.6.0 allows TX and/or RX samples to be gated via a trigger signal. This allows multiple devices to synchronize their TX/RX operations upon the reception of a trigger event.

The set of functions presented in this section of the API provides control over this triggering functionality. It is intended that these functions be used prior to starting sample streams. Attempting to use these functions while streaming may yield undefined and undesirable behavior.

These functions are thread-safe.

For devices running at the same sample rate, the trigger event should achieve synchronization within +/- 1 sample on each device in the chain.

Note

As of FPGA v0.6.0, mini_exp[1] has been allocated as the trigger signal. However, this API section is designed to allow future signals to be added, including users' software and hardware customizations.

Important: Ensure that you disarm triggers before stopping sample streams (i.e., calling bladerf_enable_module() with enable = false). Otherwise, the operation of shutting down streams will block for the entire duration of the stream timeout (or infinitely if the timeouts were set to 0).

These functions are thread-safe.

The standard usage of these functions is shown below. This example assumes:

• The two devices are connected such they share a common ground and their mini_exp[1] pins are connected. mini_exp[1] is J71-4 on bladeRF x40/x115, and J51-1 on bladeRF xA4/xA5/xA9.
• Both devices are already configured to utilize a common clock signal via the external SMB connection. Generally, this will consist of one device to outputting its reference clock via the SMB clock port, and configuring the other device(s) to use the SMB clock port as a reference clock input. This may be achieved using the bladerf_set_smb_mode() function, found in the SMB clock port control section.

int status;
bladerf_channel channel = BLADERF_CHANNEL_RX(0);
bladerf_trigger_signal signal = BLADERF_TRIGGER_J71_4;
 
// Allocate and initialize a bladerf_trigger structure for each
// trigger in the system.
struct bladerf_trigger trig_master, trig_slave;
 
status = bladerf_trigger_init(dev_master, channel, signal, &trig_master);
if (status == 0) {
    trig_master.role = BLADERF_TRIGGER_ROLE_MASTER;
} else {
    goto handle_error;
}
 
status = bladerf_trigger_init(dev_slave1, channel, signal, &trig_slave);
if (status == 0) {
    master_rx.role = BLADERF_TRIGGER_ROLE_SLAVE;
} else {
    goto handle_error;
}
 
// Arm the triggering functionality on each device
status = bladerf_trigger_arm(dev_master, &trig_master, true, 0, 0);
if (status != 0) {
    goto handle_error;
}
 
status = bladerf_trigger_arm(dev_slave, &trig_slave, true, 0, 0);
if (status != 0) {
    goto handle_error;
}
 
// Call bladerf_sync_config() and bladerf_sync_rx() on each device.
// Ensure the timeout parameters used are long enough to accommodate
// the expected time until the trigger will be fired.
status = start_rx_streams(dev_master, dev_slave);
if (status != 0) {
    goto handle_error;
}
 
// Fire the trigger signal
status = bladerf_trigger_fire(dev_master, &trig_master);
if (status != 0) {
    goto handle_error;
}
 
// Handle RX signals and then shut down streams.
// Synchronized samples should now be reaching the host following the
// reception of the external trigger signal.
status = handle_rx_operations(dev_master, dev_slave);
if (status != 0) {
    goto handle_error;
}
 
// Disable triggering on all devices to restore normal RX operation
trig_master.role = BLADERF_TRIGGER_ROLE_DISABLED;
status = bladerf_trigger_arm(dev_master, &trig_master, false, 0, 0);
if (status != 0) {
    goto handle_error;
}
 
trig_slave.role  = BLADERF_TRIGGER_ROLE_DISABLED;
status = bladerf_trigger_arm(dev_master, &trig_slave, false, 0, 0);
if (status != 0) {
    goto handle_error;
}

Data Structures
struct	bladerf_trigger

Enumerations
enum	bladerf_trigger_role { BLADERF_TRIGGER_ROLE_INVALID = -1 , BLADERF_TRIGGER_ROLE_DISABLED , BLADERF_TRIGGER_ROLE_MASTER , BLADERF_TRIGGER_ROLE_SLAVE }
enum	bladerf_trigger_signal {   BLADERF_TRIGGER_INVALID = -1 , BLADERF_TRIGGER_J71_4 , BLADERF_TRIGGER_J51_1 , BLADERF_TRIGGER_MINI_EXP_1 ,   BLADERF_TRIGGER_USER_0 = 128 , BLADERF_TRIGGER_USER_1 , BLADERF_TRIGGER_USER_2 , BLADERF_TRIGGER_USER_3 ,   BLADERF_TRIGGER_USER_4 , BLADERF_TRIGGER_USER_5 , BLADERF_TRIGGER_USER_6 , BLADERF_TRIGGER_USER_7 }

Functions
API_EXPORT int CALL_CONV	bladerf_trigger_init (struct bladerf *dev, bladerf_channel ch, bladerf_trigger_signal signal, struct bladerf_trigger *trigger)
API_EXPORT int CALL_CONV	bladerf_trigger_arm (struct bladerf *dev, const struct bladerf_trigger *trigger, bool arm, uint64_t resv1, uint64_t resv2)
API_EXPORT int CALL_CONV	bladerf_trigger_fire (struct bladerf *dev, const struct bladerf_trigger *trigger)
API_EXPORT int CALL_CONV	bladerf_trigger_state (struct bladerf *dev, const struct bladerf_trigger *trigger, bool *is_armed, bool *has_fired, bool *fire_requested, uint64_t *resv1, uint64_t *resv2)

Enumeration Type Documentation

bladerf_trigger_role

enum bladerf_trigger_role

This value denotes the role of a device in a trigger chain.

Enumerator
BLADERF_TRIGGER_ROLE_INVALID	Invalid role selection
BLADERF_TRIGGER_ROLE_DISABLED	Triggering functionality is disabled on this device. Samples are not gated and the trigger signal is an input.
BLADERF_TRIGGER_ROLE_MASTER	This device is the trigger master. Its trigger signal will be an output and this device will determine when all devices shall trigger.
BLADERF_TRIGGER_ROLE_SLAVE	This device is the trigger slave. This device's trigger signal will be an input and this devices will wait for the master's trigger signal assertion.

Definition at line 1567 of file libbladeRF.h.

bladerf_trigger_signal

enum bladerf_trigger_signal

Trigger signal selection

This selects pin or signal used for the trigger.

Note

BLADERF_TRIGGER_J71_4, BLADERF_TRIGGER_J51_1, and BLADERF_TRIGGER_MINI_EXP_1 are the only valid options as of FPGA v0.6.0. All three values have the same behavior and may be used interchangably.

The BLADERF_TRIGGER_USER_* values have been added to allow users to modify both hardware and software implementations to add custom triggers, while maintaining libbladeRF API compatibility. Official bladeRF releases will not utilize these user signal IDs.

Enumerator
BLADERF_TRIGGER_INVALID	Invalid selection
BLADERF_TRIGGER_J71_4	J71 pin 4, mini_exp[1] on x40/x115
BLADERF_TRIGGER_J51_1	J51 pin 1, mini_exp[1] on xA4/xA5/xA9
BLADERF_TRIGGER_MINI_EXP_1	mini_exp[1], hardware-independent
BLADERF_TRIGGER_USER_0	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_1	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_2	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_3	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_4	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_5	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_6	Reserved for user SW/HW customizations
BLADERF_TRIGGER_USER_7	Reserved for user SW/HW customizations

Definition at line 1606 of file libbladeRF.h.

Function Documentation

bladerf_trigger_arm()

API_EXPORT int CALL_CONV bladerf_trigger_arm	(	struct bladerf *	dev,
		const struct bladerf_trigger *	trigger,
		bool	arm,
		uint64_t	resv1,
		uint64_t	resv2
	)

Configure and (dis)arm a trigger on the specified device.

Note

If trigger->role is set to BLADERF_TRIGGER_ROLE_DISABLED, this will inherently disarm an armed trigger and clear any fire requests, regardless of the value of arm.

Parameters

	dev	Device to configure
[in]	trigger	Trigger configure
[in]	arm	(Re)Arm trigger if true, disarm if false
[in]	resv1	Reserved for future use. Set to 0.
[in]	resv2	Reserved for future use. Set to 0.

Warning

Configuring two devices in the trigger chain (or both RX and TX on a single device) as masters can damage the associated FPGA pins, as this would cause contention over the trigger signal. Ensure only one device in the chain is configured as the master!

Returns

0 on success, value from Error codes list on failure

bladerf_trigger_fire()

API_EXPORT int CALL_CONV bladerf_trigger_fire	(	struct bladerf *	dev,
		const struct bladerf_trigger *	trigger
	)

Fire a trigger event.

Calling this functiona with a trigger whose role is anything other than BLADERF_TRIGGER_REG_MASTER will yield a BLADERF_ERR_INVAL return value.

Parameters

	dev	Device handle
[in]	trigger	Trigger to assert

Returns

0 on success, value from Error codes list on failure

bladerf_trigger_init()

API_EXPORT int CALL_CONV bladerf_trigger_init	(	struct bladerf *	dev,
		bladerf_channel	ch,
		bladerf_trigger_signal	signal,
		struct bladerf_trigger *	trigger
	)

Initialize a bladerf_trigger structure based upon the current configuration of the specified trigger signal.

While it is possible to simply declare and manually fill in a bladerf_trigger structure, it is recommended to use this function to retrieve the current role and options values.

Parameters

	dev	Device to query
[in]	ch	Channel
[in]	signal	Trigger signal to query
[out]	trigger	Updated to describe trigger

Returns

0 on success, value from Error codes list on failure

bladerf_trigger_state()

API_EXPORT int CALL_CONV bladerf_trigger_state	(	struct bladerf *	dev,
		const struct bladerf_trigger *	trigger,
		bool *	is_armed,
		bool *	has_fired,
		bool *	fire_requested,
		uint64_t *	resv1,
		uint64_t *	resv2
	)

Query the fire request status of a master trigger

Parameters

	dev	Device handle
[in]	trigger	Trigger to query
[out]	is_armed	Set to true if the trigger is armed, and false otherwise. May be NULL.
[out]	has_fired	Set to true if the trigger has fired, and false otherwise. May be NULL.
[out]	fire_requested	Only applicable to a trigger master. Set to true if a fire request has been previously submitted. May be NULL.
[out]	resv1	Reserved for future use. This field is written as 0 if not set to NULL.
[out]	resv2	Reserved for future use. This field is written as 0 if not set to NULL.

Returns

0 on success, value from Error codes list on failure