WireDev.h - a drop-in replacement of Arduino Wire to support both Wire and ESP-IDF i2cdev modules

[dizcza]

Version 2 (fully independent)

Wire.h

/*
  Replacement of Arduino Wire.h
  Author: Danylo Ulianych

  Arduino C++ libraries that include <Wire.h>
  can use this code to be i2cdev-compatible.
*/

#ifndef TwoWire_h
#define TwoWire_h

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"

#include "i2cdev.h"

// WIRE_HAS_BUFFER_SIZE means Wire has setBufferSize()
#define WIRE_HAS_BUFFER_SIZE    1
// WIRE_HAS_END means Wire has end()
#define WIRE_HAS_END 1

#define I2C_BUFFER_LENGTH 128  // Default size, if none is set using Wire::setBuffersize(size_t)

class TwoWire
{
protected:
    i2c_dev_t i2cdev;

    bool initialized = false;
    bool nonStop = false;
    SemaphoreHandle_t lock;    //!< Device mutex

    size_t bufferSize;
    uint8_t *rxBuffer;
    size_t rxIndex;
    size_t rxLength;

    uint8_t *txBuffer;
    size_t txLength;

    bool initPins(int sdaPin, int sclPin);
    bool allocateWireBuffer();
    void freeWireBuffer();

public:
    TwoWire(uint8_t bus_num);
    ~TwoWire();

    bool begin();

    bool end();

    bool setClock(uint32_t freq);

    void beginTransmission(uint8_t address);
    uint8_t endTransmission(bool stopBit);
    uint8_t endTransmission();

    size_t requestFrom(uint8_t address, size_t len, bool stopBit);
    size_t requestFrom(uint8_t address, size_t len);

    //call setPins() first, so that begin() can be called without arguments from libraries
    bool setPins(int sda, int scl);

    bool begin(int sda, int scl, uint32_t frequency=400000); // returns true, if successful init of i2c bus

    size_t setBufferSize(size_t bSize);

    void setTimeOut(uint16_t timeOutMillis); // default timeout of i2c transactions is 50ms
    uint16_t getTimeOut();

    uint32_t getClock();

    size_t write(uint8_t);
    size_t write(const uint8_t *, size_t);
    int available();
    int read();
    int peek();
    void flush();
};

extern TwoWire Wire;
extern TwoWire Wire1;

#endif /* TwoWire_h */

Wire.cpp

/*
  Replacement of Arduino Wire.h
  Author: Danylo Ulianych

  Arduino C++ libraries that include <Wire.h>
  can use this code to be i2cdev-compatible.
*/

extern "C" {
#include <stdlib.h>
#include <string.h>
#include <inttypes.h>
}

#include "Wire.h"
#include "esp_log.h"


#define WIRE_LOG  ESP_LOGD

#define WIRE_LOG_STATUS(err) \
    if (err != ESP_OK) { \
        ESP_LOGE(TAG, "%s %s", __func__, esp_err_to_name(err)); \
    } else { \
        WIRE_LOG(TAG, "%s %s", __func__, esp_err_to_name(err)); \
    }


static const char *TAG = "Wire";



TwoWire::TwoWire(uint8_t bus_num)
    :bufferSize(I2C_BUFFER_LENGTH) // default Wire Buffer Size
    ,rxBuffer(NULL)
    ,rxIndex(0)
    ,rxLength(0)
    ,txBuffer(NULL)
    ,txLength(0)
{
    lock = xSemaphoreCreateMutex();
    memset(&i2cdev, 0, sizeof(i2c_dev_t));
    i2cdev.port = (i2c_port_t) bus_num;
    i2cdev.addr = 0;  // will be set later
    i2cdev.cfg.sda_pullup_en = GPIO_PULLUP_ENABLE;
    i2cdev.cfg.scl_pullup_en = GPIO_PULLUP_ENABLE;
    i2c_dev_create_mutex(&i2cdev);
}

TwoWire::~TwoWire()
{
    end();
    i2c_dev_delete_mutex(&i2cdev);
    vSemaphoreDelete(lock);
}

bool TwoWire::initPins(int sdaPin, int sclPin)
{
    i2cdev.cfg.sda_io_num = sdaPin;
    i2cdev.cfg.scl_io_num = sclPin;
    return true;
}

bool TwoWire::setPins(int sdaPin, int sclPin)
{
    return initPins(sdaPin, sclPin);
}

