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