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
hat_list() Return a list of detected DAQ HAT boards.
hat_error_message() Return a text description for a DAQ HAT result.
hat_wait_for_interrupt() Wait for an interrupt to occur.
hat_interrupt_state() Read the current interrupt status.
hat_interrupt_callback_enable() Enable an interrupt callback function.
hat_interrupt_callback_disable() 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 Raspbian. 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);
}

Return
The number of boards found.
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.

const char* hat_error_message(int result)

Return a text description for a DAQ HAT result code.

Return
The error message.
Parameters
  • result: The Result code returned from a DAQ HAT function

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

Return
RESULT_TIMEOUT, RESULT_SUCCESS, or RESULT_UNDEFINED.
Parameters
  • timeout: Wait timeout in milliseconds. -1 to wait forever, 0 to return immediately.

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

Return
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: 

void function(void* user_data)

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

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

Return
RESULT_SUCCESS or RESULT_UNDEFINED.
Parameters
  • function: The callback function.
  • user_data: The data to pass to the callback function.

int hat_interrupt_callback_disable(void)

Disable interrupt callbacks.

Removes any callback function from the interrupt handler.

Return
RESULT_SUCCESS or RESULT_UNDEFINED.

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:

HAT_ID_ANY = 0

Match any DAQ HAT ID in hat_list().

HAT_ID_MCC_118 = 0x0142

MCC 118 ID.

HAT_ID_MCC_118_BOOTLOADER = 0x8142

MCC 118 in firmware update mode ID.

HAT_ID_MCC_128 = 0x0146

MCC 128 ID.

HAT_ID_MCC_134 = 0x0143

MCC 134 ID.

HAT_ID_MCC_152 = 0x0144

MCC 152 ID.

HAT_ID_MCC_172 = 0x0145

MCC 172 ID.

Result Codes

enum ResultCode

Return values from the library functions.

Values:

RESULT_SUCCESS = 0

Success, no errors.

RESULT_BAD_PARAMETER = -1

A parameter passed to the function was incorrect.

RESULT_BUSY = -2

The device is busy.

RESULT_TIMEOUT = -3

There was a timeout accessing a resource.

RESULT_LOCK_TIMEOUT = -4

There was a timeout while obtaining a resource lock.

RESULT_INVALID_DEVICE = -5

The device at the specified address is not the correct type.

RESULT_RESOURCE_UNAVAIL = -6

A needed resource was not available.

RESULT_COMMS_FAILURE = -7

Could not communicate with the device.

RESULT_UNDEFINED = -10

Some other error occurred.

HatInfo structure

struct HatInfo

Contains information about a specific board.

Public Members

uint8_t address

The board address.

uint16_t id

The product ID, one of HatIDs.

uint16_t version

The hardware version.

char HatInfo::product_name[256]

The product name.

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:

TRIG_RISING_EDGE = 0

Start the scan on a rising edge of TRIG.

TRIG_FALLING_EDGE = 1

Start the scan on a falling edge of TRIG.

TRIG_ACTIVE_HIGH = 2

Start the scan any time TRIG is high.

TRIG_ACTIVE_LOW = 3

Start the scan any time TRIG is low.

MCC 118 functions and data

Functions

Function Description
mcc118_open() Open an MCC 118 for use.
mcc118_is_open() Check if an MCC 118 is open.
mcc118_close() Close an MCC 118.
mcc118_info() Return information about this device type.
mcc118_blink_led() Blink the MCC 118 LED.
mcc118_firmware_version() Get the firmware version.
mcc118_serial() Read the serial number.
mcc118_calibration_date() Read the calibration date.
mcc118_calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc118_calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc118_a_in_read() Read an analog input value.
mcc118_trigger_mode() Set the external trigger input mode.
mcc118_a_in_scan_actual_rate() Read the actual sample rate for a set of scan parameters.
mcc118_a_in_scan_start() Start a hardware-paced analog input scan.
mcc118_a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc118_a_in_scan_status() Read the scan status.
mcc118_a_in_scan_read() Read scan data and status.
mcc118_a_in_scan_channel_count() Get the number of channels in the current scan.
mcc118_a_in_scan_stop() Stop the scan.
mcc118_a_in_scan_cleanup() Free scan resources.
int mcc118_open(uint8_t address)

Open a connection to the MCC 118 device at the specified address.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc118_close(uint8_t address)

Close a connection to an MCC 118 device and free allocated resources.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc118_is_open(uint8_t address)

Check if an MCC 118 is open.

Return
1 if open, 0 if not open.
Parameters
  • address: The board address (0 - 7).

struct MCC118DeviceInfo* mcc118_info(void)

Return constant device information for all MCC 118s.

Return
Pointer to struct MCC118DeviceInfo.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).
  • count: The number of times to blink (0 - 255).

