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

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.

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

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

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.

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