# ES3C28P Official Battery Pin — From ~/Downloads Documentation

## Source
`~/Downloads/2.8inch_IPS_ESP32-S3_ILI9341V_ES3C28P_ES3N28P_V1.0/`
- `5-原理图_Schematic/2.8inch_ESP32-S3_Display_Schematic.pdf` — BAT_ADC net, TP4054 charger IC C668215, divider 100k/100k
- `1-示例程序_Demo/Arduino/Demo/Example_13_Get_Battery_Voltage/GetBatteryVoltage/GetBatteryVoltage.ino`
- `5-原理图_Schematic/ESP32-S3芯片IO资源分配表.xlsx` (binary xlsx)
- User MicroPython: `/Users/adolforeyna/Projects/MicroPython/test1/Screen/lib/battery_util.py` BatteryMonitor(pin_num=9)

## Official Mapping
- **GPIO9 = ADC1 Channel 8**
- Config: `ADC_UNIT_1`, `ADC_CHANNEL_8`, `ADC_ATTEN_DB_12`, `ADC_BITWIDTH_12`, curve-fitting calibration `adc_cali_create_scheme_curve_fitting`
- Divider: 2x (`vol * 2` in Arduino, `(uv/1e6)*2.0` or `(raw/4095)*3.3*2.0` in MicroPython)
- Voltage to %:
  - Arduino official: `<=2500 → 0%`, `2500-4200 → (v-2500)/17`, `>4200 → 100%`
  - MicroPython: linear 3.0V-4.2V `(voltage - 3.0)/(4.2-3.0)*100`
- Tactility final impl uses official thresholds 2500/4200 with division by 17 to match LCDWIKI demo

## Schematic Extraction
From PDF text extraction (pymupdf):
- BAT+, BAT_ADC, BAT_GND nets
- TP4054, ADCVREF, Battery charge and discharge, Battery level
- GPIO list includes GPIO9 among free pins

## Conflict Note
- ES3C28P DTS: I2S `pin-bclk = GPIO5`, so GPIO9 free — OK for battery
- Waveshare RLCD DTS: I2S `pin-bclk = GPIO9` — CONFLICTS with BAT_ADC. Cannot use same GPIO for both audio BCLK and battery ADC. Must check `waveshare,esp32-s3-rlcd.dts` before porting battery driver to RLCD variant.

## Implementation Reference
`Devices/es3c28p/Source/devices/Power.cpp`:
- `adc_oneshot_new_unit`, `adc_oneshot_config_channel(ADC_CHANNEL_8)`, `adc_cali_create_scheme_curve_fitting`
- `adc_oneshot_read` → `adc_cali_raw_to_voltage` → `vbat_mv = mv * 2`
- `supportsMetric` for BatteryVoltage, ChargeLevel, IsCharging
- `IsCharging` heuristic: <500mV (no battery, USB powered) → true; >4350mV (above Li-ion max) → true; else false (no PMIC CHG pin wired)

## Build Requirements
- `Devices/es3c28p/CMakeLists.txt` needs `REQUIRES ... esp_adc` (not just driver)
- No try/catch (-fno-exceptions), use error code checks

## Verification
Ad-hoc script under `/var/folders/3j/.../T/hermes-verify-*.py`:
- Contains ADC_CHANNEL_8, ADC_ATTEN_DB_12, vol * 2, 2500, 4200
- Contains BatteryVoltage, ChargeLevel, IsCharging
- `Configuration.cpp` contains createPower()
- `View.h` does NOT contain battery_label, `View.cpp` does NOT contain Battery:
- `Statusbar.cpp` has statusbar_set_battery_text
- build/Tactility.bin >2MB