bool TwoWire::allocateWireBuffer()
{
    // or both buffer can be allocated or none will be
    if (rxBuffer == NULL) {
        rxBuffer = (uint8_t*) calloc(bufferSize, sizeof(uint8_t));
        if (rxBuffer == NULL) {
            ESP_LOGE(TAG, "Can't allocate memory for I2C_%d rxBuffer", i2cdev.port);
            return false;
        }
    }
    if (txBuffer == NULL) {
        txBuffer = (uint8_t*) calloc(bufferSize, sizeof(uint8_t));
        if (txBuffer == NULL) {
            ESP_LOGE(TAG, "Can't allocate memory for I2C_%d txBuffer", i2cdev.port);
            freeWireBuffer();  // free rxBuffer for safety!
            return false;
        }
    }
    // in case both were allocated before, they must have the same size. All good.
    return true;
}

void TwoWire::freeWireBuffer()
{
    if (rxBuffer != NULL) {
        free(rxBuffer);
        rxBuffer = NULL;
    }
    if (txBuffer != NULL) {
        free(txBuffer);
        txBuffer = NULL;
    }
}

size_t TwoWire::setBufferSize(size_t bSize)
{
    // Maximum size .... HEAP limited ;-)
    if (bSize < 32) {    // 32 bytes is the I2C FIFO Len for ESP32/S2/S3/C3
        ESP_LOGE(TAG, "Minimum Wire Buffer size is 32 bytes");
        return 0;
    }

    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return 0;
    }

    // allocateWireBuffer allocates memory for both pointers or just free them
    if (rxBuffer != NULL || txBuffer != NULL) {
        // if begin() has been already executed, memory size changes... data may be lost. We don't care! :^)
        if (bSize != bufferSize) {
            // we want a new buffer size ... just reset buffer pointers and allocate new ones
            freeWireBuffer();
            bufferSize = bSize;
            if (!allocateWireBuffer()) {
                // failed! Error message already issued
                bSize = 0; // returns error
                ESP_LOGE(TAG, "Buffer allocation failed");
            }
        } // else nothing changes, all set!
    } else {
        // no memory allocated yet, just change the size value - allocation in begin()
        bufferSize = bSize;
    }

    //release lock
    i2c_dev_give_mutex(&i2cdev);

    return bSize;
}


bool TwoWire::begin()
{
    if (i2cdev.cfg.sda_io_num == 0) {
        ESP_LOGE(TAG, "SDA & SCL pins are not set, Wire.begin() failed");
        return false;
    }
    return TwoWire::begin(i2cdev.cfg.sda_io_num, i2cdev.cfg.scl_io_num);
}


// Master Begin
bool TwoWire::begin(int sdaPin, int sclPin, uint32_t frequency)
{
    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return false;
    }
    if (initialized){
        ESP_LOGW(TAG, "Bus already started in Master Mode.");
        goto end;
    }
    if (!allocateWireBuffer()) {
        // failed! Error Message already issued
        goto end;
    }
    if (sdaPin != -1 && sclPin != -1) {
        initPins(sdaPin, sclPin);
    }
    i2cdev.cfg.master.clk_speed = frequency;
    initialized = i2cdev.cfg.sda_io_num != 0 && i2cdev.cfg.scl_io_num != 0;

end:

    if (initialized) {
        ESP_LOGI(TAG, "Wire(port=%d, sda=%d, scl=%d) begin OK", i2cdev.port, sdaPin, sclPin);
    } else {
        ESP_LOGE(TAG, "Wire(port=%d, sda=%d, scl=%d) begin FAILED", i2cdev.port, sdaPin, sclPin);
    }

    if (!initialized) freeWireBuffer();
    //release lock
    i2c_dev_give_mutex(&i2cdev);
    return initialized;

}

bool TwoWire::end()
{
    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return false;
    }
    freeWireBuffer();
    i2c_dev_give_mutex(&i2cdev);
    return true;
}

uint32_t TwoWire::getClock()
{
    return i2cdev.cfg.master.clk_speed;
}

bool TwoWire::setClock(uint32_t frequency)
{
    i2cdev.cfg.master.clk_speed = frequency;
    return true;
}

void TwoWire::setTimeOut(uint16_t timeOutMillis)
{
    ESP_LOGW(TAG, "setTimeOut ignored and always set to %d", CONFIG_I2CDEV_TIMEOUT);
}

uint16_t TwoWire::getTimeOut()
{
    return CONFIG_I2CDEV_TIMEOUT;
}

void TwoWire::beginTransmission(uint8_t address)
{
    WIRE_LOG(TAG, "%s addr 0x%02x", __func__, address);
    if (xSemaphoreTake(lock, portMAX_DELAY) != pdTRUE) {
        ESP_LOGE(TAG, "Could not acquire the lock. Did you call endTransmission()?");
    }
    i2cdev.addr = address;
    txLength = 0;
}

