Python Library Reference

The Python library is organized as a global method for listing the DAQ HAT boards attached to your system, and board-specific classes to provide full functionality for each type of board. The Python package is named daqhats.

Global methods and data

Methods

Method Description
hat_list() Return a list of detected DAQ HAT boards.
interrupt_state() Read the current DAQ HAT interrupt status.
wait_for_interrupt() Wait for a DAQ HAT interrupt to occur.
interrupt_callback_enable() Enable an interrupt callback function.
interrupt_callback_disable() Disable interrupt callback function.
daqhats.hat_list(filter_by_id=0)

Return a list of detected DAQ HAT boards.

Scans certain locations for information from the HAT EEPROMs. Verifies the contents are valid HAT EEPROM contents and returns a list of namedtuples containing information on the HAT. Info will only be returned for DAQ HATs. The EEPROM contents are stored in /etc/mcc/hats when using the daqhats_read_eeproms tool, or in /proc/device-tree in the case of a single HAT at address 0.

Parameters:filter_by_id (int) – If this is HatIDs.ANY return all DAQ HATs found. Otherwise, return only DAQ HATs with ID matching this value.
Returns:A list of namedtuples, the number of elements match the number of DAQ HATs found. Each namedtuple will contain the following field names:
  • address (int): device address
  • id (int): device product ID, identifies the type of DAQ HAT
  • version (int): device hardware version
  • product_name (str): device product name
Return type:list
daqhats.interrupt_state()

Read the current DAQ HAT interrupt status

Returns the status of the interrupt signal, True if active or False if inactive. The signal can be shared by multiple DAQ HATs so the status of each board that may generate an interrupt must be read and the interrupt source(s) cleared before the interrupt will become inactive.

This function only applies when using devices that can generate an interrupt:

  • MCC 152
Returns:The interrupt status.
Return type:bool
daqhats.wait_for_interrupt(timeout)

Wait for an interrupt from a DAQ HAT to occur.

Pass a timeout in seconds. Pass -1 to wait forever or 0 to return immediately. If the interrupt has not occurred before the timeout elapses the function will return False.

This function only applies when using devices that can generate an interrupt:

  • MCC 152
Returns:The interrupt status - True = interrupt active, False = interrupt inactive.
Return type:bool
daqhats.interrupt_callback_enable(callback, user_data)

Enable an interrupt callback function.

Set a function that will be called when a DAQ HAT interrupt occurs.

The function will be called when the DAQ HAT interrupt signal becomes active, and cannot be called again until the interrupt signal becomes inactive. Active sources become inactive when manually cleared (such as reading the digital I/O inputs or clearing the interrupt enable.) If not latched, an active source also becomes inactive when the value returns to the original value (the value at the source before the interrupt was generated.)

There may only be one callback function at a time; if you call this when a function is already set as the callback function then it will be replaced with the new function and the old function will no longer be called if an interrupt occurs. The data argument to this function will be passed to the callback function when it is called.

The callback function must have the form “callback(user_data)”. For example:

def my_function(data):
    # This is my callback function.
    print("The interrupt occurred, and returned {}.".format(data))
    data[0] += 1

value = [0]
interrupt_enable_callback(my_function, value)

In this example my_function() will be called when the interrupt occurs, and the list value will be passed as the user_data. Inside the callback it will be received as data, but will still be the same object so any changes made will be present in the original value. Every time the interrupt occurs value[0] will be incremented and a higher number will be printed.

An integer was not used for value because integers are immutable in Python so the original value would never change.

The callback may be disabled with interrupt_callback_disable().

This function only applies when using devices that can generate an interrupt:

  • MCC 152
Parameters:
  • callback (callback function) – The callback function.
  • user_data (object) – callback function.
Raises:

Exception – Internal error enabling the callback.

daqhats.interrupt_callback_disable()

Disable interrupt callbacks.

Raises:Exception – Internal error disabling the callback.

Data

Hat IDs

class daqhats.HatIDs

Known MCC HAT IDs.

ANY = 0

Match any MCC ID in hat_list()

MCC_118 = 322

MCC 118 ID

MCC_128 = 326

MCC 128 ID

MCC_134 = 323

MCC 134 ID

MCC_152 = 324

MCC 152 ID

MCC_172 = 325

MCC 172 ID

Trigger modes

class daqhats.TriggerModes

Scan trigger input modes.

RISING_EDGE = 0

Start the scan on a rising edge of TRIG.

FALLING_EDGE = 1

Start the scan on a falling edge of TRIG.

ACTIVE_HIGH = 2

Start the scan any time TRIG is high.

ACTIVE_LOW = 3

Start the scan any time TRIG is low.

Scan / read option flags

class daqhats.OptionFlags

Scan / read option flags. See individual methods for detailed descriptions.

DEFAULT = 0

Use default behavior.

NOSCALEDATA = 1

Read / write unscaled data.

NOCALIBRATEDATA = 2

Read / write uncalibrated data.

EXTCLOCK = 4

Use an external clock source.

EXTTRIGGER = 8

Use an external trigger source.

CONTINUOUS = 16

Run until explicitly stopped.

TEMPERATURE = 32

Return temperature (MCC 134)

HatError class

exception daqhats.HatError(address, value)

Exceptions raised for MCC DAQ HAT specific errors.

Parameters:
  • address (int) – the address of the board that caused the exception.
  • value (str) – the exception description.

MCC 118 class

Methods

class daqhats.mcc118(address=0)

The class for an MCC 118 board.

Parameters:address (int) – board address, must be 0-7.
Raises:HatError – the board did not respond or was of an incorrect type

Methods

Method Description
mcc118.info() Get info about this device type.
mcc118.firmware_version() Get the firmware version.
mcc118.serial() Read the serial number.
mcc118.blink_led() Blink the MCC 118 LED.
mcc118.calibration_date() Read the calibration date.
mcc118.calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc118.calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc118.trigger_mode() Set the external trigger input mode.
mcc118.a_in_read() Read an analog input channel.
mcc118.a_in_scan_actual_rate() Read the actual sample rate for a requested sample rate.
mcc118.a_in_scan_start() Start a hardware-paced analog input scan.
mcc118.a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc118.a_in_scan_read() Read scan status / data (list).
mcc118.a_in_scan_read_numpy() Read scan status / data (NumPy array).
mcc118.a_in_scan_channel_count() Get the number of channels in the current scan.
mcc118.a_in_scan_stop() Stop the scan.
mcc118.a_in_scan_cleanup() Free scan resources.
mcc118.address() Read the board’s address.
static info()

Return constant information about this type of device.

Returns:A namedtuple containing the following field names:
  • NUM_AI_CHANNELS (int): The number of analog input channels (8.)
  • AI_MIN_CODE (int): The minimum ADC code (0.)
  • AI_MAX_CODE (int): The maximum ADC code (4095.)
  • AI_MIN_VOLTAGE (float): The voltage corresponding to the minimum ADC code (-10.0.)
  • AI_MAX_VOLTAGE (float): The voltage corresponding to the maximum ADC code (+10.0 - 1 LSB)
  • AI_MIN_RANGE (float): The minimum voltage of the input range (-10.0.)
  • AI_MAX_RANGE (float): The maximum voltage of the input range (+10.0.)
Return type:namedtuple
firmware_version()

Read the board firmware and bootloader versions.

Returns:A namedtuple containing the following field names:
  • version (string): The firmware version, i.e “1.03”.
  • bootloader_version (string): The bootloader version, i.e “1.01”.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
serial()

Read the serial number.

Returns:The serial number.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.

Blink the MCC 118 LED.

Setting count to 0 will cause the LED to blink continuously until blink_led() is called again with a non-zero count.

Parameters:count (int) – The number of times to blink (max 255).
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_date()

Read the calibration date.

Returns:The calibration date in the format “YYYY-MM-DD”.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_read(channel)

Read the calibration coefficients for a single channel.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:channel (int) – The analog input channel (0-7.)
Returns:A namedtuple containing the following field names.
  • slope (float): The slope.
  • offset (float): The offset.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_write(channel, slope, offset)

Temporarily write the calibration coefficients for a single channel.

The user can apply their own calibration coefficients by writing to these values. The values will reset to the factory values from the EEPROM whenever the class is initialized. This function will fail and raise a HatError exception if a scan is active when it is called.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:
  • channel (int) – The analog input channel (0-7.)
  • slope (float) – The new slope value.
  • offset (float) – The new offset value.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

trigger_mode(mode)

Set the external trigger input mode.

The available modes are:

Parameters:mode (TriggerModes) – The trigger mode.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_read(channel, options=<OptionFlags.DEFAULT: 0>)

Perform a single reading of an analog input channel and return the value.

options is an ORed combination of OptionFlags. Valid flags for this method are:

Parameters:
Returns:

The read value.

Return type:

float

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – the channel number is invalid.
a_in_scan_actual_rate(channel_count, sample_rate_per_channel)

Read the actual sample rate per channel for a requested sample rate.

The internal scan clock is generated from a 16 MHz clock source so only discrete frequency steps can be achieved. This function will return the actual rate for a requested channel count and rate setting.

This function does not perform any actions with a board, it simply calculates the rate.

Parameters:
  • channel_count (int) – The number of channels in the scan, 1-8.
  • sample_rate_per_channel (float) – The desired per-channel rate of the internal sampling clock, max 100,000.0.
Returns:

The actual sample rate.

Return type:

float

Raises:

ValueError – a scan argument is invalid.

a_in_scan_start(channel_mask, samples_per_channel, sample_rate_per_channel, options)

Start a hardware-paced analog input channel scan.

The scan runs as a separate thread from the user’s code. This function will allocate a scan buffer and start the thread that reads data from the device into that buffer. The user reads the data from the scan buffer and the scan status using the a_in_scan_read() function. a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call a_in_scan_cleanup() after the scan has finished and all desired data has been read; this frees all resources from the scan and allows additional scans to be performed.

The scan state has defined terminology:

  • Active: a_in_scan_start() has been called and the device may be acquiring data or finished with the acquisition. The scan has not been cleaned up by calling a_in_scan_cleanup(), so another scan may not be started.
  • Running: The scan is active and the device is still acquiring data. Certain methods like a_in_read() will return an error because the device is busy.

The scan options that may be used are:

  • OptionFlags.DEFAULT: Return scaled and calibrated data, internal scan clock, no trigger, and finite operation. Any other flags will override DEFAULT behavior.
  • OptionFlags.NOSCALEDATA: Return ADC codes (values between 0 and 4095) rather than voltage.
  • OptionFlags.NOCALIBRATEDATA: Return data without the calibration factors applied.
  • OptionFlags.EXTCLOCK: Use an external 3.3V or 5V logic signal at the CLK input as the scan clock. Multiple devices can be synchronized by connecting the CLK pins together and using this flag on all but one device so they will be clocked by the single device using its internal clock. sample_rate_per_channel is only used for buffer sizing.
  • OptionFlags.EXTTRIGGER: Hold off the scan (after calling a_in_scan_start()) until the trigger condition is met. The trigger is a 3.3V or 5V logic signal applied to the TRIG pin.
  • OptionFlags.CONTINUOUS: Scans continuously until stopped by the user by calling a_in_scan_stop() and writes data to a circular buffer. The data must be read before being overwritten to avoid a buffer overrun error. samples_per_channel is only used for buffer sizing.

The scan buffer size will be allocated as follows:

Finite mode: Total number of samples in the scan.

Continuous mode: Either samples_per_channel or the value in the table below, whichever is greater.

Sample Rate Buffer Size (per channel)
Not specified 10 kS
0-100 S/s 1 kS
100-10k S/s 10 kS
10k-100k S/s 100 kS

Specifying a very large value for samples_per_channel could use too much of the Raspberry Pi memory. If the memory allocation fails, the function will raise a HatError with this description. The allocation could succeed, but the lack of free memory could cause other problems in the Raspberry Pi. If you need to acquire a high number of samples then it is better to run the scan in continuous mode and stop it when you have acquired the desired amount of data. If a scan is active this method will raise a HatError.

Parameters:
  • channel_mask (int) – A bit mask of the desired channels (0x01 - 0xFF).
  • samples_per_channel (int) – The number of samples to acquire per channel (finite mode,) or or can be used to set a larger scan buffer size than the default value (continuous mode.)
  • sample_rate_per_channel (float) – The per-channel rate of the internal scan clock, or the expected maximum rate of an external scan clock, max 100,000.0.
  • options (int) – An ORed combination of OptionFlags flags that control the scan.
Raises:
  • HatError – a scan is active; memory could not be allocated; the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – a scan argument is invalid.
a_in_scan_buffer_size()

Read the internal scan data buffer size.

An internal data buffer is allocated for the scan when a_in_scan_start() is called. This function returns the total size of that buffer in samples.

Returns:The buffer size in samples.
Return type:int
Raises:HatError – the board is not initialized or no scan buffer is allocated (a scan is not active).
a_in_scan_status()

Read scan status and number of available samples per channel.

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and the number of samples per channel available in the scan thread buffer.

Returns:A namedtuple containing the following field names:
  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • samples_available (int): The number of samples per channel currently in the scan buffer.
Return type:namedtuple
Raises:HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_read(samples_per_channel, timeout)

Read scan status and data (as a list).

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and optionally reads sampled data from the scan buffer.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to return all available samples immediately and ignore timeout or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer (up to samples_per_channel.) If the timeout is met and the specified number of samples have not been read, then the function will return all the available samples and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (list of float): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_read_numpy(samples_per_channel, timeout)

Read scan status and data (as a NumPy array).

This function is similar to a_in_scan_read() except that the data key in the returned namedtuple is a NumPy array of float64 values and may be used directly with NumPy functions.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to read all available samples or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer. If the timeout is met and the specified number of samples have not been read, then the function will return with the amount that has been read and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (NumPy array of float64): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_channel_count()

Read the number of channels in the current analog input scan.

Returns:The number of channels (0 if no scan is active, 1-8 otherwise.)
Return type:int
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_stop()

Stops an analog input scan.

The device stops acquiring data immediately. The scan data that has been read into the scan buffer is available until a_in_scan_cleanup() is called.

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_cleanup()

Free analog input scan resources after the scan is complete.

This will free the scan buffer and other resources used by the background scan and make it possible to start another scan with a_in_scan_start().

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
address()

Return the device address.

MCC 128 class

Methods

class daqhats.mcc128(address=0)

The class for an MCC 128 board.

Parameters:address (int) – board address, must be 0-7.
Raises:HatError – the board did not respond or was of an incorrect type

Methods

Method Description
mcc128.info() Get info about this device type.
mcc128.firmware_version() Get the firmware version.
mcc128.serial() Read the serial number.
mcc128.blink_led() Blink the MCC 128 LED.
mcc128.calibration_date() Read the calibration date.
mcc128.calibration_coefficient_read() Read the calibration coefficients for a mode/range.
mcc128.calibration_coefficient_write() Write the calibration coefficients for a mode/range.
mcc128.trigger_mode() Set the external trigger input mode.
mcc128.a_in_mode_read() Read the analog input mode.
mcc128.a_in_mode_write() Write the analog input mode.
mcc128.a_in_range_read() Read the analog input range.
mcc128.a_in_range_write() Write the analog input range.
mcc128.a_in_read() Read an analog input channel.
mcc128.a_in_scan_actual_rate() Read the actual sample rate for a requested sample rate.
mcc128.a_in_scan_start() Start a hardware-paced analog input scan.
mcc128.a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc128.a_in_scan_read() Read scan status / data (list).
mcc128.a_in_scan_read_numpy() Read scan status / data (NumPy array).
mcc128.a_in_scan_channel_count() Get the number of channels in the current scan.
mcc128.a_in_scan_stop() Stop the scan.
mcc128.a_in_scan_cleanup() Free scan resources.
mcc128.address() Read the board’s address.
static info()

Return constant information about this type of device.

Returns:A namedtuple containing the following field names:
  • NUM_AI_MODES (int): The number of analog input modes (2.)
  • NUM_AI_CHANNELS (list of int): The number of analog input channels for each mode (8, 4.)
  • AI_MIN_CODE (int): The minimum ADC code (0.)
  • AI_MAX_CODE (int): The maximum ADC code (65535.)
  • NUM_AI_RANGES (int): The number of analog input ranges (4.)
  • AI_MIN_VOLTAGE (list of float): The voltage corresponding to the minimum ADC code for each range (-10.0, -5.0, -2.0, -1.0.)
  • AI_MAX_VOLTAGE (list of float): The voltage corresponding to the maximum ADC code for each range (+10.0 - 1 LSB, +5.0 - 1 LSB, +2.0 - 1 LSB, +1.0 - 1 LSB.)
  • AI_MIN_RANGE (list of float): The minimum voltage of the input range for each range (-10.0, -5.0, -2.0, -1.0.)
  • AI_MAX_RANGE (list of float): The maximum voltage of the input range for each range (+10.0, +5.0, +2.0, +1.0.)
Return type:namedtuple
firmware_version()

Read the board firmware version.

Returns:A namedtuple containing the following field names:
  • version (string): The firmware version, i.e “1.03”.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
serial()

Read the serial number.

Returns:The serial number.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.

Blink the MCC 128 LED.

Setting count to 0 will cause the LED to blink continuously until blink_led() is called again with a non-zero count.

Parameters:count (int) – The number of times to blink (max 255).
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_date()

