I2C.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 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/Callback.h"
00034 #endif
00035 
00036 namespace mbed {
00037 /** \defgroup drivers-public-api-i2c I2C
00038  * \ingroup drivers-public-api
00039  */
00040 
00041 /**
00042  * \defgroup drivers_I2C I2C class
00043  * \ingroup drivers-public-api-i2c
00044  * @{
00045  */
00046 
00047 /** An I2C Master, used for communicating with I2C slave devices
00048  *
00049  * @note Synchronization level: Thread safe
00050  *
00051  * Example:
00052  * @code
00053  * Read temperature from LM75BD
00054  * #include "mbed.h"
00055  * I2C i2c(I2C_SDA , I2C_SCL);
00056  * const int addr7bit = 0x48;      // 7-bit I2C address
00057  * const int addr8bit = 0x48 << 1; // 8-bit I2C address, 0x90
00058  *
00059  * int main() {
00060  *     char cmd[2];
00061  *     while (1) {
00062  *         cmd[0] = 0x01;
00063  *         cmd[1] = 0x00;
00064  *
00065  *         // read and write takes the 8-bit version of the address.
00066  *         // set up configuration register (at 0x01)
00067  *         i2c.write(addr8bit, cmd, 2);
00068  *
00069  *         wait(0.5);
00070  *
00071  *         // read temperature register
00072  *         cmd[0] = 0x00;
00073  *         i2c.write(addr8bit, cmd, 1);
00074  *         i2c.read( addr8bit, cmd, 2);
00075  *
00076  *         float tmp = (float((cmd[0]<<8)|cmd[1]) / 256.0);
00077  *         printf("Temp = %.2f\n", tmp);
00078  *   }
00079  * }
00080  * @endcode
00081  */
00082 class I2C : private NonCopyable<I2C> {
00083 
00084 public:
00085     enum RxStatus {
00086         NoData,
00087         MasterGeneralCall,
00088         MasterWrite,
00089         MasterRead
00090     };
00091 
00092     enum Acknowledge {
00093         NoACK = 0,
00094         ACK   = 1
00095     };
00096 
00097     /** Create an I2C Master interface, connected to the specified pins
00098      *
00099      *  @param sda I2C data line pin
00100      *  @param scl I2C clock line pin
00101      */
00102     I2C(PinName sda, PinName scl);
00103 
00104     /** Create an I2C Master interface, connected to the specified pins
00105      *
00106      *  @param static_pinmap reference to structure which holds static pinmap.
00107      */
00108     I2C(const i2c_pinmap_t &static_pinmap);
00109     I2C(const i2c_pinmap_t &&) = delete; // prevent passing of temporary objects
00110 
00111     /** Set the frequency of the I2C interface
00112      *
00113      *  @param hz The bus frequency in hertz
00114      */
00115     void frequency(int hz);
00116 
00117     /** Read from an I2C slave
00118      *
00119      * Performs a complete read transaction. The bottom bit of
00120      * the address is forced to 1 to indicate a read.
00121      *
00122      *  @param address 8-bit I2C slave address [ addr | 1 ]
00123      *  @param data Pointer to the byte-array to read data in to
00124      *  @param length Number of bytes to read
00125      *  @param repeated Repeated start, true - don't send stop at end
00126      *         default value is false.
00127      *
00128      *  @returns
00129      *       0 on success (ack),
00130      *       nonzero on failure (nack)
00131      */
00132     int read(int address, char *data, int length, bool repeated = false);
00133 
00134     /** Read a single byte from the I2C bus
00135      *
00136      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00137      *
00138      *  @returns
00139      *    the byte read
00140      */
00141     int read(int ack);
00142 
00143     /** Write to an I2C slave
00144      *
00145      * Performs a complete write transaction. The bottom bit of
00146      * the address is forced to 0 to indicate a write.
00147      *
00148      *  @param address 8-bit I2C slave address [ addr | 0 ]
00149      *  @param data Pointer to the byte-array data to send
00150      *  @param length Number of bytes to send
00151      *  @param repeated Repeated start, true - do not send stop at end
00152      *         default value is false.
00153      *
00154      *  @returns
00155      *       0 on success (ack),
00156      *       nonzero on failure (nack)
00157      */
00158     int write(int address, const char *data, int length, bool repeated = false);
00159 
00160     /** Write single byte out on the I2C bus
00161      *
00162      *  @param data data to write out on bus
00163      *
00164      *  @returns
00165      *    '0' - NAK was received
00166      *    '1' - ACK was received,
00167      *    '2' - timeout
00168      */
00169     int write(int data);
00170 
00171     /** Creates a start condition on the I2C bus
00172      */
00173     void start(void);
00174 
00175     /** Creates a stop condition on the I2C bus
00176      */
00177     void stop(void);
00178 
00179     /** Acquire exclusive access to this I2C bus
00180      */
00181     virtual void lock(void);
00182 
00183     /** Release exclusive access to this I2C bus
00184      */
00185     virtual void unlock(void);
00186 
00187     virtual ~I2C()
00188     {
00189         // Do nothing
00190     }
00191 
00192 #if DEVICE_I2C_ASYNCH
00193 
00194     /** Start nonblocking I2C transfer.
00195      *
00196      * This function locks the deep sleep until any event has occurred
00197      *
00198      * @param address   8/10 bit I2C slave address
00199      * @param tx_buffer The TX buffer with data to be transferred
00200      * @param tx_length The length of TX buffer in bytes
00201      * @param rx_buffer The RX buffer, which is used for received data
00202      * @param rx_length The length of RX buffer in bytes
00203      * @param event     The logical OR of events to modify
00204      * @param callback  The event callback function
00205      * @param repeated Repeated start, true - do not send stop at end
00206      *        default value is false.
00207      *
00208      * @returns Zero if the transfer has started, or -1 if I2C peripheral is busy
00209      */
00210     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);
00211 
00212     /** Abort the ongoing I2C transfer
00213      */
00214     void abort_transfer();
00215 
00216 #if !defined(DOXYGEN_ONLY)
00217 protected:
00218     /** Lock deep sleep only if it is not yet locked */
00219     void lock_deep_sleep();
00220 
00221     /** Unlock deep sleep only if it has been locked */
00222     void unlock_deep_sleep();
00223 
00224     void irq_handler_asynch(void);
00225     event_callback_t _callback;
00226     CThunk<I2C>  _irq;
00227     DMAUsage _usage;
00228     bool _deep_sleep_locked;
00229 #endif
00230 #endif
00231 
00232 #if !defined(DOXYGEN_ONLY)
00233 protected:
00234     void aquire();
00235 
00236     i2c_t _i2c;
00237     static I2C  *_owner;
00238     int    _hz;
00239     static SingletonPtr<PlatformMutex>  _mutex;
00240     PinName _sda;
00241     PinName _scl;
00242 
00243 private:
00244     /** Recover I2C bus, when stuck with SDA low
00245      *  @note : Initialization of I2C bus is required after this API.
00246      *
00247      *  @param sda I2C data line pin
00248      *  @param scl I2C clock line pin
00249      *
00250      * @returns
00251      *    '0' - Successfully recovered
00252      *    'I2C_ERROR_BUS_BUSY' - In case of failure
00253      *
00254      */
00255     int recover(PinName sda, PinName scl);
00256 #endif
00257 };
00258 
00259 /** @}*/
00260 
00261 } // namespace mbed
00262 
00263 #endif
00264 
00265 #endif