/*
https://www.arduino.cc/reference/en/language/functions/communication/wire/endtransmission/
endTransmission() returns:
0: success.
1: data too long to fit in transmit buffer.
2: received NACK on transmit of address.
3: received NACK on transmit of data.
4: other error.
5: timeout
*/
uint8_t TwoWire::endTransmission(bool sendStop)
{
    WIRE_LOG(TAG, "%s...", __func__);
    if (txBuffer == NULL){
        ESP_LOGE(TAG, "NULL TX buffer pointer");
        return 4;
    }
    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return 5;
    }
    WIRE_LOG(TAG, "txLength %d", txLength);
    for (int i = 0; i < txLength; i++) {
        WIRE_LOG(TAG, "txBuffer[%02d]: 0x%02x", i, txBuffer[i]);
    }

    esp_err_t err = ESP_OK;
    if (sendStop) {
        if (txLength == 0) {
            err = i2c_dev_probe(&i2cdev, I2C_DEV_READ);
        } else {
            err = i2c_dev_write(&i2cdev, NULL, 0, txBuffer, txLength);
        }
    } else {
        //mark as non-stop
        nonStop = true;
    }

    i2c_dev_give_mutex(&i2cdev);
    xSemaphoreGive(lock);

    WIRE_LOG_STATUS(err);
    switch(err){
        case ESP_OK: return 0;
        case ESP_FAIL: return 2;
        case ESP_ERR_TIMEOUT: return 5;
        default: break;
    }
    return 4;
}

uint8_t TwoWire::endTransmission()
{
    return endTransmission(true);
}


size_t TwoWire::requestFrom(uint8_t address, size_t size, bool sendStop)
{
    WIRE_LOG(TAG, "%s addr 0x%02x (%zu bytes) ...", __func__, address, size);
    uint8_t addrPrev = i2cdev.addr;
    i2cdev.addr = address;
    rxIndex = 0;
    rxLength = 0;

    if (size > bufferSize) {
        setBufferSize(size);
    }

    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return 0;
    }

    esp_err_t err = ESP_OK;
    if (nonStop) {
        nonStop = false;
        if (address != addrPrev){
            ESP_LOGE(TAG, "Unfinished Repeated Start transaction! Expected address do not match! %u != %u", address, addrPrev);
            err = ESP_FAIL;
        } else {
            err = i2c_dev_write_read_nonstop(&i2cdev, txBuffer, txLength, rxBuffer, size);
        }
    } else {
        err = i2c_dev_read(&i2cdev, NULL, 0, rxBuffer, size);
    }

    if (err == ESP_OK) {
        rxLength = size;
    }

    i2c_dev_give_mutex(&i2cdev);
    WIRE_LOG_STATUS(err);

    return rxLength;
}

size_t TwoWire::requestFrom(uint8_t address, size_t size){
    return requestFrom(address, size, true);
}

size_t TwoWire::write(uint8_t data)
{
    if (txBuffer == NULL){
        ESP_LOGE(TAG, "NULL TX buffer pointer");
        return 0;
    }
    if (txLength >= bufferSize) {
        ESP_LOGW(TAG, "TX buffer not enough space");
        return 0;
    }
    txBuffer[txLength++] = data;
    return 1;
}

size_t TwoWire::write(const uint8_t *data, size_t quantity)
{
    for (size_t i = 0; i < quantity; ++i) {
        if (!write(data[i])) {
            return i;
        }
    }
    return quantity;

}

int TwoWire::available()
{
    int result = rxLength - rxIndex;
    return result;
}

int TwoWire::read()
{
    int value = -1;
    if (rxBuffer == NULL){
        ESP_LOGE(TAG, "NULL RX buffer pointer");
        return value;
    }
    if (rxIndex < rxLength) {
        value = rxBuffer[rxIndex++];
    }
    return value;
}

int TwoWire::peek()
{
    int value = -1;
    if (rxBuffer == NULL){
        ESP_LOGE(TAG, "NULL RX buffer pointer");
        return value;
    }
    if (rxIndex < rxLength) {
        value = rxBuffer[rxIndex];
    }
    return value;
}

void TwoWire::flush()
{
    rxIndex = 0;
    rxLength = 0;
    txLength = 0;
}


TwoWire Wire = TwoWire(0);
TwoWire Wire1 = TwoWire(1);

---

Version 1 (requires Arduino as a component)

WireDev.h:

/*
  WireDev.h - a drop-in replacement of Arduino Wire to support both Wire and ESP-IDF i2cdev modules.
  Author: Danylo Ulianych

  Can be used:
    - on Arduino (copy required ESP-IDF i2cdev modules)
    - on ESP-IDF (add Arduino as a component)

  In either case, you need to change in your code:
    - Wire  --> WireDev
    - Wire1 --> WireDev1
*/

#ifndef TwoWireDev_h
#define TwoWireDev_h

#include "Wire.h"
#include "i2cdev.h"


class TwoWireDev: public TwoWire
{
protected:
    i2c_dev_t i2cdev;

public:
    TwoWireDev(uint8_t bus_num);
    ~TwoWireDev() {};