Read the calibration date.

Returns:The calibration date in the format “YYYY-MM-DD”.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_read(a_in_range)

Read the calibration coefficients for a specified input range.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:a_in_range (AnalogInputRange) – The input range.
Returns:A namedtuple containing the following field names:
  • slope (float): The slope.
  • offset (float): The offset.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_write(a_in_range, slope, offset)

Temporarily write the calibration coefficients for a specified input range.

The user can apply their own calibration coefficients by writing to these values. The values will reset to the factory values from the EEPROM whenever the class is initialized. This function will fail and raise a HatError exception if a scan is active when it is called.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:
  • a_in_range (AnalogInputRange) – The input range.
  • slope (float) – The new slope value.
  • offset (float) – The new offset value.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

trigger_mode(mode)

Set the external trigger input mode.

The available modes are:

Parameters:mode (TriggerModes) – The trigger mode.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_mode_write(a_in_mode)

This sets the analog input mode to one of the valid values:

Parameters:a_in_mode (AnalogInputMode) – The input mode.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_mode_read()

Read the analog input mode.

Reads the current analog input mode.

Returns:The current analog input mode.
Return type:AnalogInputMode
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_range_write(a_in_range)

This sets the analog input range to one of the valid values:

Parameters:a_in_range (AnalogInputRange) – The input range.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_range_read()

Read the analog input range.

Reads the current analog input range.

Returns:The current analog input range.
Return type:AnalogInputRange
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_read(channel, options=<OptionFlags.DEFAULT: 0>)

Perform a single reading of an analog input channel and return the value.

options is an ORed combination of OptionFlags. Valid flags for this method are:

Parameters:
Returns:

The read value.

Return type:

float

Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

a_in_scan_actual_rate(channel_count, sample_rate_per_channel)

Read the actual sample rate per channel for a requested sample rate.

The internal scan clock is generated from a 16 MHz clock source so only discrete frequency steps can be achieved. This function will return the actual rate for a requested channel count and rate setting.

This function does not perform any actions with a board, it simply calculates the rate.

Parameters:
  • channel_count (int) – The number of channels in the scan, 1-8.
  • sample_rate_per_channel (float) – The desired per-channel rate of the internal sampling clock, max 100,000.0.
Returns:

The actual sample rate.

Return type:

float

Raises:

ValueError – a scan argument is invalid.

a_in_scan_start(channel_mask, samples_per_channel, sample_rate_per_channel, options)

Start a hardware-paced analog input channel scan.

The scan runs as a separate thread from the user’s code. This function will allocate a scan buffer and start the thread that reads data from the device into that buffer. The user reads the data from the scan buffer and the scan status using the a_in_scan_read() function. a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call a_in_scan_cleanup() after the scan has finished and all desired data has been read; this frees all resources from the scan and allows additional scans to be performed.

The scan state has defined terminology:

  • Active: a_in_scan_start() has been called and the device may be acquiring data or finished with the acquisition. The scan has not been cleaned up by calling a_in_scan_cleanup(), so another scan may not be started.
  • Running: The scan is active and the device is still acquiring data. Certain methods like a_in_read() will return an error because the device is busy.

The scan options that may be used are:

  • OptionFlags.DEFAULT: Return scaled and calibrated data, internal scan clock, no trigger, and finite operation. Any other flags will override DEFAULT behavior.
  • OptionFlags.NOSCALEDATA: Return ADC codes (values between 0 and 65535) rather than voltage.
  • OptionFlags.NOCALIBRATEDATA: Return data without the calibration factors applied.
  • OptionFlags.EXTCLOCK: Use an external 3.3V or 5V logic signal at the CLK input as the scan clock. Multiple devices can be synchronized by connecting the CLK pins together and using this flag on all but one device so they will be clocked by the single device using its internal clock. sample_rate_per_channel is only used for buffer sizing.
  • OptionFlags.EXTTRIGGER: Hold off the scan (after calling a_in_scan_start()) until the trigger condition is met. The trigger is a 3.3V or 5V logic signal applied to the TRIG pin.
  • OptionFlags.CONTINUOUS: Scans continuously until stopped by the user by calling a_in_scan_stop() and writes data to a circular buffer. The data must be read before being overwritten to avoid a buffer overrun error. samples_per_channel is only used for buffer sizing.

The scan buffer size will be allocated as follows:

Finite mode: Total number of samples in the scan.

Continuous mode: Either samples_per_channel or the value in the table below, whichever is greater.

Sample Rate Buffer Size (per channel)
Not specified 10 kS
0-100 S/s 1 kS
100-10k S/s 10 kS
10k-100k S/s 100 kS

Specifying a very large value for samples_per_channel could use too much of the Raspberry Pi memory. If the memory allocation fails, the function will raise a HatError with this description. The allocation could succeed, but the lack of free memory could cause other problems in the Raspberry Pi. If you need to acquire a high number of samples then it is better to run the scan in continuous mode and stop it when you have acquired the desired amount of data. If a scan is active this method will raise a HatError.

Parameters:
  • channel_mask (int) – A bit mask of the desired channels (0x01 - 0xFF).
  • samples_per_channel (int) – The number of samples to acquire per channel (finite mode,) or or can be used to set a larger scan buffer size than the default value (continuous mode.)
  • sample_rate_per_channel (float) – The per-channel rate of the internal scan clock, or the expected maximum rate of an external scan clock, max 100,000.0.
  • options (int) – An ORed combination of OptionFlags flags that control the scan.
Raises:
  • HatError – a scan is active; memory could not be allocated; the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – a scan argument is invalid.
a_in_scan_buffer_size()

Read the internal scan data buffer size.

An internal data buffer is allocated for the scan when a_in_scan_start() is called. This function returns the total size of that buffer in samples.

Returns:The buffer size in samples.
Return type:int
Raises:HatError – the board is not initialized or no scan buffer is allocated (a scan is not active).
a_in_scan_status()

Read scan status and number of available samples per channel.

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and the number of samples per channel available in the scan thread buffer.

Returns:A namedtuple containing the following field names:
  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • samples_available (int): The number of samples per channel currently in the scan buffer.
Return type:namedtuple
Raises:HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_read(samples_per_channel, timeout)

Read scan status and data (as a list).

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and optionally reads sampled data from the scan buffer.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to return all available samples immediately and ignore timeout or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer (up to samples_per_channel.) If the timeout is met and the specified number of samples have not been read, then the function will return all the available samples and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (list of float): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_read_numpy(samples_per_channel, timeout)

Read scan status and data (as a NumPy array).

This function is similar to a_in_scan_read() except that the data key in the returned namedtuple is a NumPy array of float64 values and may be used directly with NumPy functions.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to read all available samples or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer. If the timeout is met and the specified number of samples have not been read, then the function will return with the amount that has been read and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (NumPy array of float64): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_channel_count()

Read the number of channels in the current analog input scan.

Returns:The number of channels (0 if no scan is active, 1-8 otherwise.)
Return type:int
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_stop()

Stops an analog input scan.

The device stops acquiring data immediately. The scan data that has been read into the scan buffer is available until a_in_scan_cleanup() is called.

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_cleanup()

Free analog input scan resources after the scan is complete.

This will free the scan buffer and other resources used by the background scan and make it possible to start another scan with a_in_scan_start().

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
address()

Return the device address.

Data

Analog input modes

class daqhats.AnalogInputMode

Analog input modes.

SE = 0

Single-ended mode.

DIFF = 1

Differential mode.

Analog input ranges

class daqhats.AnalogInputRange

Analog input ranges.

BIP_10V = 0

+/- 10V input range.

BIP_5V = 1

+/- 5V input range.

BIP_2V = 2

+/- 2V input range.

BIP_1V = 3

+/- 1V input range

MCC 134 class

Methods

class daqhats.mcc134(address=0)

The class for an MCC 134 board.

Parameters:address (int) – board address, must be 0-7.
Raises:HatError – the board did not respond or was of an incorrect type

Methods

Method Description
mcc134.info() Get info about this device type.
mcc134.serial() Read the serial number.
mcc134.calibration_date() Read the calibration date.
mcc134.calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc134.calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc134.tc_type_write() Write the thermocouple type for a channel.
mcc134.tc_type_read() Read the thermocouple type for a channel.
mcc134.update_interval_write() Write the temperature update interval.
mcc134.update_interval_read() Read the temperature update interval.
mcc134.t_in_read() Read a temperature input channel.
mcc134.a_in_read() Read an analog input channel.
mcc134.cjc_read() Read a CJC temperature
mcc134.address() Read the board’s address.
OPEN_TC_VALUE = -9999.0

Return value for an open thermocouple.

OVERRANGE_TC_VALUE = -8888.0

Return value for thermocouple voltage outside the valid range.

