I2C.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 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 #include "SingletonPtr.h"
00025 #include "PlatformMutex.h"
00026 
00027 #if DEVICE_I2C_ASYNCH
00028 #include "CThunk.h"
00029 #include "dma_api.h"
00030 #include "FunctionPointer.h"
00031 #endif
00032 
00033 namespace mbed {
00034 
00035 /** An I2C Master, used for communicating with I2C slave devices
00036  *
00037  * @Note Synchronization level: Thread safe
00038  *
00039  * Example:
00040  * @code
00041  * // Read from I2C slave at address 0x62
00042  *
00043  * #include "mbed.h"
00044  *
00045  * I2C i2c(p28, p27);
00046  *
00047  * int main() {
00048  *     int address = 0x62;
00049  *     char data[2];
00050  *     i2c.read(address, data, 2);
00051  * }
00052  * @endcode
00053  */
00054 class I2C {
00055 
00056 public:
00057     enum RxStatus {
00058         NoData,
00059         MasterGeneralCall,
00060         MasterWrite,
00061         MasterRead
00062     };
00063 
00064     enum Acknowledge {
00065         NoACK = 0,
00066         ACK   = 1
00067     };
00068 
00069     /** Create an I2C Master interface, connected to the specified pins
00070      *
00071      *  @param sda I2C data line pin
00072      *  @param scl I2C clock line pin
00073      */
00074     I2C(PinName sda, PinName scl);
00075 
00076     /** Set the frequency of the I2C interface
00077      *
00078      *  @param hz The bus frequency in hertz
00079      */
00080     void frequency(int hz);
00081 
00082     /** Read from an I2C slave
00083      *
00084      * Performs a complete read transaction. The bottom bit of
00085      * the address is forced to 1 to indicate a read.
00086      *
00087      *  @param address 8-bit I2C slave address [ addr | 1 ]
00088      *  @param data Pointer to the byte-array to read data in to
00089      *  @param length Number of bytes to read
00090      *  @param repeated Repeated start, true - don't send stop at end
00091      *
00092      *  @returns
00093      *       0 on success (ack),
00094      *   non-0 on failure (nack)
00095      */
00096     int read(int address, char *data, int length, bool repeated = false);
00097 
00098     /** Read a single byte from the I2C bus
00099      *
00100      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00101      *
00102      *  @returns
00103      *    the byte read
00104      */
00105     int read(int ack);
00106 
00107     /** Write to an I2C slave
00108      *
00109      * Performs a complete write transaction. The bottom bit of
00110      * the address is forced to 0 to indicate a write.
00111      *
00112      *  @param address 8-bit I2C slave address [ addr | 0 ]
00113      *  @param data Pointer to the byte-array data to send
00114      *  @param length Number of bytes to send
00115      *  @param repeated Repeated start, true - do not send stop at end
00116      *
00117      *  @returns
00118      *       0 on success (ack),
00119      *   non-0 on failure (nack)
00120      */
00121     int write(int address, const char *data, int length, bool repeated = false);
00122 
00123     /** Write single byte out on the I2C bus
00124      *
00125      *  @param data data to write out on bus
00126      *
00127      *  @returns
00128      *    '1' if an ACK was received,
00129      *    '0' otherwise
00130      */
00131     int write(int data);
00132 
00133     /** Creates a start condition on the I2C bus
00134      */
00135 
00136     void start(void);
00137 
00138     /** Creates a stop condition on the I2C bus
00139      */
00140     void stop(void);
00141 
00142     /** Acquire exclusive access to this I2C bus
00143      */
00144     virtual void lock(void);
00145 
00146     /** Release exclusive access to this I2C bus
00147      */
00148     virtual void unlock(void);
00149 
00150     virtual ~I2C() {
00151         // Do nothing
00152     }
00153 
00154 #if DEVICE_I2C_ASYNCH
00155 
00156     /** Start non-blocking I2C transfer.
00157      *
00158      * @param address   8/10 bit I2c slave address
00159      * @param tx_buffer The TX buffer with data to be transfered
00160      * @param tx_length The length of TX buffer in bytes
00161      * @param rx_buffer The RX buffer which is used for received data
00162      * @param rx_length The length of RX buffer in bytes
00163      * @param event     The logical OR of events to modify
00164      * @param callback  The event callback function
00165      * @param repeated Repeated start, true - do not send stop at end
00166      * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
00167      */
00168     int transfer(int address, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, const event_callback_t& callback, int event = I2C_EVENT_TRANSFER_COMPLETE, bool repeated = false);
00169 
00170     /** Abort the on-going I2C transfer
00171      */
00172     void abort_transfer();
00173 protected:
00174     void irq_handler_asynch(void);
00175     event_callback_t _callback;
00176     CThunk<I2C>  _irq;
00177     DMAUsage _usage;
00178 #endif
00179 
00180 protected:
00181     void aquire();
00182 
00183     i2c_t _i2c;
00184     static I2C  *_owner;
00185     int         _hz;
00186     static SingletonPtr<PlatformMutex>  _mutex;
00187 };
00188 
00189 } // namespace mbed
00190 
00191 #endif
00192 
00193 #endif