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.
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

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

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.

HatError class

exception daqhats.HatError(address, value)

Exceptions raised for MCC 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.blink_led() Blink the MCC 118 LED.
mcc118.info() Get info about this device type.
mcc118.firmware_version() Get the firmware version.
mcc118.address() Read the board’s address.
mcc118.serial() Read the serial number.
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.a_in_read() Read an analog input channel.
mcc118.trigger_mode() Set the external trigger input mode.
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.
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
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:
  • 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.