Added I2C driver docs

Author: pedrominatel

Diff for: docs/source/_static/arduino_i2c_master.png

@@ -0,0 +1,343 @@
+###
+I2C
+###
+
+About
+-----
+
+I2C (Inter-Integrated Circuit) / TWI (Two-wire Interface) is a widely used serial communication to connect devices in a short distance. This is one of the most common peripherals used to connect sensors, EEPROMs, RTC, ADC, DAC, displays, OLED, and many other devices and microcontrollers.
+
+This serial communication is considered as a low-speed bus, and multiple devices can be connected on the same two-wires bus, each with a unique 7-bits address (up to 128 devices). These two wires are called SDA (serial data line) and SCL (serial clock line).
+
+.. note:: The SDA and SCL lines require pull-up resistors. See the device datasheet for more details about the resistors' values and the operating voltage.
+
+
+The I2C can be used in two different modes:
+
+* I2C Master Mode
+    * In this mode, the ESP32 generates the clock signal and initiates the communication with the slave device.
+
+.. figure:: ../_static/arduino_i2c_master.png
+    :align: center
+    :width: 720
+    :figclass: align-center
+
+* I2C Slave Mode
+    * The slave mode, the clock is generated by the master device and responds to the master if the destination address is the same as the destination.
+
+.. figure:: ../_static/arduino_i2c_slave.png
+    :align: center
+    :width: 520
+    :figclass: align-center
+
+Arduino-ESP32 I2C API
+---------------------
+
+The ESP32 I2C library is based on the `Arduino Wire Library`_ and implements a few more APIs, describes in this documentation.
+
+I2C Common API
+**************
+
+Here are the common functions used for master and slave modes.
+
+setPins
+^^^^^^^
+
+This function is used to define the ``SDA`` and ``SCL`` pins.
+
+.. code-block:: arduino
+
+    bool setPins(int sdaPin, int sclPin)
+
+* ``sdaPin`` sets the GPIO to be used as the I2C peripheral data line.
+
+* ``sclPin`` sets the GPIO to be used as the I2C peripheral clock line.
+
+setClock
+^^^^^^^^
+
+Use this function to set the bus clock. The default value will be used if this function is not used.
+
+.. code-block:: arduino
+
+    bool setClock(uint32_t);
+
+getClock
+^^^^^^^^
+
+Use this function to get the bus clock.
+
+.. code-block:: arduino
+
+    uint32_t getClock();
+
+setTimeOut
+^^^^^^^^^^
+
+Set the bus timeout given in milliseconds. The default value is 50ms.
+
+.. code-block:: arduino
+
+    void setTimeOut(uint16_t timeOutMillis);
+
+* ``timeOutMillis`` sets the timeout in ms.
+    
+getTimeOut
+^^^^^^^^^^
+
+Get the bus timeout in milliseconds.
+
+.. code-block:: arduino
+
+    uint16_t getTimeOut();
+
+.. _i2c write:
+
+write
+^^^^^
+
+This function writes data to the buffer.
+
+.. code-block:: arduino
+
+    size_t write(uint8_t);
+ 
+or 
+
+.. code-block:: arduino
+
+    size_t write(const uint8_t *, size_t);
+
+The return will be the size of the data added to the buffer.
+
+end
+^^^
+
+This function will finish the communication and release all the allocated resources. After calling ``end`` you need to user ``begin`` again.
+
+.. code-block:: arduino
+
+    bool end();
+
+
+I2C Master Mode
+***************
+
+This mode is used to initiate communication to the slave.
+
+Basic Usage
+^^^^^^^^^^^
+
+To start using I2C on the Arduino, the first step is to include the ``Wire.h`` header to the scketch.
+
+.. code-block:: arduino
+
+    #include "Wire.h"
+
+Now, we can start the peripheral configuration by calling ``begin`` function.
+
+.. code-block:: arduino
+
+    Wire.begin();
+
+By using ``begin`` without any arguments, all the settings will be done by using the default values. To set the values by your own, see the function description. This function is described here: `i2c begin`_
+
+After calling ``begin``, we can start the transmission by calling ``beginTransmission`` and passing the I2C slave address:
+
+.. code-block:: arduino
+
+    Wire.beginTransmission(I2C_DEV_ADDR);
+
+To write some bytes to the slave, use the ``write`` function.
+
+.. code-block:: arduino
+
+    Wire.write(x);
+
+You can pass different data types using ``write`` function. This function is described here: `i2c write`_
+
+.. note:: The ``write`` function does not writes directly to the slave device but adds to the I2C buffer. To do so, you need to use the ``endTransmission`` function to send the buffered bytes to the slave device.
+
+.. code-block:: arduino
+
+    Wire.endTransmission(true);
+
+After calling ``endTransmission``, the data stored in the I2C buffer will be transmitted to the slave device.
+
+Now you can request a reading from the slave device. The ``requestFrom`` will ask a readout to the selected device by giving the address and the size.
+
+.. code-block:: arduino
+
+    Wire.requestFrom(I2C_DEV_ADDR, SIZE);
+
+and the ``readBytes`` will read it.
+
+.. code-block:: arduino
+
+    Wire.readBytes(temp, error);
+
+.. _i2c begin:
+
+begin
+^^^^^
+
+.. code-block:: arduino
+
+    bool begin(int sdaPin, int sclPin, uint32_t frequency)
+
+beginTransmission
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: arduino
+
+    void beginTransmission(uint16_t address)
+
+endTransmission
+^^^^^^^^^^^^^^^
+
+.. code-block:: arduino
+
+    uint8_t endTransmission(bool sendStop);
+
+* ``sendStop`` enables (true) or disables (false) the stop.
+
+.. code-block:: arduino
+    
+    uint8_t endTransmission(void);
+
+requestFrom
+^^^^^^^^^^^
+
+.. code-block:: arduino
+
+    uint8_t requestFrom(uint16_t address, uint8_t size, bool sendStop)
+
+* ``address`` set the device address.
+
+* ``size`` define the size to be requested.
+
+* ``sendStop`` enables (true) or disables (false) the stop.
+
+This function will return the number of bytes read from the device.
+
+Example Application
+^^^^^^^^^^^^^^^^^^^
+
+Here is an example on how to use the I2C in Master Mode.
+
+.. code-block:: arduino
+
+    #include "Wire.h"
+
+    #define I2C_DEV_ADDR 0x55
+
+    uint32_t i = 0;
+
+    void setup() {
+    Serial.begin(115200);
+    Serial.setDebugOutput(true);
+    Wire.begin();
+    }
+
+    void loop() {
+    delay(5000);
+
+    //Write message to the slave
+    Wire.beginTransmission(I2C_DEV_ADDR);
+    Wire.printf("Hello World! %u", i++);
+    uint8_t error = Wire.endTransmission(true);
+    Serial.printf("endTransmission: %u\n", error);
+    
+    //Read 16 bytes from the slave
+    error = Wire.requestFrom(I2C_DEV_ADDR, 16);
+    Serial.printf("requestFrom: %u\n", error);
+    if(error){
+        uint8_t temp[error];
+        Wire.readBytes(temp, error);
+        log_print_buf(temp, error);
+    }
+    }
+
+
+I2C Slave Mode
+**************
+
+This mode is used to accept communication from the master.
+
+Basic Usage
+^^^^^^^^^^^
+
+begin
+^^^^^
+
+.. code-block:: arduino
+
+    bool Wire.begin(uint8_t addr, int sdaPin, int sclPin, uint32_t frequency)
+
+onReceive
+^^^^^^^^^
+
+.. code-block:: arduino
+
+    void onReceive( void (*)(int) );
+
+onRequest
+^^^^^^^^^
+
+.. code-block:: arduino
+
+    void onRequest( void (*)(void) );
+
+slaveWrite
+^^^^^^^^^^
+
+.. code-block:: arduino
+
+    size_t slaveWrite(const uint8_t *, size_t);
+
+Example Application
+^^^^^^^^^^^^^^^^^^^
+
+Here is an example on how to use the I2C in Slave Mode.
+
+.. code-block:: arduino
+
+    #include "Wire.h"
+
+    #define I2C_DEV_ADDR 0x55
+
+    uint32_t i = 0;
+
+    void onRequest(){
+    Wire.print(i++);
+    Wire.print(" Packets.");
+    Serial.println("onRequest");
+    }
+
+    void onReceive(int len){
+    Serial.printf("onReceive[%d]: ", len);
+    while(Wire.available()){
+        Serial.write(Wire.read());
+    }
+    Serial.println();
+    }
+
+    void setup() {
+    Serial.begin(115200);
+    Serial.setDebugOutput(true);
+    Wire.onReceive(onReceive);
+    Wire.onRequest(onRequest);
+    Wire.begin((uint8_t)I2C_DEV_ADDR);
+
+    #if CONFIG_IDF_TARGET_ESP32
+    char message[64];
+    snprintf(message, 64, "%u Packets.", i++);
+    Wire.slaveWrite((uint8_t *)message, strlen(message));
+    #endif
+    }
+
+    void loop() {
+
+    }
+
+.. _Arduino Wire Library: https://www.arduino.cc/en/reference/wire

Diff for: docs/source/_static/arduino_i2c_slave.png

@@ -2,7 +2,7 @@
 Libraries
 #########
 
-Here is where the Libraries API's descriptions are located.
+Here is where the Libraries API's descriptions are located:
 
 .. toctree::
     :maxdepth: 1
@@ -12,6 +12,7 @@ Here is where the Libraries API's descriptions are located.
     Deep Sleep <api/deepsleep>
     ESPNOW <api/espnow>
     GPIO <api/gpio>
+    I2C <api/i2c>
     RainMaker <api/rainmaker>
     Reset Reason <api/reset_reason>
     Wi-Fi <api/wifi>