COMMON_MODE_TC_VALUE = -7777.0

Return value for thermocouple input outside the common-mode range.

static info()

Return constant information about this type of device.

Returns:A namedtuple containing the following field names:
  • NUM_AI_CHANNELS (int): The number of analog input channels (4.)
  • AI_MIN_CODE (int): The minimum ADC code (-8,388,608.)
  • AI_MAX_CODE (int): The maximum ADC code (8,388,607.)
  • AI_MIN_VOLTAGE (float): The voltage corresponding to the minimum ADC code (-0.078125.)
  • AI_MAX_VOLTAGE (float): The voltage corresponding to the maximum ADC code (+0.078125 - 1 LSB)
  • AI_MIN_RANGE (float): The minimum voltage of the input range (-0.078125.)
  • AI_MAX_RANGE (float): The maximum voltage of the input range (+0.078125.)
Return type:namedtuple
serial()

Read the serial number.

Returns:The serial number.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_date()

Read the calibration date.

Returns:The calibration date in the format “YYYY-MM-DD”.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_read(channel)

Read the calibration coefficients for a single channel.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:channel (int) – The thermocouple channel (0-3.)
Returns:A namedtuple containing the following field names:
  • slope (float): The slope.
  • offset (float): The offset.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_write(channel, slope, offset)

Temporarily write the calibration coefficients for a single channel.

The user can apply their own calibration coefficients by writing to these values. The values will reset to the factory values from the EEPROM whenever the class is initialized.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code * slope) + offset
Parameters:
  • channel (int) – The thermocouple channel (0-3.)
  • slope (float) – The new slope value.
  • offset (float) – The new offset value.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

tc_type_write(channel, tc_type)

Write the thermocouple type for a channel.

Enables a channel and tells the library what thermocouple type is connected to the channel. This is needed for correct temperature calculations. The type is one of TcTypes and the board will default to all channels disabled (set to TcTypes.DISABLED) when it is first opened.

Parameters:
  • channel (int) – The analog input channel number, 0-3.
  • tc_type (TcTypes) – The thermocouple type.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

tc_type_read(channel)

Read the thermocouple type for a channel.

Reads the current thermocouple type for the specified channel. The type is one of TcTypes and the board will default to all channels disable (set to TcTypes.DISABLED) when it is first opened.

Parameters:channel (int) – The analog input channel number, 0-3.
Returns
int: The thermocouple type.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
update_interval_write(interval)

Write the temperature update interval.

Tells the MCC 134 library how often to update temperatures, with the interval specified in seconds. The library defaults to updating every second, but you may increase this interval if you do not plan to call t_in_read() very often. This will reduce the load on shared resources for other DAQ HATs.

Parameters:interval (int) – The interval in seconds, 1 - 255.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
update_interval_read()

Read the temperature update interval.

Reads the library temperature update rate in seconds.

Returns
int: The update interval.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
t_in_read(channel)

Read a thermocouple input channel temperature.

The channel must be enabled with tc_type_write() or the method will raise a ValueError exception.

This method returns immediately with the most recent temperature reading for the specified channel. When a board is open, the library will read each channel approximately once per second. There will be a delay when the board is first opened because the read thread has to read the cold junction compensation sensors and thermocouple inputs before it can return the first value.

The method returns the value as degrees Celsius. The temperature value can have some special values for abnormal conditions:

Parameters:

channel (int) – The analog input channel number, 0-3.

Returns:

The thermocouple temperature.

Return type:

float

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – the channel number is invalid or the channel is disabled.
a_in_read(channel, options=<OptionFlags.DEFAULT: 0>)

Read an analog input channel and return the value.

The channel must be enabled with tc_type_write() or the method will raise a ValueError exception.

The returned voltage can have a special value to indicate abnormal conditions:

  • mcc134.COMMON_MODE_TC_VALUE if a common-mode voltage error is detected. This occurs when thermocouples on the same MCC 134 are at different voltages.

options is an ORed combination of OptionFlags. Valid flags for this method are:

Parameters:
Returns:

The read value.

Return type:

float

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – the channel number is invalid.
cjc_read(channel)

Read the cold junction compensation temperature for a specified channel.

Reads the cold junction sensor temperature for the specified thermocouple terminal. The library automatically performs cold junction compensation, so this function is only needed for informational use or if you want to perform your own compensation. The temperature is returned in degress C.

Parameters:

channel (int) – The analog input channel number, 0-3.

Returns:

The read value.

Return type:

float

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – the channel number is invalid.
address()

Return the device address.

Data

Thermocouple types

class daqhats.TcTypes

Thermocouple types.

TYPE_J = 0

Type J

TYPE_K = 1

Type K

TYPE_T = 2

Type T

TYPE_E = 3

Type E

TYPE_R = 4

Type R

TYPE_S = 5

Type S

TYPE_B = 6

Type B

TYPE_N = 7

Type N

DISABLED = 255

Disabled

MCC 152 class

Methods

class daqhats.mcc152(address=0)

The class for an MCC 152 board.

Parameters:address (int) – board address, must be 0-7.
Raises:HatError – the board did not respond or was of an incorrect type

Methods

Method Description
mcc152.info() Get info about this device type.
mcc152.serial() Read the serial number.
mcc152.a_out_write() Write an analog output channel.
mcc152.a_out_write_all() Write all analog output channels.
mcc152.dio_reset() Reset the digital I/O to the default configuration.
mcc152.dio_input_read_bit() Read a digital input.
mcc152.dio_input_read_port() Read all digital inputs.
mcc152.dio_input_read_tuple() Read all digital inputs as a tuple.
mcc152.dio_output_write_bit() Write a digital output.
mcc152.dio_output_write_port() Write all digital outputs.
mcc152.dio_output_write_dict() Write multiple digital outputs with a dictionary.
mcc152.dio_output_read_bit() Read the state of a digital output.
mcc152.dio_output_read_port() Read the state of all digital outputs.
mcc152.dio_output_read_tuple() Read the state of all digital outputs as a tuple.
mcc152.dio_int_status_read_bit() Read the interrupt status for a single channel.
mcc152.dio_int_status_read_port() Read the interrupt status for all channels.
mcc152.dio_int_status_read_tuple() Read the interrupt status for all channels as a tuple.
mcc152.dio_config_write_bit() Write a digital I/O configuration item value for a single channel.
mcc152.dio_config_write_port() Write a digital I/O configuration item value for all channels.
mcc152.dio_config_write_dict() Write a digital I/O configuration item value for multiple channels.
mcc152.dio_config_read_bit() Read a digital I/O configuration item value for a single channel.
mcc152.dio_config_read_port() Read a digital I/O configuration item value for all channels.
mcc152.dio_config_read_tuple() Read a digital I/O configuration item value for all channels as a tuple.
mcc152.address() Read the board’s address.
static info()

Return constant information about this type of device.

Returns:A namedtuple containing the following field names:
  • NUM_DIO_CHANNELS (int): The number of digital I/O channels (8.)
  • NUM_AO_CHANNELS (int): The number of analog output channels (2.)
  • AO_MIN_CODE (int): The minimum DAC code (0.)
  • AO_MAX_CODE (int): The maximum DAC code (4095.)
  • AO_MIN_VOLTAGE (float): The voltage corresponding to the minimum DAC code (0.0.)
  • AO_MAX_VOLTAGE (float): The voltage corresponding to the maximum DAC code (+5.0 - 1 LSB)
  • AO_MIN_RANGE (float): The minimum voltage of the output range (0.0.)
  • AO_MAX_RANGE (float): The maximum voltage of the output range (+5.0.)
Return type:namedtuple
serial()

Read the serial number.

Returns:The serial number.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_out_write(channel, value, options=<OptionFlags.DEFAULT: 0>)

Write a single analog output channel value. The value will be limited to the range of the DAC without raising an exception.

options is an OptionFlags value. Valid flags for this method are:

Parameters:
  • channel (int) – The analog output channel number, 0-1.
  • value (float) – The value to write.
  • options (int) – An OptionFlags value, OptionFlags.DEFAULT if unspecified.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
a_out_write_all(values, options=<OptionFlags.DEFAULT: 0>)

Write all analog output channels simultaneously.

options is an OptionFlags value. Valid flags for this method are:

Parameters:
  • values (list of float) – The values to write, in channel order. There must be at least two values, but only the first two will be used.
  • options (int) – An OptionFlags value, OptionFlags.DEFAULT if unspecified.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_reset()

Reset the DIO to the default configuration.

  • All channels input
  • Output registers set to 1
  • Input inversion disabled
  • No input latching
  • Pull-up resistors enabled
  • All interrupts disabled
  • Push-pull output type
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_input_read_bit(channel)

Read a single digital input channel.

Returns 0 if the input is low, 1 if it is high.

