Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
2194 | - | 1 | #ifndef _I2CMASTER_H |
2 | #define _I2CMASTER_H 1 |
||
3 | /************************************************************************* |
||
4 | * Title: C include file for the I2C master interface |
||
5 | * (i2cmaster.S or twimaster.c) |
||
6 | * Author: Peter Fleury <pfleury@gmx.ch> http://jump.to/fleury |
||
7 | * File: $Id: i2cmaster.h,v 1.10 2005/03/06 22:39:57 Peter Exp $ |
||
8 | * Software: AVR-GCC 3.4.3 / avr-libc 1.2.3 |
||
9 | * Target: any AVR device |
||
10 | * Usage: see Doxygen manual |
||
11 | **************************************************************************/ |
||
12 | |||
13 | #ifdef DOXYGEN |
||
14 | /** |
||
15 | @defgroup pfleury_ic2master I2C Master library |
||
16 | @code #include <i2cmaster.h> @endcode |
||
17 | |||
18 | @brief I2C (TWI) Master Software Library |
||
19 | |||
20 | Basic routines for communicating with I2C slave devices. This single master |
||
21 | implementation is limited to one bus master on the I2C bus. |
||
22 | |||
23 | This I2c library is implemented as a compact assembler software implementation of the I2C protocol |
||
24 | which runs on any AVR (i2cmaster.S) and as a TWI hardware interface for all AVR with built-in TWI hardware (twimaster.c). |
||
25 | Since the API for these two implementations is exactly the same, an application can be linked either against the |
||
26 | software I2C implementation or the hardware I2C implementation. |
||
27 | |||
28 | Use 4.7k pull-up resistor on the SDA and SCL pin. |
||
29 | |||
30 | Adapt the SCL and SDA port and pin definitions and eventually the delay routine in the module |
||
31 | i2cmaster.S to your target when using the software I2C implementation ! |
||
32 | |||
33 | Adjust the CPU clock frequence F_CPU in twimaster.c or in the Makfile when using the TWI hardware implementaion. |
||
34 | |||
35 | @note |
||
36 | The module i2cmaster.S is based on the Atmel Application Note AVR300, corrected and adapted |
||
37 | to GNU assembler and AVR-GCC C call interface. |
||
38 | Replaced the incorrect quarter period delays found in AVR300 with |
||
39 | half period delays. |
||
40 | |||
41 | @author Peter Fleury pfleury@gmx.ch http://jump.to/fleury |
||
42 | |||
43 | @par API Usage Example |
||
44 | The following code shows typical usage of this library, see example test_i2cmaster.c |
||
45 | |||
46 | @code |
||
47 | |||
48 | #include <i2cmaster.h> |
||
49 | |||
50 | |||
51 | #define Dev24C02 0xA2 // device address of EEPROM 24C02, see datasheet |
||
52 | |||
53 | int main(void) |
||
54 | { |
||
55 | unsigned char ret; |
||
56 | |||
57 | i2c_init(); // initialize I2C library |
||
58 | |||
59 | // write 0x75 to EEPROM address 5 (Byte Write) |
||
60 | i2c_start_wait(Dev24C02+I2C_WRITE); // set device address and write mode |
||
61 | i2c_write(0x05); // write address = 5 |
||
62 | i2c_write(0x75); // write value 0x75 to EEPROM |
||
63 | i2c_stop(); // set stop conditon = release bus |
||
64 | |||
65 | |||
66 | // read previously written value back from EEPROM address 5 |
||
67 | i2c_start_wait(Dev24C02+I2C_WRITE); // set device address and write mode |
||
68 | |||
69 | i2c_write(0x05); // write address = 5 |
||
70 | i2c_rep_start(Dev24C02+I2C_READ); // set device address and read mode |
||
71 | |||
72 | ret = i2c_readNak(); // read one byte from EEPROM |
||
73 | i2c_stop(); |
||
74 | |||
75 | for(;;); |
||
76 | } |
||
77 | @endcode |
||
78 | |||
79 | */ |
||
80 | #endif /* DOXYGEN */ |
||
81 | |||
82 | /**@{*/ |
||
83 | |||
84 | #if (__GNUC__ * 100 + __GNUC_MINOR__) < 304 |
||
85 | #error "This library requires AVR-GCC 3.4 or later, update to newer AVR-GCC compiler !" |
||
86 | #endif |
||
87 | |||
88 | #include <avr/io.h> |
||
89 | |||
90 | /** defines the data direction (reading from I2C device) in i2c_start(),i2c_rep_start() */ |
||
91 | #define I2C_READ 1 |
||
92 | |||
93 | /** defines the data direction (writing to I2C device) in i2c_start(),i2c_rep_start() */ |
||
94 | #define I2C_WRITE 0 |
||
95 | |||
96 | |||
97 | /** |
||
98 | @brief initialize the I2C master interace. Need to be called only once |
||
99 | @param void |
||
100 | @return none |
||
101 | */ |
||
102 | extern void i2c_init(void); |
||
103 | |||
104 | |||
105 | /** |
||
106 | @brief Terminates the data transfer and releases the I2C bus |
||
107 | @param void |
||
108 | @return none |
||
109 | */ |
||
110 | extern void i2c_stop(void); |
||
111 | |||
112 | |||
113 | /** |
||
114 | @brief Issues a start condition and sends address and transfer direction |
||
115 | |||
116 | @param addr address and transfer direction of I2C device |
||
117 | @retval 0 device accessible |
||
118 | @retval 1 failed to access device |
||
119 | */ |
||
120 | extern unsigned char i2c_start(unsigned char addr); |
||
121 | |||
122 | |||
123 | /** |
||
124 | @brief Issues a repeated start condition and sends address and transfer direction |
||
125 | |||
126 | @param addr address and transfer direction of I2C device |
||
127 | @retval 0 device accessible |
||
128 | @retval 1 failed to access device |
||
129 | */ |
||
130 | extern unsigned char i2c_rep_start(unsigned char addr); |
||
131 | |||
132 | |||
133 | /** |
||
134 | @brief Issues a start condition and sends address and transfer direction |
||
135 | |||
136 | If device is busy, use ack polling to wait until device ready |
||
137 | @param addr address and transfer direction of I2C device |
||
138 | @return none |
||
139 | */ |
||
140 | extern void i2c_start_wait(unsigned char addr); |
||
141 | |||
142 | |||
143 | /** |
||
144 | @brief Send one byte to I2C device |
||
145 | @param data byte to be transfered |
||
146 | @retval 0 write successful |
||
147 | @retval 1 write failed |
||
148 | */ |
||
149 | extern unsigned char i2c_write(unsigned char data); |
||
150 | |||
151 | |||
152 | /** |
||
153 | @brief read one byte from the I2C device, request more data from device |
||
154 | @return byte read from I2C device |
||
155 | */ |
||
156 | extern unsigned char i2c_readAck(void); |
||
157 | |||
158 | /** |
||
159 | @brief read one byte from the I2C device, read is followed by a stop condition |
||
160 | @return byte read from I2C device |
||
161 | */ |
||
162 | extern unsigned char i2c_readNak(void); |
||
163 | |||
164 | /** |
||
165 | @brief read one byte from the I2C device |
||
166 | |||
167 | Implemented as a macro, which calls either i2c_readAck or i2c_readNak |
||
168 | |||
169 | @param ack 1 send ack, request more data from device<br> |
||
170 | |||
171 | @return byte read from I2C device |
||
172 | */ |
||
173 | extern unsigned char i2c_read(unsigned char ack); |
||
174 | #define i2c_read(ack) (ack) ? i2c_readAck() : i2c_readNak(); |
||
175 | |||
176 | |||
177 | /**@}*/ |
||
178 | #endif |