Refactor, multiple modifications and added license file

Author: natanaeljr

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright 2017 Natanael Josue Rabello. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

README.md

@@ -1,3 +1,61 @@
 # I2Cbus
 
-I2C interface library for working with ESP-32. Documentation is on its way..
+I2C interface library for working with **ESP32 _esp-idf_**, and supports master mode only.
+
+The intention of this library is to read and write to I2C slave devices with ease, by providing quick and specific functions aimed at 8-bit registers. It is based on I2Cdev by Jeff Rowberg.
+
+You can clone it right into your project components directory or in your specific library path.
+
+`git clone https://github.com/natanaeljr/I2Cbus-esp32.git I2Cbus`
+
+## Usage
+
+The library provides two ready-to-use objects: `I2Cbus0` which corresponds to ESP32 I2C port 0, and `I2Cbus1` which corresponds to ESP32 I2C port 1. However you can create your own object as you will.
+
+### Example:
+
+```C++
+// default objects
+I2Cbus0.begin(GPIO_NUM_16, GPIO_NUM_17);
+I2Cbus1.begin(GPIO_NUM_21, GPIO_NUM_22);
+// OR
+// create an object which manages port 0
+I2Cbus_t myI2C(I2C_PORT_0);
+// configure and initialize
+myI2C.begin(GPIO_NUM_21, GPIO_NUM_22, 400000);  // 400KHz
+
+// call methods
+myI2C.setTimeout(100);  // default 1000ms
+myI2C.scanner();
+myI2C.close();
+```
+
+### List of methods:
+
+```C++
+// SETUP
+esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num, uint32_t clk_speed = I2CBUS_CLOCKSPEED_DEFAULT);
+esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num, gpio_pullup_t sda_pullup_en, gpio_pullup_t scl_pullup_en, uint32_t clk_speed = I2CBUS_CLOCKSPEED_DEFAULT);
+esp_err_t close();
+void setTimeout(uint32_t ms);
+
+// WRITING
+esp_err_t writeBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t data, int32_t timeout = -1);
+esp_err_t writeBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t data, int32_t timeout = -1);
+esp_err_t writeByte(uint8_t devAddr, uint8_t regAddr, uint8_t data, int32_t timeout = -1);
+esp_err_t writeBytes(uint8_t devAddr, uint8_t regAddr, size_t length, const uint8_t *data, int32_t timeout = -1);
+
+// READING
+esp_err_t readBit(uint8_t devAddr, uint8_t regAddr, uint8_t bitNum, uint8_t *data, int32_t timeout = -1);
+esp_err_t readBits(uint8_t devAddr, uint8_t regAddr, uint8_t bitStart, uint8_t length, uint8_t *data, int32_t timeout = -1);
+esp_err_t readByte(uint8_t devAddr, uint8_t regAddr, uint8_t *data, int32_t timeout = -1);
+esp_err_t readBytes(uint8_t devAddr, uint8_t regAddr, size_t length, uint8_t *data, int32_t timeout = -1);
+
+// TOOLS
+esp_err_t testConnection(uint8_t devAddr, int32_t timeout = -1);
+void scanner();
+```
+
+---
+
+Copyright (c) 2017 Natanael Rabello

component.mk

@@ -6,5 +6,3 @@ COMPONENT_SRCDIRS := src .
 
 I2CBUS_COMPONENT_NAME := $(COMPONENT_NAME)
 export I2CBUS_COMPONENT_NAME
-
-

examples/Makefile example/Makefile

@@ -0,0 +1,3 @@
+#
+# Main component makefile.
+#

example/main/component.mk

@@ -0,0 +1,60 @@
+/* =========================================================================
+The MIT License (MIT)
+
+Copyright 2017 Natanael Josue Rabello. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+ ========================================================================= */
+
+#include <stdint.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "driver/gpio.h"
+#include "driver/i2c.h"
+#include "esp_log.h"
+
+#include "I2Cbus.hpp"
+
+#ifdef __cplusplus
+extern "C" {
+    void app_main(void);
+}
+#endif
+
+/**
+ * I2Cbus0 and I2Cbus1 are the default objects
+ * */
+
+void app_main() {
+    printf(LOG_BOLD("97") "\n[APP_MAIN]" LOG_RESET_COLOR "\n");
+    
+    I2Cbus0.begin(GPIO_NUM_21, GPIO_NUM_22, 400000U);
+    I2Cbus0.setTimeout(10);
+    I2Cbus0.scanner();
+
+    I2Cbus0.writeBit(0x69, 0x6B, 6, false);
+    
+    uint8_t buffer[6];
+    while(true) {
+        I2Cbus0.readBytes(0x68, 0x6F, 6, buffer);
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+    }
+    
+    vTaskDelay(portMAX_DELAY);
+}

example/main/main.cpp

@@ -2,7 +2,7 @@
 # I2Cbus
 #
 CONFIG_I2CBUS_LOG_ERRORS=y
-CONFIG_I2CBUS_LOG_READWRITES=y
+CONFIG_I2CBUS_LOG_READWRITES=
 CONFIG_I2CBUS_LOG_RW_LEVEL_INFO=
 CONFIG_I2CBUS_LOG_RW_LEVEL_DEBUG=
