Project

General

Profile

Statistics
| Revision:

root / trunk / code / lib / src / libdragonfly / i2c.c @ 277

History | View | Annotate | Download (9.98 KB)

1
/**
2
 * Copyright (c) 2007 Colony Project
3
 *
4
 * Permission is hereby granted, free of charge, to any person
5
 * obtaining a copy of this software and associated documentation
6
 * files (the "Software"), to deal in the Software without
7
 * restriction, including without limitation the rights to use,
8
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
9
 * copies of the Software, and to permit persons to whom the
10
 * Software is furnished to do so, subject to the following
11
 * conditions:
12
 *
13
 * The above copyright notice and this permission notice shall be
14
 * included in all copies or substantial portions of the Software.
15
 *
16
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
18
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
20
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
21
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23
 * OTHER DEALINGS IN THE SOFTWARE.
24
 **/
25

    
26

    
27
/**
28
 * @file i2c.c
29
 * @brief Implemenation of I2C communications protocol
30
 *
31
 * In the case where you have master sends and then a master request to the same
32
 * address, you will not give up control of the line because the send and
33
 * request addresses are seen as different addresses. In between it will send a
34
 * restart but will not give up the line.
35
 *
36
 * @author CMU Robotics Club, Kevin Woo, Sursh Nidhiry
37
 * @bug Not tested.
38
 */
39

    
40
#include <avr/interrupt.h>
41
#include <util/twi.h>
42

    
43
#include "i2c.h"
44
#include "ring_buffer.h"
45

    
46
/**
47
 * @defgroup i2c I2C
48
 *
49
 * @brief Provides Inter-Interconnected-Communications (I2C)
50
 *
51
 * Initiates I2C functions on an ATMega128 which has a fully hardware Two Wire
52
 * Interface (TWI) module. Any Atmel chip with this hardware should be able to
53
 * use the software.
54
 *
55
 * This code will operate in a multi-master enviornment and can be either a
56
 * slave or a master at any time (as long as they are not one or the other at
57
 * the moment. You can queue up multiple transmission modes in the buffer up to
58
 * the buffer size. The buffer is implemented as a ring buffer.
59
 *
60
 * It is implemented using callback functions. Whenever you want to send a packet
61
 * you can call the built in send function (as a master) and it will send an array
62
 * of bytes. Master recieve and slave send/receive are all handled by the call back
63
 * functions. It is up to the end user to create functions that will handle the
64
 * receiving of packets. Their functions will be called with every byte recieved
65
 * so you must either buffer the inputs or handle each one separately.
66
 *
67
 * On errors we will simply flush the entire buffer.
68
 *
69
 * For information on how I2C operates, read the wikipedia article
70
 * http://en.wikipedia.org/wiki/I2c
71
 * for a good explanation of how it works.
72
 * @{
73
 */
74

    
75
/**
76
 * @brief Set bit rate 12 = 100kbit/s (max speed setting is 10 for an
77
 *  8 MHz clock). It is a divider, so the lower the number the faster the speed.
78
 */
79
#define I2C_BIT_RATE_DIVIDER 0x0C
80

    
81
static int start_flag;
82

    
83
static fun_mrecv_t master_recv_function;
84
static fun_srecv_t slave_recv_function;
85
static fun_send_t slave_send_function;
86

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

    
89

    
90
/**
91
 * @brief Initializes the i2c module.
92
 *
93
 * Initializes the I2C module to start listening on the i2c lines. If the callback functions
94
 * are not set to null they will be called when that transmission mode is called. The address
95
 * is your address that you will listen to when you are not the master.
96
 *
97
 * @param addr      Your address on the I2C bus.
98
 * @param master_recv   The address of the function to call when you receive a byte when you are a
99
 *                      master.
100
 * @param slave_recv  The address of the function to call when you are a slave you receive data
101
 *                from the master
102
 * @param slave_send    The address of the function to call when you are a slave and the master
103
 *                requests data from you.
104
 *
105
 * @return 0 for success, nonzero for failure
106
 **/
