2. Orangutan Analog-to-Digital Conversion

Function Reference

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