10. Orangutan Serial Port Communication

The OrangutanSerial class and the C functions in this section provide access to the serial port(s) on the Orangutan controllers and 3pi robot., enabling two-way TTL-level communication with another microcontroller, a serial device, or (through a USB-serial adapter or RS-232 level converter) a personal computer.

The Baby Orangutan, Orangutan SV, Orangutan LV, and 3pi robot are based on the ATmega48/168/328 line of AVR processors, which have a single UART that communicates on pins PD0 (RXD) and PD1 (TXD). Since there is only one UART on these devices, you must omit the port argument when using the commands below.

The Orangutan SVP and Orangutan X2 are based on the AVR ATmega324/644/1284 line of AVR processors, which have two UARTs. Port UART0 uses pins PD0 (RXD0) and PD1 (TXD0). Port UART1 uses pins PD2 (RXD1) and PD3 (TXD1). The SVP and X2 also have a port called USB_COMM, which lets you connect your Orangutan directly to a computer to send and receive bytes over USB. When using this port, you must call serial_check() regularly because this port does not support interrupts. See the Orangutan SVP User’s Guide for more information about using this port on the Orangutan SVP. Since there are multiple serial ports, you must include the port argument when using the commands below, and it must be either UART0, UART1, or USB_COMM.

When sending data on a UART, a UDRE interrupt vector is called by default after each byte is sent, allowing the library to automatically start sending the next byte from the send buffer. When receiving data, an RX interrupt vector is called by default after each byte is received, allowing the library to automatically store the byte in the receive buffer. To use a polling method instead of interrupts, see the serial_set_mode() and serial_check() functions below.

These functions are not available within the Arduino environment, which has its own serial functions.

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

Reference

C++ methods are shown in red.

C functions are shown in green.

static void OrangutanSerial::setBaudRate([unsigned char port,] unsigned long baud)

unsigned char serial_set_baud_rate([unsigned char port,] 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. This function is not needed for (and has no effect on ) the Orangutan SVP’s USB_COMM port. It is required for setting the baud for all UART ports and for the Orangutan X2’s USB_COMM port.

static void OrangutanSerial::receive([unsigned char port,] char * buffer, unsigned char size)

void serial_receive([unsigned char port,] char * buffer, unsigned char size)

Sets up a buffer for background reception. This function returns immediately, but data arriving at the serial port will be copied into this buffer until size bytes have been stored.

static char OrangutanSerial::receiveBlocking([unsigned char port,] char * buffer, unsigned char size, unsigned int timeout_ms)

char serial_receive_blocking([unsigned char port,] char * buffer, unsigned char size, unsigned int timeout_ms)

Receives data, not returning until the buffer is full or the timeout (specified in milliseconds) has expired. Returns 1 if the timeout occurred before the buffer filled up. Returns 0 if the buffer has been filled up. This function is useful for simple programs and for situations in which you know exactly how many bytes to expect.

static void OrangutanSerial::receiveRing([unsigned char port,] char * buffer, unsigned char size)

void serial_receive_ring([unsigned char port,] char * buffer, unsigned char size)

Sets up a ring buffer for background reception. This is a more advanced version of serial_receive() that is useful when you need to read in data continuously without pauses. When the buffer is filled, serial_get_received_bytes() will reset to zero, and data will continue to be inserted at the beginning of the buffer.

static void OrangutanSerial::cancelReceive([unsigned char port ])

void serial_cancel_receive([unsigned char port)

Stops background serial reception.

static inline unsigned char OrangutanSerial::getReceivedBytes([unsigned char port ])

unsigned char serial_get_received_bytes([unsigned char port ])

Returns the number of bytes that have been read into the buffer; this is also the index of the location at which the next received byte will be added.

static inline char OrangutanSerial::receiveBufferFull([unsigned char port ])

char serial_receive_buffer_full([unsigned char port ])

Returns 1 (true) when the receive buffer has been filled with received bytes, so that serial reception is halted. Returns 0 (false) otherwise. This function should not be called when receiving data into a ring buffer.

static void OrangutanSerial::send([unsigned char port,] char * buffer, unsigned char size)

void serial_send([unsigned char port,] char * buffer, unsigned char size)

Sets up a buffer for background transmission. Data from this buffer will be transmitted until size bytes have been sent. If serial_send() is called before serial_send_buffer_empty() returns true (when transmission of the last byte has started), the old buffer will be discarded and tramission will be cut short. This means that you should almost always wait until the data has been sent before calling this function again. See serial_send_blocking(), below, for an easy way to do this.

static void OrangutanSerial::sendBlocking([unsigned char port,] char * buffer, unsigned char size)

void serial_send_blocking([unsigned char port,] char * buffer, unsigned char size)

Same as serial_send(), but waits until transmission of the last byte has started before returning. When this function returns, it is safe to call serial_send() or serial_send_blocking() again.

Warning: When using the Orangutan SVP’s USB_COMM port, serial_send_blocking() might never return because the rate at which bytes can be sent to the computer is dictated by how often the computer requests to read bytes from the Orangutan. If the Orangutan’s USB port is not connected, or for some reason the computer has stopped reading bytes from the Orangutan’s USB Communications port, then this function might never return. This is not a problem for UART-based serial ports or the Orangutan X2’s USB_COMM port because the rate of transmission is dictated only by the AVR’s code and the baud rate, so all the bytes will finish transmitting in a relatively predictable amount of time.

static inline unsigned char OrangutanSerial::getSentBytes([unsigned char port ])

unsigned char serial_get_sent_bytes([unsigned char port ])

Returns the number of bytes that have been sent since serial_send() was called.

static char OrangutanSerial::sendBufferEmpty([unsigned char port ])

char serial_send_buffer_empty([unsigned char port ])

Returns 1 (true) when the send buffer is empty; when there are no more bytes to send. Returns 0 (false) otherwise.

static void OrangutanSerial::setMode([unsigned char port,] unsigned char mode)

void serial_set_mode([unsigned char port,] unsigned char mode)

Sets the serial library to use either interrupts (with the argument SERIAL_AUTOMATIC) or polling (SERIAL_CHECK). If SERIAL_CHECK is selected, your code must call serial_check() often to ensure reliable reception and timely transmission of data. The default mode for all UART-based ports is SERIAL_AUTOMATIC. The default and only allowed mode for the Orangutan SVP’s and Orangutan X2’s USB_COMM port is SERIAL_CHECK.

static char OrangutanSerial::getMode([unsigned char port,] unsigned char mode)

char serial_get_mode([unsigned char port ])

Returns the current serial mode.

static void OrangutanSerial::check()

void serial_check()

Checks for any bytes to be received or transmitted (on all available ports) and performs the required action. You only need to use this function if one of your ports is in SERIAL_CHECK mode. If all of your ports are in SERIAL_AUTOMATIC mode, you will not need to use this function. The default and only allowed mode for the Orangutan SVP’s and Orangutan X2’s USB_COMM port is SERIAL_CHECK, so you should call this function often if you want to use that port.