107
int i2c_init(char addr, fun_mrecv_t master_recv, fun_srecv_t slave_recv, fun_send_t slave_send) {
108
  master_recv_function = master_recv;
109
  slave_recv_function = slave_recv;
110
  slave_send_function = slave_send;
111

    
112
  RING_BUFFER_CLEAR(i2c_write_buff);
113
  RING_BUFFER_CLEAR(i2c_addr_buff);
114

    
115
  /* enables twi interrupt, automatic ack sending, and all twi hardware */
116
  TWCR =  (_BV(TWEA) | _BV(TWEN) | _BV(TWIE));
117

    
118
  /* sets the bit rate of data transmission */
119
  TWBR = I2C_BIT_RATE_DIVIDER;
120

    
121
  /* sets the address (it is stored in the 7 most significant bits) and allows
122
   * global messages to be accepted */
123
  TWAR = (addr << 1) | 1;
124

    
125
  return 0;
126
}
127

    
128
/**
129
 * @brief Sends a byte array over I2C as a master
130
 *
131
 * Will perform a send over I2C to the destination from data for the ammount of
132
 * bytes that bytes is.
133
 *
134
 * @param dest    Destination address of the data on the I2C bus.
135
 * @param data  The pointer to the byte array of data
136
 * @param bytes The amount of bytes long that the byte array is. This is how
137
 *            many bytes from the array that the function will send.
138
 *
139
 * @return zero for success, nonzero for failure
140
 **/
141
int i2c_send(char dest, char *data, size_t bytes) {
142
  int i;
143

    
144
  /* adding data to be sent to ring buffers is not atomic,
145
   * so disable interrupts */
146
  cli();
147
  for (i = 0; i < bytes; i++) {
148
    if (RING_BUFFER_FULL(i2c_write_buff)) {
149
      sei();
150
      return -1;
151
    }
152

    
153
    RING_BUFFER_ADD(i2c_write_buff, data[i]);
154
    RING_BUFFER_ADD(i2c_addr_buff, dest << 1);
155
  }
156

    
157
  /* re-enable the interrupts */
158
  sei();
159

    
160
  /* send the start bit, only if this device is not currently master */
161
  if (!start_flag) {
162
    start_flag = 1;
163
    TWCR |= _BV(TWSTA);
164
    TWCR |= _BV(TWINT);
165
  }
166

    
167
  return 0;
168
}
169

    
170
/**
171
 * @brief Send a master request to the destination
172
 *
173
 * Sends a request of data from the target address and calls
174
 * the callback function to handle data as it comes in. This function will
175
 * not work if the slave has not informationt to send or has nothing implemented
176
 * to send it.
177
 *
178
 * @param dest    The destination that we want to receive information from.
179
 *
180
 * @return 0 for success, nonzero for failure
181
 **/
182
int i2c_request(char dest) {
183
  if (RING_BUFFER_FULL(i2c_write_buff)) {
184
    return -1;
185
  }
186

    
187
  RING_BUFFER_ADD(i2c_write_buff, 0);
188
  RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);
189

    
190
  if (!start_flag) {
191
    start_flag = 1;
192
    TWCR |= _BV(TWSTA);
193
    TWCR |= _BV(TWINT);
194
  }
195

    
196
  return 0;
197
}
198

    
199
/** @} **/
200

    
201
/**
202
 * @brief Interrupt to handle I2C interrupts from the I2C hardware.
203
 *
204
 * Uses the status codes from the I2C register to handle the events
205
 * needed to advance in I2C stages. For instance, you will get a bit for
206
 * receiving a start ack, then a address ack, then a data ack, etc.
207
 * The events are handled in each switch case. The status codes are defined
208
 * by avr-gcc in /util/twi.h but are the same codes as the Atmel documentation.
209
 *
210
 * Bytes are sent by popping off the ring buffer. It also will keep track
211
 * of what modes the send is in.
212
 *
213
 * Errors are handled here as well.
214
 **/
