3.c. Orangutan Digital I/O Functions

Overview

This section of the library provides commands for using the AVR’s pins as generic digital inputs and outputs. Every pin on the AVR that has a name starting with P, followed by a letter and number (e.g. PC2) can be configured as a digital input or digital output. The program running on the AVR can change the configuration of these pins on the fly using the functions in this library.

Complete documentation of these functions can be found in Section 4 of the Pololu AVR Library Command Reference.

Digital outputs

When a pin is configured as a digital output, the AVR is either driving it low (0 V) or high (5 V). This means that the pin has a strong electrical connection to either 0 V (GND) or 5 V (VCC). An output pin can be used to send data to a peripheral device or supply a small amount of power (for example, to light an LED).

Digital inputs

When a pin is configured as a digital input, the AVR can read the voltage on the pin. The reading is always either low (0) or high (1). Basically, a low reading means that the voltage is close to 0 V, while a high reading means that the voltage is close to 5 V (see the DC characteristics section of your AVR’s datasheet for details). Note that when we talk about absolute voltages in this document, we are assuming that the voltage of the ground (GND) line is defined to be 0 V.

Every I/O pin on the AVR comes with an internal 20–50 kilo-ohm pull-up resistor that can be enabled or disabled. A pull-up resistor is a resistor with a relatively high resistance that connects between a pin and the 5 V supply (VCC). If nothing is driving the pin strongly, then the pull-up resistor will pull the voltage on the pin up to 5 V. Pull-up resistors are useful for ensuring that your input pin reaches a well-known state when nothing is connected to it. If your input pin has nothing connected to it and the pull-up resistor is disabled, then it is called a floating pin. In general, it is not recommended to take a digital reading on a floating pin, because the reading will be unpredictable.

An input pin can be used to read data from a sensor or other peripheral.

When the AVR powers up, all I/O pins are configured as inputs with their pull-up resistors disabled.

Caveats

To use your digital I/O pins correctly and safely, there are several things you should be aware of:

• Maximum voltage ratings: Be sure to not expose your input pins to voltages outside their allowed range, which is -0.5 V – 5.5 V (assuming a VCC of 5 V). For example, do not connect any AVR pins directly to an RS-232 output, which varies between -12 V and 12 V. You can use a voltage divider circuit to overcome this limitation.
• Drawing too much current from an output pin: Be sure you do not attempt to draw too much current from your output pin; it may break. Basically, each output pin can supply up to 20 mA of current (see the DC characteristics section of your AVR’s datasheet for details). This is enough to power typical LEDs, but is too small for many other devices. You can use a transistor to overcome this limitation.
• Shorts: Be sure that you do not connect a high output pin to a low output pin. This connection is called a short because it results in a low-resistance path from VCC to ground which will conduct large amounts of current until something breaks.
• Alternative functions: Many of the pins on the AVR have alternative functions. If these alternate functions are enabled, then the functions in this library may not work on those pins. For example, if you have enabled UART0, then you can not control the output value on PD1 using these functions because PD1 serves as the serial transmit line.

Usage Example

This library comes with an example in libpololu-avr\examples.

1. digital1

This example program takes a digital reading on PC1, and uses that reading to decide whether to drive pin PD1 (the red LED pin) low or high. You can test that the example is working by connecting a wire from PC1 to ground. When the connection is made the red LED should change state.

#include <pololu/orangutan.h>

/* 
 * digital1: for the Orangutan controllers and 3pi robot 
 * 
 * This example uses the OrangutanDigital functions to read a digital
 * input and set a digital output.  It takes a reading on pin PC1, and
 * provides feedback about the reading on pin PD1 (the red LED pin).
 * If you connect a wire between PC1 and ground, you should see the
 * red LED change state.
 * 
 * http://www.pololu.com/docs/0J20
 * http://www.pololu.com 
 * http://forum.pololu.com 
 */ 

int main()
{
	// Make PC1 be an input with its internal pull-up resistor enabled.
	// It will read high when nothing is connected to it.
	set_digital_input(IO_C1, PULL_UP_ENABLED);

	while(1)
	{
		if(is_digital_input_high(IO_C1))     // Take digital reading of PC1.
		{
			set_digital_output(IO_D1, HIGH); // PC1 is high, so drive PD1 high.
		}
		else
		{
			set_digital_output(IO_D1, LOW);  // PC1 is low, so drive PD1 low.
		}
	}
}