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.c

 * @brief Implemenation of I2C communications protocol

 * 

 * In the case where you have master sends and then a master request to the same

 * address, you will not give up control of the line because the send and

 * request addresses are seen as different addresses. In between it will send a

 * restart but will not give up the line.

 *

 * @author CMU Robotics Club, Kevin Woo, Sursh Nidhiry

 * @bug Not tested.

 */

#include <avr/interrupt.h>

#include <util/twi.h>

#include "i2c.h"

#include "ring_buffer.h"

//NOTE: this is here just to provide colony error codes, it can be safely removed

// for use in another project

#include <dragonfly_lib.h>

/**

 * @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.

 * @{

 */

/** 

 * @brief Set bit rate 12 = 100kbit/s (max speed setting is 10 for an

 *  8 MHz clock). It is a divider, so the lower the number the faster the speed.

 */

#define I2C_BIT_RATE_DIVIDER 0x0C

unsigned char i2c_initd=0;

static int start_flag;

static fun_mrecv_t master_recv_function;

static fun_srecv_t slave_recv_function;

static fun_send_t slave_send_function;

RING_BUFFER_NEW(i2c_buffer, 128, char, i2c_write_buff, i2c_addr_buff);

/**

 * @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) {

    if(i2c_initd)

      return ERROR_INIT_ALREADY_INITD;

    master_recv_function = master_recv;

    slave_recv_function = slave_recv;

    slave_send_function = slave_send;

    RING_BUFFER_CLEAR(i2c_write_buff);

    RING_BUFFER_CLEAR(i2c_addr_buff);

    /* enables twi interrupt, automatic ack sending, and all twi hardware */

    TWCR =  (_BV(TWEA) | _BV(TWEN) | _BV(TWIE));

    /* sets the bit rate of data transmission */

    TWBR = I2C_BIT_RATE_DIVIDER;

    /* sets the address (it is stored in the 7 most significant bits) and allows

     * global messages to be accepted */

    TWAR = (addr << 1) | 1;

    i2c_initd = 1;

    return 0;

}

/**

 * @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, unsigned int bytes) {

    int i;

    if(!i2c_initd)

      return ERROR_LIBRARY_NOT_INITD;

    /* adding data to be sent to ring buffers is not atomic,

     * so disable interrupts */

    cli();

    for(i = 0; i < bytes; i++) {

        if(RING_BUFFER_FULL(i2c_write_buff)) {

            sei();

            return -1;

        }

        RING_BUFFER_ADD(i2c_write_buff, data[i]);

        RING_BUFFER_ADD(i2c_addr_buff, dest << 1);

    }

    /* re-enable the interrupts */

    sei();

    /* send the start bit, only if this device is not currently master */

    if(!start_flag) {

        start_flag = 1;

        TWCR |= _BV(TWSTA);

        TWCR |= _BV(TWINT);

    }

    return 0;

}

/**

 * @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) {

    if(!i2c_initd)

      return ERROR_LIBRARY_NOT_INITD;

    if(RING_BUFFER_FULL(i2c_write_buff))

        return -1;

    RING_BUFFER_ADD(i2c_write_buff, 0);

    RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);

    if(!start_flag) {

        start_flag = 1;

        TWCR |= _BV(TWSTA);

        TWCR |= _BV(TWINT);

    }

    return 0;

}

/** @} **/

/**

 * @brief Interrupt to handle I2C interrupts from the I2C hardware.

 * 

 * Uses the status codes from the I2C register to handle the events

 * needed to advance in I2C stages. For instance, you will get a bit for

 * receiving a start ack, then a address ack, then a data ack, etc.

 * The events are handled in each switch case. The status codes are defined

 * by avr-gcc in /util/twi.h but are the same codes as the Atmel documentation.

 *

 * Bytes are sent by popping off the ring buffer. It also will keep track

 * of what modes the send is in.

 *

 * Errors are handled here as well.

 **/ 

ISR(TWI_vect) {

        static char data_to_send;

        static char addr_to_send = -1;

        char addr, statusCode;

        //Get status code (only upper 5 bits)

        statusCode = (TWSR & 0xF8);

    switch (statusCode) {

        //Start sent successfully

        case TW_START:

        case TW_REP_START:

            /* Send address and write

             * ring_buffer will not be empty */

            RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);

            RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);

            /* first send the address */

            TWDR = addr_to_send; 

            //Turn off start bits

            TWCR &= ~_BV(TWSTA);

            break;

        //Master Transmit - Address sent succesfully

        case TW_MT_SLA_ACK:

        //Send byte

            TWDR = data_to_send;

            PORTG &= ~_BV(PG2);

            break;

        //Master Transmit - Data sent succesfully

        case TW_MT_DATA_ACK:    

            //If there is still data to send

            if(!RING_BUFFER_EMPTY(i2c_write_buff)) {

                RING_BUFFER_PEEK(i2c_addr_buff, addr);

                //Still data for this address

                if (addr == addr_to_send) {

                    RING_BUFFER_REMOVE(i2c_addr_buff, addr);

                    RING_BUFFER_REMOVE(i2c_write_buff, TWDR);

                    break;

                //No more data for this address, data for another address -> resend start

                } else {

                    TWCR |= _BV(TWSTA);

                    break;

                }

            }

            /* there are no bytes to send */

            TWCR |= _BV(TWSTO);

            start_flag = 0;

            break; 

        //Master Transmit - Slave sends a nack, transmit is done

        case TW_MT_DATA_NACK:

            PORTG |= _BV(PG2);

            TWCR |= _BV(TWSTO);

            start_flag = 0;

            break;

        //Master Receive - Address sent succesfully

        case TW_MR_SLA_ACK:

            PORTG |= _BV(PG2);

            break;

        //Master Receive - Data received succesfully

        case TW_MR_DATA_ACK:

            if(master_recv_function) {

                if(!master_recv_function(TWDR)) {

                    TWCR &= ~_BV(TWEA);

                }

            }

            break;

        //Master Receive - Slave sends a nack, transmission is done    

        case TW_MR_DATA_NACK:

            TWCR |= _BV(TWEA);

            //If there is still data to send

            if(!RING_BUFFER_EMPTY(i2c_write_buff)) {

                TWCR |= _BV(TWSTA);

                break;

            }

            /* there are no bytes to send */

            TWCR |= _BV(TWSTO);

            start_flag = 0;  

            break;

        //Slave Transmit - Address received

        case TW_ST_SLA_ACK:

            break;

        //Slave Transmit - Nack received, no data requsted

        case TW_ST_DATA_NACK:

            break;

        //Slave Transmit - Data requested, ack received

        case TW_ST_DATA_ACK:

            if (slave_send_function) {

                TWDR = slave_send_function();

            }

            break;

        //Slave Receive - Address received  

        case TW_SR_SLA_ACK:

            break;

        //Slave Receive - Data received, ack returned

        case TW_SR_DATA_ACK:

            if(slave_recv_function) {

                slave_recv_function(TWDR);

            }

            break;

        //Stop sent  

        case TW_SR_STOP:

            break;

        //Problem on the bus, reset everything

        default:

            TWCR |= _BV(TWSTO);

            start_flag = 0;

            RING_BUFFER_CLEAR(i2c_write_buff);

            RING_BUFFER_CLEAR(i2c_addr_buff);          

    }

  /* Toggle TWINT so that it resets and executes the commands */

  TWCR |= _BV(TWINT);

}