elrebo-de/i2c_master

Readme

# I2cMaster component

This repository contains an ESP-IDF component for the I2C communication. It runs on
any ESP32 processor and is built using the ESP-IDF build system in version 5.5.0+.

The component is implemented as C++ classes `I2cMaster` and `I2cDevice`.

## Connecting the component

The first constructor of class `I2cMaster` has four parameters:

| Parameter | Type of Parameter | Usage                             |
|:----------|:------------------|:----------------------------------|
| tag       | std::string       | the tag to be used in the ESP log |
| i2cPort   | i2c_port_num_t    | the i2c port number               |
| sclPin    | gpio_num_t        | the GPIO pin for SCL              |
| sdaPin    | gpio_num_t        | the GPIO pin for SDA              |

It creates a new i2c_master_bus.

The second constructor of class `I2cMaster` has two parameters:

| Parameter | Type of Parameter       | Usage                                                |
|:----------|:------------------------|:-----------------------------------------------------|
| tag       | std::string             | the tag to be used in the ESP log                    |
| busHandle | i2c_master_bus_handle_t | the handle of the already initialized i2c_master_bus |

It creates an instance of `I2cMaster` for an already initialized i2c_master_bus.

The constructor of class `I2cDevice` has five parameters:

| Parameter     | Type of Parameter   | Usage                             |
|:--------------|:--------------------|:----------------------------------|
| tag           | std::string         | the tag to be used in the ESP log |
| deviceName    | std::string         | the device name                   |
| devAddrLength | i2c_addr_bit_len_t  | the device address length         |
| deviceAddr    | uint16_t            | the device address                |
| sclSpeedHz    | uint32_t            | the clock speed in Hz             |

# Usage

You need to include `i2c_master.hpp`.

Then you define the I2C bus master by defining an instance of class `I2cMaster`.

For every I2C device you define an instance of class `I2cDevice` and add it to `I2cMaster` with method `AddDevice`.

Now the device handles are available through method `GetDeviceHandle(std::string deviceName)` of class `I2cMaster`.

To transmit data to an I2C device and to receive data from an I2C device you use the original ESP functions or these low level methods of class `I2cDevide`:
* Method `Write` writes a buffer with specified length to the device (timeout is -1)
* Method `WriteAndRead` writes a buffer with specified length to the device and immediately reads a buffer with specified length from the device (timeout is -1)

In addition there are two higher level methods in class `I2cDevide`:
* Method `ReadRegister` to transmit one address byte to the device and immediately read one data byte from the device.
* Method `WriteRegister` to transmit one address byte and one data byte to the device.

## API
The API of the component is located in the include directory files ```include/i2c_master.hpp``` and  ```include/i2c_device.hpp``` and defines the
C++ classes ```I2cMaster``` and ```I2cDevice```

```C
/* class I2cMaster
   Implementation of an I2C master bus for ESP IDF 5.5+
*/
class I2cMaster {
public:
    // Constructor of I2cMaster
	I2cMaster(std::string tag, i2c_port_num_t i2cPort, gpio_num_t sclPin, gpio_num_t sdaPin);
	I2cMaster(std::string tag, i2c_master_bus_handle_t bus_handle);
	virtual ~I2cMaster();

    i2c_master_bus_config_t GetConfig();
    i2c_master_bus_handle_t GetHandle();

    i2c_master_dev_handle_t AddDevice(I2cDevice *device);
    void RemoveDevice(std::string deviceName);
    i2c_master_dev_handle_t GetDeviceHandle(std::string deviceName);
    I2cDevice* GetDevice(std::string deviceName);

private:
    std::string tag = "I2cMaster";
    i2c_port_num_t i2cPort;
    gpio_num_t sclPin;
    gpio_num_t sdaPin;

    i2c_master_bus_config_t busConfig;
    i2c_master_bus_handle_t busHandle;

    // Map of devices<deviceName, device*>
    std::map<std::string, I2cDevice *> devices{};
};

/* class I2cDevice
   Implementation of an I2C device for I2C master bus for ESP IDF 5.5+
*/
class I2cDevice {
public:
    // Constructor of I2cDevice
	I2cDevice(std::string tag, std::string deviceName, i2c_addr_bit_len_t devAddrLength, uint16_t deviceAddress,
	          uint32_t sclSpeedHz);
	virtual ~I2cDevice();

	i2c_device_config_t GetConfig();
	std::string GetDeviceName();

	void SetHandle(i2c_master_dev_handle_t devHandle);
	i2c_master_dev_handle_t GetHandle();
	
    uint8_t ReadRegister(uint8_t reg_addr);
    esp_err_t WriteRegister(uint8_t reg_addr, uint8_t data_val);

    esp_err_t Write(uint8_t* write_buffer, uint8_t write_buffer_length);
    esp_err_t WriteAndRead(uint8_t* write_buffer, uint8_t write_buffer_length,
                           uint8_t* read_buffer, uint8_t read_buffer_length);

private:
    std::string tag = "I2cDevice";
    std::string deviceName;
    i2c_device_config_t devConfig;
    i2c_master_dev_handle_t devHandle;
};
```

# License

This component is provided under the Apache 2.0 license.