2. Orangutan Analog-to-Digital Conversion

The OrangutanAnalog class and the C functions in this section make it easy to use to the analog inputs and integrated analog hardware on the Orangutan robot controllers (LV, SV, SVP, X2, and Baby Orangutan) and 3pi robot. These functions take care of configuring and running the analog-to-digital converter.

For a higher level overview of this library and example programs that show how this library can be used, please see Section 3.a of the Pololu AVR C/C++ Library User’s Guide.

Channels

The tables below give a summary of the analog inputs available on your AVR. Some of these pins are hardwired or jumpered to the battery voltage or sensors or trimpots built in to your device, while other pins are available for you to connect your own sensors to. Please refer to the pin assignment table in the user’s guide for your device for more information.

Analog Channels on the 3pi robot, SV, LV, and Baby Orangutan
Channel Pin Keyword Note
0PC0/ADC0
1PC1/ADC1
2PC2/ADC2
3PC3/ADC3
4PC4/ADC4
5PC5/ADC5
6ADC6TEMP_SENSORLV: External temperature sensor
SV: 1/3 VIN
3pi: 2/3 VIN
7ADC7TRIMPOTUser trimmer potentiometer
14internal 1.1Vbandgap voltage (slow to stablize)
15internal 0VGND


Single-Ended Analog Channels on the Orangutan SVP
Channel Pin Keyword Note
0PA0/ADC0
1PA1/ADC1
2PA2/ADC2
3PA3/ADC3
4PA4/ADC4
5PA5/ADC5
6PA6/ADC6
7PA7/ADC7
14internal 1.1Vbandgap voltage (slow to stablize)
15internal 0VGND
128ADC/SSTRIMPOTMeasured by auxiliary processor*
129ACHANNEL_AMeasured by auxiliary processor*
130BCHANNEL_BMeasured by auxiliary processor*
131CCHANNEL_CMeasured by auxiliary processor*
132D/RXCHANNEL_DMeasured by auxiliary processor*

*Reading the analog channels on the Orangutan SVP that are measured by the auxiliary processor requires the auxiliary processor to be in the correct mode. See the documentation for the Orangutan SVP setMode command in Section 13 for more information.

Single-Ended Analog Channels on the Orangutan X2
Channel Pin Keyword Note
0PA0/ADC0
1PA1/ADC1
2PA2/ADC2
3PA3/ADC3
4PA4/ADC4
5PA5/ADC5
6PA6/ADC6SMT jumper to 5/16 VIN*
7PA7/ADC7TRIMPOTSMT jumper to trimpot*
14internal 1.1Vbandgap voltage (slow to stablize)
15internal 0VGND

*Pins PA6 and PA7 on the Orangutan X2 are connected by default through SMT jumpers to the a battery voltage divider circuit and the user trimpot, respectively. You should not make external connections to these pins without first breaking the default SMT jumper connections, which are located on the underside of the main board and labeled in the silkscreen “ADC6=BATLEV” and “ADC7=TRIMPOT”.

Differential Analog Channels on the Orangutan SVP and X2
Channel Positive Differential Input Negative Differential Input Gain
9 PA1/ADC1 PA0/ADC0 10x
11 PA1/ADC1 PA0/ADC0 200x
13 PA3/ADC3 PA2/ADC2 10x
15 PA3/ADC3 PA2/ADC2 200x
16 PA0/ADC0 PA1/ADC1 1x
18 PA2/ADC2 PA1/ADC1 1x
19 PA3/ADC3 PA1/ADC1 1x
20 PA4/ADC4 PA1/ADC1 1x
21 PA5/ADC5 PA1/ADC1 1x
22 PA6/ADC6 PA1/ADC1 1x
23 PA7/ADC7 PA1/ADC1 1x
24 PA0/ADC0 PA2/ADC2 1x
25 PA1/ADC1 PA2/ADC2 1x
27 PA3/ADC3 PA2/ADC2 1x
28 PA4/ADC4 PA2/ADC2 1x
29 PA5/ADC5 PA2/ADC2 1x