If the specified channel is configured as an output this will return the value present at the terminal.

This method reads the entire input register even though a single channel is specified, so care must be taken when latched inputs are enabled. If a latched input changes between input reads then changes back to its original value, the next input read will report the change to the first value then the following read will show the original value. If another input is read then this input change could be missed so it is best to use dio_input_read_port() or dio_input_read_tuple() when using latched inputs.

Parameters:

channel (int) – The DIO channel number, 0-7.

Returns:

The input value.

Return type:

int

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_input_read_port()

Read all digital input channels.

Returns the values as an integer with a value of 0 - 255. Each channel is represented by a bit in the integer (bit 0 is channel 0, etc.)

The value of a specific input can be found by examining the bit at that location. For example, to act on the channel 3 input:

inputs = mcc152.dio_input_read_port()
if (inputs & (1 << 3)) == 0:
    print("channel 3 is 0")
else:
    print("channel 3 is 1")

If a channel is configured as an output this will return the value present at the terminal.

Care must be taken when latched inputs are enabled. If a latched input changes between input reads then changes back to its original value, the next input read will report the change to the first value then the following read will show the original value.

Returns
int: The input values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_input_read_tuple()

Read all digital inputs at once as a tuple.

Returns a tuple of all input values in channel order. For example, to compare the channel 1 input to the channel 3 input:

inputs = mcc152.dio_input_read_tuple()
if inputs[1] == inputs[3]:
    print("channel 1 and channel 3 inputs are the same")

If a channel is configured as an output this will return the value present at the terminal.

Care must be taken when latched inputs are enabled. If a latched input changes between input reads then changes back to its original value, the next input read will report the change to the first value then the following read will show the original value.

Returns
tuple of int: The input values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_output_write_bit(channel, value)

Write a single digital output channel.

If the specified channel is configured as an input this will not have any effect at the terminal, but allows the output register to be loaded before configuring the channel as an output.

Parameters:
  • channel (int) – The digital channel number, 0-7.
  • value (int) – The output value, 0 or 1.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_output_write_port(values)

Write all digital output channel values.

Pass an integer in the range of 0 - 255, where each bit represents the value of the associated channel (bit 0 is channel 0, etc.) If a specified channel is configured as an input this will not have any effect at the terminal, but allows the output register to be loaded before configuring the channel as an output.

To change specific outputs without affecting other outputs first read the output values with dio_output_read_port(), change the desired bits in the result, then write them back.

For example, to set channels 0 and 2 to 1 without affecting the other outputs:

values = mcc152.dio_output_read_port()
values |= 0x05
mcc152.dio_output_write_port(values)
Parameters:values (integer) – The output values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_output_write_dict(value_dict)

Write multiple digital output channel values.

Pass a dictionary containing channel:value pairs. If a channel is repeated in the dictionary then the last value will be used. If a specified channel is configured as an input this will not have any effect at the terminal, but allows the output register to be loaded before configuring the channel as an output.

For example, to set channels 0 and 2 to 1 without affecting the other outputs:

values = { 0:1, 2:1 }
mcc152.dio_output_write_dict(values)
Parameters:

value_dict (dictionary) – The output values in a dictionary of channel:value pairs.

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_output_read_bit(channel)

Read a single digital output channel value.

This function returns the value stored in the output register. It may not represent the value at the terminal if the channel is configured as input or open-drain output.

Parameters:

channel (int) – The digital channel number, 0-7.

Returns:

The output value.

Return type:

int

Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_output_read_port()

Read all digital output channel values.

Returns the values as an integer with a value of 0 - 255. Each channel is represented by a bit in the integer (bit 0 is channel 0, etc.) The value of a specific output can be found by examining the bit at that location.

This function returns the values stored in the output register. They may not represent the value at the terminal if the channel is configured as input or open-drain output.

Returns
int: The output values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_output_read_tuple()

Read all digital output channel values at once as a tuple.

Returns a tuple of all output values in channel order. For example, to compare the channel 1 output to the channel 3 output:

outputs = mcc152.dio_output_read_tuple()
if outputs[1] == outputs[3]:
    print("channel 1 and channel 3 outputs are the same")

This function returns the values stored in the output register. They may not represent the value at the terminal if the channel is configured as input or open-drain output.

Returns
tuple of int: The output values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_int_status_read_bit(channel)

Read the interrupt status for a single channel.

Returns 0 if the input is not generating an interrupt, 1 if it is generating an interrupt.

Returns
int: The interrupt status value.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_int_status_read_port()

Read the interrupt status for all channels.

Returns the values as an integer with a value of 0 - 255. Each channel is represented by a bit in the integer (bit 0 is channel 0, etc.) The status for a specific input can be found by examining the bit at that location. Each bit will be 0 if the channel is not generating an interrupt or 1 if it is generating an interrupt.

Returns
int: The interrupt status values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_int_status_read_tuple()

Read the interrupt status for all channels as a tuple.

Returns a tuple of all interrupt status values in channel order. Each value will be 0 if the channel is not generating an interrupt or 1 if it is generating an interrupt. For example, to see if an interrupt has occurred on channel 2 or 4:

status = mcc152.dio_int_status_read_tuple()
if status[2] == 1 or status[4] == 1:
    print("an interrupt has occurred on channel 2 or 4")
Returns
tuple of int: The status values.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
dio_config_write_bit(channel, item, value)

Write a digital I/O configuration value for a single channel.

There are several configuration items that may be written for the digital I/O. The item is selected with the item argument, which may be one of the DIOConfigItem values:

  • DIOConfigItem.DIRECTION: Set the digital I/O channel direction by passing 0 for output and 1 for input.

  • DIOConfigItem.PULL_CONFIG: Configure the pull-up/down resistor by passing 0 for pull-down or 1 for pull-up. The resistor may be enabled or disabled with the DIOConfigItem.PULL_ENABLE item.

  • DIOConfigItem.PULL_ENABLE: Enable or disable the pull-up/down resistor by passing 0 for disabled or 1 for enabled. The resistor is configured for pull-up/down with the DIOConfigItem.PULL_CONFIG item. The resistor is automatically disabled if the bit is set to output and is configured as open-drain.

  • DIOConfigItem.INPUT_INVERT: Enable inverting the input by passing a 0 for normal input or 1 for inverted.

  • DIOConfigItem.INPUT_LATCH: Enable input latching by passing 0 for non-latched or 1 for latched.

    When the input is non-latched, reads show the current status of the input. A state change in the input generates an interrupt (if it is not masked). A read of the input clears the interrupt. If the input goes back to its initial logic state before the input is read, then the interrupt is cleared.

    When the input is latched, a change of state of the input generates an interrupt and the input logic value is loaded into the input port register. A read of the input will clear the interrupt. If the input returns to its initial logic state before the input is read, then the interrupt is not cleared and the input register keeps the logic value that initiated the interrupt. The next read of the input will show the initial state. Care must be taken when using bit reads on the input when latching is enabled - the bit method still reads the entire input register so a change on another bit could be missed. It is best to use port or tuple input reads when using latching.

    If the input is changed from latched to non-latched, a read from the input reflects the current terminal logic level. If the input is changed from non-latched to latched input, the read from the input represents the latched logic level.

  • DIOConfigItem.OUTPUT_TYPE: Set the output type by writing 0 for push-pull or 1 for open-drain. This setting affects all outputs so is not a per-channel setting and the channel argument is ignored. It should be set to the desired type before using DIOConfigItem.DIRECTION item to set channels as outputs. Internal pull-up/down resistors are disabled when a bit is set to output and is configured as open-drain, so external resistors should be used.

  • DIOConfigItem.INT_MASK: Enable or disable interrupt generation by masking the interrupt. Write 0 to enable the interrupt or 1 to mask (disable) it.

    All MCC 152s share a single interrupt signal to the CPU, so when an interrupt occurs the user must determine the source, optionally act on the interrupt, then clear that source so that other interrupts may be detected. The current interrupt state may be read with interrupt_state(). A user program may wait for the interrupt to become active with wait_for_interrupt(), or may register an interrupt callback function with interrupt_callback_enable(). This allows the user to wait for a change on one or more inputs without constantly reading the inputs. The source of the interrupt may be determined by reading the interrupt status of each MCC 152 with dio_int_status_read_bit(), dio_int_status_read_port() or dio_int_status_read_tuple(), and all active interrupt sources must be cleared before the interrupt will become inactive. The interrupt is cleared by reading the input with dio_input_read_bit(), dio_input_read_port(), or dio_input_read_tuple().

Parameters:
  • channel (integer) – The digital I/O channel, 0 - 7
  • item (integer) – The configuration item, one of DIOConfigItem.
  • value (integer) – The configuration value.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_config_write_port(item, value)

Write a digital I/O configuration value for all channels.