int mcc118_firmware_version(uint8_t address, uint16_t * version, uint16_t * boot_version)

Return the board firmware and bootloader versions.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc118_serial(uint8_t address, char * buffer)

Read the MCC 118 serial number.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc118_calibration_date(uint8_t address, char * buffer)

Read the MCC 118 calibration date.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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:

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc118_trigger_mode(uint8_t address, uint8_t mode)

Set the trigger input mode.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • mode: One of the trigger mode values.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_BAD_PARAMETER if the scan parameters are not achievable on an MCC 118.
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.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
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.

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.

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

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • samples_per_channel: Receives the number of samples per channel available in the scan thread buffer.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • 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.

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.

Return
The number of channels, 0 - 8.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

int mcc118_a_in_scan_cleanup(uint8_t address)

Free analog input scan resources after the scan is complete.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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

MCC 128 functions and data

Functions

Function Description
mcc128_open() Open an MCC 128 for use.
mcc128_is_open() Check if an MCC 128 is open.
mcc128_close() Close an MCC 128.
mcc128_info() Return information about this device type.
mcc128_blink_led() Blink the MCC 128 LED.
mcc128_firmware_version() Get the firmware version.
mcc128_serial() Read the serial number.
mcc128_calibration_date() Read the calibration date.
mcc128_calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc128_calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc128_trigger_mode() Set the external trigger input mode.
mcc128_a_in_mode_read() Read the analog input mode.
mcc128_a_in_mode_write() Write the analog input mode.
mcc128_a_in_range_read() Read the analog input range.
mcc128_a_in_range_write() Write the analog input range.
mcc128_a_in_read() Read an analog input value.
mcc128_a_in_scan_actual_rate() Read the actual sample rate for a set of scan parameters.
mcc128_a_in_scan_start() Start a hardware-paced analog input scan.
mcc128_a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc128_a_in_scan_status() Read the scan status.
mcc128_a_in_scan_read() Read scan data and status.
mcc128_a_in_scan_channel_count() Get the number of channels in the current scan.
mcc128_a_in_scan_stop() Stop the scan.
mcc128_a_in_scan_cleanup() Free scan resources.
int mcc128_open(uint8_t address)

Open a connection to the MCC 128 device at the specified address.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc128_close(uint8_t address)

Close a connection to an MCC 128 device and free allocated resources.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc128_is_open(uint8_t address)

Check if an MCC 128 is open.

Return
1 if open, 0 if not open.
Parameters
  • address: The board address (0 - 7).

struct MCC128DeviceInfo* mcc128_info(void)

Return constant device information for all MCC 128s.

Return
Pointer to struct MCC128DeviceInfo.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).
  • count: The number of times to blink (0 - 255).

int mcc128_firmware_version(uint8_t address, uint16_t * version)

Return the board firmware version.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc128_serial(uint8_t address, char * buffer)

Read the MCC 128 serial number.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc128_calibration_date(uint8_t address, char * buffer)

Read the MCC 128 calibration date.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc128_a_in_mode_read(uint8_t address, uint8_t * mode)

Read the analog input mode.

Reads the current analog input mode.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • mode: Receives the input mode.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • mode: One of the input mode values.

int mcc128_a_in_range_read(uint8_t address, uint8_t * range)

Read the analog input range.

Returns the current analog input range.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • range: Receives the input range.

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:

This function will fail and return RESULT_BUSY if a scan is active when it is called.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • range: One of the input range values.

int mcc128_trigger_mode(uint8_t address, uint8_t mode)

Set the trigger input mode.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • mode: One of the trigger mode values.

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:

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_BAD_PARAMETER if the scan parameters are not achievable on an MCC 128.
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.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
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.

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.

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

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • samples_per_channel: Receives the number of samples per channel available in the scan thread buffer.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • 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.

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.

Return
The number of channels, 0 - 8.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

int mcc128_a_in_scan_cleanup(uint8_t address)

Free analog input scan resources after the scan is complete.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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 MCC128DeviceInfo::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 MCC128DeviceInfo::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 MCC128DeviceInfo::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 MCC128DeviceInfo::AI_MIN_RANGE[4]

The minimum voltage of the input range in each range (-10.0V, -5.0V, -2.0V, -1.0V.)

const double MCC128DeviceInfo::AI_MAX_RANGE[4]

The maximum voltage of the input range in each range (+10.0V, +5.0V, +2.0V, +1.0V.)

Analog Input Modes

enum AnalogInputMode

Analog input modes.

Values:

A_IN_MODE_SE = 0

Single-ended.

A_IN_MODE_DIFF = 1

Differential.

Analog Input Ranges

enum AnalogInputRange

Analog input ranges.

Values:

A_IN_RANGE_BIP_10V = 0

+/- 10 V