Function Reference

C++ and Arduino methods are shown in red.

C functions are shown in green.

static void OrangutanAnalog::setMode(unsigned char mode)

void set_analog_mode(unsigned char mode)

Used to set the ADC for either 8-bit or 10-bit conversions. The mode argument should be the either MODE_8_BIT or MODE_10_BIT. When the ADC is in 8-bit mode, conversion results will range from 0 to 255 for voltages ranging from 0 to 5 V. When the ADC is in 10-bit mode, conversion results will range from 0 to 1023 for voltages ranging from 0 to 5 V. The default mode setting is MODE_10_BIT.

Example:

// run the ADC in 10-bit conversion mode
OrangutanAnalog::setMode(MODE_10_BIT);
// run the ADC in 10-bit conversion mode
set_analog_mode(MODE_10_BIT);

static unsigned char OrangutanAnalog::getMode()

unsigned char get_analog_mode()

Returns the current ADC mode. The return value will be MODE_8_BIT (1) if the ADC is in 8-bit conversion mode, otherwise it will be MODE_10_BIT (0). The default mode setting is MODE_10_BIT.

static unsigned int OrangutanAnalog::read(unsigned char channel)

unsigned int analog_read(unsigned char channel)

Performs a single analog-to-digital conversion on the specified analog input channel and returns the result. In 8-bit mode, the result will range from 0 to 255 for voltages from 0 to 5 V. In 10-bit mode, the result will range from 0 to 1023 for voltages from 0 to 5 V. The channel argument should be a channel number or keyword from the appropriate table above. This function will occupy program execution until the conversion is complete (approximately 100 us). This function does not alter the I/O state of the analog pin that corresponds to the specified ADC channel.

static unsigned int OrangutanAnalog::readMillivolts(unsigned char channel)

unsigned int analog_read_millivolts(unsigned char channel)

This function is just like analog_read() except the result is returned in millivolts. A return value of 5000 indicates a voltage 5 V. In most cases, this function is equivalent to to_millivolts(analog_read(channel)). However, on the Orangutan SVP, the channels measured by the auxiliary processor are reported to the AVR in millivolts, so calling analog_read_millivolts is more efficient for those channels.

static unsigned int OrangutanAnalog::readAverage(unsigned char channel, unsigned int numSamples)

unsigned int analog_read_average(unsigned char channel, unsigned int numSamples)

Performs numSamples analog-to-digital conversions on the specified analog input channel and returns the average value of the readings. In 8-bit mode, the result will range from 0 to 255 for voltages from 0 to 5 . In 10-bit mode, the result will range from 0 to 1023 for voltages from 0 to 5 V. The channel argument should be a channel number or keyword from the appropriate table above. This function will occupy program execution until all of the requested conversions are complete (approximately 100 us per sample). This function does not alter the I/O state of the analog pin that corresponds to the specified ADC channel. On the Orangutan SVP, the channels measured by the auxiliary processor are averaged on the auxiliary processor, and the library does not support further averaging. For those channels, this function is equivalent to analog_read.

static unsigned int OrangutanAnalog::readAverageMillivolts(unsigned char channel, unsigned int numSamples)

unsigned int analog_read_average_millivolts(unsigned char channel, unsigned int numSamples)

This function is just like analog_read_average() except the result is returned in millivolts. A return value of 5000 indicates a voltage of 5 V. This function is equivalent to to_millivolts(analog_read_average(channel, numSamples)).

static unsigned int OrangutanAnalog::readVCCMillivolts()

unsigned int read_vcc_millivolts()

