I2Cdevlib

I2C device library collection for AVR/Arduino or other C++-based MCUs

I2Cdev.h
00001 // I2Cdev library collection - Main I2C device class header file
00002 // Abstracts bit and byte I2C R/W functions into a convenient class
00003 // 11/1/2011 by Jeff Rowberg <jeff@rowberg.net>
00004 //
00005 // Changelog:
00006 //     2011-11-01 - fix write*Bits mask calculation (thanks sasquatch @ Arduino forums)
00007 //     2011-10-03 - added automatic Arduino version detection for ease of use
00008 //     2011-10-02 - added Gene Knight's NBWire TwoWire class implementation with small modifications
00009 //     2011-08-31 - added support for Arduino 1.0 Wire library (methods are different from 0.x)
00010 //     2011-08-03 - added optional timeout parameter to read* methods to easily change from default
00011 //     2011-08-02 - added support for 16-bit registers
00012 //                - fixed incorrect Doxygen comments on some methods
00013 //                - added timeout value for read operations (thanks mem @ Arduino forums)
00014 //     2011-07-30 - changed read/write function structures to return success or byte counts
00015 //                - made all methods static for multi-device memory savings
00016 //     2011-07-28 - initial release
00017 
00018 /* ============================================
00019 I2Cdev device library code is placed under the MIT license
00020 Copyright (c) 2011 Jeff Rowberg
00021 
00022 Permission is hereby granted, free of charge, to any person obtaining a copy
00023 of this software and associated documentation files (the "Software"), to deal
00024 in the Software without restriction, including without limitation the rights
00025 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00026 copies of the Software, and to permit persons to whom the Software is
00027 furnished to do so, subject to the following conditions:
00028 
00029 The above copyright notice and this permission notice shall be included in
00030 all copies or substantial portions of the Software.
00031 
00032 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00033 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00034 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00035 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00036 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00037 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00038 THE SOFTWARE.
00039 ===============================================
00040 */
00041 
00042 #ifndef _I2CDEV_H_
00043 #define _I2CDEV_H_
00044 
00045 // -----------------------------------------------------------------------------
00046 // I2C interface implementation setting
00047 // -----------------------------------------------------------------------------
00048 #define I2CDEV_IMPLEMENTATION       I2CDEV_ARDUINO_WIRE
00049 
00050 // -----------------------------------------------------------------------------
00051 // I2C interface implementation options
00052 // -----------------------------------------------------------------------------
00053 #define I2CDEV_ARDUINO_WIRE         1 // Wire object from Arduino
00054 #define I2CDEV_BUILTIN_NBWIRE       2 // Tweaked Wire object from Gene Knight's NBWire project
00055                                       // ^^^ NBWire implementation is still buggy w/some interrupts!
00056 #define I2CDEV_BUILTIN_FASTWIRE     3 // FastWire object from Francesco Ferrara's project
00057 
00058 // -----------------------------------------------------------------------------
00059 // Arduino-style "Serial.print" debug constant (uncomment to enable)
00060 // -----------------------------------------------------------------------------
00061 //#define I2CDEV_SERIAL_DEBUG
00062 
00063 #ifdef ARDUINO
00064     #if ARDUINO < 100
00065         #include "WProgram.h"
00066     #else
00067         #include "Arduino.h"
00068     #endif
00069     #if I2CDEV_IMPLEMENTATION == I2CDEV_ARDUINO_WIRE
00070         #include <Wire.h>
00071     #endif
00072 #else
00073     #include "ArduinoWrapper.h"
00074 #endif
00075 
00076 // 1000ms default read timeout (modify with "I2Cdev::readTimeout = [ms];")
00077 #define I2CDEV_DEFAULT_READ_TIMEOUT     1000
00078 
00079 class I2Cdev {
00080     public:
00081         I2Cdev();
00082         
00083         static int8_t readBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t *data, uint16_t timeout=I2Cdev::readTimeout);
00084         static int8_t readBitW(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint16_t *data, uint16_t timeout=I2Cdev::readTimeout);
00085         static int8_t readBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t *data, uint16_t timeout=I2Cdev::readTimeout);
00086         static int8_t readBitsW(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint16_t *data, uint16_t timeout=I2Cdev::readTimeout);
00087         static int8_t readByte(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint16_t timeout=I2Cdev::readTimeout);
00088         static int8_t readWord(uint8_t devAddr, uint8_t regAddr, uint16_t *data, uint16_t timeout=I2Cdev::readTimeout);
00089         static int8_t readBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data, uint16_t timeout=I2Cdev::readTimeout);
00090         static int8_t readWords(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint16_t *data, uint16_t timeout=I2Cdev::readTimeout);
00091 
00092         static bool writeBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t data);
00093         static bool writeBitW(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint16_t data);
00094         static bool writeBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t data);
00095         static bool writeBitsW(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint16_t data);
00096         static bool writeByte(uint8_t devAddr, uint8_t regAddr, uint8_t data);
00097         static bool writeWord(uint8_t devAddr, uint8_t regAddr, uint16_t data);
00098         static bool writeBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data);
00099         static bool writeWords(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint16_t *data);
00100 
00101         static uint16_t readTimeout;
00102 };
00103 
00104 #if I2CDEV_IMPLEMENTATION == I2CDEV_BUILTIN_FASTWIRE
00105     // I2C library
00107     // Copyright(C) 2011
00108     // Francesco Ferrara
00110     
00111     /* Master */
00112     #define TW_START                0x08
00113     #define TW_REP_START            0x10
00114 
00115     /* Master Transmitter */
00116     #define TW_MT_SLA_ACK           0x18
00117     #define TW_MT_SLA_NACK          0x20
00118     #define TW_MT_DATA_ACK          0x28
00119     #define TW_MT_DATA_NACK         0x30
00120     #define TW_MT_ARB_LOST          0x38
00121 
00122     /* Master Receiver */
00123     #define TW_MR_ARB_LOST          0x38
00124     #define TW_MR_SLA_ACK           0x40
00125     #define TW_MR_SLA_NACK          0x48
00126     #define TW_MR_DATA_ACK          0x50
00127     #define TW_MR_DATA_NACK         0x58
00128 
00129     #define TW_OK                   0
00130     #define TW_ERROR                1
00131 
00132     class Fastwire {
00133         private:
00134           static boolean waitInt();
00135 
00136         public:
00137           static void setup(int khz, boolean pullup);
00138           static byte write(byte device, byte address, byte value);
00139           static byte readBuf(byte device, byte address, byte *data, byte num);
00140     };
00141 #endif
00142 
00143 #if I2CDEV_IMPLEMENTATION == I2CDEV_BUILTIN_NBWIRE
00144     // NBWire implementation based heavily on code by Gene Knight <Gene@Telobot.com>
00145     // Originally posted on the Arduino forum at http://arduino.cc/forum/index.php/topic,70705.0.html
00146     // Originally offered to the i2cdevlib project at http://arduino.cc/forum/index.php/topic,68210.30.html
00147 
00148     #define NBWIRE_BUFFER_LENGTH 32
00149     
00150     class TwoWire {
00151         private:
00152             static uint8_t rxBuffer[];
00153             static uint8_t rxBufferIndex;
00154             static uint8_t rxBufferLength;
00155         
00156             static uint8_t txAddress;
00157             static uint8_t txBuffer[];
00158             static uint8_t txBufferIndex;
00159             static uint8_t txBufferLength;
00160         
00161             // static uint8_t transmitting;
00162             static void (*user_onRequest)(void);
00163             static void (*user_onReceive)(int);
00164             static void onRequestService(void);
00165             static void onReceiveService(uint8_t*, int);
00166     
00167         public:
00168             TwoWire();
00169             void begin();
00170             void begin(uint8_t);
00171             void begin(int);
00172             void beginTransmission(uint8_t);
00173             //void beginTransmission(int);
00174             uint8_t endTransmission(uint16_t timeout=0);
00175             void nbendTransmission(void (*function)(int)) ;
00176             uint8_t requestFrom(uint8_t, int, uint16_t timeout=0);
00177             //uint8_t requestFrom(int, int);
00178             void nbrequestFrom(uint8_t, int, void (*function)(int));
00179             void send(uint8_t);
00180             void send(uint8_t*, uint8_t);
00181             //void send(int);
00182             void send(char*);
00183             uint8_t available(void);
00184             uint8_t receive(void);
00185             void onReceive(void (*)(int));
00186             void onRequest(void (*)(void));
00187     };
00188     
00189     #define TWI_READY   0
00190     #define TWI_MRX     1
00191     #define TWI_MTX     2
00192     #define TWI_SRX     3
00193     #define TWI_STX     4
00194     
00195     #define TW_WRITE    0
00196     #define TW_READ     1
00197     
00198     #define TW_MT_SLA_NACK      0x20
00199     #define TW_MT_DATA_NACK     0x30
00200     
00201     #define CPU_FREQ            16000000L
00202     #define TWI_FREQ            100000L
00203     #define TWI_BUFFER_LENGTH   32
00204     
00205     /* TWI Status is in TWSR, in the top 5 bits: TWS7 - TWS3 */
00206     
00207     #define TW_STATUS_MASK              (_BV(TWS7)|_BV(TWS6)|_BV(TWS5)|_BV(TWS4)|_BV(TWS3))
00208     #define TW_STATUS                   (TWSR & TW_STATUS_MASK)
00209     #define TW_START                    0x08
00210     #define TW_REP_START                0x10
00211     #define TW_MT_SLA_ACK               0x18
00212     #define TW_MT_SLA_NACK              0x20
00213     #define TW_MT_DATA_ACK              0x28
00214     #define TW_MT_DATA_NACK             0x30
00215     #define TW_MT_ARB_LOST              0x38
00216     #define TW_MR_ARB_LOST              0x38
00217     #define TW_MR_SLA_ACK               0x40
00218     #define TW_MR_SLA_NACK              0x48
00219     #define TW_MR_DATA_ACK              0x50
00220     #define TW_MR_DATA_NACK             0x58
00221     #define TW_ST_SLA_ACK               0xA8
00222     #define TW_ST_ARB_LOST_SLA_ACK      0xB0
00223     #define TW_ST_DATA_ACK              0xB8
00224     #define TW_ST_DATA_NACK             0xC0
00225     #define TW_ST_LAST_DATA             0xC8
00226     #define TW_SR_SLA_ACK               0x60
00227     #define TW_SR_ARB_LOST_SLA_ACK      0x68
00228     #define TW_SR_GCALL_ACK             0x70
00229     #define TW_SR_ARB_LOST_GCALL_ACK    0x78
00230     #define TW_SR_DATA_ACK              0x80
00231     #define TW_SR_DATA_NACK             0x88
00232     #define TW_SR_GCALL_DATA_ACK        0x90
00233     #define TW_SR_GCALL_DATA_NACK       0x98
00234     #define TW_SR_STOP                  0xA0
00235     #define TW_NO_INFO                  0xF8
00236     #define TW_BUS_ERROR                0x00
00237     
00238     //#define _MMIO_BYTE(mem_addr) (*(volatile uint8_t *)(mem_addr))
00239     //#define _SFR_BYTE(sfr) _MMIO_BYTE(_SFR_ADDR(sfr))
00240     
00241     #ifndef sbi // set bit
00242         #define sbi(sfr, bit) (_SFR_BYTE(sfr) |= _BV(bit))
00243     #endif // sbi
00244     
00245     #ifndef cbi // clear bit
00246         #define cbi(sfr, bit) (_SFR_BYTE(sfr) &= ~_BV(bit))
00247     #endif // cbi
00248     
00249     extern TwoWire Wire;
00250 
00251 #endif // I2CDEV_IMPLEMENTATION == I2CDEV_BUILTIN_NBWIRE
00252 
00253 #endif /* _I2CDEV_H_ */
 All Data Structures Functions Variables