A_IN_RANGE_BIP_5V = 1

+/- 5 V

A_IN_RANGE_BIP_2V = 2

+/- 2 V

A_IN_RANGE_BIP_1V = 3

+/- 1 V

MCC 134 functions and data

Functions

Function Description
mcc134_open() Open an MCC 134 for use.
mcc134_is_open() Check if an MCC 134 is open.
mcc134_close() Close an MCC 134.
mcc134_info() Return information about this device type.
mcc134_serial() Read the serial number.
mcc134_calibration_date() Read the calibration date.
mcc134_calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc134_calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc134_tc_type_write() Write the thermocouple type for a channel.
mcc134_tc_type_read() Read the thermocouple type for a channel.
mcc134_update_interval_write() Write the temperature update interval.
mcc134_update_interval_read() Read the temperature update interval.
mcc134_t_in_read() Read a temperature input value.
mcc134_a_in_read() Read an analog input value.
mcc134_cjc_read() Read a CJC temperature.
int mcc134_open(uint8_t address)

Open a connection to the MCC 134 device at the specified address.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc134_is_open(uint8_t address)

Check if an MCC 134 is open.

Return
1 if open, 0 if not open.
Parameters
  • address: The board address (0 - 7).

int mcc134_close(uint8_t address)

Close a connection to an MCC 134 device and free allocated resources.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

struct MCC134DeviceInfo* mcc134_info(void)

Return constant device information for all MCC 134s.

Return
Pointer to struct MCC134DeviceInfo.

int mcc134_serial(uint8_t address, char * buffer)

Read the MCC 134 serial number.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc134_calibration_date(uint8_t address, char * buffer)

Read the MCC 134 calibration date.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • interval: The interval in seconds (1 - 255).

int mcc134_update_interval_read(uint8_t address, uint8_t * interval)

Read the temperature update interval.

Reads the library temperature update rate in seconds.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • interval: Receives the update rate.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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:

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Thermocouple Types

enum TcTypes

Thermocouple type constants.

Values:

TC_TYPE_J = 0

J type.

TC_TYPE_K = 1

K type.

TC_TYPE_T = 2

T type.

TC_TYPE_E = 3

E type.

TC_TYPE_R = 4

R type.

TC_TYPE_S = 5

S type.

TC_TYPE_B = 6

B type.

TC_TYPE_N = 7

N type.

TC_DISABLED = 0xFF

Input disabled.

MCC 152 functions and data

Functions

Function Description
mcc152_open() Open an MCC 152 for use.
mcc152_is_open() Check if an MCC 152 is open.
mcc152_close() Close an MCC 152.
mcc152_info() Return information about this device type.
mcc152_serial() Read the serial number.
mcc152_a_out_write() Write an analog output channel value.
mcc152_a_out_write_all() Write all analog output channels simultaneously.
mcc152_dio_reset() Reset the digital I/O to the default configuration.
mcc152_dio_input_read_bit() Read a digital input.
mcc152_dio_input_read_port() Read all digital inputs.
mcc152_dio_output_write_bit() Write a digital output.
mcc152_dio_output_write_port() Write all digital outputs.
mcc152_dio_output_read_bit() Read the state of a digital output.
mcc152_dio_output_read_port() Read the state of all digital outputs.
mcc152_dio_int_status_read_bit() Read the interrupt status for a single channel.
mcc152_dio_int_status_read_port() Read the interrupt status for all channels.
mcc152_dio_config_write_bit() Write a digital I/O configuration item value for a single channel.
mcc152_dio_config_write_port() Write a digital I/O configuration item value for all channels.
mcc152_dio_config_read_bit() Read a digital I/O configuration item value for a single channel.
mcc152_dio_config_read_port() Read a digital I/O configuration item value for all channels.
int mcc152_open(uint8_t address)

Open a connection to the MCC 152 device at the specified address.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc152_is_open(uint8_t address)

Check if an MCC 152 is open.

Return
1 if open, 0 if not open.
Parameters
  • address: The board address (0 - 7).

int mcc152_close(uint8_t address)

Close a connection to an MCC 152 device and free allocated resources.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

struct MCC152DeviceInfo* mcc152_info(void)

Return constant device information for all MCC 152s.

Return
Pointer to struct MCC152DeviceInfo.

int mcc152_serial(uint8_t address, char * buffer)

Read the MCC 152 serial number.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • channel: The DIO channel number, 0 - 7.
  • value: Receives the input value.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • value: Receives the input values.

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.

Return
Result code, RESULT_SUCCESS if successful.
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)

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);

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • value: The output values.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • channel: The DIO channel number, 0 - 7.
  • value: Receives the output value.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • value: Receives the output values.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • value: Receives the interrupt status value.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • item: The config item, one of DIOConfigItem.
  • value: The config value.

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • item: The config item, one of DIOConfigItem.
  • value: Receives the config value.

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

