eth32_input_analog

int eth32_input_analog(eth32 handle, int channel, int *value);

Summary

This function retrieves an analog reading from one of the analog channels on the device. The analog readings are only meaningful when the ADC has been enabled (see eth32_set_analog_state). The analog readings are 10-bit values. See below for further explanation of their meaning.

Parameters

  • handle - The value returned by the eth32_open function.

  • channel - Specifies the logical analog channel (0-7) to read. Note that each logical analog channel may be arbitrarily assigned to physical channels using eth32_set_analog_assignment.

  • value - Pointer to a variable which will receive the reading from the specified channel.

Return Value

This function returns zero on success and a negative error code on failure. Please see the Error Codes section for possible error codes.

Remarks

The reading that is obtained with this function is a 10-bit value (range of 0-1023) representing the voltage level relative to the analog reference voltage. The exact interpretation depends on whether a single-ended or differential channel has been selected (see eth32_set_analog_assignment).

For single-ended channels, the reading is:

(analog reading) = (channel voltage * 1024) / (voltage reference)

For example, a reading of 0 means 0V and a reading of 1023 means a voltage just under the voltage reference (assuming internal 5V reference, about 4.99V). Once you have the analog reading, you can calculate the input voltage that produced it by calculating:

voltage = (analog reading)/1024 * (voltage reference)

For differential channels, the reading is:

(analog reading) = 512 + (positive side voltage - negative side voltage) * GAIN * 512 / (voltage reference)

For example, assuming a gain of 1X, a reading of 0 means the positive pin is (voltage reference) volts less than the negative pin, a reading of 512 means the positive pin and negative pin are at the same voltage, and a reading of 1023 means the positive pin is almost (voltage reference) volts higher than the negative pin. Once you have the analog reading, you can calculate the voltage of the positive pin relative to the negative pin by calculating:

voltage = (analog reading - 512) / 512 * (voltage reference)

Example
// NOTE: Error handling omitted for clarity
eth32 handle;
int result;
int chan0;
float voltage;

// .... Your code that establishes a connection here

// Enable the Analog to Digital Converter
eth32_set_analog_state(handle, ADC_ENABLED);

// Configure logical channel 0 to read the physical channel 0 relative to ground (single-ended)
// This is the power-on default anyway, but is shown here for completeness:
eth32_set_analog_assignment(handle, 0, ANALOG_SE0);

// Configure the analog voltage reference to be the internal 5V source
eth32_set_analog_reference(handle, REF_INTERNAL);

// Finally, read the voltage on channel 0
eth32_input_analog(handle, 0, &chan0);

// Now, determine whether the voltage was >= 3V.  Remember
// we're using a 5V voltage reference.
if( chan0 >= (3.0/5.0 * 1024) )
{
	// The voltage on channel 0 was at least 3V
}
else
{
	// The voltage was less than 3V
}

// If you want to calculate the voltage:
voltage = chan0 / 1024.0 * 5.0;
         
See Also

eth32_set_analog_assignment, eth32_set_analog_reference, eth32_set_analog_state