feat(wire): std::functional Wire slave callback functions (#668)

Jason2866 · web-flow · commit bd037ccdffa2 · 2025-07-12T11:14:04.000+02:00
diff --git a/cores/esp32/HardwareI2C.h b/cores/esp32/HardwareI2C.h
@@ -20,6 +20,7 @@
 
 #include <inttypes.h>
 #include "Stream.h"
+#include <functional>
 
 class HardwareI2C : public Stream {
 public:
@@ -36,6 +37,7 @@ class HardwareI2C : public Stream {
   virtual size_t requestFrom(uint8_t address, size_t len, bool stopBit) = 0;
   virtual size_t requestFrom(uint8_t address, size_t len) = 0;
 
-  virtual void onReceive(void (*)(int)) = 0;
-  virtual void onRequest(void (*)(void)) = 0;
+  // Update base class to use std::function
+  virtual void onReceive(const std::function<void(int)> &) = 0;
+  virtual void onRequest(const std::function<void()> &) = 0;
 };
diff --git a/docs/en/api/i2c.rst b/docs/en/api/i2c.rst
@@ -347,20 +347,147 @@ This function will return ``true`` if the peripheral was initialized correctly.
 onReceive
 ^^^^^^^^^
 
-The ``onReceive`` function is used to define the callback for the data received from the master.
+The ``onReceive`` function is used to define the callback for data received from the master device.
 
 .. code-block:: arduino
 
-    void onReceive( void (*)(int) );
+    void onReceive(const std::function<void(int)>& callback);
+
+**Function Signature:**
+
+The callback function must have the signature ``void(int numBytes)`` where ``numBytes`` indicates how many bytes were received from the master.
+
+**Usage Examples:**
+
+.. code-block:: arduino
+
+    // Method 1: Regular function
+    void handleReceive(int numBytes) {
+        Serial.printf("Received %d bytes: ", numBytes);
+        while (Wire.available()) {
+            char c = Wire.read();
+            Serial.print(c);
+        }
+        Serial.println();
+    }
+    Wire.onReceive(handleReceive);
+
+    // Method 2: Lambda function
+    Wire.onReceive([](int numBytes) {
+        Serial.printf("Master sent %d bytes\n", numBytes);
+        while (Wire.available()) {
+            uint8_t data = Wire.read();
+            // Process received data
+            Serial.printf("Data: 0x%02X\n", data);
+        }
+    });
+
+    // Method 3: Lambda with capture (for accessing variables)
+    int deviceId = 42;
+    Wire.onReceive([deviceId](int numBytes) {
+        Serial.printf("Device %d received %d bytes\n", deviceId, numBytes);
+        // Process data...
+    });
+
+    // Method 4: Using std::function variable
+    std::function<void(int)> receiveHandler = [](int bytes) {
+        Serial.printf("Handling %d received bytes\n", bytes);
+    };
+    Wire.onReceive(receiveHandler);
+
+    // Method 5: Class member function (using lambda wrapper)
+    class I2CDevice {
+    private:
+        int deviceAddress;
+    public:
+        I2CDevice(int addr) : deviceAddress(addr) {}
+
+        void handleReceive(int numBytes) {
+            Serial.printf("Device 0x%02X received %d bytes\n", deviceAddress, numBytes);
+        }
+
+        void setup() {
+            Wire.onReceive([this](int bytes) {
+                this->handleReceive(bytes);
+            });
+        }
+    };
+
+.. note::
+    The ``onReceive`` callback is triggered when the I2C master sends data to this slave device.
+    Use ``Wire.available()`` and ``Wire.read()`` inside the callback to retrieve the received data.
 
 onRequest
 ^^^^^^^^^
 
-The ``onRequest`` function is used to define the callback for the data to be send to the master.
+The ``onRequest`` function is used to define the callback for responding to master read requests.
+
+.. code-block:: arduino
+
+    void onRequest(const std::function<void()>& callback);
+
+**Function Signature:**
+
+The callback function must have the signature ``void()`` with no parameters. This callback is triggered when the master requests data from this slave device.
+
+**Usage Examples:**
 
 .. code-block:: arduino
 
-    void onRequest( void (*)(void) );
+    // Method 1: Regular function
+    void handleRequest() {
+        static int counter = 0;
+        Wire.printf("Response #%d", counter++);
+    }
+    Wire.onRequest(handleRequest);
+
+    // Method 2: Lambda function
+    Wire.onRequest([]() {
+        // Send sensor data to master
+        int sensorValue = analogRead(A0);
+        Wire.write(sensorValue >> 8);    // High byte
+        Wire.write(sensorValue & 0xFF);  // Low byte
+    });
+
+    // Method 3: Lambda with capture (for accessing variables)
+    int deviceStatus = 1;
+    String deviceName = "Sensor1";
+    Wire.onRequest([&deviceStatus, &deviceName]() {
+        Wire.write(deviceStatus);
+        Wire.write(deviceName.c_str(), deviceName.length());
+    });
+
+    // Method 4: Using std::function variable
+    std::function<void()> requestHandler = []() {
+        Wire.write("Hello Master!");
+    };
+    Wire.onRequest(requestHandler);
+
+    // Method 5: Class member function (using lambda wrapper)
+    class TemperatureSensor {
+    private:
+        float temperature;
+    public:
+        void updateTemperature() {
+            temperature = 25.5; // Read from actual sensor
+        }
+
+        void sendTemperature() {
+            // Convert float to bytes and send
+            uint8_t* tempBytes = (uint8_t*)&temperature;
+            Wire.write(tempBytes, sizeof(float));
+        }
+
+        void setup() {
+            Wire.onRequest([this]() {
+                this->sendTemperature();
+            });
+        }
+    };
+
+.. note::
+    The ``onRequest`` callback is triggered when the I2C master requests data from this slave device.
+    Use ``Wire.write()`` inside the callback to send response data back to the master.
 
 slaveWrite
 ^^^^^^^^^^
diff --git a/libraries/Wire/src/Wire.cpp b/libraries/Wire/src/Wire.cpp
@@ -39,7 +39,7 @@ extern "C" {
 #include "Arduino.h"
 
 TwoWire::TwoWire(uint8_t bus_num)
-  : num(bus_num & 1), sda(-1), scl(-1), bufferSize(I2C_BUFFER_LENGTH)  // default Wire Buffer Size
+  : num(bus_num), sda(-1), scl(-1), bufferSize(I2C_BUFFER_LENGTH)  // default Wire Buffer Size
     ,
     rxBuffer(NULL), rxIndex(0), rxLength(0), txBuffer(NULL), txLength(0), txAddress(0), _timeOutMillis(50), nonStop(false)
 #if !CONFIG_DISABLE_HAL_LOCKS
@@ -48,7 +48,7 @@ TwoWire::TwoWire(uint8_t bus_num)
 #endif
 #if SOC_I2C_SUPPORT_SLAVE
     ,
-    is_slave(false), user_onRequest(NULL), user_onReceive(NULL)
+    is_slave(false), user_onRequest(nullptr), user_onReceive(nullptr)
 #endif /* SOC_I2C_SUPPORT_SLAVE */
 {
 }
@@ -62,6 +62,10 @@ TwoWire::~TwoWire() {
 #endif
 }
 
+uint8_t TwoWire::getBusNum() {
+  return num;
+}
+
 bool TwoWire::initPins(int sdaPin, int sclPin) {
   if (sdaPin < 0) {  // default param passed
     if (num == 0) {
@@ -462,10 +466,11 @@ uint8_t TwoWire::endTransmission(bool sendStop) {
     nonStop = true;
   }
   switch (err) {
-    case ESP_OK:          return 0;
-    case ESP_FAIL:        return 2;
-    case ESP_ERR_TIMEOUT: return 5;
-    default:              break;
+    case ESP_OK:            return 0;
+    case ESP_FAIL:          return 2;
+    case ESP_ERR_NOT_FOUND: return 2;
+    case ESP_ERR_TIMEOUT:   return 5;
+    default:                break;
   }
   return 4;
 }
@@ -591,14 +596,14 @@ void TwoWire::flush() {
   //i2cFlush(num); // cleanup
 }
 
-void TwoWire::onReceive(void (*function)(int)) {
+void TwoWire::onReceive(const std::function<void(int)> &function) {
 #if SOC_I2C_SUPPORT_SLAVE
   user_onReceive = function;
 #endif
 }
 
 // sets function called on slave read
-void TwoWire::onRequest(void (*function)(void)) {
+void TwoWire::onRequest(const std::function<void()> &function) {
 #if SOC_I2C_SUPPORT_SLAVE
   user_onRequest = function;
 #endif
@@ -646,8 +651,16 @@ void TwoWire::onRequestService(uint8_t num, void *arg) {
 #endif /* SOC_I2C_SUPPORT_SLAVE */
 
 TwoWire Wire = TwoWire(0);
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 4, 0)
+#if SOC_I2C_NUM > 1
+TwoWire Wire1 = TwoWire(1);
+#elif SOC_I2C_NUM > 2
+TwoWire Wire2 = TwoWire(2);
+#endif /* SOC_I2C_NUM */
+#else
 #if SOC_HP_I2C_NUM > 1
 TwoWire Wire1 = TwoWire(1);
 #endif /* SOC_HP_I2C_NUM */
+#endif
 
 #endif /* SOC_I2C_SUPPORTED */
diff --git a/libraries/Wire/src/Wire.h b/libraries/Wire/src/Wire.h
@@ -28,6 +28,7 @@
 
 #include "soc/soc_caps.h"
 #if SOC_I2C_SUPPORTED
+#include "esp_idf_version.h"
 
 #include <esp32-hal.h>
 #include <esp32-hal-log.h>
@@ -47,10 +48,6 @@
 #ifndef I2C_BUFFER_LENGTH
 #define I2C_BUFFER_LENGTH 128  // Default size, if none is set using Wire::setBuffersize(size_t)
 #endif
-#if SOC_I2C_SUPPORT_SLAVE
-typedef void (*user_onRequest)(void);
-typedef void (*user_onReceive)(uint8_t *, int);
-#endif /* SOC_I2C_SUPPORT_SLAVE */
 
 class TwoWire : public HardwareI2C {
 protected:
@@ -76,8 +73,8 @@ class TwoWire : public HardwareI2C {
 private:
 #if SOC_I2C_SUPPORT_SLAVE
   bool is_slave;
-  void (*user_onRequest)(void);
-  void (*user_onReceive)(int);
+  std::function<void()> user_onRequest;
+  std::function<void(int)> user_onReceive;
   static void onRequestService(uint8_t, void *);
   static void onReceiveService(uint8_t, uint8_t *, size_t, bool, void *);
 #endif /* SOC_I2C_SUPPORT_SLAVE */
@@ -104,6 +101,8 @@ class TwoWire : public HardwareI2C {
 
   bool end() override;
 
+  uint8_t getBusNum();
+
   bool setClock(uint32_t freq) override;
 
   void beginTransmission(uint8_t address) override;
@@ -113,8 +112,8 @@ class TwoWire : public HardwareI2C {
   size_t requestFrom(uint8_t address, size_t len, bool stopBit) override;
   size_t requestFrom(uint8_t address, size_t len) override;
 
-  void onReceive(void (*)(int)) override;
-  void onRequest(void (*)(void)) override;
+  void onReceive(const std::function<void(int)> &) override;
+  void onRequest(const std::function<void()> &) override;
 
   //call setPins() first, so that begin() can be called without arguments from libraries
   bool setPins(int sda, int scl);
@@ -144,9 +143,17 @@ class TwoWire : public HardwareI2C {
 };
 
 extern TwoWire Wire;
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 4, 0)
+#if SOC_I2C_NUM > 1
+extern TwoWire Wire1;
+#elif SOC_I2C_NUM > 2
+extern TwoWire Wire2;
+#endif /* SOC_I2C_NUM */
+#else
 #if SOC_HP_I2C_NUM > 1
 extern TwoWire Wire1;
 #endif /* SOC_HP_I2C_NUM */
+#endif
 
 #endif /* SOC_I2C_SUPPORTED */
 #endif /* TwoWire_h */