DIO Config Items

enum DIOConfigItem

DIO Configuration Items.

Values:

DIO_DIRECTION = 0

Configure channel direction.

DIO_PULL_CONFIG = 1

Configure pull-up/down resistor.

DIO_PULL_ENABLE = 2

Enable pull-up/down resistor.

DIO_INPUT_INVERT = 3

Configure input inversion.

DIO_INPUT_LATCH = 4

Configure input latching.

DIO_OUTPUT_TYPE = 5

Configure output type.

DIO_INT_MASK = 6

Configure interrupt mask.

MCC 172 functions and data

Functions

Function Description
mcc172_open() Open an MCC 172 for use.
mcc172_is_open() Check if an MCC 172 is open.
mcc172_close() Close an MCC 172.
mcc172_info() Return information about this device type.
mcc172_blink_led() Blink the MCC 172 LED.
mcc172_firmware_version() Get the firmware version.
mcc172_serial() Read the serial number.
mcc172_calibration_date() Read the calibration date.
mcc172_calibration_coefficient_read() Read the calibration coefficients for a channel.
mcc172_calibration_coefficient_write() Write the calibration coefficients for a channel.
mcc172_iepe_config_read() Read the IEPE configuration for a channel.
mcc172_iepe_config_write() Write the IEPE configuration for a channel.
mcc172_a_in_sensitivity_read() Read the sensitivity scaling for a channel.
mcc172_a_in_sensitivity_write() Write the sensitivity scaling for a channel.
mcc172_a_in_clock_config_read() Read the sampling clock configuration.
mcc172_a_in_clock_config_write() Write the sampling clock configuration.
mcc172_trigger_config() Configure the external trigger input.
mcc172_a_in_scan_start() Start a hardware-paced analog input scan.
mcc172_a_in_scan_buffer_size() Read the size of the internal scan data buffer.
mcc172_a_in_scan_status() Read the scan status.
mcc172_a_in_scan_read() Read scan data and status.
mcc172_a_in_scan_channel_count() Get the number of channels in the current scan.
mcc172_a_in_scan_stop() Stop the scan.
mcc172_a_in_scan_cleanup() Free scan resources.
int mcc172_open(uint8_t address)

Open a connection to the MCC 172 device at the specified address.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc172_close(uint8_t address)

Close a connection to an MCC 172 device and free allocated resources.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).

int mcc172_is_open(uint8_t address)

Check if an MCC 172 is open.

Return
1 if open, 0 if not open.
Parameters
  • address: The board address (0 - 7).

struct MCC172DeviceInfo* mcc172_info(void)

Return constant device information for all MCC 172s.

Return
Pointer to struct MCC172DeviceInfo.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7).
  • count: The number of times to blink (0 - 255).

int mcc172_firmware_version(uint8_t address, uint16_t * version)

Return the board firmware version.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc172_serial(uint8_t address, char * buffer)

Read the MCC 172 serial number.

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc172_calibration_date(uint8_t address, char * buffer)

Read the MCC 172 calibration date.

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

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

Return
Result code, RESULT_SUCCESS if successful.
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.

int mcc172_iepe_config_read(uint8_t address, uint8_t channel, uint8_t * config)

Read the MCC 172 IEPE configuration for a single channel.

Return
Result code, RESULT_SUCCESS if successful.
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

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.

Return
Result code, RESULT_SUCCESS if successful.
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

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.

Return
Result code, RESULT_SUCCESS if successful.
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

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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.

Return
Result code, RESULT_SUCCESS if successful
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)

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.

Return
Result code, RESULT_SUCCESS if successful
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

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:

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.

Return
Result code, RESULT_SUCCESS if successful.
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.

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:

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_BUSY if a scan is already active.
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.

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.

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

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan has not been started under this instance of the device.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • samples_per_channel: Receives the number of samples per channel available in the scan thread buffer.

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.

Return
Result code, RESULT_SUCCESS if successful, RESULT_RESOURCE_UNAVAIL if a scan is not active.
Parameters
  • address: The board address (0 - 7). Board must already be opened.
  • status: Receives the scan status, an ORed combination of the flags:
  • 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.

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.

Return
The number of channels, 0 - 2.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

int mcc172_a_in_scan_cleanup(uint8_t address)

Free analog input scan resources after the scan is complete.

Return
Result code, RESULT_SUCCESS if successful.
Parameters
  • address: The board address (0 - 7). Board must already be opened.

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

Source Types

enum SourceType

Clock / trigger source definitions.

Values:

SOURCE_LOCAL = 0

Use a local-only source.

SOURCE_MASTER = 1

Use a local source and set it as master.

SOURCE_SLAVE = 2

Use a separate master source.