Analog I/O C Library
This glossary defines C library functions used in the Analog I/O Wildcard driver code.

The Analog I/O Wildcard is used with Mosaic's microcontrollers to provide your instrument's needs for data acquisition and precise voltage control.

A C language driver is provided with the Analog I/O Wildcard to provide all necessary instrumentation and control functions. The driver functions provide precise control of the the board's 16-bit ADC, 12-bit DAC, voltage references, and channel selection.

The C function entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet). The keyword name of each entry is in bold typeface. Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below. The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program. Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary. The case conventions are as follows:

• Function names begin with a capital letter, and every letter after an underscore is capitalized. Other letters are lower case, except for capitalized acronyms such as "DAC".
• Constant names and C macros use capital letters.
• Variable names use lower case letters.

Each glossary entry starts with C-style and Forth-style declarations, and presents a description of the function. Here is a sample glossary entry:

The C declaration specifies the return data type before the function name, and lists the comma-delimited input parameters between parentheses, showing the type and a descriptive name for each.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program. The items to the left of the double-dash ( -- ) are input parameters, and the item to the right of the double-dash is the output parameter. Forth is stack-based, and the first item shown is lowest on the stack. The backslash ( \ ) character is read as "under" to indicate the relative positions of the input parameters on the stack. In the Forth declaration the parameter names and their data types are combined. All unspecified parameters are 16-bit integers. Forth promotes all characters to integer type.

The presence of both C and Forth declarations is helpful: the C syntax shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

void Init_Analog_IO ( int reference_option, int module_num )

void AD16_Multiple ( xaddr buffer, uint timing, uint samples, int channel, int module )

uint AD16_Sample ( int channel_num, int module_num )

void To_DAC12 ( int value, int channel_num, int module_num )

void To_All_DACs ( int value, int module_num )

void Delay_Update_DAC12 ( int module_num )

void Update_DAC12 ( int module_num )

C: AD16_CH0
4th: AD16_CH0 ( -- n )

A constant (= 0x04) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 0, pin 14, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH0_CH1
4th: AD16_CH0_CH1 ( -- n )

A constant (= 0x00) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 0 and Channel 1 (pins 14 and 13) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH1
4th: AD16_CH1 ( -- n )

A constant (= 0x44) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 1, pin 13, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH1_CH0
4th: AD16_CH1_CH0 ( -- n )

A constant (= 0x40) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 1 and Channel 0 (pins 13 and 14) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH2
4th: AD16_CH2 ( -- n )

A constant (= 0x14) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 2, pin 12, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH2_CH3
4th: AD16_CH2_CH3 ( -- n )

A constant (= 0x10) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 2 and Channel 3 (pins 12 and 11) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH3
4th: AD16_CH3 ( -- n )

A constant (= 0x54) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 3, pin 11, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH3_CH2
4th: AD16_CH3_CH2 ( -- n )

A constant (= 0x50) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 3 and Channel 2 (pins 11 and 12) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH4
4th: AD16_CH4 ( -- n )

A constant (= 0x24) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 4, pin 10, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH4_CH5
4th: AD16_CH4_CH5 ( -- n )

A constant (= 0x20) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 4 and Channel 5 (pins 10 and 9) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH5
4th: AD16_CH5 ( -- n )

A constant (= 0x64) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 5, pin 9, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH5_CH4
4th: AD16_CH5_CH4 ( -- n )

A constant (= 0x60) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 5 and Channel 4 (pins 9 and 10) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH6
4th: AD16_CH6 ( -- n )

A constant (= 0x34) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 6, pin 8, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH6_CH7
4th: AD16_CH6_CH7 ( -- n )

A constant (= 0x30) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 6 and Channel 7 (pins 8 and 7) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH7
4th: AD16_CH7 ( -- n )

A constant (= 0x74) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform single-ended conversions on Channel 7, pin 7, on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: AD16_CH7_CH6
4th: AD16_CH7_CH6 ( -- n )

A constant (= 0x70) that, when passed as a parameter to AD16_Sample or AD16_Multiple, configures the 16-bit A/D to perform differential conversions between Channel 7 and Channel 6 (pins 7 and 8) on the Analog I/O Field Header.

See also AD16_Sample and AD16_Multiple.

C: void AD16_Multiple ( xaddr buffer, uint timing, uint samples, int channel, int module )
4th: AD16_Multiple ( xaddr\timing\num_samples\channel_num\module_num -- )

