I2C.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_I2C_H
00018 #define MBED_I2C_H
00019 
00020 #include "platform/platform.h"
00021 #include "hal/gpio_api.h"
00022 
00023 #if DEVICE_I2C || defined(DOXYGEN_ONLY)
00024 
00025 #include "hal/i2c_api.h"
00026 #include "platform/SingletonPtr.h"
00027 #include "platform/PlatformMutex.h"
00028 #include "platform/NonCopyable.h"
00029 
00030 #if DEVICE_I2C_ASYNCH
00031 #include "platform/CThunk.h"
00032 #include "hal/dma_api.h"
00033 #include "platform/FunctionPointer.h"
00034 #endif
00035 
00036 namespace mbed {
00037 /** \addtogroup drivers */
00038 
00039 /** An I2C Master, used for communicating with I2C slave devices
00040  *
00041  * @note Synchronization level: Thread safe
00042  *
00043  * Example:
00044  * @code
00045  * Read temperature from LM75BD
00046  * #include "mbed.h"
00047  * I2C i2c(I2C_SDA , I2C_SCL);
00048  * const int addr7bit = 0x48;      // 7-bit I2C address
00049  * const int addr8bit = 0x48 << 1; // 8-bit I2C address, 0x90
00050  *
00051  * int main() {
00052  *     char cmd[2];
00053  *     while (1) {
00054  *         cmd[0] = 0x01;
00055  *         cmd[1] = 0x00;
00056  *
00057  *         // read and write takes the 8-bit version of the address.
00058  *         // set up configuration register (at 0x01)
00059  *         i2c.write(addr8bit, cmd, 2);
00060  *
00061  *         wait(0.5);
00062  *
00063  *         // read temperature register
00064  *         cmd[0] = 0x00;
00065  *         i2c.write(addr8bit, cmd, 1);
00066  *         i2c.read( addr8bit, cmd, 2);
00067  *
00068  *         float tmp = (float((cmd[0]<<8)|cmd[1]) / 256.0);
00069  *         printf("Temp = %.2f\n", tmp);
00070  *   }
00071  * }
00072  * @endcode
00073  * @ingroup drivers
00074  */
00075 class I2C : private NonCopyable<I2C> {
00076 
00077 public:
00078     enum RxStatus {
00079         NoData,
00080         MasterGeneralCall,
00081         MasterWrite,
00082         MasterRead
00083     };
00084 
00085     enum Acknowledge {
00086         NoACK = 0,
00087         ACK   = 1
00088     };
00089 
00090     /** Create an I2C Master interface, connected to the specified pins
00091      *
00092      *  @param sda I2C data line pin
00093      *  @param scl I2C clock line pin
00094      */
00095     I2C(PinName sda, PinName scl);
00096 
00097     /** Set the frequency of the I2C interface
00098      *
00099      *  @param hz The bus frequency in hertz
00100      */
00101     void frequency(int hz);
00102 
00103     /** Read from an I2C slave
00104      *
00105      * Performs a complete read transaction. The bottom bit of
00106      * the address is forced to 1 to indicate a read.
00107      *
00108      *  @param address 8-bit I2C slave address [ addr | 1 ]
00109      *  @param data Pointer to the byte-array to read data in to
00110      *  @param length Number of bytes to read
00111      *  @param repeated Repeated start, true - don't send stop at end
00112      *         default value is false.
00113      *
00114      *  @returns
00115      *       0 on success (ack),
00116      *       nonzero on failure (nack)
00117      */
00118     int read(int address, char *data, int length, bool repeated = false);
00119 
00120     /** Read a single byte from the I2C bus
00121      *
00122      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00123      *
00124      *  @returns
00125      *    the byte read
00126      */
00127     int read(int ack);
00128 
00129     /** Write to an I2C slave
00130      *
00131      * Performs a complete write transaction. The bottom bit of
00132      * the address is forced to 0 to indicate a write.
00133      *
00134      *  @param address 8-bit I2C slave address [ addr | 0 ]
00135      *  @param data Pointer to the byte-array data to send
00136      *  @param length Number of bytes to send
00137      *  @param repeated Repeated start, true - do not send stop at end
00138      *         default value is false.
00139      *
00140      *  @returns
00141      *       0 on success (ack),
00142      *       nonzero on failure (nack)
00143      */
00144     int write(int address, const char *data, int length, bool repeated = false);
00145 
00146     /** Write single byte out on the I2C bus
00147      *
00148      *  @param data data to write out on bus
00149      *
00150      *  @returns
00151      *    '0' - NAK was received
00152      *    '1' - ACK was received,
00153      *    '2' - timeout
00154      */
00155     int write(int data);
00156 
00157     /** Creates a start condition on the I2C bus
00158      */
00159     void start(void);
00160 
00161     /** Creates a stop condition on the I2C bus
00162      */
00163     void stop(void);
00164 
00165     /** Acquire exclusive access to this I2C bus
00166      */
00167     virtual void lock(void);
00168 
00169     /** Release exclusive access to this I2C bus
00170      */
00171     virtual void unlock(void);
00172 
00173     virtual ~I2C()
00174     {
00175         // Do nothing
00176     }
00177 
00178 #if DEVICE_I2C_ASYNCH
00179 
00180     /** Start nonblocking I2C transfer.
00181      *
00182      * This function locks the deep sleep until any event has occurred
00183      *
00184      * @param address   8/10 bit I2C slave address
00185      * @param tx_buffer The TX buffer with data to be transferred
00186      * @param tx_length The length of TX buffer in bytes
00187      * @param rx_buffer The RX buffer, which is used for received data
00188      * @param rx_length The length of RX buffer in bytes
00189      * @param event     The logical OR of events to modify
00190      * @param callback  The event callback function
00191      * @param repeated Repeated start, true - do not send stop at end
00192      *        default value is false.
00193      *
00194      * @returns Zero if the transfer has started, or -1 if I2C peripheral is busy
00195      */
00196     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);
00197 
00198     /** Abort the ongoing I2C transfer
00199      */
00200     void abort_transfer();
00201 
00202 #if !defined(DOXYGEN_ONLY)
00203 protected:
00204     /** Lock deep sleep only if it is not yet locked */
00205     void lock_deep_sleep();
00206 
00207     /** Unlock deep sleep only if it has been locked */
00208     void unlock_deep_sleep();
00209 
00210     void irq_handler_asynch(void);
00211     event_callback_t _callback;
00212     CThunk<I2C>  _irq;
00213     DMAUsage _usage;
00214     bool _deep_sleep_locked;
00215 #endif
00216 #endif
00217 
00218 #if !defined(DOXYGEN_ONLY)
00219 protected:
00220     void aquire();
00221 
00222     i2c_t _i2c;
00223     static I2C  *_owner;
00224     int    _hz;
00225     static SingletonPtr<PlatformMutex>  _mutex;
00226     PinName _sda;
00227     PinName _scl;
00228 
00229 private:
00230     /** Recover I2C bus, when stuck with SDA low
00231      *  @note : Initialization of I2C bus is required after this API.
00232      *
00233      *  @param sda I2C data line pin
00234      *  @param scl I2C clock line pin
00235      *
00236      * @returns
00237      *    '0' - Successfully recovered
00238      *    'I2C_ERROR_BUS_BUSY' - In case of failure
00239      *
00240      */
00241     int recover(PinName sda, PinName scl);
00242 #endif
00243 };
00244 
00245 } // namespace mbed
00246 
00247 #endif
00248 
00249 #endif