Merge branch 'develop'

Author: GOB52

.github/workflows/arduino-m5-build-check.yml

@@ -80,7 +80,7 @@ jobs:
           - m5stack_dinmeter
           - m5stack_fire
           - m5stack_nano_c6
-#          - m5stack_nano_h2
+          - m5stack_nano_h2
           - m5stack_paper
           - m5stack_papers3
 #          - m5stack_poe_cam

.github/workflows/platformio-build-check.yml

@@ -71,6 +71,7 @@ jobs:
           - AtomS3
           - AtomS3R
           - NanoC6
+          - NanoH2
           - StickCPlus
           - StickCPlus2
           - StickS3

.gitignore

@@ -37,8 +37,19 @@ docs/html/
 # PlatformIO
 .pio/
 
+# ESP-IDF (idf.py) build artifacts
+build/
+managed_components/
+sdkconfig
+sdkconfig.old
+dependencies.lock
+
 # IDE
 .vscode/
+.clangd
+
+# clangd index cache
+.cache/
 
 # macOS
 .DS_Store

README.md

@@ -6,14 +6,25 @@ Library for M5Stack light-related units using [M5UnitUnified](https://github.com
 M5UnitUnified is a library for unified handling of various M5 units products.
 
 ### SKU:U136
-Unit DLight is a digital ambient light detection sensor that uses the BH1750FVI illuminance sensor IC (I2C interface). It has a built-in 16-bit AD converter supporting illuminance value detection ranging from 1 to 65535 lx. It is characterized by its small size and low power consumption, making it suitable for various illuminance detection and light control adjustment scenarios.
+Unit DLight is a digital ambient light detection sensor. The hardware uses a BH1750FVI illuminance sensor IC (I2C interface), with built-in 16-bit AD conversion supporting (1 ~ 65535 lx) illuminance value detection. It features a small size and low power consumption, making it suitable for various illuminance detection and light control adjustment scenarios.
 
 ### SKU:U134
 Hat DLight is a digital ambient light detection sensor compatible with the M5StickC/C Plus series. The hardware uses the BH1750FVI illuminance sensor IC (I2C interface), with a built-in 16-bit AD converter, supporting illuminance value detection from 1 to 65535 lx. It features a small size and low power consumption, making it suitable for various illuminance detection and light control adjustment scenarios.
 
 ### SKU:U021
 Unit Light is a light intensity detection sensor. It integrates a photoresistor and a 10K adjustable resistor, capable of detecting light intensity and setting a light intensity threshold. The resistance of the photoresistor decreases as the incident light intensity increases, thus detecting the change in voltage, and obtaining light intensity data through AD conversion. To achieve more accurate light intensity measurements, this Unit also adopts the LM393 dual differential comparator, used to compare the differential voltage between the photoresistor and the varistor.
 
+#### Analog reading notes (chip-generation dependent)
+
+Raw ADC values from `unit.analog()` are **not directly comparable across boards** because ESP32 ADC characteristics differ by chip generation:
+
+- **ESP32 classic** (Core / Fire / StickCPlus 等): ATTEN_DB_11 is non-linear above ~2.45 V; dark readings tend to saturate near 4095 due to ADC compression, not true full-scale.
+- **ESP32-C6 / -H2 / -S3 / -P4** (NanoC6 / NanoH2 / CoreS3 / StickS3 / Tab5): ATTEN_DB_12 is linear across 0–3.3 V; the same physical light level yields a lower raw value (~3900) than on ESP32 classic — this is the more accurate reading.
+
+Reference: [Espressif Developer Blog — Comparing ADC Performance of Espressif SoCs (2025-08)](https://developer.espressif.com/blog/2025/08/adc-performance/)
+
+**Always calibrate per board** via `unit.calibrateDark()` / `unit.calibrateBright()` (BtnA click / hold in `PlotToSerial` example) so that `unit.normalized()` returns a portable 0–100 % value regardless of chip.
+
 ## Related Link
 See also examples using conventional methods here.
 

boards/m5stack-nanoc6.json

@@ -2,7 +2,7 @@
     "build": {
 	"core": "esp32",
         "extra_flags": [
-            "-DARDUINO_M5STACK_NANOC6"
+            "-DARDUINO_M5STACK_NANO_C6"
         ],
 	"f_cpu": "160000000L",
 	"f_flash": "80000000L",

boards/m5stack-nanoh2.json

@@ -0,0 +1,34 @@
+{
+    "build": {
+        "core": "esp32",
+        "extra_flags": [
+            "-DARDUINO_M5STACK_NANO_H2"
+        ],
+        "f_cpu": "96000000L",
+        "f_flash": "16000000L",
+        "flash_mode": "qio",
+        "mcu": "esp32h2",
+        "variant": "esp32h2"
+    },
+    "connectivity": [
+        "bluetooth",
+        "zigbee"
+    ],
+    "debug": {
+        "openocd_target": "esp32h2.cfg"
+    },
+    "frameworks": [
+        "arduino",
+        "espidf"
+    ],
+    "name": "M5Stack NanoH2",
+    "upload": {
+        "flash_size": "4MB",
+        "maximum_ram_size": 327680,
+        "maximum_size": 4194304,
+        "require_upload_port": true,
+        "speed": 460800
+    },
+    "url": "https://docs.m5stack.com/en/core/NanoH2",
+    "vendor": "M5Stack"
+}

examples/UnitUnified/UnitDLight/PlotToSerial/main/PlotToSerial.cpp

@@ -12,13 +12,13 @@
   BtnA hold:  cycle resolution Low -> High -> High2 (also re-measures
               for instant feedback in either mode)
 */
+#include <driver/gpio.h>
 #include <M5Unified.h>
 #include <M5UnitUnified.h>
 #include <M5UnitUnifiedLIGHT.h>
-#include <Wire.h>
-#include <M5HAL.hpp>  // For NessoN1
-#include <cmath>      // std::isnan
-#include <limits>     // std::numeric_limits
+#include <wiring/m5_unit_unified_wiring.hpp>  // Board-aware connection helpers (include last)
+#include <cmath>                              // std::isnan
+#include <limits>                             // std::numeric_limits
 
 // *************************************************************
 // Choose one define symbol to match the unit you are using
@@ -153,51 +153,17 @@ void draw_status()
     canvas.pushSprite(0, 0);
 }
 
-#if defined(USING_HAT_DLIGHT)
-struct I2cPins {
-    int sda;
-    int scl;
-};
-
-I2cPins get_hat_i2c_pins(const m5::board_t board)
-{
-    switch (board) {
-        case m5::board_t::board_M5StickC:
-        case m5::board_t::board_M5StickCPlus:
-        case m5::board_t::board_M5StickCPlus2:
-            return {0, 26};
-        case m5::board_t::board_M5StickS3:
-            return {8, 0};
-        case m5::board_t::board_M5StackCoreInk:
-            return {25, 26};
-        case m5::board_t::board_ArduinoNessoN1:
-            return {6, 7};
-        default:
-            return {-1, -1};
-    }
-}
-#endif
-
 }  // namespace
 
 void setup()
 {
-    auto m5cfg{M5.config()};
-#if defined(USING_HAT_DLIGHT)
-    m5cfg.pmic_button  = false;  // Disable BtnPWR on StickC series
-    m5cfg.internal_imu = false;
-    m5cfg.internal_rtc = false;
-#endif
-
-    M5.begin(m5cfg);
+    M5.begin();
     M5.setTouchButtonHeightByRatio(100);
 
     if (lcd.height() > lcd.width()) {
         lcd.setRotation(1);
     }
 
-    auto board{M5.getBoard()};
-
     // Prioritize response speed over resolution so brief lighting changes
     // (e.g. a flash) are tracked in near-real-time.
     // Low-res + MTREG_MIN = 24 * 31 / 69 ~= 11ms per sample (4 lx resolution).
@@ -210,61 +176,19 @@ void setup()
     }
 
 #if defined(USING_HAT_DLIGHT)
-    const auto pins{get_hat_i2c_pins(board)};
-    M5_LOGI("getHatPin: SDA:%d SCL:%d", pins.sda, pins.scl);
-    if (pins.sda < 0 || pins.scl < 0) {
-        M5_LOGE("Illegal pin number");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
-    }
-
-    pinMode(pins.scl, OUTPUT);
-
-    auto& wire{(board == m5::board_t::board_ArduinoNessoN1) ? Wire1 : Wire};
-    wire.end();
-    wire.begin(pins.sda, pins.scl, 400 * 1000U);
-    //    m5::utility::delay(50);  // Allow BH1750 VCC rails to settle after Wire.begin().
-    if (!Units.add(unit, wire) || !Units.begin()) {
+    // HatDLight: NessoN1 uses Wire1, other StickC-family boards use Wire.
+    // Drive SCL as OUTPUT before bus init (some boards leave it floating on reset).
+    const auto pins = m5::unit::wiring::hatI2CPins();
+    gpio_set_direction(static_cast<gpio_num_t>(pins.scl), GPIO_MODE_OUTPUT);
+    if (!m5::unit::wiring::addHatI2C(Units, unit, 400 * 1000U) || !Units.begin()) {
         M5_LOGE("Failed to begin");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
+        m5::unit::wiring::failStop();
     }
 #else
-    // NessoN1: Use SoftwareI2C via M5HAL for GROVE port.
-    // NanoC6: Use M5.Ex_I2C (m5::I2C_Class) directly.
-    bool unit_ready{};
-    if (board == m5::board_t::board_ArduinoNessoN1) {
-        auto pin_num_sda{M5.getPin(m5::pin_name_t::port_b_out)};
-        auto pin_num_scl{M5.getPin(m5::pin_name_t::port_b_in)};
-        M5_LOGI("getPin(M5HAL): SDA:%d SCL:%d", pin_num_sda, pin_num_scl);
-        m5::hal::bus::I2CBusConfig i2c_cfg;
-        i2c_cfg.pin_sda = m5::hal::gpio::getPin(pin_num_sda);
-        i2c_cfg.pin_scl = m5::hal::gpio::getPin(pin_num_scl);
-        auto i2c_bus{m5::hal::bus::i2c::getBus(i2c_cfg)};
-        M5_LOGI("Bus:%d", i2c_bus.has_value());
-        unit_ready = Units.add(unit, i2c_bus ? i2c_bus.value() : nullptr) && Units.begin();
-    } else if (board == m5::board_t::board_M5NanoC6) {
-        M5_LOGI("Using M5.Ex_I2C");
-        unit_ready = Units.add(unit, M5.Ex_I2C) && Units.begin();
-    } else {
-        auto pin_num_sda{M5.getPin(m5::pin_name_t::port_a_sda)};
-        auto pin_num_scl{M5.getPin(m5::pin_name_t::port_a_scl)};
-        M5_LOGI("getPin: SDA:%d SCL:%d", pin_num_sda, pin_num_scl);
-        Wire.end();
-        Wire.begin(pin_num_sda, pin_num_scl, 400 * 1000U);
-        //        m5::utility::delay(50);  // Allow BH1750 VCC rails to settle after Wire.begin().
-        unit_ready = Units.add(unit, Wire) && Units.begin();
-    }
-    if (!unit_ready) {
+    // UnitDLight: NessoN1 -> SoftwareI2C (M5HAL), NanoC6 / NanoH2 -> M5.Ex_I2C, others -> Wire
+    if (!m5::unit::wiring::addI2C(Units, unit, 400 * 1000U) || !Units.begin()) {
         M5_LOGE("Failed to begin");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
+        m5::unit::wiring::failStop();
     }
 #endif
 

examples/UnitUnified/UnitLight/PlotToSerial/main/PlotToSerial.cpp

@@ -12,6 +12,7 @@
 #include <M5Unified.h>
 #include <M5UnitUnified.h>
 #include <M5UnitUnifiedLIGHT.h>
+#include <wiring/m5_unit_unified_wiring.hpp>  // Board-aware connection helpers (include last)
 
 namespace {
 auto& lcd = M5.Display;
@@ -23,25 +24,6 @@ m5::unit::UnitLight unit;
 constexpr uint32_t DRAW_INTERVAL_MS{200};
 uint32_t last_draw_ms{0};
 
-struct IoPins {
-    int rx;
-    int tx;
-};
-
-IoPins get_gpio_pins(const m5::board_t board)
-{
-    // Port.B on M5Core family (analog=in, digital=out on U021 layout)
-    auto rx{M5.getPin(m5::pin_name_t::port_b_in)};
-    auto tx{M5.getPin(m5::pin_name_t::port_b_out)};
-    if (rx >= 0 && tx >= 0) {
-        return {rx, tx};
-    }
-    // Fallback to Port.A (use SCL as analog input, SDA as digital input on Grove).
-    rx = M5.getPin(m5::pin_name_t::port_a_scl);
-    tx = M5.getPin(m5::pin_name_t::port_a_sda);
-    return {rx, tx};
-}
-
 void draw_status()
 {
     // Skip drawing on boards without a display (Atom / AtomLite / StampS3 / NanoC6 etc.)
@@ -91,31 +73,17 @@ void draw_status()
 
 void setup()
 {
-    auto m5cfg{M5.config()};
-    M5.begin(m5cfg);
+    M5.begin();
     M5.setTouchButtonHeightByRatio(100);
 
     if (lcd.height() > lcd.width()) {
         lcd.setRotation(1);
     }
 
-    const auto board{M5.getBoard()};
-    const auto pins{get_gpio_pins(board)};
-    M5_LOGI("UnitLight pins: RX=%d (analog) TX=%d (digital)", pins.rx, pins.tx);
-    if (pins.rx < 0 || pins.tx < 0) {
-        M5_LOGE("No GPIO pins available for this board (%u)", static_cast<unsigned>(board));
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
-    }
-
-    if (!Units.add(unit, pins.rx, pins.tx) || !Units.begin()) {
+    // U021 uses both analog input (rx) and digital comparator output (tx); PortB preferred, PortA fallback.
+    if (!m5::unit::wiring::addGPIO(Units, unit) || !Units.begin()) {
         M5_LOGE("Failed to begin");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
+        m5::unit::wiring::failStop();
     }
 
     // Prepare off-screen canvas: 1-bit depth, no PSRAM — keeps flicker and memory footprint low.

examples/UnitUnified/UnitLight/ViaPbHub/main/ViaPbHub.cpp

@@ -13,9 +13,9 @@
 */
 #include <M5Unified.h>
 #include <M5UnitUnified.h>
-#include <M5HAL.hpp>
 #include <M5UnitUnifiedLIGHT.h>
-#include <M5UnitUnifiedHUB.h>  // UnitPbHub
+#include <M5UnitUnifiedHUB.h>                 // UnitPbHub
+#include <wiring/m5_unit_unified_wiring.hpp>  // Board-aware connection helpers (include last)
 
 namespace {
 auto& lcd = M5.Display;
@@ -82,51 +82,13 @@ void setup()
 
     if (!hub.add(unit, 3)) {  // PbHub ch:3 -> UnitLight
         M5_LOGE("Failed to add children");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
+        m5::unit::wiring::failStop();
     }
 
-    auto board = M5.getBoard();
-
-    // NessoN1: Arduino Wire (I2C_NUM_0) cannot be used for GROVE port.
-    //   Wire is used by M5Unified In_I2C for internal devices.
-    //   Reconfiguring Wire to GROVE pins breaks In_I2C.
-    //   Solution: Use SoftwareI2C via M5HAL for the GROVE port.
-    // NanoC6: Wire.begin() on GROVE pins conflicts with m5::I2C_Class
-    //   registered by Ex_I2C.setPort() on the same I2C_NUM_0.
-    //   Solution: Use M5.Ex_I2C directly instead of Arduino Wire.
-    bool unit_ready{};
-    if (board == m5::board_t::board_ArduinoNessoN1) {
-        // NessoN1: GROVE is port_b (port_a is reserved for internal use)
-        auto pin_num_sda = M5.getPin(m5::pin_name_t::port_b_out);
-        auto pin_num_scl = M5.getPin(m5::pin_name_t::port_b_in);
-        M5_LOGI("getPin(M5HAL): SDA:%u SCL:%u", pin_num_sda, pin_num_scl);
-        m5::hal::bus::I2CBusConfig i2c_cfg;
-        i2c_cfg.pin_sda = m5::hal::gpio::getPin(pin_num_sda);
-        i2c_cfg.pin_scl = m5::hal::gpio::getPin(pin_num_scl);
-        auto i2c_bus    = m5::hal::bus::i2c::getBus(i2c_cfg);
-        M5_LOGI("Bus:%d", i2c_bus.has_value());
-        unit_ready = Units.add(hub, i2c_bus ? i2c_bus.value() : nullptr) && Units.begin();
-    } else if (board == m5::board_t::board_M5NanoC6) {
-        M5_LOGI("Using M5.Ex_I2C");
-        unit_ready = Units.add(hub, M5.Ex_I2C) && Units.begin();
-    } else {
-        auto pin_num_sda = M5.getPin(m5::pin_name_t::port_a_sda);
-        auto pin_num_scl = M5.getPin(m5::pin_name_t::port_a_scl);
-        M5_LOGI("getPin: SDA:%u SCL:%u", pin_num_sda, pin_num_scl);
-        Wire.end();
-        Wire.begin(pin_num_sda, pin_num_scl, 400000U);
-        unit_ready = Units.add(hub, Wire) && Units.begin();
-    }
-
-    if (!unit_ready) {
+    // UnitPbHub: NessoN1 -> SoftwareI2C (M5HAL), NanoC6 / NanoH2 -> M5.Ex_I2C, others -> Wire
+    if (!m5::unit::wiring::addI2C(Units, hub, 400 * 1000U) || !Units.begin()) {
         M5_LOGE("Failed to begin");
-        lcd.fillScreen(TFT_RED);
-        while (true) {
-            m5::utility::delay(10000);
-        }
+        m5::unit::wiring::failStop();
     }
 
     // Prepare off-screen canvas: 1-bit depth, no PSRAM — keeps flicker and memory footprint low.