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¶
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.
-
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 typeMethods
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_led
(count)¶ 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:
TriggerModes.RISING_EDGE
: Start the scan when the TRIG input transitions from low to high.TriggerModes.FALLING_EDGE
: Start the scan when the TRIG input transitions from high to low.TriggerModes.ACTIVE_HIGH
: Start the scan when the TRIG input is high.TriggerModes.ACTIVE_LOW
: Start the scan when the TRIG input is low.
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:
OptionFlags.DEFAULT
: Return a calibrated voltage value. Any other flags will override DEFAULT behavior.OptionFlags.NOSCALEDATA
: Return an ADC code (a value between 0 and 4095) rather than voltage.OptionFlags.NOCALIBRATEDATA
: Return data without the calibration factors applied.
Parameters: - channel (int) – The analog input channel number, 0-7.
- options (int) – ORed combination of
OptionFlags
,OptionFlags.DEFAULT
if unspecified.
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 calla_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 callinga_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 callinga_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 callinga_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.
- Active:
-
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.
-
static