I2Cdev.cpp
Go to the documentation of this file.
00001 // I2Cdev library collection - Main I2C device class
00002 // Abstracts bit and byte I2C R/W functions into a convenient class
00003 // 6/9/2012 by Jeff Rowberg <jeff@rowberg.net>
00004 //
00005 // Changelog:
00006 //     2012-06-09 - fix major issue with reading > 32 bytes at a time with Arduino Wire
00007 //                - add compiler warnings when using outdated or IDE or limited I2Cdev implementation
00008 //     2011-11-01 - fix write*Bits mask calculation (thanks sasquatch @ Arduino forums)
00009 //     2011-10-03 - added automatic Arduino version detection for ease of use
00010 //     2011-10-02 - added Gene Knight's NBWire TwoWire class implementation with small modifications
00011 //     2011-08-31 - added support for Arduino 1.0 Wire library (methods are different from 0.x)
00012 //     2011-08-03 - added optional timeout parameter to read* methods to easily change from default
00013 //     2011-08-02 - added support for 16-bit registers
00014 //                - fixed incorrect Doxygen comments on some methods
00015 //                - added timeout value for read operations (thanks mem @ Arduino forums)
00016 //     2011-07-30 - changed read/write function structures to return success or byte counts
00017 //                - made all methods static for multi-device memory savings
00018 //     2011-07-28 - initial release
00019 
00020 /* ============================================
00021 I2Cdev device library code is placed under the MIT license
00022 Copyright (c) 2012 Jeff Rowberg
00023 
00024 Permission is hereby granted, free of charge, to any person obtaining a copy
00025 of this software and associated documentation files (the "Software"), to deal
00026 in the Software without restriction, including without limitation the rights
00027 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00028 copies of the Software, and to permit persons to whom the Software is
00029 furnished to do so, subject to the following conditions:
00030 
00031 The above copyright notice and this permission notice shall be included in
00032 all copies or substantial portions of the Software.
00033 
00034 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00035 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00036 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00037 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00038 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00039 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00040 THE SOFTWARE.
00041 ===============================================
00042 */
00043 
00044 #include "I2Cdev.h"
00045 //#define I2CDEV_SERIAL_DEBUG
00048 I2Cdev::I2Cdev() {
00049 }
00050 
00059 int8_t I2Cdev::readBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t *data, uint16_t timeout) {
00060     uint8_t b;
00061     uint8_t count = readByte(devAddr, regAddr, &b, timeout);
00062     *data = b & (1 << bitNum);
00063     return count;
00064 }
00065 
00074 /*
00075 int8_t I2Cdev::readBitW(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint16_t *data, uint16_t timeout) {
00076     uint16_t b;
00077     uint8_t count = readWord(devAddr, regAddr, &b, timeout);
00078     *data = b & (1 << bitNum);
00079     return count;
00080 }
00081 */
00082 
00092 int8_t I2Cdev::readBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t *data, uint16_t timeout) {
00093     // 01101001 read byte
00094     // 76543210 bit numbers
00095     //    xxx   args: bitStart=4, length=3
00096     //    010   masked
00097     //   -> 010 shifted
00098     uint8_t count, b;
00099     if ((count = readByte(devAddr, regAddr, &b, timeout)) != 0) {
00100         uint8_t mask = ((1 << length) - 1) << (bitStart - length + 1);
00101         b &= mask;
00102         b >>= (bitStart - length + 1);
00103         *data = b;
00104     }
00105     return count;
00106 }
00107 
00117  /*
00118 int8_t I2Cdev::readBitsW(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint16_t *data, uint16_t timeout)
00119 {
00120     // 1101011001101001 read byte
00121     // fedcba9876543210 bit numbers
00122     //    xxx           args: bitStart=12, length=3
00123     //    010           masked
00124     //           -> 010 shifted
00125     uint16_t w;
00126     
00127     uint8_t count = readWord(devAddr, regAddr, &w, timeout);
00128     
00129     if (count != 0) {
00130         uint16_t mask = ((1 << length) - 1) << (bitStart - length + 1);
00131         w &= mask;
00132         w >>= (bitStart - length + 1);
00133         *data = w;
00134     }
00135     
00136     return count;
00137 }
00138 */
00146 int8_t I2Cdev::readByte(uint8_t devAddr, uint8_t regAddr, uint8_t *data, uint16_t timeout)
00147 {
00148     return readBytes(devAddr, regAddr, 1, data, timeout);
00149 }
00150 
00158 /*
00159 int8_t I2Cdev::readWord(uint8_t devAddr, uint8_t regAddr, uint16_t *data, uint16_t timeout)
00160 {
00161     return readWords(devAddr, regAddr, 1, data, timeout);
00162 }
00163 */
00172 int8_t I2Cdev::readBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t *data, uint16_t timeout) 
00173 {
00174 #ifdef I2CDEV_SERIAL_DEBUG
00175     Serial.print("I2C (0x");
00176     Serial.print(devAddr, HEX);
00177     Serial.print(") reading ");
00178     Serial.print(length, DEC);
00179     Serial.print(" bytes from 0x");
00180     Serial.print(regAddr, HEX);
00181     Serial.print("...");
00182 #endif
00183 
00184     int8_t count = 0;
00185     uint32_t t1 = millis();
00186 
00187     // Arduino v1.0.1+, Wire library
00188     // Adds official support for repeated start condition, yay!
00189 
00190     // I2C/TWI subsystem uses internal buffer that breaks with large data requests
00191     // so if user requests more than BUFFER_LENGTH bytes, we have to do it in
00192     // smaller chunks instead of all at once
00193     for (uint8_t k = 0; k < length; k += min(length, BUFFER_LENGTH)) {
00194         Wire.beginTransmission(devAddr);
00195         Wire.write(regAddr);
00196         Wire.endTransmission();
00197         Wire.beginTransmission(devAddr);
00198         Wire.requestFrom(devAddr, (uint8_t)min(length - k, BUFFER_LENGTH));
00199         
00200         while (Wire.available() && (timeout == 0 || millis() - t1 < timeout)) {
00201             data[count++] = Wire.read();
00202             
00203 #ifdef I2CDEV_SERIAL_DEBUG
00204             Serial.print(data[count], HEX);
00205             if (count < length) {
00206                 Serial.print(" ");
00207             }                
00208 #endif
00209         }
00210         
00211         Wire.endTransmission();
00212     }
00213 
00214     // check for timeout
00215     if (timeout > 0 && millis() - t1 >= timeout && count < length) {
00216         count = -1; // timeout
00217     }
00218     
00219     #ifdef I2CDEV_SERIAL_DEBUG
00220         Serial.print(". Done (");
00221         Serial.print(count, DEC);
00222         Serial.println(" read).");
00223     #endif
00224 
00225     return count;
00226 }
00227 
00236 /*
00237 int8_t I2Cdev::readWords(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint16_t *data, uint16_t timeout) 
00238 {
00239 #ifdef I2CDEV_SERIAL_DEBUG
00240     Serial.print("I2C (0x");
00241     Serial.print(devAddr, HEX);
00242     Serial.print(") reading ");
00243     Serial.print(length, DEC);
00244     Serial.print(" words from 0x");
00245     Serial.print(regAddr, HEX);
00246     Serial.print("...");
00247 #endif
00248 
00249     int8_t count = 0;
00250     uint32_t t1 = millis();
00251 
00252     // Arduino v1.0.1+, Wire library
00253     // Adds official support for repeated start condition, yay!
00254 
00255     // I2C/TWI subsystem uses internal buffer that breaks with large data requests
00256     // so if user requests more than BUFFER_LENGTH bytes, we have to do it in
00257     // smaller chunks instead of all at once
00258     for (uint8_t k = 0; k < length * 2; k += min(length * 2, BUFFER_LENGTH)) {
00259         Wire.beginTransmission(devAddr);
00260         Wire.write(regAddr);
00261         Wire.endTransmission();
00262         Wire.beginTransmission(devAddr);
00263         Wire.requestFrom(devAddr, (uint8_t)(length * 2)); // length=words, this wants bytes
00264         
00265         bool msb = true; // starts with MSB, then LSB
00266         
00267         while (Wire.available() && count < length && (timeout == 0 || millis() - t1 < timeout)) {
00268             if (msb) {
00269                 // first byte is bits 15-8 (MSb=15)
00270                 data[count] = Wire.read() << 8;
00271             } 
00272             else {
00273                 // second byte is bits 7-0 (LSb=0)
00274                 data[count++] |= Wire.read();
00275                 
00276 #ifdef I2CDEV_SERIAL_DEBUG
00277                 Serial.print(data[count], HEX);
00278                 if (count < length) {
00279                     Serial.print(" ");
00280                 }
00281 #endif
00282             }
00283 
00284             msb = !msb;
00285         }
00286         
00287         Wire.endTransmission();
00288     }
00289 
00290     if (timeout > 0 && millis() - t1 >= timeout && count < length) {
00291         count = -1; // timeout
00292     }
00293     
00294 #ifdef I2CDEV_SERIAL_DEBUG
00295     Serial.print(". Done (");
00296     Serial.print(count, DEC);
00297     Serial.println(" read).");
00298 #endif
00299     
00300     return count;
00301 }
00302 */
00303 
00311 bool I2Cdev::writeBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t data) {
00312     uint8_t b;
00313     readByte(devAddr, regAddr, &b);
00314     b = (data != 0) ? (b | (1 << bitNum)) : (b & ~(1 << bitNum));
00315     return writeByte(devAddr, regAddr, b);
00316 }
00317 
00325 /*
00326 bool I2Cdev::writeBitW(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint16_t data) {
00327     uint16_t w;
00328     readWord(devAddr, regAddr, &w);
00329     w = (data != 0) ? (w | (1 << bitNum)) : (w & ~(1 << bitNum));
00330     return writeWord(devAddr, regAddr, w);
00331 }
00332 */
00333 
00342 bool I2Cdev::writeBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t data)
00343 {
00344     //      010 value to write
00345     // 76543210 bit numbers
00346     //    xxx   args: bitStart=4, length=3
00347     // 00011100 mask byte
00348     // 10101111 original value (sample)
00349     // 10100011 original & ~mask
00350     // 10101011 masked | value
00351     uint8_t b;
00352 
00353     if (readByte(devAddr, regAddr, &b) != 0) {
00354         uint8_t mask = ((1 << length) - 1) << (bitStart - length + 1);
00355         data <<= (bitStart - length + 1); // shift data into correct position
00356         data &= mask; // zero all non-important bits in data
00357         b &= ~(mask); // zero all important bits in existing byte
00358         b |= data; // combine data with existing byte
00359 
00360         return writeByte(devAddr, regAddr, b);
00361     }
00362 
00363     return false;
00364 }
00365 
00374 /*
00375 bool I2Cdev::writeBitsW(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint16_t data)
00376 {
00377     //              010 value to write
00378     // fedcba9876543210 bit numbers
00379     //    xxx           args: bitStart=12, length=3
00380     // 0001110000000000 mask byte
00381     // 1010111110010110 original value (sample)
00382     // 1010001110010110 original & ~mask
00383     // 1010101110010110 masked | value
00384     uint16_t w;
00385 
00386     if (readWord(devAddr, regAddr, &w) != 0) {
00387         uint8_t mask = ((1 << length) - 1) << (bitStart - length + 1);
00388         data <<= (bitStart - length + 1); // shift data into correct position
00389         data &= mask; // zero all non-important bits in data
00390         w &= ~(mask); // zero all important bits in existing word
00391         w |= data; // combine data with existing word
00392         
00393         return writeWord(devAddr, regAddr, w);
00394     } 
00395 
00396     return false;
00397 }
00398 */
00405 bool I2Cdev::writeByte(uint8_t devAddr, uint8_t regAddr, uint8_t data)
00406 {
00407     return writeBytes(devAddr, regAddr, 1, &data);
00408 }
00409 
00416 bool I2Cdev::writeWord(uint8_t devAddr, uint8_t regAddr, uint16_t data)
00417 {
00418     return writeWords(devAddr, regAddr, 1, &data);
00419 }
00420 
00428 bool I2Cdev::writeBytes(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint8_t* data)
00429 {
00430 #ifdef I2CDEV_SERIAL_DEBUG
00431     Serial.print("I2C (0x");
00432     Serial.print(devAddr, HEX);
00433     Serial.print(") writing ");
00434     Serial.print(length, DEC);
00435     Serial.print(" bytes to 0x");
00436     Serial.print(regAddr, HEX);
00437     Serial.print("...");
00438 #endif
00439 
00440     uint8_t status = 0;
00441 
00442     Wire.beginTransmission(devAddr);
00443     Wire.write((uint8_t) regAddr); // send address
00444 
00445     for (uint8_t i = 0; i < length; i++) {
00446         Wire.write((uint8_t) data[i]);
00447 
00448 #ifdef I2CDEV_SERIAL_DEBUG
00449         Serial.print(data[i], HEX);
00450         if (i + 1 < length) Serial.print(" ");
00451 #endif
00452     }
00453 
00454     status = Wire.endTransmission();
00455 
00456 #ifdef I2CDEV_SERIAL_DEBUG
00457     Serial.println(". Done.");
00458 #endif
00459 
00460 #ifdef __SAM3X8E__
00461     return status > 0;
00462 #else
00463     return status == 0;
00464 #endif
00465 }
00466 
00474 bool I2Cdev::writeWords(uint8_t devAddr, uint8_t regAddr, uint8_t length, uint16_t* data)
00475 {
00476 #ifdef I2CDEV_SERIAL_DEBUG
00477     Serial.print("I2C (0x");
00478     Serial.print(devAddr, HEX);
00479     Serial.print(") writing ");
00480     Serial.print(length, DEC);
00481     Serial.print(" words to 0x");
00482     Serial.print(regAddr, HEX);
00483     Serial.print("...");
00484 #endif
00485 
00486     uint8_t status = 0;
00487 
00488     Wire.beginTransmission(devAddr);
00489     Wire.write(regAddr); // send address
00490 
00491     for (uint8_t i = 0; i < length * 2; i++) {
00492         Wire.write((uint8_t)(data[i++] >> 8)); // send MSB
00493         Wire.write((uint8_t)data[i]);          // send LSB
00494 
00495 #ifdef I2CDEV_SERIAL_DEBUG
00496         Serial.print(data[i], HEX);
00497         if (i + 1 < length) Serial.print(" ");
00498 #endif
00499     }
00500 
00501     status = Wire.endTransmission();
00502 
00503 #ifdef I2CDEV_SERIAL_DEBUG
00504     Serial.println(". Done.");
00505 #endif
00506 
00507 #ifdef __SAM3X8E__
00508     return status > 0;
00509 #else
00510     return status == 0;
00511 #endif
00512 }
00513 
00517 uint16_t I2Cdev::readTimeout = I2CDEV_DEFAULT_READ_TIMEOUT;
00518 
00519 


segbot_firmware
Author(s): Jose Bigio, Jack O'Quin, Tim Eckel (NewPing library)
autogenerated on Fri Aug 28 2015 13:02:53