ADC Sampling State and Resource Release
This page corresponds to the 2026-10-04 successor candidate in the main repository. Implementation and test preparation are complete; centralized host/native/nine-environment verification is still pending and must not be read as the device firmware being updated. Actual calibration, memory recovery, and long-term stability remain to be accepted.
For parameters and wiring, see ADC Analog Input.
How to Interpret Readings
A valid zero and a read failure must be distinguished: a zero from a successful sample is kept as a numeric value; when the SDK read fails, rawValue is null, the engineering value is invalid, and the quality is read_failed. A failed calibration conversion may keep the sampled raw value, but the engineering value is still invalid and cannot be used for rule thresholds or pass/fail measurement decisions. Low/high-range quality still means the real sample exceeded the configured range; it is not automatically passed off as a valid endpoint.
HTTP analog-input readings, protocol reports, and actuators all derive raw, voltage, engineering value, and quality from the same batch of samples. Chip calibration takes no additional samples and is not the same as traceable calibration of the sensor or meter. The legacy sensor paths for current, voltage, NTC, and current loop (sensorType 4..7) also check the whole batch read; a mid-batch failure invalidates the result.
Why the Pin Is Still Reserved After Disabling
One ADC unit can be shared by multiple channels. The current SDK has no interface to delete a single channel, so after one configuration is removed, the configured channel/pin stays reserved until the last consumer exits, as long as other samplers remain on the same unit. Runtime resource information shows unit, channel, and consumer separately; do not judge resource release by configuration count alone.
PM ADC uses a persistent lease on the actual peripheral ID; legacy sensor sampling uses a temporary lease with the Sensor role on the actual pin, released after non-cached reads, and does not generate fake peripheral IDs. SDK acquire, configure, sample, or release failures are reported explicitly; partial allocation or cleanup failures keep possibly still-valid resources to prevent reuse by other GPIO/PWM/DAC/NeoPixel. A failed temporary lease requires a controlled restart after troubleshooting; it is not implicitly cleared by repeated sampling.
Project pin admission also checks other PM-managed drivers and Arduino periman; when another owner is detected, its resources are not torn down automatically. Third-party SDK/GPIO reconfiguration that bypasses the project manager is outside the proven global concurrency protection.
Configuration Compatibility and Physical Acceptance
The candidate fixes hardware sampling at 12 bit; the configured 9-12 bits are derived from the same raw by right shift. Classic ESP32 previously changed the native hardware resolution, so legacy calibration, noise, and range need re-acceptance. Calibration converts the same filtered sample and cannot recover already-discarded low bits.
The calibration scheme depends on the chip; when unsupported, uncalibrated, ADC2 is occupied by Wi-Fi, or the SDK rejects it, the failure must be reported — do not substitute zero or an assumed vRef for "calibration success". The resource snapshot is zero-wait and does not start the ADC; busy means not observed this time; the count is not memory bytes and does not cover unregistered third-party drivers.
No device, serial port, field configuration, or physical output has been operated. Continuing acceptance requires confirming the specific firmware, device identity, and safe wiring, testing with known voltage/current sources, and keeping separate records for ADC2/Wi-Fi, abnormal wiring, memory recovery, and 24h/7d logs; passing software tests does not replace these results.