Statistics
| Revision:

root / demos / hunter_prey / lib / src / libdragonfly / i2c.c @ 1828

History | View | Annotate | Download (11 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, unsigned int 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
    RING_BUFFER_ADD(i2c_write_buff, 0);
187
    RING_BUFFER_ADD(i2c_addr_buff, (dest << 1) | 1);
188
  
189
    if(!start_flag) {
190
        start_flag = 1;
191
        TWCR |= _BV(TWSTA);
192
        TWCR |= _BV(TWINT);
193
    }
194
  
195
    return 0;
196
}
197

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

    
222
    switch (statusCode) {
223
        //Start sent successfully
224
        case TW_START:
225
        case TW_REP_START:
226
            /* Send address and write
227
             * ring_buffer will not be empty */
228
            RING_BUFFER_REMOVE(i2c_addr_buff, addr_to_send);
229
            RING_BUFFER_REMOVE(i2c_write_buff, data_to_send);
230
            
231
            /* first send the address */
232
            TWDR = addr_to_send; 
233
            
234
            //Turn off start bits
235
            TWCR &= ~_BV(TWSTA);
236
            break;
237

    
238
        //Master Transmit - Address sent succesfully
239
        case TW_MT_SLA_ACK:
240
        //Send byte
241
            TWDR = data_to_send;
242
            PORTG &= ~_BV(PG2);
243
            break;
244
         
245
        //Master Transmit - Data sent succesfully
246
        case TW_MT_DATA_ACK:    
247
            //If there is still data to send
248
            if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
249
                RING_BUFFER_PEEK(i2c_addr_buff, addr);
250
        
251
                //Still data for this address
252
                if (addr == addr_to_send) {
253
                    RING_BUFFER_REMOVE(i2c_addr_buff, addr);
254
                    RING_BUFFER_REMOVE(i2c_write_buff, TWDR);
255
                    break;
256
                //No more data for this address, data for another address -> resend start
257
                } else {
258
                    TWCR |= _BV(TWSTA);
259
                    break;
260
                }
261
            }
262
            /* there are no bytes to send */
263
            TWCR |= _BV(TWSTO);
264
            start_flag = 0;
265
            break; 
266
            
267
        //Master Transmit - Slave sends a nack, transmit is done
268
        case TW_MT_DATA_NACK:
269
            PORTG |= _BV(PG2);
270
            TWCR |= _BV(TWSTO);
271
            start_flag = 0;
272
            break;
273
    
274
        //Master Receive - Address sent succesfully
275
        case TW_MR_SLA_ACK:
276
            PORTG |= _BV(PG2);
277
            break;
278
            
279
        //Master Receive - Data received succesfully
280
        case TW_MR_DATA_ACK:
281
            if(master_recv_function) {
282
                if(!master_recv_function(TWDR)) {
283
                    TWCR &= ~_BV(TWEA);
284
                }
285
            }
286
            break;
287
            
288
        //Master Receive - Slave sends a nack, transmission is done    
289
        case TW_MR_DATA_NACK:
290
            TWCR |= _BV(TWEA);
291
      
292
            //If there is still data to send
293
            if(!RING_BUFFER_EMPTY(i2c_write_buff)) {
294
                TWCR |= _BV(TWSTA);
295
                break;
296
            }
297
      
298
            /* there are no bytes to send */
299
            TWCR |= _BV(TWSTO);
300
            start_flag = 0;  
301
            break;
302
    
303
        //Slave Transmit - Address received
304
        case TW_ST_SLA_ACK:
305
            break;
306
    
307
        //Slave Transmit - Nack received, no data requsted
308
        case TW_ST_DATA_NACK:
309
            break;
310
        
311
        //Slave Transmit - Data requested, ack received
312
        case TW_ST_DATA_ACK:
313
            if (slave_send_function) {
314
                TWDR = slave_send_function();
315
            }
316
            break;
317
    
318
        //Slave Receive - Address received  
319
        case TW_SR_SLA_ACK:
320
            break;
321
    
322
        //Slave Receive - Data received, ack returned
323
        case TW_SR_DATA_ACK:
324
            if(slave_recv_function) {
325
                slave_recv_function(TWDR);
326
            }
327
            
328
            break;
329
      
330
        //Stop sent  
331
        case TW_SR_STOP:
332
            break;
333
        
334
        //Problem on the bus, reset everything
335
        default:
336
            TWCR |= _BV(TWSTO);
337
            start_flag = 0;
338
            RING_BUFFER_CLEAR(i2c_write_buff);
339
            RING_BUFFER_CLEAR(i2c_addr_buff);          
340
    }
341
  
342
  /* Toggle TWINT so that it resets and executes the commands */
343
  TWCR |= _BV(TWINT);
344
}
345