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 i2c.h

 *  @brief Header file for I2C

 *

 *  Contains functions for I2C.

 *

 *  @author Kevin Woo and Suresh Nidhiry, Colony Project, CMU Robotics Club

 **/

/**

 * @defgroup i2c I2C

 *

 * @brief Provides Inter-Interconnected-Communications (I2C)

 *

 * Initiates I2C functions on an ATMega128 which has a fully hardware Two Wire

 * Interface (TWI) module. Any Atmel chip with this hardware should be able to

 * use the software.

 *

 * This code will operate in a multi-master enviornment and can be either a

 * slave or a master at any time (as long as they are not one or the other at

 * the moment. You can queue up multiple transmission modes in the buffer up to

 * the buffer size. The buffer is implemented as a ring buffer.

 *

 * It is implemented using callback functions. Whenever you want to send a packet

 * you can call the built in send function (as a master) and it will send an array

 * of bytes. Master recieve and slave send/receive are all handled by the call back

 * functions. It is up to the end user to create functions that will handle the

 * receiving of packets. Their functions will be called with every byte recieved

 * so you must either buffer the inputs or handle each one separately.

 *

 * On errors we will simply flush the entire buffer.

 *

 * For information on how I2C operates, read the wikipedia article

 * http://en.wikipedia.org/wiki/I2c

 * for a good explanation of how it works.

 * @{

 */

#ifndef _I2C_H_

#define _I2C_H_

#include <stddef.h>

/** @brief Address of slave receive handler function **/

typedef void (*fun_srecv_t)(char);

/** @brief Address of master receive handler function**/

typedef int (*fun_mrecv_t)(char);

/** @brief Address of slave send handler function**/

typedef char (*fun_send_t)(void);

/**

 * @brief Initializes the i2c module.

 *

 * Initializes the I2C module to start listening on the i2c lines. If the callback functions

 * are not set to null they will be called when that transmission mode is called. The address

 * is your address that you will listen to when you are not the master.

 *

 * @param addr                         Your address on the I2C bus.

 * @param master_recv         The address of the function to call when you receive a byte when you are a

 *                            master.

 * @param slave_recv         The address of the function to call when you are a slave you receive data

 *                                                                from the master

 * @param slave_send                The address of the function to call when you are a slave and the master

 *                                                                requests data from you.

 *

 * @return 0 for success, nonzero for failure

 **/

int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send);

/**

 * @brief Sends a byte array over I2C as a master

 *

 * Will perform a send over I2C to the destination from data for the ammount of

 * bytes that bytes is.

 *

 * @param dest                Destination address of the data on the I2C bus.

 * @param data         The pointer to the byte array of data

 * @param bytes        The amount of bytes long that the byte array is. This is how

 *                                                many bytes from the array that the function will send.

 *

 * @return zero for success, nonzero for failure

 **/

int i2c_send(char dest, char* data, size_t bytes);

/**

 * @brief Send a master request to the destination

 *

 * Sends a request of data from the target address and calls

 * the callback function to handle data as it comes in. This function will

 * not work if the slave has not informationt to send or has nothing implemented

 * to send it.

 *

 * @param dest                The destination that we want to receive information from.

 *

 * @return 0 for success, nonzero for failure

 **/

int i2c_request(char dest);

#endif