    bool setPins(int sda, int scl);
    bool begin(int sda, int scl, uint32_t frequency=0); // returns true, if successful init of i2c bus

    void beginTransmission(uint8_t address);
    uint8_t endTransmission(bool stopBit);

    size_t requestFrom(uint8_t address, size_t len, bool stopBit);
};

extern TwoWireDev WireDev;
extern TwoWireDev WireDev1;

#endif /* TwoWireDev_h */

WireDev.cpp:

/*
 * WireDev.cpp
 *
 *  Created on: Mar 4, 2024
 *      Author: Danylo Ulianych
 */

#include "WireDev.h"
#include "esp_log.h"

#ifdef ARDUINO_ARCH_ESP32
// You can also use this module on arduino.
// Just copy-paste needed ESP-IDF i2cdev modules.
#include "esp32-hal-log.h"  // To see the logs
#endif


//#define WIRE_LOG  ESP_LOGI
#define WIRE_LOG  ESP_LOGD


static const char *TAG = "WireDev";


TwoWireDev::TwoWireDev(uint8_t bus_num) : TwoWire(bus_num) {
    memset(&i2cdev, 0, sizeof(i2c_dev_t));
    i2cdev.port = (i2c_port_t) bus_num;
    i2cdev.addr = 0;  // will be set later
    i2cdev.cfg.sda_pullup_en = GPIO_PULLUP_ENABLE;
    i2cdev.cfg.scl_pullup_en = GPIO_PULLUP_ENABLE;
    i2c_dev_create_mutex(&i2cdev);
}


bool TwoWireDev::begin(int sda, int scl, uint32_t frequency) {
    i2cdev.cfg.sda_io_num = sda;
    i2cdev.cfg.scl_io_num = scl;
    i2cdev.cfg.master.clk_speed = frequency;
    bool res = TwoWire::begin(sda, scl, frequency);
    if (res) {
        ESP_LOGI(TAG, "Wire(port=%d, sda=%d, scl=%d) begin OK", this->num, sda, scl);
    } else {
        ESP_LOGI(TAG, "Wire(port=%d, sda=%d, scl=%d) begin FAILED", this->num, sda, scl);
    }
    return res;
}


bool TwoWireDev::setPins(int sda, int scl) {
    i2cdev.cfg.sda_io_num = sda;
    i2cdev.cfg.scl_io_num = scl;
    return TwoWire::setPins(sda, scl);
}


void TwoWireDev::beginTransmission(uint8_t address) {
    WIRE_LOG(TAG, "%s addr 0x%02x", __func__, address);
    i2cdev.addr = address;
    TwoWire::beginTransmission(address);
}


uint8_t TwoWireDev::endTransmission(bool sendStop) {
    WIRE_LOG(TAG, "%s...", __func__);
    if (txBuffer == NULL){
        log_e("NULL TX buffer pointer");
        return 4;
    }
    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return 0;
    }
    WIRE_LOG(TAG, "txLength %d", txLength);
    for (int i = 0; i < txLength; i++) {
        WIRE_LOG(TAG, "txBuffer[%02d]: 0x%02x", i, txBuffer[i]);
    }
    esp_err_t err;
    if (txLength == 0) {
        err = i2c_dev_probe(&i2cdev, I2C_DEV_READ);
    } else {
        err = i2c_dev_write(&i2cdev, NULL, 0, txBuffer, txLength);
    }
    i2c_dev_give_mutex(&i2cdev);
    WIRE_LOG(TAG, "%s %s", __func__, esp_err_to_name(err));
    switch(err){
        case ESP_OK: return 0;
        case ESP_FAIL: return 2;
        case ESP_ERR_TIMEOUT: return 5;
        default: break;
    }
    return 4;
}


size_t TwoWireDev::requestFrom(uint8_t address, size_t size, bool sendStop) {
    WIRE_LOG(TAG, "%s addr 0x%02x (%zu bytes) ...", __func__, address, size);
    i2cdev.addr = address;
    rxIndex = 0;
    rxLength = 0;
    if (i2c_dev_take_mutex(&i2cdev) != ESP_OK) {
        return 0;
    }

    esp_err_t err = i2c_dev_read(&i2cdev, NULL, 0, rxBuffer, size);

    if (err == ESP_OK) {
        rxIndex = 0;
        rxLength = size;
    }

    i2c_dev_give_mutex(&i2cdev);
    WIRE_LOG(TAG, "%s %s", __func__, esp_err_to_name(err));

    return rxLength;
}


TwoWireDev WireDev = TwoWireDev(0);
TwoWireDev WireDev1 = TwoWireDev(1);

With this extension, I managed to run Sparkfun uBlox Arduino Example1 in my ESP-IDF code.

You can point readme to this wrapper for anyone who faces ESP-IDF & Arduino I2C compatibility issues.