C Library Reference
The C library is organized as a global function for listing the DAQ HAT boards attached to your system, and board-specific functions to provide full functionality for each type of board. The library may be used with C and C++.
Global functions and data
Functions
Function |
Description |
Return a list of detected DAQ HAT boards. |
|
Return a text description for a DAQ HAT result. |
|
Wait for an interrupt to occur. |
|
Read the current interrupt status. |
|
Enable an interrupt callback function. |
|
Disable interrupt callback function. |
-
int hat_list(uint16_t filter_id, struct HatInfo *list)
Return a list of detected DAQ HAT boards.
It creates the list from the DAQ HAT EEPROM files that are currently on the system. In the case of a single DAQ HAT at address 0 this information is automatically provided by the OS. However, when you have a stack of multiple boards you must extract the EEPROM images using the daqhats_read_eeproms tool.
Example usage:
int count = hat_list(HAT_ID_ANY, NULL); if (count > 0) { struct HatInfo* list = (struct HatInfo*)malloc(count * sizeof(struct HatInfo)); hat_list(HAT_ID_ANY, list); // perform actions with list free(list); }
- Parameters:
filter_id – An optional ID filter to only return boards with a specific ID. Use HAT_ID_ANY to return all boards.
list – A pointer to a user-allocated array of struct HatInfo. The function will fill the structures with information about the detected boards. You may have an array of the maximum number of boards (MAX_NUMBER_HATS) or call this function while passing NULL for list, which will return the count of boards found, then allocate the correct amount of memory and call this function again with a valid pointer.
- Returns:
The number of boards found.
-
const char *hat_error_message(int result)
Return a text description for a DAQ HAT result code.
- Parameters:
result – The Result code returned from a DAQ HAT function
- Returns:
The error message.
-
int hat_wait_for_interrupt(int timeout)
Wait for an interrupt to occur.
It waits for the interrupt signal to become active, with a timeout parameter.
This function only applies when using devices that can generate an interrupt:
MCC 152
- Parameters:
timeout – Wait timeout in milliseconds. -1 to wait forever, 0 to return immediately.
- Returns:
-
int hat_interrupt_state(void)
Read the current interrupt status.
It returns the status of the interrupt signal. This signal can be shared by multiple boards so the status of each board that may generate 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:
1 if interrupt is active, 0 if inactive.
-
int hat_interrupt_callback_enable(void (*function)(void*), void *user_data)
Enable an interrupt callback function.
Set a function that will be called when a DAQ HAT interrupt occurs. The function must have a void return type and void * argument, such as:
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.)void function(void* user_data)
The user_data argument can be used for passing a reference to anything needed by the callback function. It will be passed to the callback function when the interrupt occurs. Set it to NULL if not needed.
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 callback function may be disabled with hat_interrupt_callback_disable().
This function only applies when using devices that can generate an interrupt:
MCC 152
- Parameters:
function – The callback function.
user_data – The data to pass to the callback function.
- Returns:
-
int hat_interrupt_callback_disable(void)
Disable interrupt callbacks.
Removes any callback function from the interrupt handler.
- Returns:
Data types and definitions
-
MAX_NUMBER_HATS 8
The maximum number of DAQ HATs that may be connected.
HAT IDs
-
enum HatIDs
Known DAQ HAT IDs.
Values:
-
enumerator HAT_ID_ANY
Match any DAQ HAT ID in hat_list().
-
enumerator HAT_ID_MCC_118
MCC 118 ID.
-
enumerator HAT_ID_MCC_118_BOOTLOADER
MCC 118 in firmware update mode ID.
-
enumerator HAT_ID_MCC_128
MCC 128 ID.
-
enumerator HAT_ID_MCC_134
MCC 134 ID.
-
enumerator HAT_ID_MCC_152
MCC 152 ID.
-
enumerator HAT_ID_MCC_172
MCC 172 ID.
-
enumerator HAT_ID_ANY
Result Codes
-
enum ResultCode
Return values from the library functions.
Values:
-
enumerator RESULT_SUCCESS
Success, no errors.
-
enumerator RESULT_BAD_PARAMETER
A parameter passed to the function was incorrect.
-
enumerator RESULT_BUSY
The device is busy.
-
enumerator RESULT_TIMEOUT
There was a timeout accessing a resource.
-
enumerator RESULT_LOCK_TIMEOUT
There was a timeout while obtaining a resource lock.
-
enumerator RESULT_INVALID_DEVICE
The device at the specified address is not the correct type.
-
enumerator RESULT_RESOURCE_UNAVAIL
A needed resource was not available.
-
enumerator RESULT_COMMS_FAILURE
Could not communicate with the device.
-
enumerator RESULT_UNDEFINED
Some other error occurred.
-
enumerator RESULT_SUCCESS
HatInfo structure
-
struct HatInfo
Contains information about a specific board.
Analog Input / Scan Option Flags
See individual function documentation for detailed usage information.
-
OPTS_DEFAULT (0x0000)
Default behavior.
-
OPTS_NOSCALEDATA (0x0001)
Read / write unscaled data.
-
OPTS_NOCALIBRATEDATA (0x0002)
Read / write uncalibrated data.
-
OPTS_EXTCLOCK (0x0004)
Use an external clock source.
-
OPTS_EXTTRIGGER (0x0008)
Use an external trigger source.
-
OPTS_CONTINUOUS (0x0010)
Run until explicitly stopped.
Scan Status Flags
-
STATUS_HW_OVERRUN (0x0001)
A hardware overrun occurred.
-
STATUS_BUFFER_OVERRUN (0x0002)
A scan buffer overrun occurred.
-
STATUS_TRIGGERED (0x0004)
The trigger event occurred.
-
STATUS_RUNNING (0x0008)
The scan is running (actively acquiring data.)
Trigger Modes
-
enum TriggerMode
Scan trigger input modes.
Values:
-
enumerator TRIG_RISING_EDGE
Start the scan on a rising edge of TRIG.
-
enumerator TRIG_FALLING_EDGE
Start the scan on a falling edge of TRIG.
-
enumerator TRIG_ACTIVE_HIGH
Start the scan any time TRIG is high.
-
enumerator TRIG_ACTIVE_LOW
Start the scan any time TRIG is low.
-
enumerator TRIG_RISING_EDGE
MCC 118 functions and data
Functions
Function |
Description |
Open an MCC 118 for use. |
|
Check if an MCC 118 is open. |
|
Close an MCC 118. |
|
Return information about this device type. |
|
Blink the MCC 118 LED. |
|
Get the firmware version. |
|
Read the serial number. |
|
Read the calibration date. |
|
Read the calibration coefficients for a channel. |
|
Write the calibration coefficients for a channel. |
|
Read an analog input value. |
|
Set the external trigger input mode. |
|
Read the actual sample rate for a set of scan parameters. |
|
Start a hardware-paced analog input scan. |
|
Read the size of the internal scan data buffer. |
|
Read the scan status. |
|
Read scan data and status. |
|
Get the number of channels in the current scan. |
|
Stop the scan. |
|
Free scan resources. |
-
int mcc118_open(uint8_t address)
Open a connection to the MCC 118 device at the specified address.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_close(uint8_t address)
Close a connection to an MCC 118 device and free allocated resources.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_is_open(uint8_t address)
Check if an MCC 118 is open.
- Parameters:
address – The board address (0 - 7).
- Returns:
1 if open, 0 if not open.
-
struct MCC118DeviceInfo *mcc118_info(void)
Return constant device information for all MCC 118s.
- Returns:
Pointer to struct MCC118DeviceInfo.
-
int mcc118_blink_led(uint8_t address, uint8_t count)
Blink the LED on the MCC 118.
Passing 0 for count will result in the LED blinking continuously until the board is reset or mcc118_blink_led() is called again with a non-zero value for count.
- Parameters:
address – The board address (0 - 7).
count – The number of times to blink (0 - 255).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_firmware_version(uint8_t address, uint16_t *version, uint16_t *boot_version)
Return the board firmware and bootloader versions.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
version – Receives the firmware version. The version will be in BCD hexadecimal with the high byte as the major version and low byte as minor, i.e. 0x0103 is version 1.03.
boot_version – Receives the bootloader version. The version will be in BCD hexadecimal as above.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_serial(uint8_t address, char *buffer)
Read the MCC 118 serial number.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the serial number as a string. The buffer must be at least 9 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_calibration_date(uint8_t address, char *buffer)
Read the MCC 118 calibration date.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the date as a string (format “YYYY-MM-DD”). The buffer must be at least 11 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_calibration_coefficient_read(uint8_t address, uint8_t channel, double *slope, double *offset)
Read the MCC 118 calibration coefficients for a single channel.
The coefficients are applied in the library as:
calibrated_ADC_code = (raw_ADC_code * slope) + offset
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 7).
slope – Receives the slope.
offset – Receives the offset.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_calibration_coefficient_write(uint8_t address, uint8_t channel, double slope, double offset)
Temporarily write the MCC 118 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 mcc118_open() is called. This function will fail and return RESULT_BUSY 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:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 7).
slope – The new slope value.
offset – The new offset value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_a_in_read(uint8_t address, uint8_t channel, uint32_t options, double *value)
Perform a single reading of an analog input channel and return the value.
The valid options are:
OPTS_NOSCALEDATA: Return ADC code (a value between 0 and 4095) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
The options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the value read from the ADC without calibration or converting to voltage.
The function will return RESULT_BUSY if called while a scan is running.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number, 0 - 7.
options – Options bitmask.
value – Receives the analog input value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_trigger_mode(uint8_t address, uint8_t mode)
Set the trigger input mode.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
mode – One of the trigger mode values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_a_in_scan_actual_rate(uint8_t channel_count, double sample_rate_per_channel, double *actual_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. This function does not perform any actions with a board, it simply calculates the rate.
- Parameters:
channel_count – The number of channels in the scan.
sample_rate_per_channel – The desired sampling rate in samples per second per channel, max 100,000.
actual_sample_rate_per_channel – The actual sample rate that would occur when requesting this rate on an MCC 118, or 0 if there is an error.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_BAD_PARAMETER if the scan parameters are not achievable on an MCC 118.
-
int mcc118_a_in_scan_start(uint8_t address, uint8_t channel_mask, uint32_t samples_per_channel, double sample_rate_per_channel, uint32_t options)
Start a hardware-paced analog input scan.
The scan runs as a separate thread from the user’s code. The function will allocate a scan buffer and read data from the device into that buffer. The user reads the data from this buffer and the scan status using the mcc118_a_in_scan_read() function. mcc118_a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call mcc118_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: mcc118_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 mcc118_a_in_scan_cleanup(), so another scan may not be started.
Running: The scan is active and the device is still acquiring data. Certain functions like mcc118_a_in_read() will return an error because the device is busy.
The valid options are:
OPTS_NOSCALEDATA: Returns ADC code (a value between 0 and 4095) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
OPTS_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 option 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.
OPTS_EXTTRIGGER: Hold off the scan (after calling mcc118_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.
OPTS_CONTINUOUS: Scans continuously until stopped by the user by calling mcc118_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 options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data, internal scan clock, no trigger, and finite operation.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the values read from the ADC without calibration or converting to voltage.
The buffer size will be allocated as follows:
Finite mode: Total number of samples in the scan
Continuous mode (buffer size is per channel): Either samples_per_channel or the value in the following table, 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 return RESULT_RESOURCE_UNAVAIL. 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 already active this function will return RESULT_BUSY.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel_mask – A bit mask of the channels to be scanned. Set each bit to enable the associated channel (0x01 - 0xFF.)
samples_per_channel – The number of samples to acquire for each channel in the scan (finite mode,) or can be used to set a larger scan buffer size than the default value (continuous mode.)
sample_rate_per_channel – The sampling rate in samples per second per channel, max 100,000. When using an external sample clock set this value to the maximum expected rate of the clock.
options – The options bitmask.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
-
int mcc118_a_in_scan_buffer_size(uint8_t address, uint32_t *buffer_size_samples)
Returns the size of the internal scan data buffer.
An internal data buffer is allocated for the scan when mcc118_a_in_scan_start() is called. This function returns the total size of that buffer in samples.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer_size_samples – Receives the size of the buffer in samples. Each sample is a double.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not currently active, RESULT_BAD_PARAMETER if the address is invalid or buffer_size_samples is NULL.
-
int mcc118_a_in_scan_status(uint8_t address, uint16_t *status, uint32_t *samples_per_channel)
Reads status and number of available samples from an analog input scan.
The scan is started with mcc118_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the status of the scan and amount of data in the scan buffer.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – Receives the number of samples per channel available in the scan thread buffer.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
-
int mcc118_a_in_scan_read(uint8_t address, uint16_t *status, int32_t samples_per_channel, double timeout, double *buffer, uint32_t buffer_size_samples, uint32_t *samples_read_per_channel)
Reads status and multiple samples from an analog input scan.
The scan is started with mcc118_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the data from the scan buffer, and returns the current scan status.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – The number of samples per channel to read. Specify -1 to read all available samples in the scan thread buffer, ignoring timeout. If buffer does not contain enough space then the function will read as many samples per channel as will fit in buffer.
timeout – 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 whatever samples are available (up to the value of samples_per_channel or buffer_size_samples.)
buffer – The user data buffer that receives the samples.
buffer_size_samples – The size of the buffer in samples. Each sample is a double.
samples_read_per_channel – Returns the actual number of samples read from each channel.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
-
int mcc118_a_in_scan_channel_count(uint8_t address)
Return the number of channels in the current analog input scan.
This function returns 0 if no scan is active.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
The number of channels, 0 - 8.
-
int mcc118_a_in_scan_stop(uint8_t address)
Stops an analog input scan.
The scan is stopped immediately. The scan data that has been read into the scan buffer is available until mcc118_a_in_scan_cleanup() is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc118_a_in_scan_cleanup(uint8_t address)
Free analog input scan resources after the scan is complete.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
Data definitions
Device Info
-
struct MCC118DeviceInfo
MCC 118 constant device information.
Public Members
-
const uint8_t NUM_AI_CHANNELS
The number of analog input channels (8.)
-
const uint16_t AI_MIN_CODE
The minimum ADC code (0.)
-
const uint16_t AI_MAX_CODE
The maximum ADC code (4095.)
-
const double AI_MIN_VOLTAGE
The input voltage corresponding to the minimum code (-10.0V.)
-
const double AI_MAX_VOLTAGE
The input voltage corresponding to the maximum code (+10.0V - 1 LSB.)
-
const double AI_MIN_RANGE
The minimum voltage of the input range (-10.0V.)
-
const double AI_MAX_RANGE
The maximum voltage of the input range (+10.0V.)
-
const uint8_t NUM_AI_CHANNELS
MCC 128 functions and data
Functions
Function |
Description |
Open an MCC 128 for use. |
|
Check if an MCC 128 is open. |
|
Close an MCC 128. |
|
Return information about this device type. |
|
Blink the MCC 128 LED. |
|
Get the firmware version. |
|
Read the serial number. |
|
Read the calibration date. |
|
Read the calibration coefficients for a channel. |
|
Write the calibration coefficients for a channel. |
|
Set the external trigger input mode. |
|
Read the analog input mode. |
|
Write the analog input mode. |
|
Read the analog input range. |
|
Write the analog input range. |
|
Read an analog input value. |
|
Read the actual sample rate for a set of scan parameters. |
|
Start a hardware-paced analog input scan. |
|
Read the size of the internal scan data buffer. |
|
Read the scan status. |
|
Read scan data and status. |
|
Get the number of channels in the current scan. |
|
Stop the scan. |
|
Free scan resources. |
-
int mcc128_open(uint8_t address)
Open a connection to the MCC 128 device at the specified address.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_close(uint8_t address)
Close a connection to an MCC 128 device and free allocated resources.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_is_open(uint8_t address)
Check if an MCC 128 is open.
- Parameters:
address – The board address (0 - 7).
- Returns:
1 if open, 0 if not open.
-
struct MCC128DeviceInfo *mcc128_info(void)
Return constant device information for all MCC 128s.
- Returns:
Pointer to struct MCC128DeviceInfo.
-
int mcc128_blink_led(uint8_t address, uint8_t count)
Blink the LED on the MCC 128.
Passing 0 for count will result in the LED blinking continuously until the board is reset or mcc128_blink_led() is called again with a non-zero value for count.
- Parameters:
address – The board address (0 - 7).
count – The number of times to blink (0 - 255).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_firmware_version(uint8_t address, uint16_t *version)
Return the board firmware version.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
version – Receives the firmware version. The version will be in BCD hexadecimal with the high byte as the major version and low byte as minor, i.e. 0x0103 is version 1.03.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_serial(uint8_t address, char *buffer)
Read the MCC 128 serial number.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the serial number as a string. The buffer must be at least 9 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_calibration_date(uint8_t address, char *buffer)
Read the MCC 128 calibration date.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the date as a string (format “YYYY-MM-DD”). The buffer must be at least 11 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_calibration_coefficient_read(uint8_t address, uint8_t range, double *slope, double *offset)
Read the MCC 128 calibration coefficients for a specified input range.
The coefficients are applied in the library as:
calibrated_ADC_code = (raw_ADC_code * slope) + offset
- Parameters:
address – The board address (0 - 7). Board must already be opened.
range – The input range, one of the input range values.
slope – Receives the slope.
offset – Receives the offset.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_calibration_coefficient_write(uint8_t address, uint8_t range, double slope, double offset)
Temporarily write the MCC 128 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 mcc128_open() is called. This function will fail and return RESULT_BUSY 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:
address – The board address (0 - 7). Board must already be opened.
range – The input range, one of the input range values.
slope – The new slope value.
offset – The new offset value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_mode_read(uint8_t address, uint8_t *mode)
Read the analog input mode.
Reads the current analog input mode.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
mode – Receives the input mode.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_mode_write(uint8_t address, uint8_t mode)
Set the analog input mode.
This sets the analog inputs to one of the valid values:
A_IN_MODE_SE: Single-ended (8 inputs relative to ground.)
A_IN_MODE_DIFF: Differential (4 channels with positive and negative inputs.)
This function will fail and return RESULT_BUSY if a scan is active when it is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
mode – One of the input mode values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_range_read(uint8_t address, uint8_t *range)
Read the analog input range.
Returns the current analog input range.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
range – Receives the input range.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_range_write(uint8_t address, uint8_t range)
Set the analog input range.
This sets the analog input range to one of the valid ranges:
A_IN_RANGE_BIP_10V: +/- 10V
A_IN_RANGE_BIP_5V: +/- 5V
A_IN_RANGE_BIP_2V: +/- 2V
A_IN_RANGE_BIP_1V: +/- 1V
This function will fail and return RESULT_BUSY if a scan is active when it is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
range – One of the input range values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_trigger_mode(uint8_t address, uint8_t mode)
Set the trigger input mode.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
mode – One of the trigger mode values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_read(uint8_t address, uint8_t channel, uint32_t options, double *value)
Perform a single reading of an analog input channel and return the value.
The valid options are:
OPTS_NOSCALEDATA: Return ADC code (a value between 0 and 65535) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
The options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the value read from the ADC without calibration or converting to voltage.
The function will return RESULT_BUSY if called while a scan is running.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number, 0 - 7.
options – Options bitmask.
value – Receives the analog input value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_scan_actual_rate(uint8_t channel_count, double sample_rate_per_channel, double *actual_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. This function does not perform any actions with a board, it simply calculates the rate.
- Parameters:
channel_count – The number of channels in the scan.
sample_rate_per_channel – The desired sampling rate in samples per second per channel, max 100,000.
actual_sample_rate_per_channel – The actual sample rate that would occur when requesting this rate on an MCC 128, or 0 if there is an error.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_BAD_PARAMETER if the scan parameters are not achievable on an MCC 128.
-
int mcc128_a_in_scan_start(uint8_t address, uint8_t channel_mask, uint32_t samples_per_channel, double sample_rate_per_channel, uint32_t options)
Start a hardware-paced analog input scan.
The scan runs as a separate thread from the user’s code. The function will allocate a scan buffer and read data from the device into that buffer. The user reads the data from this buffer and the scan status using the mcc128_a_in_scan_read() function. mcc128_a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call mcc128_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: mcc128_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 mcc128_a_in_scan_cleanup(), so another scan may not be started.
Running: The scan is active and the device is still acquiring data. Certain functions like mcc128_a_in_read() will return an error because the device is busy.
The valid options are:
OPTS_NOSCALEDATA: Returns ADC code (a value between 0 and 65535) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
OPTS_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 option 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.
OPTS_EXTTRIGGER: Hold off the scan (after calling mcc128_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.
OPTS_CONTINUOUS: Scans continuously until stopped by the user by calling mcc128_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 options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data, internal scan clock, no trigger, and finite operation.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the values read from the ADC without calibration or converting to voltage.
The buffer size will be allocated as follows:
Finite mode: Total number of samples in the scan
Continuous mode (buffer size is per channel): Either samples_per_channel or the value in the following table, 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 return RESULT_RESOURCE_UNAVAIL. 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 already active this function will return RESULT_BUSY.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel_mask – A bit mask of the channels to be scanned. Set each bit to enable the associated channel (0x01 - 0xFF.)
samples_per_channel – The number of samples to acquire for each channel in the scan (finite mode), or can be used to set a larger scan buffer size than the default value (continuous mode.)
sample_rate_per_channel – The sampling rate in samples per second per channel, max 100,000. When using an external sample clock set this value to the maximum expected rate of the clock.
options – The options bitmask.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
-
int mcc128_a_in_scan_buffer_size(uint8_t address, uint32_t *buffer_size_samples)
Returns the size of the internal scan data buffer.
An internal data buffer is allocated for the scan when mcc128_a_in_scan_start() is called. This function returns the total size of that buffer in samples.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer_size_samples – Receives the size of the buffer in samples. Each sample is a double.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not currently active, RESULT_BAD_PARAMETER if the address is invalid or buffer_size_samples is NULL.
-
int mcc128_a_in_scan_status(uint8_t address, uint16_t *status, uint32_t *samples_per_channel)
Reads status and number of available samples from an analog input scan.
The scan is started with mcc128_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the status of the scan and amount of data in the scan buffer.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – Receives the number of samples per channel available in the scan thread buffer.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
-
int mcc128_a_in_scan_read(uint8_t address, uint16_t *status, int32_t samples_per_channel, double timeout, double *buffer, uint32_t buffer_size_samples, uint32_t *samples_read_per_channel)
Reads status and multiple samples from an analog input scan.
The scan is started with mcc128_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the data from the scan buffer, and returns the current scan status.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – The number of samples per channel to read. Specify -1 to read all available samples in the scan thread buffer, ignoring timeout. If buffer does not contain enough space then the function will read as many samples per channel as will fit in buffer.
timeout – 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 whatever samples are available (up to the value of samples_per_channel or buffer_size_samples.)
buffer – The user data buffer that receives the samples.
buffer_size_samples – The size of the buffer in samples. Each sample is a double.
samples_read_per_channel – Returns the actual number of samples read from each channel.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
-
int mcc128_a_in_scan_channel_count(uint8_t address)
Return the number of channels in the current analog input scan.
This function returns 0 if no scan is active.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
The number of channels, 0 - 8.
-
int mcc128_a_in_scan_stop(uint8_t address)
Stops an analog input scan.
The scan is stopped immediately. The scan data that has been read into the scan buffer is available until mcc128_a_in_scan_cleanup() is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc128_a_in_scan_cleanup(uint8_t address)
Free analog input scan resources after the scan is complete.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
Data definitions
Device Info
-
struct MCC128DeviceInfo
MCC 128 constant device information.
Public Members
-
const uint8_t NUM_AI_MODES
The number of analog input modes (2.)
-
const uint8_t NUM_AI_CHANNELS[2]
The number of analog input channels in each mode (8, 4.)
-
const uint16_t AI_MIN_CODE
The minimum ADC code (0.)
-
const uint16_t AI_MAX_CODE
The maximum ADC code (65535.)
-
const uint8_t NUM_AI_RANGES
The number of analog input ranges (4.)
-
const double AI_MIN_VOLTAGE[4]
The input voltage corresponding to the minimum code in each range (-10.0V, -5.0V, -2.0V, -1.0V.)
-
const double AI_MAX_VOLTAGE[4]
The input voltage corresponding to the maximum code in each range (+10.0V - 1 LSB, +5.0V - 1 LSB, +2.0V - 1 LSB, +1.0V - 1 LSB.)
-
const double AI_MIN_RANGE[4]
The minimum voltage of the input range in each range (-10.0V, -5.0V, -2.0V, -1.0V.)
-
const double AI_MAX_RANGE[4]
The maximum voltage of the input range in each range (+10.0V, +5.0V, +2.0V, +1.0V.)
-
const uint8_t NUM_AI_MODES
Analog Input Modes
Analog Input Ranges
MCC 134 functions and data
Functions
Function |
Description |
Open an MCC 134 for use. |
|
Check if an MCC 134 is open. |
|
Close an MCC 134. |
|
Return information about this device type. |
|
Read the serial number. |
|
Read the calibration date. |
|
Read the calibration coefficients for a channel. |
|
Write the calibration coefficients for a channel. |
|
Write the thermocouple type for a channel. |
|
Read the thermocouple type for a channel. |
|
Write the temperature update interval. |
|
Read the temperature update interval. |
|
Read a temperature input value. |
|
Read an analog input value. |
|
Read a CJC temperature. |
-
int mcc134_open(uint8_t address)
Open a connection to the MCC 134 device at the specified address.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_is_open(uint8_t address)
Check if an MCC 134 is open.
- Parameters:
address – The board address (0 - 7).
- Returns:
1 if open, 0 if not open.
-
int mcc134_close(uint8_t address)
Close a connection to an MCC 134 device and free allocated resources.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
struct MCC134DeviceInfo *mcc134_info(void)
Return constant device information for all MCC 134s.
- Returns:
Pointer to struct MCC134DeviceInfo.
-
int mcc134_serial(uint8_t address, char *buffer)
Read the MCC 134 serial number.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the serial number as a string. The buffer must be at least 9 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_calibration_date(uint8_t address, char *buffer)
Read the MCC 134 calibration date.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the date as a string (format “YYYY-MM-DD”). The buffer must be at least 11 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_calibration_coefficient_read(uint8_t address, uint8_t channel, double *slope, double *offset)
Read the MCC 134 calibration coefficients for a single channel.
The coefficients are applied in the library as:
calibrated_ADC_code = (raw_ADC_code * slope) + offset
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 3).
slope – Receives the slope.
offset – Receives the offset.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_calibration_coefficient_write(uint8_t address, uint8_t channel, double slope, double offset)
Temporarily write the MCC 134 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 mcc134_open() is called.
The coefficients are applied in the library as:
calibrated_ADC_code = (raw_ADC_code * slope) + offset
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 3).
slope – The new slope value.
offset – The new offset value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_tc_type_write(uint8_t address, uint8_t channel, uint8_t type)
Write the thermocouple type for a channel.
Tells the MCC 134 library what thermocouple type is connected to the specified channel and enables the channel. This is required for correct temperature calculations. The type is one of TcTypes and the board will default to all disabled (set to TC_DISABLED) when it is first opened.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number (0 - 3).
type – The thermocouple type, one of TcTypes.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_tc_type_read(uint8_t address, uint8_t channel, uint8_t *type)
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 disabled (set to TC_DISABLED) when it is first opened.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number (0 - 3).
type – Receives the thermocouple type, one of TcTypes.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_update_interval_write(uint8_t address, uint8_t 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 mcc134_t_in_read() very often. This will reduce the load on shared resources for other DAQ HATs.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
interval – The interval in seconds (1 - 255).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_update_interval_read(uint8_t address, uint8_t *interval)
Read the temperature update interval.
Reads the library temperature update rate in seconds.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
interval – Receives the update rate.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_t_in_read(uint8_t address, uint8_t channel, double *value)
Read a temperature input channel.
Reads the specified channel and returns the value as degrees Celsius. The channel must be enabled with mcc134_tc_type_write() or the function will return RESULT_BAD_PARAMETER.
This function returns immediately with the most recent internal temperature reading for the specified channel. When a board is open, the library will read each channel once per second. This interval can be increased with mcc134_update_interval_write(). 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 returned temperature can have some special values to indicate abnormal conditions:
OPEN_TC_VALUE if an open thermocouple is detected on the channel.
OVERRANGE_TC_VALUE if an overrange is detected on the channel.
COMMON_MODE_TC_VALUE if a common-mode error is detected on the channel. This occurs when thermocouples attached to the board are at different voltages.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number (0 - 3.)
value – Receives the temperature value in degrees C.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_a_in_read(uint8_t address, uint8_t channel, uint32_t options, double *value)
Read an analog input channel and return the value.
This function returns immediately with the most recent voltage or ADC code reading for the specified channel. The channel must be enabled with mcc134_tc_type_write() or the function will return RESULT_BAD_PARAMETER.
The library reads the ADC at the time interval set with mcc134_update_interval_write(), which defaults to 1 second. This interval may be increased with mcc134_update_interval_write().
The returned voltage can have a special value to indicate abnormal conditions:
COMMON_MODE_TC_VALUE if a common-mode error is detected on the channel. This occurs when thermocouples attached to the board are at different voltages.
The valid options are:
OPTS_NOSCALEDATA: Return ADC code (a value between -8,388,608 and 8,388,607) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
The options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the value read from the ADC without calibration or converting to voltage.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number (0 - 3).
options – Options bitmask.
value – Receives the analog input value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc134_cjc_read(uint8_t address, uint8_t channel, double *value)
Read the cold junction compensation temperature for a specified channel.
Returns the most recent 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.
The library reads the cold junction compensation sensors at the time interval set with mcc134_update_interval_write(), which defaults to 1 second. This interval may be increased with mcc134_update_interval_write().
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog input channel number, 0 - 3.
value – Receives the read value.
- Returns:
Result code, RESULT_SUCCESS if successful.
Data definitions
-
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 voltage outside the common-mode range.
Device Info
-
struct MCC134DeviceInfo
MCC 134 constant device information.
Public Members
-
const uint8_t NUM_AI_CHANNELS
The number of analog input channels (4.)
-
const int32_t AI_MIN_CODE
The minimum ADC code (-8,388,608.)
-
const int32_t AI_MAX_CODE
The maximum ADC code (8,388,607.)
-
const double AI_MIN_VOLTAGE
The input voltage corresponding to the minimum code (-0.078125V.)
-
const double AI_MAX_VOLTAGE
The input voltage corresponding to the maximum code (+0.078125V - 1 LSB.)
-
const double AI_MIN_RANGE
The minimum voltage of the input range (-0.078125V.)
-
const double AI_MAX_RANGE
The maximum voltage of the input range (0.078125V.)
-
const uint8_t NUM_AI_CHANNELS
Thermocouple Types
-
enum TcTypes
Thermocouple type constants.
Values:
-
enumerator TC_TYPE_J
J type.
-
enumerator TC_TYPE_K
K type.
-
enumerator TC_TYPE_T
T type
-
enumerator TC_TYPE_E
E type
-
enumerator TC_TYPE_R
R type.
-
enumerator TC_TYPE_S
S type.
-
enumerator TC_TYPE_B
B type.
-
enumerator TC_TYPE_N
N type.
-
enumerator TC_DISABLED
Input disabled.
-
enumerator TC_TYPE_J
MCC 152 functions and data
Functions
Function |
Description |
Open an MCC 152 for use. |
|
Check if an MCC 152 is open. |
|
Close an MCC 152. |
|
Return information about this device type. |
|
Read the serial number. |
|
Write an analog output channel value. |
|
Write all analog output channels simultaneously. |
|
Reset the digital I/O to the default configuration. |
|
Read a digital input. |
|
Read all digital inputs. |
|
Write a digital output. |
|
Write all digital outputs. |
|
Read the state of a digital output. |
|
Read the state of all digital outputs. |
|
Read the interrupt status for a single channel. |
|
Read the interrupt status for all channels. |
|
Write a digital I/O configuration item value for a single channel. |
|
Write a digital I/O configuration item value for all channels. |
|
Read a digital I/O configuration item value for a single channel. |
|
Read a digital I/O configuration item value for all channels. |
-
int mcc152_open(uint8_t address)
Open a connection to the MCC 152 device at the specified address.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_is_open(uint8_t address)
Check if an MCC 152 is open.
- Parameters:
address – The board address (0 - 7).
- Returns:
1 if open, 0 if not open.
-
int mcc152_close(uint8_t address)
Close a connection to an MCC 152 device and free allocated resources.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
struct MCC152DeviceInfo *mcc152_info(void)
Return constant device information for all MCC 152s.
- Returns:
Pointer to struct MCC152DeviceInfo.
-
int mcc152_serial(uint8_t address, char *buffer)
Read the MCC 152 serial number.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the serial number as a string. The buffer must be at least 9 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_a_out_write(uint8_t address, uint8_t channel, uint32_t options, double value)
Perform a write to an analog output channel.
Updates the analog output channel in either volts or DAC code (set the OPTS_NOSCALEDATA option to use DAC code.) The voltage must be 0.0 - 5.0 and DAC code 0.0 - 4095.0.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The analog output channel number, 0 - 1.
options – Options bitmask
value – The analog output value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_a_out_write_all(uint8_t address, uint32_t options, double *values)
Perform a write to all analog output channels simultaneously.
Update all analog output channels in either volts or DAC code (set the OPTS_NOSCALEDATA option to use DAC code.) The outputs will update at the same time.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
options – Options bitmask
values – The array of analog output values; there must be at least 2 values, but only the first two values will be used.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_reset(uint8_t address)
Reset the digital I/O 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
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_input_read_bit(uint8_t address, uint8_t channel, uint8_t *value)
Read a single digital input channel.
Returns 0 or 1 in value. If the specified channel is configured as an output this will return the value present at the terminal.
This function reads the entire input register, 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 mcc152_dio_input_read_port() when using latched inputs.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The DIO channel number, 0 - 7.
value – Receives the input value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_input_read_port(uint8_t address, uint8_t *value)
Read all digital input channels simultaneously.
Returns an 8-bit value in value representing all channels in channel order (bit 0 is channel 0, etc.) 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.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
value – Receives the input values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_output_write_bit(uint8_t address, uint8_t channel, uint8_t 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:
address – The board address (0 - 7). Board must already be opened.
channel – The DIO channel number, 0 - 7.
value – The output value (0 or 1)
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_output_write_port(uint8_t address, uint8_t value)
Write all digital output channels simultaneously.
Pass an 8-bit value in value representing the desired output for all channels in channel order (bit 0 is channel 0, etc.)
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.
For example, to set channels 0 - 3 to 0 and channels 4 - 7 to 1 call:
mcc152_dio_output_write(address, 0xF0);
- Parameters:
address – The board address (0 - 7). Board must already be opened.
value – The output values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_output_read_bit(uint8_t address, uint8_t channel, uint8_t *value)
Read a single digital output register.
Returns 0 or 1 in 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:
address – The board address (0 - 7). Board must already be opened.
channel – The DIO channel number, 0 - 7.
value – Receives the output value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_output_read_port(uint8_t address, uint8_t *value)
Read all digital output registers simultaneously.
Returns an 8-bit value in value representing all channels in channel order (bit 0 is channel 0, etc.)
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:
address – The board address (0 - 7). Board must already be opened.
value – Receives the output values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_int_status_read_bit(uint8_t address, uint8_t channel, uint8_t *value)
Read the interrupt status for a single channel.
Returns 0 when the channel is not generating an interrupt, 1 when the channel is generating an interrupt.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The DIO channel number, 0 - 7.
value – Receives the interrupt status value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_int_status_read_port(uint8_t address, uint8_t *value)
Read the interrupt status for all channels.
Returns an 8-bit value in value representing all channels in channel order (bit 0 is channel 0, etc.) A 0 in a bit indicates the corresponding channel is not generating an interrupt, a 1 indicates the channel is generating an interrupt.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
value – Receives the interrupt status value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_config_write_bit(uint8_t address, uint8_t channel, uint8_t item, uint8_t 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:
DIO_DIRECTION: Set the digital I/O channel direction by passing 0 for output and 1 for input.
DIO_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 DIO_PULL_ENABLE item.
DIO_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 DIO_PULL_CONFIG item. The resistor is automatically disabled if the bit is set to output and is configured as open-drain.
DIO_INPUT_INVERT: Enable inverting the input by passing a 0 for normal input or 1 for inverted.
DIO_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 function still reads the entire input register so a change on another bit could be missed. It is best to use port 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.
DIO_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 will be ignored. It should be set to the desired type before using the DIO_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.
DIO_INT_MASK: Enable or disable interrupt generation for the input by masking the interrupt. Write 0 to enable the interrupt or 1 to 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 hat_interrupt_state(). A user program may wait for the interrupt to become active with hat_wait_for_interrupt(), or may register an interrrupt callback function with hat_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 mcc152_dio_int_status_read_bit() or mcc152_dio_int_status_read_port(), and all active interrupt sources must be cleared before the interrupt will become inactive. The interrupt is cleared by reading the input(s) with mcc152_dio_input_read_bit() or mcc152_dio_input_read_port().
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The digital I/O channel, 0 - 7.
item – The config item, one of DIOConfigItem.
value – The config value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_config_write_port(uint8_t address, uint8_t item, uint8_t 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 the 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:
DIO_DIRECTION: Set the digital I/O channel directions by passing 0 in a bit for output and 1 for input.
DIO_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 DIO_PULL_ENABLE item.
DIO_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 DIO_PULL_CONFIG item. The resistors are automatically disabled if a bit is set to output and is configured as open-drain.
DIO_INPUT_INVERT: Enable inverting inputs by passing a 0 in a bit for normal input or 1 for inverted.
DIO_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 function still reads the entire input register so a change on another bit could be missed. It is best to use port 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.
DIO_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 DIO_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.
DIO_INT_MASK: Enable or disable interrupt generation for specific inputs by masking the interrupts. Write 0 in a bit to enable the interrupt from that channel or 1 to 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 hat_interrupt_state(). A user program may wait for the interrupt to become active with hat_wait_for_interrupt(), or may register an interrrupt callback function with hat_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 mcc152_dio_int_status_read_bit() or mcc152_dio_int_status_read_port(), and all active interrupt sources must be cleared before the interrupt will become inactive. The interrupt is cleared by reading the input(s) with mcc152_dio_input_read_bit() or mcc152_dio_input_read_port().
- Parameters:
address – The board address (0 - 7). Board must already be opened.
item – The config item, one of DIOConfigItem.
value – The config value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_config_read_bit(uint8_t address, uint8_t channel, uint8_t item, uint8_t *value)
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 DIOConfigItem values:
DIO_DIRECTION: Read the digital I/O channel direction setting, where 0 is output and 1 is input.
DIO_PULL_CONFIG: Read the pull-up/down resistor configuration where 0 is pull-down and 1 is pull-up.
DIO_PULL_ENABLE: Read the pull-up/down resistor enable setting where 0 is disabled and 1 is enabled.
DIO_INPUT_INVERT: Read the input invert setting where 0 is normal input and 1 is inverted.
DIO_INPUT_LATCH: Read the input latching setting where 0 is non-latched and 1 is latched.
DIO_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 and the channel argument is ignored.
DIO_INT_MASK: Read the interrupt mask setting where 0 enables the interrupt and 1 disables it.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The digital I/O channel, 0 - 7.
item – The config item, one of DIOConfigItem.
value – Receives the config value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc152_dio_config_read_port(uint8_t address, uint8_t item, uint8_t *value)
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 value 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:
DIO_DIRECTION: Read the digital I/O channels direction settings, where 0 for a bit is output and 1 is input.
DIO_PULL_CONFIG: Read the pull-up/down resistor configurations where 0 for a bit is pull-down and 1 is pull-up.
DIO_PULL_ENABLE: Read the pull-up/down resistor enable settings where 0 for a bit is disabled and 1 is enabled.
DIO_INPUT_INVERT: Read the input invert settings where 0 for a bit is normal input and 1 is inverted.
DIO_INPUT_LATCH: Read the input latching settings where 0 for a bit is non-latched and 1 is latched.
DIO_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.
DIO_INT_MASK: Read the interrupt mask settings where 0 enables the interrupt from the corresponding channel and 1 disables it.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
item – The config item, one of DIOConfigItem.
value – Receives the config value.
- Returns:
Result code, RESULT_SUCCESS if successful.
Data types and definitions
Device Info
-
struct MCC152DeviceInfo
MCC 152 constant device information.
Public Members
-
const uint8_t NUM_DIO_CHANNELS
The number of digital I/O channels (8.)
-
const uint8_t NUM_AO_CHANNELS
The number of analog output channels (2.)
-
const uint16_t AO_MIN_CODE
The minimum DAC code (0.)
-
const uint16_t AO_MAX_CODE
The maximum DAC code (4095.)
-
const double AO_MIN_VOLTAGE
The output voltage corresponding to the minimum code (0.0V.)
-
const double AO_MAX_VOLTAGE
The output voltage corresponding to the maximum code (+5.0V - 1 LSB.)
-
const double AO_MIN_RANGE
The minimum voltage of the output range (0.0V.)
-
const double AO_MAX_RANGE
The maximum voltage of the output range (+5.0V.)
-
const uint8_t NUM_DIO_CHANNELS
DIO Config Items
-
enum DIOConfigItem
DIO Configuration Items.
Values:
-
enumerator DIO_DIRECTION
Configure channel direction.
-
enumerator DIO_PULL_CONFIG
Configure pull-up/down resistor.
-
enumerator DIO_PULL_ENABLE
Enable pull-up/down resistor.
-
enumerator DIO_INPUT_INVERT
Configure input inversion.
-
enumerator DIO_INPUT_LATCH
Configure input latching.
-
enumerator DIO_OUTPUT_TYPE
Configure output type.
-
enumerator DIO_INT_MASK
Configure interrupt mask.
-
enumerator DIO_DIRECTION
MCC 172 functions and data
Functions
Function |
Description |
Open an MCC 172 for use. |
|
Check if an MCC 172 is open. |
|
Close an MCC 172. |
|
Return information about this device type. |
|
Blink the MCC 172 LED. |
|
Get the firmware version. |
|
Read the serial number. |
|
Read the calibration date. |
|
Read the calibration coefficients for a channel. |
|
Write the calibration coefficients for a channel. |
|
Read the IEPE configuration for a channel. |
|
Write the IEPE configuration for a channel. |
|
Read the sensitivity scaling for a channel. |
|
Write the sensitivity scaling for a channel. |
|
Read the sampling clock configuration. |
|
Write the sampling clock configuration. |
|
Configure the external trigger input. |
|
Start a hardware-paced analog input scan. |
|
Read the size of the internal scan data buffer. |
|
Read the scan status. |
|
Read scan data and status. |
|
Get the number of channels in the current scan. |
|
Stop the scan. |
|
Free scan resources. |
-
int mcc172_open(uint8_t address)
Open a connection to the MCC 172 device at the specified address.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_close(uint8_t address)
Close a connection to an MCC 172 device and free allocated resources.
- Parameters:
address – The board address (0 - 7).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_is_open(uint8_t address)
Check if an MCC 172 is open.
- Parameters:
address – The board address (0 - 7).
- Returns:
1 if open, 0 if not open.
-
struct MCC172DeviceInfo *mcc172_info(void)
Return constant device information for all MCC 172s.
- Returns:
Pointer to struct MCC172DeviceInfo.
-
int mcc172_blink_led(uint8_t address, uint8_t count)
Blink the LED on the MCC 172.
Passing 0 for count will result in the LED blinking continuously until the board is reset or mcc172_blink_led() is called again with a non-zero value for count.
- Parameters:
address – The board address (0 - 7).
count – The number of times to blink (0 - 255).
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_firmware_version(uint8_t address, uint16_t *version)
Return the board firmware version.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
version – Receives the firmware version. The version will be in BCD hexadecimal with the high byte as the major version and low byte as minor, i.e. 0x0103 is version 1.03.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_serial(uint8_t address, char *buffer)
Read the MCC 172 serial number.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the serial number as a string. The buffer must be at least 9 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_calibration_date(uint8_t address, char *buffer)
Read the MCC 172 calibration date.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer – Pass a user-allocated buffer pointer to receive the date as a string (format “YYYY-MM-DD”). The buffer must be at least 11 characters in length.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_calibration_coefficient_read(uint8_t address, uint8_t channel, double *slope, double *offset)
Read the MCC 172 calibration coefficients for a single channel.
The coefficients are applied in the library as:
calibrated_ADC_code = (raw_ADC_code - offset) * slope
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
slope – Receives the slope.
offset – Receives the offset.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_calibration_coefficient_write(uint8_t address, uint8_t channel, double slope, double offset)
Temporarily write the MCC 172 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 mcc172_open() is called. This function will fail and return RESULT_BUSY 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:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
slope – The new slope value.
offset – The new offset value.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_iepe_config_read(uint8_t address, uint8_t channel, uint8_t *config)
Read the MCC 172 IEPE configuration for a single channel.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
config – Receives the configuration for the specified channel:
0: IEPE power off
1: IEPE power on
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_iepe_config_write(uint8_t address, uint8_t channel, uint8_t config)
Write the MCC 172 IEPE configuration for a single channel.
Writes the new IEPE configuration for a channel. This function will fail and return RESULT_BUSY if a scan is active when it is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
config – The IEPE configuration for the specified channel:
0: IEPE power off
1: IEPE power on
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_a_in_sensitivity_read(uint8_t address, uint8_t channel, double *value)
Read the MCC 172 analog input sensitivity scaling factor for a single channel.
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.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
value – Receives the sensitivity for the specified channel
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_a_in_sensitivity_write(uint8_t address, uint8_t channel, double 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 mcc172_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.
This function will fail and return RESULT_BUSY if a scan is active when it is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel – The channel number (0 - 1).
value – The sensitivity for the specified channel.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_a_in_clock_config_read(uint8_t address, uint8_t *clock_source, double *sample_rate_per_channel, uint8_t *synced)
Read the sampling clock configuration.
This function 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 the following values:
SOURCE_LOCAL: The clock is generated on this MCC 172 and not shared with other MCC 172s.
SOURCE_MASTER: The clock is generated on this MCC 172 and is shared as the master clock for other MCC 172s.
SOURCE_SLAVE: No clock is generated on this MCC 172, it receives its clock from the master MCC 172.
The data rate will not be valid in slave mode if synced is equal to 0. 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.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
clock_source – Receives the ADC clock source, one of the source type values.
sample_rate_per_channel – Receives the sample rate in samples per second per channel
synced – Receives the syncronization status (0: sync in progress, 1: sync complete)
- Returns:
Result code, RESULT_SUCCESS if successful
-
int mcc172_a_in_clock_config_write(uint8_t address, uint8_t clock_source, double sample_rate_per_channel)
Write the sampling clock configuration.
This function will configure the ADC sampling clock. The default configuration after opening the device is local mode, 51.2 KHz data rate.
The clock_source must be one of:
SOURCE_LOCAL: The clock is generated on this MCC 172 and not shared with other MCC 172s.
SOURCE_MASTER: The clock is generated on this MCC 172 and is shared as the master clock for other MCC 172s. All other MCC 172s must be configured for local or slave clock.
SOURCE_SLAVE: No clock is generated on this MCC 172, it receives its clock from the master MCC 172.
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 for multiple MCC 172s 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 an ADC sampling clock equal to 51.2 kHz divided by an integer between 1 and 256. The data_rate_per_channel will be internally converted to the nearest valid rate. The actual rate can be read back using mcc172_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 mcc172_a_in_clock_config_read() after this will return the measured data rate.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
clock_source – The ADC clock source, one of the source type values.
sample_rate_per_channel – The requested sample rate in samples per second per channel
- Returns:
Result code, RESULT_SUCCESS if successful
-
int mcc172_trigger_config(uint8_t address, uint8_t source, uint8_t 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:
SOURCE_LOCAL: The trigger terminal on this MCC 172 is used and not shared with other MCC 172s.
SOURCE_MASTER: The trigger terminal on this MCC 172 is used and is shared as the master trigger for other MCC 172s.
SOURCE_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:
TRIG_RISING_EDGE: Start the scan on a rising edge of TRIG.
TRIG_FALLING_EDGE: Start the scan on a falling edge of TRIG.
TRIG_ACTIVE_HIGH: Start the scan any time TRIG is high.
TRIG_ACTIVE_LOW: Start the scan any time TRIG is low.
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:
address – The board address (0 - 7). Board must already be opened.
source – The trigger source, one of the source type values.
mode – The trigger mode, one of the trigger mode values.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_a_in_scan_start(uint8_t address, uint8_t channel_mask, uint32_t samples_per_channel, uint32_t options)
Start capturing analog input data from the specified channels.
The scan runs as a separate thread from the user’s code. The function will allocate a scan buffer and read data from the device into that buffer. The user reads the data from this buffer and the scan status using the mcc172_a_in_scan_read() function. mcc172_a_in_scan_stop() is used to stop a continuous scan, or to stop a finite scan before it completes. The user must call mcc172_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 mcc172_a_in_clock_config_read() before starting the scan.
The scan state has defined terminology:
Active: mcc172_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 mcc172_a_in_scan_cleanup(), so another scan may not be started.
Running: The scan is active and the device is still acquiring data. Certain functions will return an error because the device is busy.
The valid options are:
OPTS_NOSCALEDATA: Returns ADC code (a value between AI_MIN_CODE and AI_MAX_CODE) rather than voltage.
OPTS_NOCALIBRATEDATA: Return data without the calibration factors applied.
OPTS_EXTTRIGGER: Hold off the scan (after calling mcc172_a_in_scan_start()) until the trigger condition is met.
OPTS_CONTINUOUS: Scans continuously until stopped by the user by calling mcc172_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 OPTS_EXTCLOCK option is not supported for this device and will return an error.
The options parameter is set to 0 or OPTS_DEFAULT for default operation, which is scaled and calibrated data, no trigger, and finite operation.
Multiple options may be specified by ORing the flags. For instance, specifying OPTS_NOSCALEDATA | OPTS_NOCALIBRATEDATA will return the values read from the ADC without calibration or converting to voltage.
The buffer size will be allocated as follows:
Finite mode: Total number of samples in the scan
Continuous mode (buffer size is per channel): Either samples_per_channel or the value in the following table, whichever is greater
Sample Rate
Buffer Size (per channel)
200-1024 S/s
1 kS
1280-10.24 kS/s
10 kS
12.8, 25.6, 51.2 kS/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 return RESULT_RESOURCE_UNAVAIL. 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 already active this function will return RESULT_BUSY.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
channel_mask – A bit mask of the channels to be scanned. Set each bit to enable the associated channel (0x01 - 0x03.)
samples_per_channel – The number of samples to acquire for each channel in the scan (finite mode,) or can be used to set a larger scan buffer size than the default value (continuous mode.)
options – The options bitmask.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
-
int mcc172_a_in_scan_buffer_size(uint8_t address, uint32_t *buffer_size_samples)
Returns the size of the internal scan data buffer.
An internal data buffer is allocated for the scan when mcc172_a_in_scan_start() is called. This function returns the total size of that buffer in samples.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
buffer_size_samples – Receives the size of the buffer in samples. Each sample is a double.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not currently active, RESULT_BAD_PARAMETER if the address is invalid or buffer_size_samples is NULL.
-
int mcc172_a_in_scan_status(uint8_t address, uint16_t *status, uint32_t *samples_per_channel)
Reads status and number of available samples from an analog input scan.
The scan is started with mcc172_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the status of the scan and amount of data in the scan buffer.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – Receives the number of samples per channel available in the scan thread buffer.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
-
int mcc172_a_in_scan_read(uint8_t address, uint16_t *status, int32_t samples_per_channel, double timeout, double *buffer, uint32_t buffer_size_samples, uint32_t *samples_read_per_channel)
Reads status and multiple samples from an analog input scan.
The scan is started with mcc172_a_in_scan_start() and runs in a background thread that reads the data from the board into an internal scan buffer. This function reads the data from the scan buffer, and returns the current scan status.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
status – Receives the scan status, an ORed combination of the flags:
STATUS_HW_OVERRUN: The device scan buffer was not read fast enough and data was lost.
STATUS_BUFFER_OVERRUN: The thread scan buffer was not read by the user fast enough and data was lost.
STATUS_TRIGGERED: The trigger conditions have been met.
STATUS_RUNNING: The scan is running.
samples_per_channel – The number of samples per channel to read. Specify -1 to read all available samples in the scan thread buffer, ignoring timeout. If buffer does not contain enough space then the function will read as many samples per channel as will fit in buffer.
timeout – 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 whatever samples are available (up to the value of samples_per_channel or buffer_size_samples.)
buffer – The user data buffer that receives the samples.
buffer_size_samples – The size of the buffer in samples. Each sample is a double.
samples_read_per_channel – Returns the actual number of samples read from each channel.
- Returns:
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
-
int mcc172_a_in_scan_channel_count(uint8_t address)
Return the number of channels in the current analog input scan.
This function returns 0 if no scan is active.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
The number of channels, 0 - 2.
-
int mcc172_a_in_scan_stop(uint8_t address)
Stops an analog input scan.
The scan is stopped immediately. The scan data that has been read into the scan buffer is available until mcc172_a_in_scan_cleanup() is called.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
-
int mcc172_a_in_scan_cleanup(uint8_t address)
Free analog input scan resources after the scan is complete.
- Parameters:
address – The board address (0 - 7). Board must already be opened.
- Returns:
Result code, RESULT_SUCCESS if successful.
Data definitions
Device Info
-
struct MCC172DeviceInfo
MCC 172 constant device information.
Public Members
-
const uint8_t NUM_AI_CHANNELS
The number of analog input channels (2.)
-
const int32_t AI_MIN_CODE
The minimum ADC code (-8,388,608.)
-
const int32_t AI_MAX_CODE
The maximum ADC code (8,388,607.)
-
const double AI_MIN_VOLTAGE
The input voltage corresponding to the minimum code (-5.0V.)
-
const double AI_MAX_VOLTAGE
The input voltage corresponding to the maximum code (+5.0V - 1 LSB.)
-
const double AI_MIN_RANGE
The minimum voltage of the input range (-5.0V.)
-
const double AI_MAX_RANGE
The maximum voltage of the input range (+5.0V.)
-
const uint8_t NUM_AI_CHANNELS