I2C.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_I2C_H
00017 #define MBED_I2C_H
00018 
00019 #include "platform.h"
00020 
00021 #if DEVICE_I2C
00022 
00023 #include "i2c_api.h"
00024 
00025 namespace mbed {
00026 
00027 /** An I2C Master, used for communicating with I2C slave devices
00028  *
00029  * Example:
00030  * @code
00031  * // Read from I2C slave at address 0x62
00032  *
00033  * #include "mbed.h"
00034  *
00035  * I2C i2c(p28, p27);
00036  *
00037  * int main() {
00038  *     int address = 0x62;
00039  *     char data[2];
00040  *     i2c.read(address, data, 2);
00041  * }
00042  * @endcode
00043  */
00044 class I2C {
00045 
00046 public:
00047     enum RxStatus {
00048         NoData,
00049         MasterGeneralCall,
00050         MasterWrite,
00051         MasterRead
00052     };
00053 
00054     enum Acknowledge {
00055         NoACK = 0,
00056         ACK   = 1
00057     };
00058 
00059     /** Create an I2C Master interface, connected to the specified pins
00060      *
00061      *  @param sda I2C data line pin
00062      *  @param scl I2C clock line pin
00063      */
00064     I2C(PinName sda, PinName scl);
00065     
00066     ~I2C() {
00067         i2c_free(&_i2c);
00068     }
00069 
00070     /** Set the frequency of the I2C interface
00071      *
00072      *  @param hz The bus frequency in hertz
00073      */
00074     void frequency(int hz);
00075 
00076     /** Read from an I2C slave
00077      *
00078      * Performs a complete read transaction. The bottom bit of
00079      * the address is forced to 1 to indicate a read.
00080      *
00081      *  @param address 8-bit I2C slave address [ addr | 1 ]
00082      *  @param data Pointer to the byte-array to read data in to
00083      *  @param length Number of bytes to read
00084      *  @param repeated Repeated start, true - don't send stop at end
00085      *
00086      *  @returns
00087      *       0 on success (ack),
00088      *   non-0 on failure (nack)
00089      */
00090     int read(int address, char *data, int length, bool repeated = false);
00091 
00092     /** Read a single byte from the I2C bus
00093      *
00094      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00095      *
00096      *  @returns
00097      *    the byte read
00098      */
00099     int read(int ack);
00100 
00101     /** Write to an I2C slave
00102      *
00103      * Performs a complete write transaction. The bottom bit of
00104      * the address is forced to 0 to indicate a write.
00105      *
00106      *  @param address 8-bit I2C slave address [ addr | 0 ]
00107      *  @param data Pointer to the byte-array data to send
00108      *  @param length Number of bytes to send
00109      *  @param repeated Repeated start, true - do not send stop at end
00110      *
00111      *  @returns
00112      *       0 on success (ack),
00113      *   non-0 on failure (nack)
00114      */
00115     int write(int address, const char *data, int length, bool repeated = false);
00116 
00117     /** Write single byte out on the I2C bus
00118      *
00119      *  @param data data to write out on bus
00120      *
00121      *  @returns
00122      *    '1' if an ACK was received,
00123      *    '0' otherwise
00124      */
00125     int write(int data);
00126 
00127     /** Creates a start condition on the I2C bus
00128      */
00129 
00130     void start(void);
00131 
00132     /** Creates a stop condition on the I2C bus
00133      */
00134     void stop(void);
00135 
00136 protected:
00137     void aquire();
00138 
00139     i2c_t _i2c;
00140     static I2C  *_owner;
00141     int         _hz;
00142 };
00143 
00144 } // namespace mbed
00145 
00146 #endif
00147 
00148 #endif