Acquires num_samples from the specified channel of the 16-bit A/D on the specified module and stores the samples as sequential unsigned 16-bit values starting at the specified buffer address. The timing parameter specifies the timing of the samples. The eight valid module numbers are 0 to 7.

For single-ended conversions, the channel is selected using one of the following constants: AD16_CH0, AD16_CH1, AD16_CH2, AD16_CH3, AD16_CH4, AD16_CH5, AD16_CH6, and AD16_CH7. Single-ended sampling means that the input voltage of the specified channel is referenced to ADCGND (pins 5 or 6 on the Field Header).

For differential conversions, the channel is selected using one of the following constants: AD16_CH0_CH1, AD16_CH1_CH0, AD16_CH2_CH3, AD16_CH3_CH2, AD16_CH4_CH5, AD16_CH5_CH4, AD16_CH6_CH7, and AD16_CH7_CH6. Differential sampling means that the voltage of the second specified channel is subtracted from the voltage of the first specified channel and the resulting voltage is digitized by the A/D. Be sure that the second specified channel's voltage does not exceed 1.25 volts and the second specified channel's voltage does not exceed the first specified channel's voltage (i.e. the 16-bit A/D can only operate in unipolar mode). Init_Analog_IO must be called before calling AD16_Multiple.

On the V4.xx platforms, the timing is as follows. If the specified buffer is in common memory, the first sample is taken after 32.5 microseconds and subsequent samples are taken every (57.5+2.5*timing parameter) microseconds. If the specified buffer is in paged memory, the first sample is taken after 32.5 microseconds and subsequent samples are taken every (82.5+2.5*timing parameter) microseconds. If the buffer crosses a page boundary, the sampling interval increases by approximately 4 microseconds for the sample stored after the page boundary was crossed. Disables interrupts for 27 microseconds per sample.

On the V6.xx (PDQ) platforms, the timing is as follows. Samples are taken every (71.5+2.5*timing parameter) microseconds; the first sample takes slightly longer to acquire. This function disables interrupts for 57.5 microseconds per sample on V6.xx platforms.

Of course, the operation of interrupts (including timesliced multitasking) will affect these sampling times.

See also AD16_Sample and Init_Analog_IO.

C: uint AD16_Sample ( int channel_num, int module_num )
4th: AD16_Sample ( channel_num\module_num -- 16-bit_result )

Returns a single 16-bit sample from the specified channel of the 16-bit A/D on the specified module. The eight valid module numbers are 0 to 7. For single-ended conversions, the channel is selected using one of the following constants: AD16_CH0, AD16_CH1, AD16_CH2, AD16_CH3, AD16_CH4, AD16_CH5, AD16_CH6, and AD16_CH7. Single-ended sampling means that the input voltage of the specified channel is referenced to ADCGND (pins 5 or 6 on the Field Header).

For differential conversions, the channel is selected using one of the following constants: AD16_CH0_CH1, AD16_CH1_CH0, AD16_CH2_CH3, AD16_CH3_CH2, AD16_CH4_CH5, AD16_CH5_CH4, AD16_CH6_CH7, and AD16_CH7_CH6. Differential sampling means that the voltage of the second specified channel is subtracted from the voltage of the first specified channel and the resulting voltage is digitized by the A/D. Be sure that the second specified channel's voltage does not exceed 1.25 volts and the second specified channel's voltage does not exceed the first specified channel's voltage (i.e. the 16-bit A/D can only operate in unipolar mode).

Init_Analog_IO must be called before calling AD16_Sample. Unlike the routines for the 8-bit DAC and 12-bit A/D, a resource variable is not required for the 12-bit DAC or the 16-bit A/D in multitasking systems. On the V6.xx platforms, AD16_Sample executes in 52.25 microseconds and disables interrupts for 27 microseconds.

On the V6.xx (PDQ) platforms, AD16_Sample executes in 65 microseconds and disables interrupts for 57.5 microseconds.

See also AD16_Multiple and Init_Analog_IO.

C: DAC12_CH0
4th: DAC12_CH0 ( -- n )

A constant (= 0x00) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 0, pin 24, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH1
4th: DAC12_CH1 ( -- n )

A constant (= 0x10) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 1, pin 23, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH2
4th: DAC12_CH2 ( -- n )

A constant (= 0x20) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 2, pin 22, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH3
4th: DAC12_CH3 ( -- n )

A constant (= 0x30) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 3, pin 21, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH4
4th: DAC12_CH4 ( -- n )

A constant (= 0x40) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 4, pin 20, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH5
4th: DAC12_CH5 ( -- n )

