# enable_event()

Binds one or more event conditions to a user-defined callback function. Upon detection of an event condition, the user-defined function is invoked with board- and event-specific data. Detection of event conditions occurs in response to interrupts. Typically, this function is used in conjunction with interrupt driven processes such as a_in_scan(), a_pretrig(), or a_out_scan().

## Prototype

enable_event(board_num, event_type, event_param, callback_func, c_user_data)

## Parameters

board_num (int)

The number associated with the board when it was installed with InstaCal or created with create_daq_device().

event_type (EventType)

Specifies one or more event conditions that will be bound to the user-defined callback function. More than one event type can be specified by adding the event types. Refer to the constants in the event_type parameter values section below.

event_param (int)

Additional data required to specify some event conditions, such as an EventType.ON_DATA_AVAILABLE event or EventType.ON_EXTERNAL_INTERRUPT event.

For EventType.ON_DATA_AVAILABLE events, event_param is used to determine the minimum number of samples to acquire during an analog input scan before generating the event. For EventType.ON_EXTERNAL_INTERRUPT events, event_param is used to latch digital bits on supported hardware by setting it to one of the constants in the event_param parameter values section below.

Most event conditions ignore this value.

callback_func (ULEventCallback)

A ULEventCallback instance used to handle the above event type(s).

No reference to the ULEventCallback object is stored internally. The ULEventCallback object must remain allocated until no more events will occur, otherwise the next callback will cause a crash. It is up to the user of this function to ensure that Python will not garbage-collect the object. Typically, assigning the ULEventCallback to a member variable or making it a global variable is sufficient.

The function passed to the ULEventCallback constructor should accept four parameters (not including self if it is a member function): board_num, event_type, event_data, c_user_data. Refer to the Callback function parameters section below for more information.

c_user_data

User-defined data that will be passed to the callback function.

The data may be any C type object. Care must be taken to cast back to the same type in the callback method. In most cases, py_object is recommended.

No reference to the c_user_data object is stored internally. It is up to the user of this function to ensure that Python will not garbage-collect the object. Typically, assigning the c_user_data to a member variable is sufficient.

### event_type parameter values

ON_DATA_AVAILABLE | Generates an event whenever the number of samples acquired during an analog input scan increases by event_param samples or more. Note that for BLOCKIO scans, events will be generated on packet transfers; for example, even if event_param is set to 1, events will only be generated every packet-size worth of data for aggregate rates greater than 1 kHz for the default a_in_scan() mode. For a_pretrig(), the first event is not generated until a minimum of EventParam samples after the pretrigger.
ON_END_OF_INPUT_SCAN | Generates an event upon completion or fatal error of a_in_scan() or a_pretrig(). Some devices, such as the USB-1208FS and USB-1408FS, will generate an end of scan event after stop_background() is called, but most devices do not. Handle post-scan tasks directly after calling stop_background.
ON_END_OF_OUTPUT_SCAN | Generates an event upon completion or fatal error of a_out_scan() or a_pretrig(). Some devices, such as the USB-1208FS and USB-1408FS, will generate an end of scan event after stop_background() is called, but most devices do not. Handle post-scan tasks directly after calling stop_background.
ON_EXTERNAL_INTERRUPT | For some digital and counter boards, generates an event upon detection of a pulse at the External Interrupt pin.
ON_PRETRIGGER | For a_pretrig(), generates an event upon detection of the first trigger.
ON_SCAN_ERROR | Generates an event upon detection of a driver error during BACKGROUND input and output scans. This includes OVERRUN, UNDERRUN, and TOOFEW errors.

### event_param parameter values

LATCH_DI | Returns the data that was latched in at the most recent interrupt edge.
LATCH_DO | Latches out the data most recently written to the hardware.

## Callback function parameters

- board_num (int) – Indicates which board caused the event.
- event_type (EventType) – Indicates which event occurred.
- event_data (int) – Board-specific data associated with this event. Returns a value based on the event_type as listed in the Callback event_data parameter values section.

##### Callback event_data parameter values

ON_DATA_AVAILABLE | The number of samples acquired since the start of the scan.
ON_END_OF_INPUT_SCAN | The total number of samples acquired upon the scan completion or end.
ON_END_OF_OUTPUT_SCAN | scan completion or end.
ON_EXTERNAL_INTERRUPT | The number of interrupts generated since enabling the ON_EXTERNAL_INTERRUPT event.
ON_PRETRIGGER | The number of pretrigger samples available at the time of pretrigger. This value is invalid for some boards when a TOOFEW error occurs. Refer to board-specific information.
ON_SCAN_ERROR | The error code of the scan error.

- c_user_data – The C type object supplied by the user_data parameter in enable_event(). Note that before use, this parameter must be cast to the same data type as passed in to enable_event().

## Notes

- This function cannot be called while any background operations (a_in_scan(), a_pretrig(), or a_out_scan()) are active. If a background operation is in progress when enable_event() is called, the function raises a ULError with the error code ErrorCode.ALREADYACTIVE. Perform a stop_background() call before calling enable_event().
- Events will not be generated faster than the user callback function can handle them. If an event type becomes multi-signaled before the event handler returns, events are merged. The event handler is called once per event type, and is supplied with the event data corresponding to the latest event. When more than one event type is generated, the event handler for each event type is called in the same order in which they are enabled.
- Events are generated while handling board-generated interrupts. Therefore, using stop_background() to abort background operations does not generate EventType.ON_END_OF_INPUT_SCAN or EventType.ON_END_OF_OUTPUT_SCAN events. However, the event handlers can be called immediately after calling stop_background().