Diff: drivers/I2C.h

Revision:

189:f392fc9709a3

Parent:

188:bcfe06ba3d64

--- a/drivers/I2C.h	Thu Nov 08 11:46:34 2018 +0000
+++ b/drivers/I2C.h	Wed Feb 20 22:31:08 2019 +0000
@@ -1,5 +1,6 @@
 /* mbed Microcontroller Library
  * Copyright (c) 2006-2015 ARM Limited
+ * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,8 +18,9 @@
 #define MBED_I2C_H
 
 #include "platform/platform.h"
+#include "hal/gpio_api.h"
 
-#if defined (DEVICE_I2C) || defined(DOXYGEN_ONLY)
+#if DEVICE_I2C || defined(DOXYGEN_ONLY)
 
 #include "hal/i2c_api.h"
 #include "platform/SingletonPtr.h"
@@ -40,16 +42,32 @@
  *
  * Example:
  * @code
- * // Read from I2C slave at address 0x62
- *
+ * Read temperature from LM75BD
  * #include "mbed.h"
- *
- * I2C i2c(p28, p27);
+ * I2C i2c(I2C_SDA , I2C_SCL);
+ * const int addr7bit = 0x48;      // 7-bit I2C address
+ * const int addr8bit = 0x48 << 1; // 8-bit I2C address, 0x90
  *
  * int main() {
- *     int address = 0x62;
- *     char data[2];
- *     i2c.read(address, data, 2);
+ *     char cmd[2];
+ *     while (1) {
+ *         cmd[0] = 0x01;
+ *         cmd[1] = 0x00;
+ *
+ *         // read and write takes the 8-bit version of the address.
+ *         // set up configuration register (at 0x01)
+ *         i2c.write(addr8bit, cmd, 2);
+ *
+ *         wait(0.5);
+ *
+ *         // read temperature register
+ *         cmd[0] = 0x00;
+ *         i2c.write(addr8bit, cmd, 1);
+ *         i2c.read( addr8bit, cmd, 2);
+ *
+ *         float tmp = (float((cmd[0]<<8)|cmd[1]) / 256.0);
+ *         printf("Temp = %.2f\n", tmp);
+ *   }
  * }
  * @endcode
  * @ingroup drivers
@@ -91,10 +109,11 @@
      *  @param data Pointer to the byte-array to read data in to
      *  @param length Number of bytes to read
      *  @param repeated Repeated start, true - don't send stop at end
+     *         default value is false.
      *
      *  @returns
      *       0 on success (ack),
-     *   non-0 on failure (nack)
+     *       nonzero on failure (nack)
      */
     int read(int address, char *data, int length, bool repeated = false);
 
@@ -116,10 +135,11 @@
      *  @param data Pointer to the byte-array data to send
      *  @param length Number of bytes to send
      *  @param repeated Repeated start, true - do not send stop at end
+     *         default value is false.
      *
      *  @returns
      *       0 on success (ack),
-     *   non-0 on failure (nack)
+     *       nonzero on failure (nack)
      */
     int write(int address, const char *data, int length, bool repeated = false);
 
@@ -136,7 +156,6 @@
 
     /** Creates a start condition on the I2C bus
      */
-
     void start(void);
 
     /** Creates a stop condition on the I2C bus
@@ -158,26 +177,29 @@
 
 #if DEVICE_I2C_ASYNCH
 
-    /** Start non-blocking I2C transfer.
+    /** Start nonblocking I2C transfer.
      *
      * This function locks the deep sleep until any event has occurred
      *
      * @param address   8/10 bit I2C slave address
      * @param tx_buffer The TX buffer with data to be transferred
      * @param tx_length The length of TX buffer in bytes
-     * @param rx_buffer The RX buffer which is used for received data
+     * @param rx_buffer The RX buffer, which is used for received data
      * @param rx_length The length of RX buffer in bytes
      * @param event     The logical OR of events to modify
      * @param callback  The event callback function
      * @param repeated Repeated start, true - do not send stop at end
-     * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
+     *        default value is false.
+     *
+     * @returns Zero if the transfer has started, or -1 if I2C peripheral is busy
      */
     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);
 
-    /** Abort the on-going I2C transfer
+    /** Abort the ongoing I2C transfer
      */
     void abort_transfer();
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     /** Lock deep sleep only if it is not yet locked */
     void lock_deep_sleep();
@@ -191,14 +213,33 @@
     DMAUsage _usage;
     bool _deep_sleep_locked;
 #endif
+#endif
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     void aquire();
 
     i2c_t _i2c;
     static I2C  *_owner;
-    int         _hz;
+    int    _hz;
     static SingletonPtr<PlatformMutex> _mutex;
+    PinName _sda;
+    PinName _scl;
+
+private:
+    /** Recover I2C bus, when stuck with SDA low
+     *  @note : Initialization of I2C bus is required after this API.
+     *
+     *  @param sda I2C data line pin
+     *  @param scl I2C clock line pin
+     *
+     * @returns
+     *    '0' - Successfully recovered
+     *    'I2C_ERROR_BUS_BUSY' - In case of failure
+     *
+     */
+    int recover(PinName sda, PinName scl);
+#endif
 };
 
 } // namespace mbed