-CONFIG_I2CBUS_LOG_RW_LEVEL_VERBOSE=y
+CONFIG_I2CBUS_LOG_RW_LEVEL_VERBOSE=

examples/sdkconfig.defaults example/sdkconfig.defaults

@@ -1,6 +1,30 @@
+/* =========================================================================
+I2Cbus library is placed under the MIT License
+Copyright 2017 Natanael Josue Rabello. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+ ========================================================================= */
+
 #ifndef _I2CBUS_HPP_
 #define _I2CBUS_HPP_
 
+#include <stdint.h>
 #include "driver/i2c.h"
 #include "driver/gpio.h"
 #include "esp_err.h"
@@ -25,7 +49,9 @@ extern I2Cbus_t I2Cbus0;        /*!< port: I2C_NUM_0 */
 extern I2Cbus_t I2Cbus1;        /*!< port: I2C_NUM_1 */
 
 
-
+/* ^^^^^^
+ * I2CBUS
+ * ^^^^^^ */
 class I2Cbus_t {
 private:
     i2c_port_t port;            /*!< I2C port: I2C_NUM_0 or I2C_NUM_1 */
@@ -47,8 +73,10 @@ class I2Cbus_t {
      *                       - ESP_ERR_INVALID_ARG Parameter error
      *                       - ESP_FAIL Driver install error
      */
-    esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num, uint32_t clk_speed = I2CBUS_CLOCKSPEED_DEFAULT);
-    esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num, 
+    esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num,
+                    uint32_t clk_speed = I2CBUS_CLOCKSPEED_DEFAULT);
+
+    esp_err_t begin(gpio_num_t sda_io_num, gpio_num_t scl_io_num,
                     gpio_pullup_t sda_pullup_en, gpio_pullup_t scl_pullup_en, 
                     uint32_t clk_speed = I2CBUS_CLOCKSPEED_DEFAULT);
 
@@ -67,12 +95,15 @@ class I2Cbus_t {
      * *** WRITING interface ***
      * @brief  I2C commands for writing to a 8-bit slave device register.
      *         All of them returns standard esp_err_t codes. So it can be used
-     *         within ESP_ERROR_CHECK();
+     *         with ESP_ERROR_CHECK();
      * @param  devAddr   [I2C slave device register]
-     * @param  regAddr [Register address to write to]
-     * @param  bit       [Number of the bit position to write (bit 7~0)]
+     * @param  regAddr   [Register address to write to]
+     * @param  bitNum    [Bit position number to write to (bit 7~0)]
+     * @param  bitStart  [Start bit number when writing a bit-sequence (MSB)]
      * @param  data      [Value(s) to be write to the register]
      * @param  length    [Number of bytes to write (should be within the data buffer size)]
+     *                   [writeBits() -> Number of bits after bitStart (including)]
+     * @param  timeout   [Custom timeout for the particular call]
      * @return  - ESP_OK Success
      *          - ESP_ERR_INVALID_ARG Parameter error
      *          - ESP_FAIL Sending command error, slave doesn't ACK the transfer.
@@ -88,12 +119,14 @@ class I2Cbus_t {
      * *** READING interface ***
      * @breif  I2C commands for reading a 8-bit slave device register.
      *         All of them returns standard esp_err_t codes.So it can be used
-     *         within ESP_ERROR_CHECK();
+     *         with ESP_ERROR_CHECK();
      * @param  devAddr   [I2C slave device register]
-     * @param  regAddr [Register address to read from]
-     * @param  bit       [Number of the bit position to write (bit 7~0)]
-     * @param  data      [Buffer to store the read data(s)]
+     * @param  regAddr   [Register address to read from]
+     * @param  bitNum    [Bit position number to write to (bit 7~0)]
+     * @param  bitStart  [Start bit number when writing a bit-sequence (MSB)]
+     * @param  data      [Buffer to store the read value(s)]
      * @param  length    [Number of bytes to read (should be within the data buffer size)]
+     * @param  timeout   [Custom timeout for the particular call]
      * @return  - ESP_OK Success
      *          - ESP_ERR_INVALID_ARG Parameter error
      *          - ESP_FAIL Sending command error, slave doesn't ACK the transfer.
@@ -107,7 +140,8 @@ class I2Cbus_t {
 
     /**
      * @brief  Quick check to see if a slave device responds.
-     * @param  devAddr [I2C slave device register]
+     * @param  devAddr   [I2C slave device register]
+     * @param  timeout   [Custom timeout for the particular call]
      * @return  - ESP_OK Success
      *          - ESP_ERR_INVALID_ARG Parameter error
      *          - ESP_FAIL Sending command error, slave doesn't ACK the transfer.
@@ -124,8 +158,4 @@ class I2Cbus_t {
 
 
 
-
-
-
-
 #endif /* end of include guard: _I2CBUS_H_ */

examples/main/component.mk

@@ -1,4 +1,28 @@
+/* =========================================================================
+I2Cbus library is placed under the MIT License
+Copyright 2017 Natanael Josue Rabello. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+ ========================================================================= */
+
 #include "I2Cbus.hpp"
+#include <stdint.h>
 #include "driver/i2c.h"
 #include "driver/gpio.h"
 #include "esp_err.h"
@@ -205,13 +229,3 @@ void I2Cbus_t::scanner() {
 
 
 
-
-
-
-
-
-
-
-
-
-