Performs ten 10-bit analog-to-digital conversions on the fixed internal 1.1V bandgap voltage and computes the analog reference voltage, VCC, from the results. On the Orangutans and 3pi, VCC is regulated to a steady 5 V, but VCC will fall below 5 V on all devices except the Orangutan LV if VIN drops to around 5 V or lower. On the LV, VCC will rise above 5 V if VIN exceeds 5 V. This function can be used to monitor VCC and catch when it is lower or higher than it should be. It can also be used as an argument to the set_millivolt_calibration() function to ensure that millivolt conversions of analog voltage readings stay accurate when the ADC reference voltage, VCC, cannot be regulated to 5 V. Note that this function performs 10-bit conversions regardless of the analog mode, but it restores the analog mode to its previous state before the function returns.

static void OrangutanAnalog::setMillivoltCalibration(unsigned int referenceMillivolts)

void set_millivolt_calibration(unsigned int referenceMillivolts)

This function updates the value of the reference voltage used by the to_millivolts() function (and all other functions that return conversion results in millivolts) to be referenceMillivolts. The default callibration value is 5000 mV, which is accurate when VCC is 5 V, as it is during normal operation for all devices. If VCC is not 5 V and the analog reference voltage value is not adjusted to the new VCC, however, millivolt conversions of analog readings performed by this library will be inaccurate. An easy way to ensure that your conversions remain accurate even when VCC falls below 5 V is to call set_millivolt_calibration(read_vcc_millivolts()) in your main loop.

static unsigned int OrangutanAnalog::readTrimpot()

unsigned int read_trimpot()

Performs 20 analog-to-digital conversions on the output of the trimmer potentiometer on the Orangutan (including the SVP) or 3pi robot. In 8-bit mode, the result will range from 0 to 255 for voltages from 0 to 5 . In 10-bit mode, the result will range from 0 to 1023 for voltages from 0 to 5 V. This method is equivalent to readAverage(TRIMPOT, 20).

static unsigned int OrangutanAnalog::readTrimpotMillivolts()

unsigned int read_trimpot_millivolts()

This function is just like read_trimpot() except the result is returned in millivolts. On the Orangutan SVP, this function is more efficient than to_millivolts(read_trimpot()). On all other devices the two are equivalent.

static int readBatteryMillivolts_3pi()

int read_battery_millivolts_3pi()

Performs ten 10-bit analog-to-digital conversions on the battery voltage sensing circuit (a 2/3 voltage divider of VIN) of the 3pi and returns the average measured battery voltage in millivolts. A result of 5234 would mean a battery voltage of 5.234 V. For rechargeable NiMH batteries, the voltage usually starts at a value above 5 V and drops to around 4 V before the robot shuts off, so monitoring this number can be helpful in determining when to recharge batteries. This function will only return the correct result when the ADC6 shorting block is in place on the front-left side of the robot. The 3pi ships with this shorting block in place, so this function will return the correct result by default. Note that this function performs 10-bit conversions regardless of the analog mode, but it restores the analog mode to its previous state before the function returns.

static int readBatteryMillivolts_SV()

int read_battery_millivolts_sv()

Performs ten 10-bit analog-to-digital conversions on the battery voltage sensing circuit (a 1/3 voltage divider of VIN) of the Orangutan SV and returns the average measured battery voltage in millivolts. A result of 9153 would mean a battery voltage of 9.153 V. This function will only return the correct result when there is a short across the “ADC6=VBAT/3” SMT jumper on the bottom side of the PCB. The SV ships with this SMT jumper shorted with a solder bridge, so this function will return the correct result by default. Note that this function performs 10-bit conversions regardless of the analog mode, but it restores the analog mode to its previous state before the function returns.

static int readBatteryMillivolts_SVP()

int read_battery_millivolts_svp()

Returns the measured Orangutan SVP battery voltage in millivolts. The battery voltage on the SVP is measured by the auxiliary microcontroller, so this function just asks the auxiliary MCU for the most recent measurement; it does not use the ADC on the user MCU.

static int readBatteryMillivolts_X2()

int read_battery_millivolts_x2()

