1020: Introduction to Programming Winter 2014

1020 3π Function Reference

This is a shorter function reference for the functions that we're using most frequently in ENGI 1020. For more detailed discussion, and other functions, see the Pololu AVR Library Command Reference.

LCD

void clear()
Clear the LCD
void lcd_goto_xy(unsigned char col, unsigned char row)
Position the LCD cursor at col and row.
@pre 0 ≤ col ≤ 7 and 0 ≤ row ≤ 1
void print(const char *str)
void print_from_program_space(const char *str)
Print the contents of str on the LCD starting at the current cursor position. The latter form requires that the string be in program space.
void print_long(long val)
Print the value of val on the LCD at the current cursor position.

Buttons

unsigned char button_is_pressed(unsigned char buttons)
Returns true if and only if the given button is pressed. buttons is normally one of BUTTON_A, BUTTON_B or BUTTON_C.

Music/Tones

void play(const char* sequence)
void play_from_program_space(const char* sequence)
Play the specified sequence of notes (see http://www.pololu.com/docs/0J18/3 for details about the notes). The latter form requires that the string be in program space instead of RAM. This is desirable since RAM is limited and the string must be stored in program space anyway.

Motors

void set_motors(int m1, int m2)
Set the left motor speed to m1 and the right to m2. A negative speed indicates a reverse motion.
@pre -255 ≤ m1 ≤ 255 and -255 ≤ m2 ≤ 255.

System

void delay_ms(unsigned int milliseconds)
Wait milliseconds ms.
unsigned int read_battery_millivolts()
Returns the voltage level of the battery in millivolts.

util3pi

Note: These functions are not defined in the Pololu 3π resources, but rather are developed specifically for this course (with some heavy reference to the posted sample code).

void displayWelcome()
Output welcome message, play tune and delay 2s.
void displayBattery()
Output battery level as a percentage, wait for button B.
void waitForButton(unsigned char button, const char *tune)
Pause until a specific button is pressed.
@params button -- identifier of button to wait for
                @pre BUTTON_A, BUTTON_B or BUTTON_C
        tune -- sequence of notes played when button is pressed
                @pre Must be in program space.
unsigned char waitForAnyButton()
Pause until any button is pressed.
@returns BUTTON_A, BUTTON_B or BUTTON_C depending on which button 
                 was pressed.
void lineCalibration()
Perform line sensor calibration routine. Robot will turn about 1/4 turn counterclockwise, then 1/2 turn clockwise and 1/4 turn counterclockwise, to return to approximately the same starting point. The calibrated values are then displayed in a bar graph along with the value (as for readLineSensors()) until the B button is pressed.
void turnCalibration()
Measure the turn rate (μs / deg) for a given motor speed. The 3π will make several full revolutions on the spot.
@params speed -- motor speed for turn @pre [0,255]

@pre this routine assumes that the robot is positioned over a
straight black line such that the sensors will cross the line
twice in a full (360 deg) turn. It watches for transitions in the
center sensor and times the duration of NUM_TURNS full revolutions
after the first transition.

@returns measured turn rate μs/deg
void load_custom_characters()
Set up the display for showing the bar graph.
int readLineSensors()
Read the IR line sensors and return an interpreted result. Sensors are numbered 0 - 4 starting at the left.
 @returns 0           -- line sensed under leftmost sensor (0) only
                         or no line detected
          1 - 999     -- line sensed under left two sensors (0 and 1)
          1000 - 1999 -- line sensed under sensors 1 and 2
          2000        -- line sensed under sensors 1, 2 and 3
          2001 - 2999 -- line sensed under sensors 2 and 3
          3000 - 3999 -- line sensed under sensors 3 and 4
          4000        -- line sensed under rightmost sensor (4) only
                         or no line detected
int readSensorsBranches(bool& isLeft, bool& isRight)
Read the IR line sensors and return an interpreted result. Sensors are numbered 0 - 4 starting at the left. This version returns a value as for readLineSensors, but also sets isLeft and isRight to indicate if there is a line under sensor 0 (isLeft) and/or sensor 4 (isRight). If either isLeft or isRight is true then the value returned shouldn't be trusted for steering.
 @modifies  isLeft is true if and only if there is a line detected directly
              under the left sensor (0)
            isRight is true if and only if there is a line detected directly
              under the right sensor (4)

 @returns 0           -- line sensed under leftmost sensor (0) only
                         or no line detected
          1 - 999     -- line sensed under left two sensors (0 and 1)
          1000 - 1999 -- line sensed under sensors 1 and 2
          2000        -- line sensed under sensors 1, 2 and 3
          2001 - 2999 -- line sensed under sensors 2 and 3
          3000 - 3999 -- line sensed under sensors 3 and 4
          4000        -- line sensed under rightmost sensor (4) only
                         or no line detected