215
ISR(TWI_vect) {
216
  static char data_to_send;
217
  static char addr_to_send = -1;
218
  char addr, statusCode;
219

    
220
  //Get status code (only upper 5 bits)
221
  statusCode = (TWSR & 0xF8);
222

    
223
  switch (statusCode) {
224
    //Start sent successfully
225
  case TW_START:
226
  case TW_REP_START:
227
    /* Send address and write
228
     * ring_buffer will not be empty */
229
    RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);
230
    RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);
231

    
232
    /* first send the address */
233
    TWDR = addr_to_send;
234

    
235
    //Turn off start bits
236
    TWCR &= ~_BV(TWSTA);
237
    break;
238

    
239
    //Master Transmit - Address sent succesfully
240
  case TW_MT_SLA_ACK:
241
    //Send byte
242
    TWDR = data_to_send;
243
    PORTG &= ~_BV(PG2);
244
    break;
245

    
246
    //Master Transmit - Data sent succesfully
247
  case TW_MT_DATA_ACK:
248
    //If there is still data to send
249
    if (!RING_BUFFER_EMPTY(i2c_write_buff)) {
250
      RING_BUFFER_PEEK(i2c_addr_buff, addr);
251

    
252
      //Still data for this address
253
      if (addr == addr_to_send) {
254
        RING_BUFFER_REMOVE(i2c_addr_buff, addr);
255
        RING_BUFFER_REMOVE(i2c_write_buff, TWDR);
256
        break;
257
        //No more data for this address, data for another address -> resend start
258
      } else {
259
        TWCR |= _BV(TWSTA);
260
        break;
261
      }
262
    }
263
    /* there are no bytes to send */
264
    TWCR |= _BV(TWSTO);
265
    start_flag = 0;
266
    break;
267

    
268
    //Master Transmit - Slave sends a nack, transmit is done
269
  case TW_MT_DATA_NACK:
270
    PORTG |= _BV(PG2);
271
    TWCR |= _BV(TWSTO);
272
    start_flag = 0;
273
    break;
274

    
275
    //Master Receive - Address sent succesfully
276
  case TW_MR_SLA_ACK:
277
    PORTG |= _BV(PG2);
278
    break;
279

    
280
    //Master Receive - Data received succesfully
281
  case TW_MR_DATA_ACK:
282
    if (master_recv_function) {
283
      if (!master_recv_function(TWDR)) {
284
        TWCR &= ~_BV(TWEA);
285
      }
286
    }
287
    break;
288

    
289
    //Master Receive - Slave sends a nack, transmission is done
290
  case TW_MR_DATA_NACK:
291
    TWCR |= _BV(TWEA);
292

    
293
    //If there is still data to send
294
    if (!RING_BUFFER_EMPTY(i2c_write_buff)) {
295
      TWCR |= _BV(TWSTA);
296
      break;
297
    }
298

    
299
    /* there are no bytes to send */
300
    TWCR |= _BV(TWSTO);
301
    start_flag = 0;
302
    break;
303

    
304
    //Slave Transmit - Address received
305
  case TW_ST_SLA_ACK:
306
    break;
307

    
308
    //Slave Transmit - Nack received, no data requsted
309
  case TW_ST_DATA_NACK:
310
    break;
311

    
312
    //Slave Transmit - Data requested, ack received
313
  case TW_ST_DATA_ACK:
314
    if (slave_send_function) {
315
      TWDR = slave_send_function();
316
    }
317
    break;
318

    
319
    //Slave Receive - Address received
320
  case TW_SR_SLA_ACK:
321
    break;
322

    
323
    //Slave Receive - Data received, ack returned
324
  case TW_SR_DATA_ACK:
325
    if (slave_recv_function) {
326
      slave_recv_function(TWDR);
327
    }
328

    
329
    break;
330

    
331
    //Stop sent
332
  case TW_SR_STOP:
333
    break;
334

    
335
    //Problem on the bus, reset everything
336
  default:
337
    TWCR |= _BV(TWSTO);
338
    start_flag = 0;
339
    RING_BUFFER_CLEAR(i2c_write_buff);
340
    RING_BUFFER_CLEAR(i2c_addr_buff);
341
  }
342

    
343
  /* Toggle TWINT so that it resets and executes the commands */
344
  TWCR |= _BV(TWINT);
345
}