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/platform.h"
00020 #include "hal/gpio_api.h"
00021 
00022 #if defined (DEVICE_I2C) || defined(DOXYGEN_ONLY)
00023 
00024 #include "hal/i2c_api.h"
00025 #include "platform/SingletonPtr.h"
00026 #include "platform/PlatformMutex.h"
00027 #include "platform/NonCopyable.h"
00028 
00029 #if DEVICE_I2C_ASYNCH
00030 #include "platform/CThunk.h"
00031 #include "hal/dma_api.h"
00032 #include "platform/FunctionPointer.h"
00033 #endif
00034 
00035 namespace mbed {
00036 /** \addtogroup drivers */
00037 
00038 /** An I2C Master, used for communicating with I2C slave devices
00039  *
00040  * @note Synchronization level: Thread safe
00041  *
00042  * Example:
00043  * @code
00044  * // Read from I2C slave at address 0x62
00045  *
00046  * #include "mbed.h"
00047  *
00048  * I2C i2c(p28, p27);
00049  *
00050  * int main() {
00051  *     int address = 0x62;
00052  *     char data[2];
00053  *     i2c.read(address, data, 2);
00054  * }
00055  * @endcode
00056  * @ingroup drivers
00057  */
00058 class I2C : private NonCopyable<I2C> {
00059 
00060 public:
00061     enum RxStatus {
00062         NoData,
00063         MasterGeneralCall,
00064         MasterWrite,
00065         MasterRead
00066     };
00067 
00068     enum Acknowledge {
00069         NoACK = 0,
00070         ACK   = 1
00071     };
00072 
00073     /** Create an I2C Master interface, connected to the specified pins
00074      *
00075      *  @param sda I2C data line pin
00076      *  @param scl I2C clock line pin
00077      */
00078     I2C(PinName sda, PinName scl);
00079 
00080     /** Set the frequency of the I2C interface
00081      *
00082      *  @param hz The bus frequency in hertz
00083      */
00084     void frequency(int hz);
00085 
00086     /** Read from an I2C slave
00087      *
00088      * Performs a complete read transaction. The bottom bit of
00089      * the address is forced to 1 to indicate a read.
00090      *
00091      *  @param address 8-bit I2C slave address [ addr | 1 ]
00092      *  @param data Pointer to the byte-array to read data in to
00093      *  @param length Number of bytes to read
00094      *  @param repeated Repeated start, true - don't send stop at end
00095      *
00096      *  @returns
00097      *       0 on success (ack),
00098      *   non-0 on failure (nack)
00099      */
00100     int read(int address, char *data, int length, bool repeated = false);
00101 
00102     /** Read a single byte from the I2C bus
00103      *
00104      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00105      *
00106      *  @returns
00107      *    the byte read
00108      */
00109     int read(int ack);
00110 
00111     /** Write to an I2C slave
00112      *
00113      * Performs a complete write transaction. The bottom bit of
00114      * the address is forced to 0 to indicate a write.
00115      *
00116      *  @param address 8-bit I2C slave address [ addr | 0 ]
00117      *  @param data Pointer to the byte-array data to send
00118      *  @param length Number of bytes to send
00119      *  @param repeated Repeated start, true - do not send stop at end
00120      *
00121      *  @returns
00122      *       0 on success (ack),
00123      *   non-0 on failure (nack)
00124      */
00125     int write(int address, const char *data, int length, bool repeated = false);
00126 
00127     /** Write single byte out on the I2C bus
00128      *
00129      *  @param data data to write out on bus
00130      *
00131      *  @returns
00132      *    '0' - NAK was received
00133      *    '1' - ACK was received,
00134      *    '2' - timeout
00135      */
00136     int write(int data);
00137 
00138     /** Creates a start condition on the I2C bus
00139      */
00140 
00141     void start(void);
00142 
00143     /** Creates a stop condition on the I2C bus
00144      */
00145     void stop(void);
00146 
00147     /** Acquire exclusive access to this I2C bus
00148      */
00149     virtual void lock(void);
00150 
00151     /** Release exclusive access to this I2C bus
00152      */
00153     virtual void unlock(void);
00154 
00155     virtual ~I2C()
00156     {
00157         // Do nothing
00158     }
00159 
00160 #if DEVICE_I2C_ASYNCH
00161 
00162     /** Start non-blocking I2C transfer.
00163      *
00164      * This function locks the deep sleep until any event has occurred
00165      *
00166      * @param address   8/10 bit I2C slave address
00167      * @param tx_buffer The TX buffer with data to be transfered
00168      * @param tx_length The length of TX buffer in bytes
00169      * @param rx_buffer The RX buffer which is used for received data
00170      * @param rx_length The length of RX buffer in bytes
00171      * @param event     The logical OR of events to modify
00172      * @param callback  The event callback function
00173      * @param repeated Repeated start, true - do not send stop at end
00174      * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
00175      */
00176     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);
00177 
00178     /** Abort the on-going I2C transfer
00179      */
00180     void abort_transfer();
00181 
00182 protected:
00183     /** Lock deep sleep only if it is not yet locked */
00184     void lock_deep_sleep();
00185 
00186     /** Unlock deep sleep only if it has been locked */
00187     void unlock_deep_sleep();
00188 
00189     void irq_handler_asynch(void);
00190     event_callback_t _callback;
00191     CThunk<I2C>  _irq;
00192     DMAUsage _usage;
00193     bool _deep_sleep_locked;
00194 #endif
00195 
00196 protected:
00197     void aquire();
00198 
00199     i2c_t _i2c;
00200     static I2C  *_owner;
00201     int    _hz;
00202     static SingletonPtr<PlatformMutex>  _mutex;
00203     PinName _sda;
00204     PinName _scl;
00205 
00206 private:
00207     /** Recover I2C bus, when stuck with SDA low
00208      *  @note : Initialization of I2C bus is required after this API.
00209      *
00210      *  @param sda I2C data line pin
00211      *  @param scl I2C clock line pin
00212      *
00213      * @returns:
00214      *    '0' - Successfully recovered
00215      *    'I2C_ERROR_BUS_BUSY' - In case of failure
00216      *
00217      */
00218     int recover(PinName sda, PinName scl);
00219 };
00220 
00221 } // namespace mbed
00222 
00223 #endif
00224 
00225 #endif