Library for M5Stack light-related units using M5UnitUnified. M5UnitUnified is a library for unified handling of various M5 units products.
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.
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.
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.
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 etc.): the effective measurement range is 150–2450 mV, so readings near full scale are compressed.
- ESP32-S3 (CoreS3 / StickS3 etc.): 0–2900 mV, non-linear above ~2750 mV (*).
- ESP32-C6 / -H2 / -P4 (NanoC6 / NanoH2 / Tab5): 0–3300 mV.
The ranges are the effective measurement range at the highest attenuation (ATTEN3) in the ADC Calibration Results table of each datasheet: ESP32 (v5.3, Table 4-4), ESP32-S3 (v2.2, Table 5-6), ESP32-C6 (v1.5, Table 5-6), ESP32-H2 (v1.3, Table 5-5), ESP32-P4 (v0.7, Table 5-6).
(*) Measured by Espressif, not in the datasheet: Espressif Developer Blog — Comparing ADC Performance of Espressif SoCs (2025-08)
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.
Board-specific wiring notes:
- Core Basic: connect the unit to PortB on the M5GO bottom. PortA (G21 / G22) has no ADC on the analog pin.
- StampS3: the analog input is on PortA G15, which is ADC2. On ESP32-S3, ADC2 reads can fail while Wi-Fi / Bluetooth is active.
See also examples/UnitUnified
You must choose a define symbol for the unit you will use. (Uncomment the corresponding #define in the example, or specify it with compile options.)
- UnitDLight / HatDLight (PlotToSerial)
// *************************************************************
// Choose one define symbol to match the unit you are using
// *************************************************************
#if !defined(USING_UNIT_DLIGHT) && !defined(USING_HAT_DLIGHT)
// For UnitDLight (U136)
// #define USING_UNIT_DLIGHT
// For HatDLight (U134)
// #define USING_HAT_DLIGHT
#endifNOTE: The ESP-IDF native build (
idf.py) targets ESP-IDF 5.1 or later (5.x and 6.x).
NOTE: On NessoN1, the Hat port (ESP32-C6 LP I2C) needs ESP-IDF 5.3 or later (Arduino: Arduino-ESP32 3.2 or later).
- UnitDLight / HatDLight (PlotToSerial)
Choose the unit withidf.py menuconfig→M5Unit-LIGHT example→Target unit(Unit DLightis the default).common/variant.cmakemaps the choice toUSING_UNIT_DLIGHT/USING_HAT_DLIGHT, so you do not need to edit the source.
cd examples/UnitUnified/UnitDLight/PlotToSerial
idf.py set-target esp32s3 # or esp32 / esp32c5 / esp32c6 / esp32h2 / esp32p4 / ...
idf.py menuconfig
idf.py build flash monitor- UnitDLight (ViaPaHub) / UnitLight (PlotToSerial / ViaPbHub)
These examples need no Kconfig choice. Build them directly in the same way.
Support via PaHub
| Unit | Support | Note |
|---|---|---|
| UnitDLight | OK |
Support via PbHub
| Unit | Support | Note |
|---|---|---|
| UnitLight | OK |
See also the ViaPaHub / ViaPbHub examples and M5Unit-HUB
If you want to generate documents on your local machine, execute the following command
bash docs/doxy.sh
It will output it under docs/html
If you want to output Git commit hashes to html, do it for the git cloned folder.