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