There are several configuration items that may be written for the digital I/O. They are written for all channels at once using an 8-bit value passed in value, where each bit corresponds to a channel (bit 0 is channel 0, etc.) The item is selected with the item argument, which may be one of the DIOConfigItem values.

  • DIOConfigItem.DIRECTION: Set the digital I/O channel directions by passing 0 in a bit for output and 1 for input.

  • DIOConfigItem.PULL_CONFIG: Configure the pull-up/down resistors by passing 0 in a bit for pull-down or 1 for pull-up. The resistors may be enabled or disabled with the DIOConfigItem.PULL_ENABLE item.

  • DIOConfigItem.PULL_ENABLE: Enable or disable pull-up/down resistors by passing 0 in a bit for disabled or 1 for enabled. The resistors are configured for pull-up/down with the DIOConfigItem.PULL_CONFIG item. The resistors are automatically disabled if the bits are set to output and configured as open-drain.

  • DIOConfigItem.INPUT_INVERT: Enable inverting inputs by passing a 0 in a bit for normal input or 1 for inverted.

  • DIOConfigItem.INPUT_LATCH: Enable input latching by passing 0 in a bit for non-latched or 1 for latched.

    When the input is non-latched, reads show the current status of the input. A state change in the corresponding input generates an interrupt (if it is not masked). A read of the input clears the interrupt. If the input goes back to its initial logic state before the input is read, then the interrupt is cleared. When the input is latched, a change of state of the input generates an interrupt and the input logic value is loaded into the input port register. A read of the input will clear the interrupt. If the input returns to its initial logic state before the input is read, then the interrupt is not cleared and the input register keeps the logic value that initiated the interrupt. The next read of the input will show the initial state. Care must be taken when using bit reads on the input when latching is enabled - the bit method still reads the entire input register so a change on another bit could be missed. It is best to use port or tuple input reads when using latching.

    If the input is changed from latched to non-latched, a read from the input reflects the current terminal logic level. If the input is changed from non-latched to latched input, the read from the input represents the latched logic level.

  • DIOConfigItem.OUTPUT_TYPE: Set the output type by writing 0 for push-pull or 1 for open-drain. This setting affects all outputs so is not a per-channel setting. It should be set to the desired type before using DIOConfigItem.DIRECTION to set channels as outputs. Internal pull-up/down resistors are disabled when a bit is set to output and is configured as open-drain, so external resistors should be used.

  • DIOConfigItem.INT_MASK: Enable or disable interrupt generation for specific inputs by masking the interrupt. Write 0 in a bit to enable the interrupt from that channel or 1 to mask (disable) it.

    All MCC 152s share a single interrupt signal to the CPU, so when an interrupt occurs the user must determine the source, optionally act on the interrupt, then clear that source so that other interrupts may be detected. The current interrupt state may be read with interrupt_state(). A user program may wait for the interrupt to become active with wait_for_interrupt(), or may register an interrupt callback function with interrupt_callback_enable(). This allows the user to wait for a change on one or more inputs without constantly reading the inputs. The source of the interrupt may be determined by reading the interrupt status of each MCC 152 with dio_int_status_read_bit(), dio_int_status_read_port() or dio_int_status_read_tuple(), and all active interrupt sources must be cleared before the interrupt will become inactive. The interrupt is cleared by reading the input with dio_input_read_bit(), dio_input_read_port(), or dio_input_read_tuple().

Parameters:
  • item (integer) – The configuration item, one of DIOConfigItem.
  • value (integer) – The configuration value.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_config_write_dict(item, value_dict)

Write a digital I/O configuration value for multiple channels.

There are several configuration items that may be written for the digital I/O. They are written for multiple channels at once using a dictionary of channel:value pairs. If a channel is repeated in the dictionary then the last value will be used. The item is selected with the item argument, which may be one of the DIOConfigItem values:

  • DIOConfigItem.DIRECTION: Set the digital I/O channel directions by passing 0 in a value for output and 1 for input.

  • DIOConfigItem.PULL_CONFIG: Configure the pull-up/down resistors by passing 0 in a value for pull-down or 1 for pull-up. The resistors may be enabled or disabled with the DIOConfigItem.PULL_ENABLE item.

  • DIOConfigItem.PULL_ENABLE: Enable or disable pull-up/down resistors by passing 0 in a value for disabled or 1 for enabled. The resistors are configured for pull-up/down with the DIOConfigItem.PULL_CONFIG item. The resistors are automatically disabled if the bits are set to output and configured as open-drain.

  • DIOConfigItem.INPUT_INVERT: Enable inverting inputs by passing a 0 in a value for normal input or 1 for inverted.

  • DIOConfigItem.INPUT_LATCH: Enable input latching by passing 0 in a value for non-latched or 1 for latched.

    When the input is non-latched, reads show the current status of the input. A state change in the corresponding input generates an interrupt (if it is not masked). A read of the input clears the interrupt. If the input goes back to its initial logic state before the input is read, then the interrupt is cleared. When the input is latched, a change of state of the input generates an interrupt and the input logic value is loaded into the input port register. A read of the input will clear the interrupt. If the input returns to its initial logic state before the input is read, then the interrupt is not cleared and the input register keeps the logic value that initiated the interrupt. The next read of the input will show the initial state. Care must be taken when using bit reads on the input when latching is enabled - the bit method still reads the entire input register so a change on another bit could be missed. It is best to use port or tuple input reads when using latching.

    If the input is changed from latched to non-latched, a read from the input reflects the current terminal logic level. If the input is changed from non-latched to latched input, the read from the input represents the latched logic level.

  • DIOConfigItem.OUTPUT_TYPE: Set the output type by writing 0 for push-pull or 1 for open-drain. This setting affects all outputs so is not a per-channel setting. It should be set to the desired type before using DIOConfigItem.DIRECTION to set channels as outputs. Internal pull-up/down resistors are disabled when a bit is set to output and is configured as open-drain, so external resistors should be used.

  • DIOConfigItem.INT_MASK: Enable or disable interrupt generation for specific inputs by masking the interrupt. Write 0 in a value to enable the interrupt from that channel or 1 to mask (disable) it.

    All MCC 152s share a single interrupt signal to the CPU, so when an interrupt occurs the user must determine the source, optionally act on the interrupt, then clear that source so that other interrupts may be detected. The current interrupt state may be read with interrupt_state(). A user program may wait for the interrupt to become active with wait_for_interrupt(), or may register an interrupt callback function with interrupt_callback_enable(). This allows the user to wait for a change on one or more inputs without constantly reading the inputs. The source of the interrupt may be determined by reading the interrupt status of each MCC 152 with dio_int_status_read_bit(), dio_int_status_read_port() or dio_int_status_read_tuple(), and all active interrupt sources must be cleared before the interrupt will become inactive. The interrupt is cleared by reading the input with dio_input_read_bit(), dio_input_read_port(), or dio_input_read_tuple().

For example, to set channels 6 and 7 to output:

values = { 6:0, 7:0 }
mcc152.dio_config_write_dict(DIOConfigItem.DIRECTION, values)
Parameters:
  • item (integer) – The configuration item, one of DIOConfigItem.
  • value_dict (dictionary) – The configuration values for multiple channels in a dictionary of channel:value pairs.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_config_read_bit(channel, item)

Read a digital I/O configuration value for a single channel.

There are several configuration items that may be read for the digital I/O. The item is selected with the item argument, which may be one of the DIOConfigItems values:

Parameters:
  • channel (integer) – The digital I/O channel, 0 - 7.
  • item (integer) – The configuration item, one of DIOConfigItem.
Returns
int: The configuration item value.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_config_read_port(item)

Read a digital I/O configuration value for all channels.

There are several configuration items that may be read for the digital I/O. They are read for all channels at once, returning an 8-bit integer where each bit corresponds to a channel (bit 0 is channel 0, etc.) The item is selected with the item argument, which may be one of the DIOConfigItem values:

  • DIOConfigItem.DIRECTION: Read the digital I/O channels direction settings, where 0 in a bit is output and 1 is input.
  • DIOConfigItem.PULL_CONFIG: Read the pull-up/down resistor configurations where 0 in a bit is pull-down and 1 is pull-up.
  • DIOConfigItem.PULL_ENABLE: Read the pull-up/down resistor enable settings where 0 in a bit is disabled and 1 is enabled.
  • DIOConfigItem.INPUT_INVERT: Read the input inversion settings where 0 in a bit is normal input and 1 is inverted.
  • DIOConfigItem.INPUT_LATCH: Read the input latching settings where 0 in a bit is non-latched and 1 is latched.
  • DIOConfigItem.OUTPUT_TYPE: Read the output type setting where 0 is push-pull and 1 is open-drain. This setting affects all outputs so is not a per-channel setting.
  • DIOConfigItem.INT_MASK: Read the interrupt mask settings where 0 in a bit enables the interrupt and 1 disables it.
