10. Orangutan Serial Port Communication

Reference

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.