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