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"

/**

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

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

  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;

  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, size_t bytes) {

  int i;

  /* 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 (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);

}