Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# i2c.h

Go to the documentation of this file.

    00001 /*! \file i2c.h \brief I2C interface using AVR Two-Wire Interface (TWI) hardware. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'i2c.h'
    00005 // Title        : I2C interface using AVR Two-Wire Interface (TWI) hardware
    00006 // Author       : Pascal Stang - Copyright (C) 2002-2003
    00007 // Created      : 2002.06.25
    00008 // Revised      : 2003.03.03
    00009 // Version      : 0.9
    00010 // Target MCU   : Atmel AVR series
    00011 // Editor Tabs  : 4
    00012 //
    00013 /// \ingroup driver_avr
    00014 /// \defgroup i2c I2C Serial Interface Function Library (i2c.c)
    00015 /// \code #include "i2c.h" \endcode
    00016 /// \par Overview
    00017 ///     This library provides the high-level functions needed to use the I2C
    00018 /// serial interface supported by the hardware of several AVR processors.
    00019 /// The library is functional but has not been exhaustively tested yet and is
    00020 /// still expanding.  Thanks to the standardization of the I2C protocol and
    00021 /// register access, the send and receive commands are everything you need to
    00022 /// talk to thousands of different I2C devices including: EEPROMS, Flash memory,
    00023 /// MP3 players, A/D and D/A converters, electronic potentiometers, etc.
    00024 ///
    00025 /// \par About I2C
    00026 ///         I2C (pronounced "eye-squared-see") is a two-wire bidirectional
    00027 ///     network designed for easy transfer of information between a wide variety
    00028 ///     of intelligent devices.  Many of the Atmel AVR series processors have
    00029 ///     hardware support for transmitting and receiving using an I2C-type bus.
    00030 ///     In addition to the AVRs, there are thousands of other parts made by
    00031 ///     manufacturers like Philips, Maxim, National, TI, etc that use I2C as
    00032 ///     their primary means of communication and control.  Common device types
    00033 ///     are A/D & D/A converters, temp sensors, intelligent battery monitors,
    00034 ///     MP3 decoder chips, EEPROM chips, multiplexing switches, etc.
    00035 ///
    00036 ///     I2C uses only two wires (SDA and SCL) to communicate bidirectionally
    00037 ///     between devices.  I2C is a multidrop network, meaning that you can have
    00038 ///     several devices on a single bus.  Because I2C uses a 7-bit number to
    00039 ///     identify which device it wants to talk to, you cannot have more than
    00040 ///     127 devices on a single bus.
    00041 ///
    00042 ///     I2C ordinarily requires two 4.7K pull-up resistors to power (one each on
    00043 ///     SDA and SCL), but for small numbers of devices (maybe 1-4), it is enough
    00044 ///     to activate the internal pull-up resistors in the AVR processor.  To do
    00045 ///     this, set the port pins, which correspond to the I2C pins SDA/SCL, high.
    00046 ///     For example, on the mega163, sbi(PORTC, 0); sbi(PORTC, 1);.
    00047 ///
    00048 ///     For complete information about I2C, see the Philips Semiconductor
    00049 ///     website.  They created I2C and have the largest family of devices that
    00050 ///     work with I2C.
    00051 ///
    00052 /// \Note: Many manufacturers market I2C bus devices under a different or generic
    00053 ///     bus name like "Two-Wire Interface".  This is because Philips still holds
    00054 ///     "I2C" as a trademark.  For example, SMBus and SMBus devices are hardware
    00055 ///     compatible and closely related to I2C.  They can be directly connected
    00056 ///     to an I2C bus along with other I2C devices are are generally accessed in
    00057 ///     the same way as I2C devices.  SMBus is often found on modern motherboards
    00058 ///     for temp sensing and other low-level control tasks.
    00059 //
    00060 // This code is distributed under the GNU Public License
    00061 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00062 //
    00063 //*****************************************************************************
    00064
    00065 #ifndef I2C_H
    00066 #define I2C_H
    00067
    00068 #include "global.h"
    00069
    00070 // include project-specific configuration
    00071 #include "i2cconf.h"
    00072
    00073 // TWSR values (not bits)
    00074 // (taken from avr-libc twi.h - thank you Marek Michalkiewicz)
    00075 // Master
    00076 #define TW_START                    0x08
    00077 #define TW_REP_START                0x10
    00078 // Master Transmitter
    00079 #define TW_MT_SLA_ACK               0x18
    00080 #define TW_MT_SLA_NACK              0x20
    00081 #define TW_MT_DATA_ACK              0x28
    00082 #define TW_MT_DATA_NACK             0x30
    00083 #define TW_MT_ARB_LOST              0x38
    00084 // Master Receiver
    00085 #define TW_MR_ARB_LOST              0x38
    00086 #define TW_MR_SLA_ACK               0x40
    00087 #define TW_MR_SLA_NACK              0x48
    00088 #define TW_MR_DATA_ACK              0x50
    00089 #define TW_MR_DATA_NACK             0x58
    00090 // Slave Transmitter
    00091 #define TW_ST_SLA_ACK               0xA8
    00092 #define TW_ST_ARB_LOST_SLA_ACK      0xB0
    00093 #define TW_ST_DATA_ACK              0xB8
    00094 #define TW_ST_DATA_NACK             0xC0
    00095 #define TW_ST_LAST_DATA             0xC8
    00096 // Slave Receiver
    00097 #define TW_SR_SLA_ACK               0x60
    00098 #define TW_SR_ARB_LOST_SLA_ACK      0x68
    00099 #define TW_SR_GCALL_ACK             0x70
    00100 #define TW_SR_ARB_LOST_GCALL_ACK    0x78
    00101 #define TW_SR_DATA_ACK              0x80
    00102 #define TW_SR_DATA_NACK             0x88
    00103 #define TW_SR_GCALL_DATA_ACK        0x90
    00104 #define TW_SR_GCALL_DATA_NACK       0x98
    00105 #define TW_SR_STOP                  0xA0
    00106 // Misc
    00107 #define TW_NO_INFO                  0xF8
    00108 #define TW_BUS_ERROR                0x00
    00109
    00110 // defines and constants
    00111 #define TWCR_CMD_MASK       0x0F
    00112 #define TWSR_STATUS_MASK    0xF8
    00113
    00114 // return values
    00115 #define I2C_OK              0x00
    00116 #define I2C_ERROR_NODEV     0x01
    00117
    00118 // types
    00119 typedef enum
    00120 {
    00121     I2C_IDLE = 0, I2C_BUSY = 1,
    00122     I2C_MASTER_TX = 2, I2C_MASTER_RX = 3,
    00123     I2C_SLAVE_TX = 4, I2C_SLAVE_RX = 5
    00124 } eI2cStateType;
    00125
    00126 // functions
    00127
    00128 //! Initialize I2C (TWI) interface
    00129 void i2cInit(void);
    00130
    00131 //! Set the I2C transaction bitrate (in KHz)
    00132 void i2cSetBitrate(u16 bitrateKHz);
    00133
    00134 // I2C setup and configurations commands
    00135 //! Set the local (AVR processor's) I2C device address
    00136 void i2cSetLocalDeviceAddr(u08 deviceAddr, u08 genCallEn);
    00137
    00138 //! Set the user function which handles receiving (incoming) data as a slave
    00139 void i2cSetSlaveReceiveHandler(void (*i2cSlaveRx_func)(u08 receiveDataLength, u08* recieveData));
    00140 //! Set the user function which handles transmitting (outgoing) data as a slave
    00141 void i2cSetSlaveTransmitHandler(u08 (*i2cSlaveTx_func)(u08 transmitDataLengthMax, u08* transmitData));
    00142
    00143 // Low-level I2C transaction commands
    00144 //! Send an I2C start condition in Master mode
    00145 void i2cSendStart(void);
    00146 //! Send an I2C stop condition in Master mode
    00147 void i2cSendStop(void);
    00148 //! Wait for current I2C operation to complete
    00149 void i2cWaitForComplete(void);
    00150 //! Send an (address|R/W) combination or a data byte over I2C
    00151 void i2cSendByte(u08 data);
    00152 //! Receive a data byte over I2C
    00153 // ackFlag = TRUE if recevied data should be ACK'ed
    00154 // ackFlag = FALSE if recevied data should be NACK'ed
    00155 void i2cReceiveByte(u08 ackFlag);
    00156 //! Pick up the data that was received with i2cReceiveByte()
    00157 u08 i2cGetReceivedByte(void);
    00158 //! Get current I2c bus status from TWSR
    00159 u08 i2cGetStatus(void);
    00160
    00161 // high-level I2C transaction commands
    00162
    00163 //! send I2C data to a device on the bus
    00164 void i2cMasterSend(u08 deviceAddr, u08 length, u08 *data);
    00165 //! receive I2C data from a device on the bus
    00166 void i2cMasterReceive(u08 deviceAddr, u08 length, u08* data);
    00167
    00168 //! send I2C data to a device on the bus (non-interrupt based)
    00169 u08 i2cMasterSendNI(u08 deviceAddr, u08 length, u08* data);
    00170 //! receive I2C data from a device on the bus (non-interrupt based)
    00171 u08 i2cMasterReceiveNI(u08 deviceAddr, u08 length, u08 *data);
    00172
    00173 //! Get the current high-level state of the I2C interface
    00174 eI2cStateType i2cGetState(void);
    00175
    00176 #endif