Parameters:item (integer) – The configuration item, one of DIOConfigItem.
Returns
int: The configuration item value.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
dio_config_read_tuple(item)

Read a digital I/O configuration value for all channels as a tuple.

There are several configuration items that may be read for the digital I/O. They are read for all channels at once, returning a tuple in channel order. The item is selected with the item argument, which may be one of the DIOConfigItem values:

  • DIOConfigItem.DIRECTION: Read the digital I/O channels direction settings, where 0 in a value is output and 1 is input.
  • DIOConfigItem.PULL_CONFIG: Read the pull-up/down resistor configurations where 0 in a value is pull-down and 1 is pull-up.
  • DIOConfigItem.PULL_ENABLE: Read the pull-up/down resistor enable settings where 0 in a value is disabled and 1 is enabled.
  • DIOConfigItem.INPUT_INVERT: Read the input inversion settings where 0 in a value is normal input and 1 is inverted.
  • DIOConfigItem.INPUT_LATCH: Read the input latching settings where 0 in a value is non-latched and 1 is latched.
  • DIOConfigItem.OUTPUT_TYPE: Read the output type setting where 0 is push-pull and 1 is open-drain. This setting affects all outputs so is not a per-channel setting.
  • DIOConfigItem.INT_MASK: Read the interrupt mask settings where 0 in a value enables the interrupt and 1 disables it.
Parameters:item (integer) – The configuration item, one of DIOConfigItem.
Returns
tuple of int: The configuration item values.
Raises:
  • HatError – the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – an argument is invalid.
address()

Return the device address.

Data

DIO Config Items

class daqhats.DIOConfigItem

Digital I/O Configuration Items.

DIRECTION = 0

Configure channel direction

PULL_CONFIG = 1

Configure pull-up/down resistor

PULL_ENABLE = 2

Enable pull-up/down resistor

INPUT_INVERT = 3

Configure input inversion

INPUT_LATCH = 4

Configure input latching

OUTPUT_TYPE = 5

Configure output type

INT_MASK = 6

Configure interrupt mask

MCC 172 class

Methods

class daqhats.mcc172(address=0)

The class for an MCC 172 board.

Parameters:address (int) – board address, must be 0-7.
Raises:HatError – the board did not respond or was of an incorrect type

Methods

Method Description
mcc172.info() Get info about this device type.
mcc172.firmware_version() Get the firmware version.
mcc172.serial() Read the serial number.
mcc172.blink_led() Blink the MCC 172 LED.
mcc172.calibration_date() Read the calibration date.
mcc172.calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc172.calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc172.iepe_config_read() Read the IEPE configuration for a channel.
mcc172.iepe_config_write() Write the IEPE configuration for a channel.
mcc172.a_in_sensitivity_read() Read the sensitivity factor for a channel.
mcc172.a_in_sensitivity_write() Write the sensitivity factor for a channel.
mcc172.a_in_clock_config_read() Read the sampling clock configuration.
mcc172.a_in_clock_config_write() Write the sampling clock configuration.
mcc172.trigger_config() Configure the external trigger input.
mcc172.a_in_scan_actual_rate() Read the actual sample rate for a requested sample rate.
mcc172.a_in_scan_start() Start a hardware-paced analog input scan.
mcc172.a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc172.a_in_scan_read() Read scan status / data (list).
mcc172.a_in_scan_read_numpy() Read scan status / data (NumPy array).
mcc172.a_in_scan_channel_count() Get the number of channels in the current scan.
mcc172.a_in_scan_stop() Stop the scan.
mcc172.a_in_scan_cleanup() Free scan resources.
mcc172.address() Read the board’s address.
static info()

Return constant information about this type of device.

Returns:A namedtuple containing the following field names:
  • NUM_AI_CHANNELS (int): The number of analog input channels (2.)
  • AI_MIN_CODE (int): The minimum ADC code (-8388608.)
  • AI_MAX_CODE (int): The maximum ADC code (8388607.)
  • AI_MIN_VOLTAGE (float): The voltage corresponding to the minimum ADC code (-5.0.)
  • AI_MAX_VOLTAGE (float): The voltage corresponding to the maximum ADC code (+5.0 - 1 LSB)
  • AI_MIN_RANGE (float): The minimum voltage of the input range (-5.0.)
  • AI_MAX_RANGE (float): The maximum voltage of the input range (+5.0.)
Return type:namedtuple
firmware_version()

Read the board firmware and bootloader versions.

Returns:A namedtuple containing the following field names:
  • version (string): The firmware version, i.e “1.03”.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
serial()

Read the serial number.

Returns:The serial number.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.

Blink the MCC 172 LED.

Setting count to 0 will cause the LED to blink continuously until blink_led() is called again with a non-zero count.

Parameters:count (int) – The number of times to blink (max 255).
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_date()

Read the calibration date.

Returns:The calibration date in the format “YYYY-MM-DD”.
Return type:string
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_read(channel)

Read the calibration coefficients for a single channel.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code - offset) * slope
Parameters:channel (int) – The analog input channel (0-1.)
Returns:A namedtuple containing the following field names:
  • slope (float): The slope.
  • offset (float): The offset.
Return type:namedtuple
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
calibration_coefficient_write(channel, slope, offset)

Temporarily write the calibration coefficients for a single channel.

The user can apply their own calibration coefficients by writing to these values. The values will reset to the factory values from the EEPROM whenever the class is initialized. This function will fail and raise a HatError exception if a scan is active when it is called.

The coefficients are applied in the library as:

calibrated_ADC_code = (raw_ADC_code - offset) * slope
Parameters:
  • channel (int) – The analog input channel (0-1.)
  • slope (float) – The new slope value.
  • offset (float) – The new offset value.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

iepe_config_write(channel, mode)

Configure a channel for an IEPE sensor.

This method turns on / off the IEPE power supply for the specified channel. The power-on default is IEPE power off.

Parameters:
  • channel (int) – The channel, 0 or 1.
  • mode (int) – The IEPE mode for the channel, 0 = IEPE off, 1 = IEPE on.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

iepe_config_read(channel)

Read the IEPE configuration for a channel.

This method returns the state of the IEPE power supply for the specified channel

Parameters:channel (int) – The channel, 0 or 1.
Returns
int: The IEPE mode for the channel, 0 = IEPE off, 1 = IEPE on.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_sensitivity_write(channel, value)

Write the MCC 172 analog input sensitivity scaling factor for a single channel.

This applies a scaling factor to the analog input data so it returns values that are meaningful for the connected sensor.

The sensitivity is specified in mV / mechanical unit. The default value when opening the library is 1000, resulting in no scaling of the input voltage. Changing this value will not change the values reported by info() since it is simply sensor scaling applied to the data before returning it.

Examples:

  • A seismic sensor with a sensitivity of 10 V/g. Set the sensitivity to 10,000 and the returned data will be in units of g.
  • A vibration sensor with a sensitivity of 100 mV/g. Set the sensitivity to 100 and the returned data will be in units of g.
Parameters:
  • channel (int) – The channel, 0 or 1.
  • value (float) – The sensitivity for the specified channel.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

a_in_sensitivity_read(channel)
Read the MCC 172 analog input sensitivity scaling factor for a single
channel.

The sensitivity is returned in mV / mechanical unit. The default value when opening the library is 1000, resulting in no scaling of the input voltage.

Parameters:channel (int) – The channel, 0 or 1.
Returns
float: The sensitivity factor for the channel.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_clock_config_write(clock_source, sample_rate_per_channel)

Configure the ADC sampling clock.

This method will configure the ADC sampling clock. The default configuration after opening the device is local mode, 51.2 KHz sampling rate. The clock source must be one of:

  • SourceType.LOCAL: the clock is generated on this MCC 172 and not shared with any other devices.
  • SourceType.MASTER: the clock is generated on this MCC 172 and shared over the Raspberry Pi header with other MCC 172s. All other MCC 172s must be configured for local or slave clock.
  • SourceType.SLAVE: no clock is generated on this MCC 172, it receives its clock from the Raspberry Pi header. Another MCC 172 must be configured for master clock.

The ADCs will be synchronized so they sample the inputs at the same time. This requires 128 clock cycles before the first sample is available. When using a master - slave clock configuration there are additional considerations:

  • There should be only one master device; otherwise, you will be connecting multiple outputs together and could damage a device.
  • Configure the clock on the slave device(s) first, master last. The synchronization will occur when the master clock is configured, causing the ADCs on all the devices to be in sync.
  • If you change the clock configuration on one device after configuring the master, then the data will no longer be in sync. The devices cannot detect this and will still report that they are synchronized. Always write the clock configuration to all devices when modifying the configuration.
  • Slave devices must have a master clock source or scans will never complete.
  • A trigger must be used for the data streams from all devices to start on the same sample.

