From 665bf2adb5e5b6ad1d27d2bf2ef02dcdd4051f12 Mon Sep 17 00:00:00 2001 From: onexs-xsi <850559025@qq.com> Date: Thu, 26 Feb 2026 17:43:17 +0800 Subject: [PATCH] 1. Optimize the description of i2c_bus-related usage --- README.md | 4 +++ src/M5PM1_i2c_compat.h | 78 +++++++++++++++++++++++++++++++++--------- 2 files changed, 66 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 3f4f6e4..6fb2267 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,10 @@ If used alongside `M5Unified`, include it **before** `M5PM1`: > > Alternatively, enable `CONFIG_I2C_BUS_BACKWARD_CONFIG` in menuconfig to remove the restriction. +### i2c_bus mode is not supported when M5GFX / M5Unified is present + +Use `begin(&M5.In_I2C, addr, freq)` instead — M5GFX already owns the I2C bus and the two drivers cannot share it. + ## License - [M5PM1 - MIT](LICENSE) diff --git a/src/M5PM1_i2c_compat.h b/src/M5PM1_i2c_compat.h index 244eb98..b0b134e 100644 --- a/src/M5PM1_i2c_compat.h +++ b/src/M5PM1_i2c_compat.h @@ -142,9 +142,16 @@ static inline void M5PM1_I2C_ARDUINO_SEND_WAKE(TwoWire *wire, uint8_t addr) // → i2c_bus.h 内部回退到 driver/i2c.h，可安全使用 // // ESP-IDF >= 5.3.0 -// 启用 BACKWARD_CONFIG -// → i2c_bus.h 内部使用 driver/i2c.h，无冲突风险 -// 未启用 BACKWARD_CONFIG +// [最优先] 检测到 M5GFX 或 M5Unified 存在于项目中 +// → i2c_bus 模式无论 BACKWARD_CONFIG 是否启用均不可用，编译报错： +// · BACKWARD_CONFIG=y：i2c_bus.c 使用旧驱动 i2c_driver_install()， +// 与 M5GFX 的 i2c_new_master_bus()（driver_ng）冲突 → 运行时 abort() +// · BACKWARD_CONFIG=n：i2c_bus_v2.c 也使用 i2c_new_master_bus()， +// 与 M5GFX 争抢同一端口句柄 → 行为未定义 +// 解决方法：改用 pm1.begin(&M5.In_I2C, addr, freq) +// 启用 BACKWARD_CONFIG（无 M5GFX/M5Unified） +// → i2c_bus.h 内部使用 driver/i2c.h，与 M5GFX 不共存，可安全使用 +// 未启用 BACKWARD_CONFIG（无 M5GFX/M5Unified） // driver/i2c.h 已被其他组件提前包含（_DRIVER_I2C_H_ 已定义） // → i2c_bus.h 会自定义 i2c_config_t，与已定义的版本冲突 → 禁用 // driver/i2c.h 尚未被包含（_DRIVER_I2C_H_ 未定义） @@ -155,17 +162,19 @@ static inline void M5PM1_I2C_ARDUINO_SEND_WAKE(TwoWire *wire, uint8_t addr) // Without BACKWARD_CONFIG: i2c_bus not supported; use legacy driver/i2c.h API. // With BACKWARD_CONFIG: i2c_bus.h falls back to driver/i2c.h internally, safe to use. // ESP-IDF >= 5.3.0: -// With BACKWARD_CONFIG: i2c_bus.h uses driver/i2c.h internally, always conflict-free. -// Without BACKWARD_CONFIG: +// [Highest priority] M5GFX or M5Unified is present in the project: +// → i2c_bus mode is NEVER safe, compile error emitted: +// · BACKWARD_CONFIG=y: i2c_bus.c uses i2c_driver_install() (legacy); +// conflicts with M5GFX's i2c_new_master_bus() (driver_ng) → runtime abort() +// · BACKWARD_CONFIG=n: i2c_bus_v2.c also uses i2c_new_master_bus(), +// contends with M5GFX for the same port handle → undefined behaviour +// Fix: use pm1.begin(&M5.In_I2C, addr, freq) instead. +// With BACKWARD_CONFIG (no M5GFX/M5Unified): i2c_bus.h uses driver/i2c.h internally, safe. +// Without BACKWARD_CONFIG (no M5GFX/M5Unified): // _DRIVER_I2C_H_ defined (driver/i2c.h already included by another component) // → i2c_bus.h would define its own i2c_config_t, conflicting with the existing one → disabled. // _DRIVER_I2C_H_ not defined (driver/i2c.h not yet included) // → no conflict risk, enable i2c_bus with default config. -// -// Note: _DRIVER_I2C_H_ is the include guard of driver/i2c.h (ESP-IDF legacy I2C header). -// Checking it at preprocessor time reflects whether driver/i2c.h was included -// BEFORE this header. Inclusion after this header cannot be detected here; -// in that case the user is responsible for ensuring no conflict (or enabling BACKWARD_CONFIG). #if __has_include() #if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(5, 3, 0) #if defined(CONFIG_I2C_BUS_BACKWARD_CONFIG) @@ -175,14 +184,51 @@ static inline void M5PM1_I2C_ARDUINO_SEND_WAKE(TwoWire *wire, uint8_t addr) #endif #else // IDF >= 5.3.0 -#if defined(CONFIG_I2C_BUS_BACKWARD_CONFIG) -#define M5PM1_HAS_I2C_BUS 1 // BACKWARD_CONFIG：i2c_bus.h 使用 driver/i2c.h，无冲突 / no conflict -#elif defined(_DRIVER_I2C_H_) || (defined(__cplusplus) && __has_include()) +// +// ── 运行时冲突（优先级最高）────────────────────────────────────────────────── +// M5GFX 在全局构造阶段调用 i2c_new_master_bus()，将 I2C 端口注册为 driver_ng。 +// espressif__i2c_bus 的两条路径均与之冲突： +// · BACKWARD_CONFIG=y → i2c_bus.c 调用 i2c_driver_install()（旧驱动） +// ESP-IDF check_i2c_driver_conflict() 检测到新旧驱动共存 → abort() +// · BACKWARD_CONFIG=n → i2c_bus_v2.c 也调用 i2c_new_master_bus()，与 M5GFX 争抢 +// 同一端口的 bus_handle，行为未定义 +// 因此，只要 M5GFX 或 M5Unified 存在于项目中，i2c_bus 模式就必须禁用。 +// +// Runtime conflict (highest priority): +// M5GFX calls i2c_new_master_bus() (driver_ng) during global construction. +// espressif__i2c_bus conflicts with it on both code paths: +// · BACKWARD_CONFIG=y → i2c_bus.c calls i2c_driver_install() (legacy driver); +// check_i2c_driver_conflict() detects the clash → abort() +// · BACKWARD_CONFIG=n → i2c_bus_v2.c also calls i2c_new_master_bus(), competing +// with M5GFX for the same port bus_handle → undefined behaviour +// Therefore, i2c_bus mode MUST be disabled whenever M5GFX or M5Unified is in the project. +// ───────────────────────────────────────────────────────────────────────────── +#if __has_include() || __has_include() +// M5GFX registers driver_ng via i2c_new_master_bus() during global construction. +// espressif__i2c_bus conflicts with it on both code paths: +// BACKWARD_CONFIG=y: i2c_bus.c calls i2c_driver_install() (legacy) → runtime abort() +// BACKWARD_CONFIG=n: i2c_bus_v2.c calls i2c_new_master_bus() again → port handle contention +// Detection: if the user placed '#include ' before '#include ', +// _I2C_BUS_H_ is already defined here and we can emit a clear error. +// If not, the begin(i2c_bus_handle_t,...) overload silently disappears and the compiler +// will report 'no matching function for call to begin()' at the call site. +#if defined(_I2C_BUS_H_) +#error \ + "[M5PM1] i2c_bus cannot be used together with M5GFX/M5Unified. " \ + "M5GFX registers driver_ng via i2c_new_master_bus() during global construction. " \ + "BACKWARD_CONFIG=y: i2c_bus.c calls i2c_driver_install() (legacy driver) -> runtime abort() in check_i2c_driver_conflict(). " \ + "BACKWARD_CONFIG=n: i2c_bus_v2.c calls i2c_new_master_bus() on the same port -> undefined behaviour. " \ + "Fix: use pm1.begin(&M5.In_I2C, addr, freq) and set I2C_USE_MODE=0." +#endif +#define M5PM1_HAS_I2C_BUS 0 +// ── 编译期头文件冲突（无 M5GFX/M5Unified）────────────────────────────────── +#elif defined(CONFIG_I2C_BUS_BACKWARD_CONFIG) +#define M5PM1_HAS_I2C_BUS 1 // BACKWARD_CONFIG，无 M5GFX/M5Unified：兼容 / compatible without M5GFX/M5Unified +#elif defined(_DRIVER_I2C_H_) #define M5PM1_HAS_I2C_BUS \ - 0 // driver/i2c.h 已包含或 M5Unified 可用（将包含 driver/i2c.h）→ i2c_config_t 冲突风险，禁用 - // driver/i2c.h already included or M5Unified available (will include driver/i2c.h) → conflict risk, disabled + 0 // driver/i2c.h 已包含 → i2c_config_t 重复定义风险，禁用 / driver/i2c.h already included → typedef conflict risk #else -#define M5PM1_HAS_I2C_BUS 1 // driver/i2c.h 尚未包含，无冲突风险 / driver/i2c.h not yet included, no conflict +#define M5PM1_HAS_I2C_BUS 1 // 无冲突风险 / no conflict risk #endif #endif #else