]> git.friedersdorff.com Git - max/tmk_keyboard.git/blob - keyboard/ergodox/i2cmaster.h
Merge remote-tracking branch 'tmk/master'
[max/tmk_keyboard.git] / keyboard / ergodox / i2cmaster.h
1 #ifndef _I2CMASTER_H
2 #define _I2CMASTER_H
3 /************************************************************************* 
4 * Title:    C include file for the I2C master interface 
5 *           (i2cmaster.S or twimaster.c)
6 * Author:   Peter Fleury <pfleury@gmx.ch>
7 * File:     $Id: i2cmaster.h,v 1.12 2015/09/16 09:27:58 peter Exp $
8 * Software: AVR-GCC 4.x
9 * Target:   any AVR device
10 * Usage:    see Doxygen manual
11 **************************************************************************/
12
13 /**
14  @file
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://tinyurl.com/peterfleury
42  @copyright (C) 2015 Peter Fleury, GNU General Public License Version 3
43  
44  @par API Usage Example
45   The following code shows typical usage of this library, see example test_i2cmaster.c
46
47  @code
48
49  #include <i2cmaster.h>
50
51
52  #define Dev24C02  0xA2      // device address of EEPROM 24C02, see datasheet
53
54  int main(void)
55  {
56      unsigned char ret;
57
58      i2c_init();                             // initialize I2C library
59
60      // write 0x75 to EEPROM address 5 (Byte Write) 
61      i2c_start_wait(Dev24C02+I2C_WRITE);     // set device address and write mode
62      i2c_write(0x05);                        // write address = 5
63      i2c_write(0x75);                        // write value 0x75 to EEPROM
64      i2c_stop();                             // set stop conditon = release bus
65
66
67      // read previously written value back from EEPROM address 5 
68      i2c_start_wait(Dev24C02+I2C_WRITE);     // set device address and write mode
69
70      i2c_write(0x05);                        // write address = 5
71      i2c_rep_start(Dev24C02+I2C_READ);       // set device address and read mode
72
73      ret = i2c_readNak();                    // read one byte from EEPROM
74      i2c_stop();
75
76      for(;;);
77  }
78  @endcode
79
80 */
81
82
83 /**@{*/
84
85 #if (__GNUC__ * 100 + __GNUC_MINOR__) < 304
86 #error "This library requires AVR-GCC 3.4 or later, update to newer AVR-GCC compiler !"
87 #endif
88
89 #include <avr/io.h>
90
91 /** defines the data direction (reading from I2C device) in i2c_start(),i2c_rep_start() */
92 #define I2C_READ    1
93
94 /** defines the data direction (writing to I2C device) in i2c_start(),i2c_rep_start() */
95 #define I2C_WRITE   0
96
97
98 /**
99  @brief initialize the I2C master interace. Need to be called only once 
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  @return none
108  */
109 extern void i2c_stop(void);
110
111
112 /** 
113  @brief Issues a start condition and sends address and transfer direction 
114   
115  @param    addr address and transfer direction of I2C device
116  @retval   0   device accessible 
117  @retval   1   failed to access device 
118  */
119 extern unsigned char i2c_start(unsigned char addr);
120
121
122 /**
123  @brief Issues a repeated start condition and sends address and transfer direction 
124
125  @param   addr address and transfer direction of I2C device
126  @retval  0 device accessible
127  @retval  1 failed to access device
128  */
129 extern unsigned char i2c_rep_start(unsigned char addr);
130
131
132 /**
133  @brief Issues a start condition and sends address and transfer direction 
134    
135  If device is busy, use ack polling to wait until device ready 
136  @param    addr address and transfer direction of I2C device
137  @return   none
138  */
139 extern void i2c_start_wait(unsigned char addr);
140
141  
142 /**
143  @brief Send one byte to I2C device
144  @param    data  byte to be transfered
145  @retval   0 write successful
146  @retval   1 write failed
147  */
148 extern unsigned char i2c_write(unsigned char data);
149
150
151 /**
152  @brief    read one byte from the I2C device, request more data from device 
153  @return   byte read from I2C device
154  */
155 extern unsigned char i2c_readAck(void);
156
157 /**
158  @brief    read one byte from the I2C device, read is followed by a stop condition 
159  @return   byte read from I2C device
160  */
161 extern unsigned char i2c_readNak(void);
162
163 /** 
164  @brief    read one byte from the I2C device
165  
166  Implemented as a macro, which calls either @ref i2c_readAck or @ref i2c_readNak
167  
168  @param    ack 1 send ack, request more data from device<br>
169                0 send nak, read is followed by a stop condition 
170  @return   byte read from I2C device
171  */
172 extern unsigned char i2c_read(unsigned char ack);
173 #define i2c_read(ack)  (ack) ? i2c_readAck() : i2c_readNak(); 
174
175
176
177 /**@}*/
178 #endif