The MCC 172 can generate a sampling clock equal to 51.2 KHz divided by an integer between 1 and 256. The sample_rate_per_channel will be internally converted to the nearest valid rate. The actual rate can be read back using a_in_clock_config_read(). When used in slave clock configuration, the device will measure the frequency of the incoming master clock after the synchronization period is complete. Calling a_in_clock_config_read() after this will return the measured sample rate.

Parameters:
  • clock_source (SourceType) – The ADC clock source.
  • sample_rate_per_channel (float) – The requested sampling rate in samples per second per channel.
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

a_in_clock_config_read()

Read the sampling clock configuration.

This method will return the sample clock configuration and rate. If the clock is configured for local or master source, then the rate will be the internally adjusted rate set by the user. If the clock is configured for slave source, then the rate will be measured from the master clock after the synchronization period has ended. The synchronization status is also returned.

The clock source will be one of:

  • SourceType.LOCAL: the clock is generated on this MCC 172 and not shared with any other devices.
  • SourceType.MASTER: the clock is generated on this MCC 172 and shared over the Raspberry Pi header with other MCC 172s.
  • SourceType.SLAVE: no clock is generated on this MCC 172, it receives its clock from the Raspberry Pi header.

The sampling rate will not be valid in slave mode if synced is False. The device will not detect a loss of the master clock when in slave mode; it only monitors the clock when a sync is initiated.

Returns

namedtuple: a namedtuple containing the following field names:

  • clock_source (SourceType): The ADC clock source.
  • sample_rate_per_channel (float): The sample rate in samples per second per channel.
  • synchronized (bool): True if the ADCs are synchronized, False if a synchronization is in progress.
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
trigger_config(trigger_source, trigger_mode)

Configure the digital trigger.

The analog input scan may be configured to start saving the acquired data when the digital trigger is in the desired state. A single device trigger may also be shared with multiple boards. This command sets the trigger source and mode.

The trigger source must be one of:

  • SourceType.LOCAL: the trigger terminal on this MCC 172 is used and not shared with any other devices.
  • SourceType.MASTER: the trigger terminal on this MCC 172 is used and is shared as the master trigger for other MCC 172s.
  • SourceType.SLAVE: the trigger terminal on this MCC 172 is not used, it receives its trigger from the master MCC 172.

The trigger mode must be one of:

Due to the nature of the filtering in the A/D converters there is an input delay of 39 samples, so the data coming from the converters at any time is delayed by 39 samples from the current time. This is most noticeable when using a trigger - there will be approximately 39 samples prior to the trigger event in the captured data.

Care must be taken when using master / slave triggering; the input trigger signal on the master will be passed through to the slave(s), but the mode is set independently on each device. For example, it is possible for the master to trigger on the rising edge of the signal and the slave to trigger on the falling edge.

Parameters:
Raises:

HatError – the board is not initialized, does not respond, or responds incorrectly.

static a_in_scan_actual_rate(sample_rate_per_channel)

Calculate the actual sample rate per channel for a requested sample rate.

The scan clock is generated from a 51.2 KHz clock source divided by an integer between 1 and 256, so only discrete frequency steps can be achieved. This method will return the actual rate for a requested sample rate.

This function does not perform any actions with a board, it simply calculates the rate.

Parameters:sample_rate_per_channel (float) – The desired per-channel rate of the internal sampling clock.
Returns:The actual sample rate.
Return type:float
a_in_scan_start(channel_mask, samples_per_channel, options)

Start capturing analog input data.

The scan runs as a separate thread from the user’s code. This function will allocate a scan buffer and start the thread that reads data from the device into that buffer. The user reads the data from the scan buffer and the scan status using the a_in_scan_read() function. a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call a_in_scan_cleanup() after the scan has finished and all desired data has been read; this frees all resources from the scan and allows additional scans to be performed.

The scan cannot be started until the ADCs are synchronized, so this function will not return until that has completed. It is best to wait for sync using a_in_clock_config_read() before starting the scan.

The scan state has defined terminology:

  • Active: a_in_scan_start() has been called and the device may be acquiring data or finished with the acquisition. The scan has not been cleaned up by calling a_in_scan_cleanup(), so another scan may not be started.
  • Running: The scan is active and the device is still acquiring data. Certain methods like a_in_clock_config_write() will return an error because the device is busy.

The scan options that may be used are:

The OptionFlags.EXTCLOCK option is not supported for this device and will raise a ValueError.

The scan buffer size will be allocated as follows:

Finite mode: Total number of samples in the scan.

Continuous mode: Either samples_per_channel or the value in the table below, whichever is greater.

Sample Rate Buffer Size (per channel)
200-1024 S/s 1 kS
1280-10.24 kS/s 10 kS
12.8 kS or higher 100 kS

Specifying a very large value for samples_per_channel could use too much of the Raspberry Pi memory. If the memory allocation fails, the function will raise a HatError with this description. The allocation could succeed, but the lack of free memory could cause other problems in the Raspberry Pi. If you need to acquire a high number of samples then it is better to run the scan in continuous mode and stop it when you have acquired the desired amount of data. If a scan is active this method will raise a HatError.

Parameters:
  • channel_mask (int) – A bit mask of the desired channels (0x01 - 0x03).
  • samples_per_channel (int) – The number of samples to acquire per channel (finite mode,) or or can be used to set a larger scan buffer size than the default value (continuous mode.)
  • options (int) – An ORed combination of OptionFlags flags that control the scan.
Raises:
  • HatError – a scan is active; memory could not be allocated; the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – a scan argument is invalid.
a_in_scan_buffer_size()

Read the internal scan data buffer size.

An internal data buffer is allocated for the scan when a_in_scan_start() is called. This function returns the total size of that buffer in samples.

Returns:The buffer size in samples.
Return type:int
Raises:HatError – the board is not initialized or no scan buffer is allocated (a scan is not active).
a_in_scan_status()

Read scan status and number of available samples per channel.

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and the number of samples per channel available in the scan thread buffer.

Returns:A namedtuple containing the following field names:
  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • samples_available (int): The number of samples per channel currently in the scan buffer.
Return type:namedtuple
Raises:HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_read(samples_per_channel, timeout)

Read scan status and data (as a list).

The analog input scan is started with a_in_scan_start() and runs in the background. This function reads the status of that background scan and optionally reads sampled data from the scan buffer.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to return all available samples immediately and ignore timeout or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer (up to samples_per_channel.) If the timeout is met and the specified number of samples have not been read, then the function will return all the available samples and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (list of float): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_read_numpy(samples_per_channel, timeout)

Read scan status and data (as a NumPy array).

This function is similar to a_in_scan_read() except that the data key in the returned namedtuple is a NumPy array of float64 values and may be used directly with NumPy functions.

Parameters:
  • samples_per_channel (int) – The number of samples per channel to read from the scan buffer. Specify a negative number to read all available samples or 0 to only read the scan status and return no data.
  • timeout (float) – The amount of time in seconds to wait for the samples to be read. Specify a negative number to wait indefinitely, or 0 to return immediately with the samples that are already in the scan buffer. If the timeout is met and the specified number of samples have not been read, then the function will return with the amount that has been read and the timeout status set.
Returns:

A namedtuple containing the following field names:

  • running (bool): True if the scan is running, False if it has stopped or completed.
  • hardware_overrun (bool): True if the hardware could not acquire and unload samples fast enough and data was lost.
  • buffer_overrun (bool): True if the background scan buffer was not read fast enough and data was lost.
  • triggered (bool): True if the trigger conditions have been met and data acquisition started.
  • timeout (bool): True if the timeout time expired before the specified number of samples were read.
  • data (NumPy array of float64): The data that was read from the scan buffer.

Return type:

namedtuple

Raises:
  • HatError – A scan is not active, the board is not initialized, does not respond, or responds incorrectly.
  • ValueError – Incorrect argument.
a_in_scan_channel_count()

Read the number of channels in the current analog input scan.

Returns:The number of channels (0 if no scan is active, 1-2 otherwise.)
Return type:int
Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_stop()

Stops an analog input scan.

The device stops acquiring data immediately. The scan data that has been read into the scan buffer is available until a_in_scan_cleanup() is called.

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
a_in_scan_cleanup()

Free analog input scan resources after the scan is complete.

This will free the scan buffer and other resources used by the background scan and make it possible to start another scan with a_in_scan_start().

Raises:HatError – the board is not initialized, does not respond, or responds incorrectly.
address()

Return the device address.

Data

Source types

class daqhats.SourceType

Clock / trigger source options.

LOCAL = 0

Use a local-only source.

MASTER = 1

Use a local source and set it as master.

SLAVE = 2

Use a master source from another MCC 172.