Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Pololu AVR Library Command Reference 1. Introduction . . . . . . . . . . . . . . . . 2. Timing and Delays . . . . . . . . . . . . 3. Orangutan Analog-to-Digital Conversion 4. Orangutan Buzzer: Beeps and Music . . . 5. Orangutan LCD . . . . . . . . . . . . . . 6. Orangutan LEDs . . . . . . . . . . . . . 7. Orangutan Motor Control . . . . . . . . 8. Orangutan Pushbuttons . . . . . . . . . . 9. Orangutan Serial Port Communication . . 10.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 1. Introduction This document describes a programming library designed for use with Pololu products. The library is used to create programs that run on Atmel ATmega168 and ATmega48 processors, and it supports the following products: Pololu 3pi robot: a mega168-based robot controller. The 3pi robot essentially contains an LV-168 and a 5-sensor version of the QTR-8RC, both of which are in the list below.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 2. Timing and Delays The following timing and delay functions are designed for the Orangutans and 3pi, which run at 20 MHz. They will give different results at other processor frequencies. These functions are not available within the Arduino environment, which has its own delay functions. For the functions in this section only, the C functions are also available from C++.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ methods are shown in red. C/C++ functions are shown in green. static void OrangutanTime::delayMilliseconds(unsigned int milliseconds) void delay_ms(unsigned int milliseconds) void delay(unsigned int milliseconds) Delays for the specified number of milliseconds.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 3. Orangutan Analog-to-Digital Conversion The OrangutanAnalog class and the C functions in this section allow easy access to the analog inputs on the Orangutan controllers and 3pi. These functions take care of configuring and running the analog-to-digital converters, but they do not automatically set the ports to be inputs or enable/disable the pull-up resistors.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 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 library defines the keywords MODE_8_BIT and MODE_10_BIT, which can be used as the argument to this method.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation int read_temperature_c() This method is the same as readTemperatureF() above, except that it returns the temperature in tenths of a degree Celcius. static int readBatteryMillivolts_3pi() int read_battery_millivolts_3pi() Performs 10 analog-to-digital conversions on the battery voltage sensing circuit of the 3pi and returns the average result in millivolts. A result of 5234 would mean a battery voltage of 5.234 V.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 4. Orangutan Buzzer: Beeps and Music The OrangutanBuzzer class and the C functions in this section allow various sounds to be played on the buzzer of the Orangutan SV-168, Orangutan LV-168, and 3pi, from simple beeps to complex tunes. The buzzer is controlled using one of the Timer1 PWM outputs, so it will conflict with any other uses of Timer1.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. static void OrangutanBuzzer::playFrequency(unsigned int frequency, unsigned int duration, unsigned char volume) void play_frequency(unsigned int freq, unsigned int duration, unsigned char volume) This method will play the specified frequency (in Hz or 0.1 Hz) for the specified duration (in ms). frequency must be between 40 Hz and 10 kHz.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation // 255 (silences buzzer for the note duration) #define SILENT_NOTE 0xFF // e.g. frequency = 445 | DIV_BY_10 // gives a frequency of 44.5 Hz #define DIV_BY_10 (1 << 15) static void OrangutanBuzzer::play(const char* sequence) void play(const char* sequence) This method plays the specified sequence of notes. If the play mode is PLAY_AUTOMATIC (default), the sequence of notes will play with no further action required by the user.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation // the first few measures of Bach's fugue in D-minor OrangutanBuzzer::play("!T240 L8 a gafaeada c+adaeafa >aa>bac#ada c#adaeaf4"); static void playFromProgramSpace(const char* sequence) void play_from_program_space(const char* sequence) A version of play() that takes a pointer to program space instead of RAM. This is desirable since RAM is limited and the string must be stored in program space anyway. Example: #include
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 5. Orangutan LCD The OrangutanLCD class and the C functions in this section provide a variety of ways of displaying data to the LCD screen of an Orangutan SV-168, Orangutan LV-168, and 3pi, providing an essential tool for user interfaces and debugging. The library implements the standard 4-bit HD44780 protocol, and it uses the busy-wait-flag feature to avoid the unnecessarily long delays present in other 4-bit LCD Arduino libraries.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. static void OrangutanLCD::clear() void clear() Clears the display and returns the cursor to the upper-left corner (0, 0). void OrangutanLCD::initPrintf() void lcd_init_printf() Initializes the display for use with the standard C function printf(). This is not available in the Arduino environment. See the avr-libc manual [http://www.nongnu.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Example: OrangutanLCD::print(-25); static void OrangutanLCD::print(long value) void print_long(long value) Prints the specified signed long (4-byte) value to the display at the current cursor position. It will not wrap or otherwise span lines. static void OrangutanLCD::print(unsigned int value) Prints the specified unsigned integer (2-byte) value to the display at the current cursor position.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation void lcd_scroll(unsigned char direction, unsigned char num, unsigned int delay_time) Shifts the display left or right by distance spaces, delaying for delay_time milliseconds between each shift. This library defines literals LCD_LEFT and LCD_RIGHT for use as a direction argument to this method. Execution does not return from this method until the shift is complete.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 6. Orangutan LEDs The OrangutanLEDs class and the C functions in this section are a very simple interface to the two user LEDs included on Orangutan controllers and 3pi. Note that the green/right LED is on the same pin as an LCD control pin; this LED will blink briefly whenever data is sent to the LCD, but the two functions will otherwise not interfere with each other.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++and Arduino methods are shown in red. C functions are shown in green. static void OrangutanLEDs::red(unsigned char state) void red_led(unsigned char state) This method will turn the red user LED off if state is zero, otherwise it will turn the red user LED on. You can use the Arduino keyword HIGH as an argument to turn the LED on, and you can use the Arduino keyword LOW as an argument to turn the LED off.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 7. Orangutan Motor Control The OrangutanMotors class and the C functions in this section allow PWM speed control of the two motor channels on the Orangutan controllers and 3pi. The motor control functions rely on PWM outputs from Timer0 and Timer2, so they will conflict with other code using these timers.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. static void OrangutanMotors::setM1Speed(int speed) void set_m1_speed(int speed) This method will set the speed and direction of motor 1. Speed is a value between -255 and +255. The sign of speed determines the direction of the motor and the magnitude determines the speed.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 8. Orangutan Pushbuttons The OrangutanPushbuttons class and the C functions in this section provide access to the three pushbuttons on the Orangutan SV-168, Orangutan LV-168, and 3pi. Various methods are provided for accessing button presses, which will be useful in different situations. For a higher level overview of this library and programs that show how this library can be used, please see Section 5.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. static unsigned char OrangutanPushbuttons::waitForPress(unsigned char buttons) unsigned char wait_for_button_press(unsigned char buttons) This method will wait for any of the buttons specified by buttons to be pressed, at which point execution will return.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 9. Orangutan Serial Port Communication The OrangutanSerial class and the C functions in this section provide access to the serial port on the Baby Orangutan B, Orangutan SV-168, Orangutan LV-168, and 3pi. This allows two-way, TTL-level communication on pins PD0 (RX) and PD1 (TX) with another microcontroller, a serial device, or (through a USB-serial adapter or RS-232 level converter) a laptop or desktop computer.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ methods are shown in red. C functions are shown in green. static void OrangutanSerial::setBaudRate(unsigned long baud) unsigned char serial_set_baud_rate(unsigned long baud) Sets the baud rate on the serial port. Standard values up to 115200 should work fine; for higher speeds, please consult the AVR documentation.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation static inline unsigned char OrangutanSerial::getSentBytes() unsigned char serial_get_sent_bytes() Gets the number of bytes that have been sent since send() was called. static char OrangutanSerial::sendBufferEmpty() char serial_send_buffer_empty() True when the send buffer is empty; when there are no more bytes to send.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 10. Orangutan System Resources This section of the library is intended to provide access to information about resources that are available on the Orangutan board. Currently, it only provides information about the amount of free RAM on the AVR. static unsigned char OrangutanResources::getFreeRAM() unsigned char get_free_ram() Returns an estimate of the available free RAM on the AVR, in bytes.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 11. QTR Reflectance Sensors The PololuQTRSensors class and the C functions in this section provide an interface for using Pololu’s QTR reflectance sensors [http://www.pololu.com/catalog/product/961] together with the Orangutan, Arduino, or other mega168-based boards. The library provides access to the raw sensors values as well as to high level functions including calibration and line-tracking.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. void PololuQTRSensors::read(unsigned int *sensorValues, unsigned char readMode = QTR_EMITTERS_ON) void qtr_read(unsigned int *sensorValues, unsigned char readMode) Reads the raw sensor values into an array. There MUST be space for as many values as there were sensors specified in the constructor.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation void qtr_read_calibrated(unsigned int *sensorValues, unsigned char readMode) Returns sensor readings calibrated to a value between 0 and 1000, where 0 corresponds to a reading that is less than or equal to the minimum value read by calibrate() and 1000 corresponds to a reading that is greater than or equal to the maximum value.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation This constructor performs no initialization. If it is used, the user must call init() before using the methods in this class. PololuQTRSensorsRC::PololuQTRSensorsRC(unsigned char* pins, unsigned char numSensors, unsigned int timeout = 4000, unsigned char emitterPin = 255); This constructor just calls init(), below.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation analog input channels (ADC0 – ADC7) that correspond to port C pins PC0 – PC5 and dedicated analog inputs ADC6 and ADC7. numSensors specifies the length of the analogPins array (the number of QTR-A sensors you are using). numSensors must be no greater than 8. numSamplesPerSensor indicates the number of 10-bit analog samples to average per channel (per sensor) for each reading.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 12. 3pi Robot Functions This section of the library provides convenient access for 3pi-specific hardware. Currently, it only provides access for the 5 QTR-based line sensors that are included in the 3pi. That is, the QTR functions described in Section 11 do not need to be used for the 3pi. The functions described below are enabled by including one of the 3pi files: #include #include
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation void Pololu3pi::emittersOff() void emitters_off() Turn the IR LEDs off. This is mainly for use by read_line_sensors(), and calling this function before or after the reading the sensors will have no effect on the readings, but you may wish to use it for testing purposes. void Pololu3pi::calibrate(unsigned char readMode = IR_EMITTERS_ON) void calibrate_line_sensors(unsigned char readMode) Reads the sensors for calibration.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation unsigned int* get_line_sensors_calibrated_minimum_off() The calibrated minimum values measured for each sensor, with emitters off. unsigned int* PololuQTRSensors::getLineSensorsCalibratedMaximumOff() unsigned int* get_line_sensors_calibrated_maximum_off() The calibrated maximum values measured for each sensor, with emitters off. 12.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation 13. Wheel Encoders The PololuWheelEncoders class and the associated C functions provide an easy interface for using the Pololu Wheel Encoders [http://www.pololu.com/catalog/product/1217], which allow a robot to know exactly how far its motors have turned at any point in time. This section of the library makes uses of pin-change interrupts to quickly detect and record each transition on the encoder.
Pololu AVR Library Command Reference © 2001–2009 Pololu Corporation Reference C++ and Arduino methods are shown in red. C functions are shown in green. static void PololuWheelEncoders::init(unsigned char a1, unsigned char a2, unsigned char b1, unsigned char b2) void encoders_init(unsigned char a1, unsigned char a2, unsigned char b1, unsigned char b2) Initializes the wheel encoders.
