keyboard/ergodox/i2cmaster.h

   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                0 send nak, read is followed by a stop condition
 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