A constant (= 0x50) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 5, pin 19, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH6
4th: DAC12_CH6 ( -- n )

A constant (= 0x60) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 6, pin 18, of the Analog I/O Field Header.

See also To_DAC12.

C: DAC12_CH7
4th: DAC12_CH7 ( -- n )

A constant (= 0x70) that, when passed as a parameter to the To_DAC12 function, configures the 12-bit DAC to output a voltage on Channel 7, pin 17, of the Analog I/O Field Header.

See also To_DAC12.

C: void Delay_Update_DAC12 ( int module_num )
4th: Delay_Update_DAC12 ( module_num -- )

Configures the 12-bit DAC to accept 12-bit values for each DAC channel but to delay outputting the voltage to the corresponding pin of the DAC until Update_DAC12 is called. This option is disabled by default and is typically used to simultaneously set the output voltages of all 12-bit DAC channels.

See also Update_DAC12 and To_All_DACs.

C: EXT_DAC12
4th: EXT_DAC12 ( -- n )

A constant (= 0x00) that, when passed as a parameter to the Init_Analog_IO function, configures the 12-bit DAC to use the voltage on the reference pin of the Analog I/O Field Header, pin 4 as its reference if jumper J6 is installed.

See also Init_Analog_IO.

C: void Init_Analog_IO ( int reference_option, int module_num )
4th: Init_Analog_IO ( reference_option\module_num -- )

Initializes the software drivers for the 12-bit DAC and the 16-bit A/D, sets the reference voltage of the DAC to the specified option on the specified module, and sets all 8 DAC channels to 0 volts. The reference option is selected using one of the following constants: INT_2V_DAC12, INT_1V_DAC12, and EXT_DAC12. The eight valid module numbers are 0 to 7. See also INT_2V_DAC12, INT_1V_DAC12, and EXT_DAC12.

C: INT_1V_DAC12
4th: INT_1V_DAC12 ( -- n )

A constant (= 0x04) that, when passed as a parameter to the Init_Analog_IO function, configures the 12-bit DAC to use its own internally generated 1.024 volt as its reference. With this option, the DAC output range is from 0 to 2.048 volts.

See also Init_Analog_IO.

C: INT_2V_DAC12
4th: INT_2V_DAC12 ( -- n )

A constant (= 0x06) that, when passed as a parameter to the Init_Analog_IO function, configures the 12-bit DAC to use its own internally generated 2.048 volt as its reference. With this option, the DAC output range is 0 to 4.096 volts.

See also Init_Analog_IO.

C: void To_All_DACs ( int value, int module_num )
4th: To_All_DACs ( value\module_num -- )

Writes the specified 12-bit value simultaneously to all channels of the 12-bit DAC on the specified module. To_All_DACs uses the functions Delay_Update_DAC12 and Update_DAC12 to output all voltages to all channels at the same time. The eight valid module numbers are 0 to 7. The 12-bit value is clamped to the range of 0 to 4095 but no error checking is performed on the module number. Init_Analog_IO must be called before this routine initialize the reference voltage of the DAC.

See also Init_Analog_IO, Delay_Update_DAC12, and Update_DAC12.

C: void To_DAC12 ( int value, int channel_num, int module_num )
4th: To_DAC12 ( value\channel_num\module_num -- )

Writes the specified 12-bit value to the specified channel of the 12-bit DAC on the specified module. The eight valid module numbers are 0 to 7 while the channel number is specified with one of the constants DAC12_CH0, DAC12_CH1, DAC12_CH2, DAC12_CH3, DAC12_CH4, DAC12_CH5, DAC12_CH6, and DAC12_CH7. The 12-bit value is clamped to the range of 0 to 4095 but no error checking is performed on the channel number or the module number. Init_Analog_IO must be called before calling To_DAC12 to initialize the DAC's reference voltage. Unlike the routines for the 8-bit DAC and 12-bit A/D, a resource variable is not needed for the 12-bit DAC and the 16-bit A/D in multitasking systems. To_DAC12 executes in approximately 37 microseconds and disables interrupts for 16.5 microseconds.

See also Init_Analog_IO.

C: void Update_DAC12 ( int module_num )
4th: Update_DAC12 ( module_num -- )

Configures the 12-bit DAC to immediately output a voltage on each DAC channel corresponding to the last 12-bit value written to the channel. This option is enabled by default and is typically used after a call to the Delay_Update_DAC12 routine.

See also Delay_Update_DAC12.

See also → Analog I/O Wildcard User Guide