Colony

/**

 * Copyright (c) 2007 Colony Project

 * 

 * Permission is hereby granted, free of charge, to any person

 * obtaining a copy of this software and associated documentation

 * files (the "Software"), to deal in the Software without

 * restriction, including without limitation the rights to use,

 * copy, modify, merge, publish, distribute, sublicense, and/or sell

 * copies of the Software, and to permit persons to whom the

 * Software is furnished to do so, subject to the following

 * conditions:

 * 

 * The above copyright notice and this permission notice shall be

 * included in all copies or substantial portions of the Software.

 * 

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES

 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,

 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

 * OTHER DEALINGS IN THE SOFTWARE.

 **/

/**

 * @file serial.h

 * @brief Contains declarations for serial input and output

 *

 * Contains definitions for serial input and output.

 *

 * @author Colony Project, CMU Robotics Club

 * Based on Tom Lauwer's Firefly Library

 *

 **/

/*

  serial.h - Contains definitions and function prototypes for the RS232 serial port

  author(s): pkv

  Directions:

  Call the initialization function for the serial port you wish to use.  Then, use

  either the provided functions or the stdio functions (fprintf, etc) to read and

  write characters to the serial ports.

  UART Mapping:

  usb_*() -> UART0

  xbee_*() -> UART1

  Options: (Add the following defines to your code to configure this library)

  #define USB_BAUD { 115200 | 9600 } <= pick ONE value from in here

  #define XBEE_BAUD { 115200 | 9600 } <= pick ONE value from in here

  #define USE_STDIO

  Note: If you enable USE_STDIO, the first init function that is called will 

  automatically be linked to stdin, stdout, and stderr.  To use the baud rate 

  commands, add something like the following to your code:

  #define FOO_BAUD 9600

  **UNLESS YOU KNOW WHAT YOU ARE DOING, PLEASE DO NOT CHANGE THIS FILE**

  Many, many other people use this file in their code.  If you change it, you will

  probably break all of their nice code.  You should not need to change anything in

  here, except to accomodate new hardware.

*/

#ifndef _SERIAL_H

#define _SERIAL_H

/**

 * @defgroup usb USB Input / Output

 * @brief Functions for USB input / output

 *

 * Low level functions for USB input and output.

 *

 * @{

 **/

// if no baud rate is defined for usb, default is set here

#ifndef USB_BAUD

/** @brief the USB baud rate **/

#define USB_BAUD 115200

#endif

/**

 * @brief Initialize the USB

 *

 * Initializes communication over the USB serial port.

 * This must be called before any other usb function

 * may be used.

 **/

void usb_init(void);

/**

 * @brief Print a character to USB

 *

 * Sends a character over USB.

 *

 * @param c the character to send

 * @return 0 for success, nonzero for failure

 **/

int usb_putc(char c);

/**

 * @brief Read a character from USB

 *

 * Returns the first character in the buffer received from USB.

 * This function blocks execution until a character has been received.

 * usb_init must be called before this function may be used.

 * 

 * @return the first character in the usb buffer

 *

 * @see usb_init, usb_getc_nb

 **/

int usb_getc(void);

/**

 * @brief Read a character from USB without blocking

 *

 * Non blocking version of usb_getc. If a character is present in the buffer,

 * it is returned, otherwise -1 is returned immediately. usb_init must be

 * called before this function can be used.

 *

 * @param c the received character. This will be set if a character has

 * been received.

 * 

 * @return -1 if no character is available, 0 otherwise

 * 

 * @see usb_init, usb_getc

 **/

int usb_getc_nb(char *c);

/**

 * @brief Print a string to USB

 *

 * Sends a sequence of characters over USB.

 *

 * @param s the string to send

 * @return 0 for success, nonzero for failure

 **/

int usb_puts(char *s);

/**

 * @brief Print an integer to USB

 *

 * Prints an integer, converted to ASCII, to usb. usb_init must be called

 * before this function can be used.

 *

 * @param value the integer to print

 * 

 * @return 0 if successful, nonzero otherwise

 *

 * @see usb_init, usb_putc

 **/

int usb_puti(int value);

/** @} **/ //end addtogroup

/**

 * @defgroup xbee XBee Input / Output

 * @brief Functions for XBee input / output

 *

 * Low level functions for XBee input and output.

 *

 * @{

 **/

// if no baud rate is defined for usb, default is set here

// if no baud rate is defined for xbee, default is set here

#ifndef XBEE_BAUD

/** @brief the XBee baud rate **/

#define XBEE_BAUD 9600

#endif

/**

 * @brief Initialize the XBee

 *

 * Initializes communication over the XBee.

 * This must be called before any other xbee function

 * may be used.

**/

void xbee_init(void);

/**

 * @brief Print a character to the XBee

 *

 * Sends a character to the XBee.

 *

 * @param c the character to send

 * @return 0 for success, nonzero for failure

 **/

int xbee_putc(char c);

/**

 * @brief Read a character from the XBee

 *

 * Returns the first character in the buffer received from USB.

 * This function blocks execution until a character has been

 * received. xbee_init must be called before this function

 * may be used.

 * 

 * @return the first character in the xbee buffer

 * 

 * @see xbee_init, xbee_getc_nb

 **/

int xbee_getc(void);

/**

 * @brief Read a character from the XBee without blocking

 *

 * Non blocking version of xbee_getc. If a character is present in the buffer,

 * it is returned, otherwise -1 is returned immediately. xbee_init

 * must be called before this function can be used.

 *

 * @param c the received character. This will be set if a character has

 * been received.

 * 

 * @return -1 if no character is available, 0 otherwise

 *

 * @see xbee_init, xbee_getc

 **/

int xbee_getc_nb(char *c);

/** @} **/ //end addtogroup

#endif