Performs ten 10-bit analog-to-digital conversions on the battery voltage sensing circuit (a 5/16 voltage divider of VIN) of the Orangutan X2 and returns the average measured battery voltage in millivolts. A result of 9153 would mean a battery voltage of 9.153 V. This function will only return the correct result when there is a short across the “ADC6=BATLEV” SMT jumper on the bottom side of the PCB. The X2 ships with this SMT jumper shorted with a solder bridge, so this function will return the correct result by default. Note that this function performs 10-bit conversions regardless of the analog mode, but it restores the analog mode to its previous state before the function returns.

static int OrangutanAnalog::readTemperatureF()

int read_temperature_f()

Performs 20 10-bit analog-to-digital conversions on the output of the temperature sensor on the Orangutan LV and returns average result in tenths of a degree Farenheit, so a result of 827 would mean a temperature of 82.7 degrees F. The temperature sensor is on analog input 6 on the Orangutan LV, so this method is equivalent to readAverage(TEMP_SENSOR, 20) converted to tenths of a degree F. This function will only return the correct result when there is a short across the “ADC6=TEMP” SMT jumper on the bottom side of the Orangutan LV PCB. The LV ships with this SMT jumper shorted with a solder bridge, so this function will return the correct result by default. Note that this function performs 10-bit conversions regardless of the analog mode, but it restores the analog mode to its previous state before the function returns. Only the Orangutan LV has an external temperature sensor, so this function will only return correct results when used on an Orangutan LV.

static int readTemperatureC()

int read_temperature_c()

This method is the same as readTemperatureF() above, except that it returns the temperature in tenths of a degree Celcius. This function will only return correct results when used on an Orangutan LV, and it requires a short across the “ADC6=TEMP” SMT jumper (this short is present by default).

static void OrangutanAnalog::startConversion(unsigned char channel)

void start_analog_conversion(unsigned char channel)

Initiates an ADC conversion that runs in the background, allowing the CPU to perform other tasks while the conversion is in progress. The channel argument should be a channel number or keyword from the appropriate table above. The procedure is to start a conversion on an analog input with this method, then poll is_converting() in your main loop. Once is_converting() returns a zero, the result can be obtained through a call to analog_conversion_result() or analog_conversion_result_millivolts() and this method can be used to start a new conversion. This function does not alter the I/O state of the analog pin that corresponds to the specified ADC channel.

static unsigned char OrangutanAnalog::isConverting()

unsigned char analog_is_converting()

Returns a 1 if the ADC is in the middle of performing an analog-to-digital conversion, otherwise it returns a 0. The AVR is only capable of performing one conversion at a time.

static unsigned int conversionResult()

unsigned int analog_conversion_result()

Returns the result of the previous analog-to-digital conversion. In 8-bit mode, the result will range from 0 to 255 for voltages from 0 to 5 V. In 10-bit mode, the result will range from 0 to 1023 for voltages from 0 to 5 V.

static unsigned int conversionResultMillivolts()

unsigned int analog_conversion_result_millivolts()

This function is just like analog_conversion_result() except the result is returned in millivolts. A return value of 5000 indicates a voltage 5 V. In most cases, this function is equivalent to to_millivolts(analog_conversion_result(channel)). However, on the Orangutan SVP, the channels measured by the auxiliary processor are reported to the AVR in millivolts, so calling analog_conversion_result_millivolts is more efficient for those channels.

static unsigned int toMillivolts(unsigned int adcResult)

unsigned int to_millivolts(unsigned int adc_result)

Converts the result of an analog-to-digital conversion to millivolts. By default, this assumes an analog reference voltage of exactly 5000 mV. The analog reference voltage used by this function can be changed using the set_millivolt_calibration() function.

Example:

OrangutanAnalog::toMillivolts(OrangutanAnalog::read(0));
// e.g. returns 5000 if analog input 0 is at 5 V
to_millivolts(analog_read(0));
// e.g. returns 5000 if analog input 0 is at 5 V