m5::unit::UnitLight Class Reference

Analog light-level detector with a comparator threshold output (U021) More...

#include <unit_Light.hpp>

Inheritance diagram for m5::unit::UnitLight:

Classes
struct	config_t
	Settings for begin. More...

Public Member Functions
	UnitLight (const uint8_t addr=DEFAULT_ADDRESS)
	Constructor.
virtual	~UnitLight ()
	Destructor.
virtual bool	begin () override
	Begin the unit (configures RX as analog input, TX as digital input)
virtual void	update (const bool force=false) override
	Update the unit.
Settings for begin
config_t	config () const
	Gets the configuration.
void	config (const config_t &cfg)
	Set the configuration.
Measurement data by periodic
uint16_t	analog () const
	Latest analog raw value.
bool	digital () const
	Latest digital threshold output.
float	normalized () const
	Latest normalized light level (0..100), recomputed against the current calibration.
Periodic measurement
bool	startPeriodicMeasurement ()
	Start periodic measurement in the current settings.
bool	startPeriodicMeasurement (const uint32_t interval_ms)
	Start periodic measurement.
bool	stopPeriodicMeasurement ()
	Stop periodic measurement.
Calibration
bool	calibrateDark ()
	Record the current analog reading as the dark reference.
bool	calibrateBright ()
	Record the current analog reading as the bright reference.
void	setCalibration (const uint16_t dark, const uint16_t bright)
	Set dark/bright references explicitly.
void	resetCalibration ()
	Reset calibration (dark=0, bright=4095)
uint16_t	dark () const
	Current dark reference.
uint16_t	bright () const
	Current bright reference.

Protected Member Functions
bool	start_periodic_measurement ()
bool	start_periodic_measurement (const uint32_t interval_ms)
bool	stop_periodic_measurement ()
bool	read_measurement (light::Data &data)
	M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER (UnitLight, light::Data)

Protected Attributes
std::unique_ptr< m5::container::CircularBuffer< light::Data > >	_data {}
config_t	_cfg {}
uint16_t	_dark {0}
uint16_t	_bright {4095}

Detailed Description

Analog light-level detector with a comparator threshold output (U021)

Constructor & Destructor Documentation

UnitLight()

m5::unit::UnitLight::UnitLight ( const uint8_t addr = DEFAULT_ADDRESS )

inlineexplicit

Constructor.

Parameters

addr	Placeholder (GPIO unit; address is ignored)

Member Function Documentation

analog()

uint16_t m5::unit::UnitLight::analog ( ) const

inline

Latest analog raw value.

Returns

Raw ADC value (0 if no data)

Note

Raw ADC is chip-generation dependent: ESP32 classic saturates near 4095 (non-linear above ~2.45 V), while ESP32-C6/H2/S3/P4 read linearly up to 3.3 V (so dark values may not reach 4095 on those chips). Use normalized() with calibrateDark()/calibrateBright() for portable 0-100% readings. See: https://developer.espressif.com/blog/2025/08/adc-performance/

begin()

bool m5::unit::UnitLight::begin ( )

overridevirtual

Begin the unit (configures RX as analog input, TX as digital input)

Returns

True if successful

bright()

uint16_t m5::unit::UnitLight::bright ( ) const

inline

Current bright reference.

Returns

Bright reference ADC value

calibrateBright()

bool m5::unit::UnitLight::calibrateBright

(

)

Record the current analog reading as the bright reference.

Returns

True if successful

Note

Calibration is stored in RAM only; persistence is the user's responsibility.

calibrateDark()

bool m5::unit::UnitLight::calibrateDark

(

)

Record the current analog reading as the dark reference.

Returns

True if successful

Note

Calibration is stored in RAM only; persistence is the user's responsibility.

config() [1/2]

config_t m5::unit::UnitLight::config ( ) const

inline

Gets the configuration.

Returns

Current configuration

config() [2/2]

void m5::unit::UnitLight::config ( const config_t & cfg )

inline

Set the configuration.

Parameters

cfg	Configuration to apply

dark()

uint16_t m5::unit::UnitLight::dark ( ) const

inline

Current dark reference.

Returns

Dark reference ADC value

digital()

bool m5::unit::UnitLight::digital ( ) const

inline

Latest digital threshold output.

Returns

Comparator output (false if no data)

Note

Comparator output polarity depends on board revision / trimpot setting; do not assume true == bright.

normalized()

float m5::unit::UnitLight::normalized ( ) const

inline

Latest normalized light level (0..100), recomputed against the current calibration.

Returns

Normalized percentage (NaN if no data or dark == bright)

Note

Uses the currently configured _dark / _bright references rather than the values stored at measurement time, so calibrateDark/Bright/setCalibration/resetCalibration affect the next normalized() call immediately (no stale buffered output).

resetCalibration()

void m5::unit::UnitLight::resetCalibration

(

)

Reset calibration (dark=0, bright=4095)

Note

Calibration is stored in RAM only; persistence is the user's responsibility.

setCalibration()

void m5::unit::UnitLight::setCalibration	(	const uint16_t	dark,
		const uint16_t	bright )

Set dark/bright references explicitly.

Parameters

dark	Dark reference (ADC value measured under covered sensor)
bright	Bright reference (ADC value measured under bright exposure)

Note

Calibration is stored in RAM only; persistence is the user's responsibility.

startPeriodicMeasurement() [1/2]

bool m5::unit::UnitLight::startPeriodicMeasurement ( )

inline

Start periodic measurement in the current settings.

Returns

True if successful

startPeriodicMeasurement() [2/2]

bool m5::unit::UnitLight::startPeriodicMeasurement ( const uint32_t interval_ms )

inline

Start periodic measurement.

Parameters

interval_ms

Sampling interval in milliseconds

Returns

True if successful

stopPeriodicMeasurement()

bool m5::unit::UnitLight::stopPeriodicMeasurement ( )

inline

Stop periodic measurement.

Returns

True if successful

update()

void m5::unit::UnitLight::update ( const bool force = false )

overridevirtual

Update the unit.

Parameters

force

If true, force a read regardless of the interval