Electronics

• ESP32 x1 - Microcontroller — runs the ADC pipeline and OLED render loop
• 0.96" I2C OLED display, SSD1306, 128×64 x1 - Displays battery health, voltage, and status
• 9V battery x1 - System power source
• 0.1µF ceramic capacitor - Decouples ADC sampling spikes on GPIO 34

Enclosure Materials

• Corrugated cardboard sheet - Main enclosure body
• Colored paper (yellow, brown, or any color of choice) - Outer wrap and trim
• White school glue (PVA) or hot-glue gun - Assembly
• Ruler, pencil, scissors, box cutter - Cutting and marking
• Black marker or acrylic paint - Detailing and trim

Software

• Arduino IDE v2.x - Code editor and uploader
• U8g2 library (by Oliver Kraus) - OLED display driver
• ESP32 Arduino core (includes esp_adc_cal) - ADC calibration driver
• Lopaka (lopaka.app, browser-based) - Pixel UI editor — used to design the UI

All grounds in this project must connect to the ESP32 GND pin:

• OLED GND
• AA holder negative terminal
• 9V snap negative wire

Voltage is measured as a difference between two points. If the AA's negative terminal is not tied to the ESP32's ground, the reading will be garbage.

The 0.1µF Capacitor

The ESP32's ADC uses an internal sample-and-hold capacitor that charges in a fraction of a microsecond. When reading a fresh AA (low internal resistance), this causes a brief voltage spike — a 1.6V battery can sample as 2.5V or 3V. The 0.1µF ceramic cap acts as a local energy reservoir, absorbing the spikes before they reach the ADC.

Solder the capacitor as close to the ESP32's GPIO 34 pin as physically possible. Do not skip this component.

NOTE : The first version i made, I didn't connect this Capacitor and got random flicker on a fully charged battery. Wasted a whole day trying to fix it in software but didn't work. So it's a hardware only fix : (

4.1 Install the Arduino IDE

Download and install Arduino IDE v2.x from arduino.cc.

4.2 Add ESP32 Board Support

1. Open Arduino IDE → File → Preferences
2. In Additional Board Manager URLs, paste:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json 

Open Tools → Board → Boards Manager

Search for esp32 and install esp32 by Espressif Systems.

4.3 Install the U8g2 Library

1. Open Tools → Manage Libraries
2. Search for U8g2
3. Install U8g2 by Oliver Kraus (any recent version)

4.4 Select the Board

1. Tools → Board → ESP32 Arduino → select your board (e.g., ESP32 Dev Module)
2. Tools → Port → select the COM port (Windows) or /dev/ttyUSB* (Mac/Linux) where the ESP32 is connected
3. Tools → Upload Speed → 921600

5.1 Project Folder Structure

Create a folder named BATTERY (must match the .ino filename exactly). Place both files inside(you can find the code files in the end of this step or in links) and open the sketch:

BATTERY/
├── BATTERY.ino # Main sketch
└── charging_battery_64_64_28f.h     

5.3 Upload

1. Connect the ESP32 via USB-C
2. Click the Upload button (right arrow)
3. Wait for the compile + flash to complete (typically 30–60 seconds)
4. Open Tools → Serial Monitor at 115200 baud
   

Code - here

cut the pieces as shown in the image

1. OLED window — rectangular cutout, approximately 2.5 cm × 1.5 cm, centered horizontally, positioned in the upper portion of the panel. Make it slightly smaller than the OLED's bezel so the screen presses in snugly from behind.
2. AA holder slot — rectangular cutout sized to fit the AA battery holder. Position it on the right side of the front panel. The holder should protrude proudly, like a slot on a vending machine. This is the testing bay.
3. 9V battery access flap — on the back panel, cut a small rectangular flap (approximately 3 cm × 2 cm) for swapping the 9V battery. Secure it with a strip of tape after assembly.

Assemble the panels except the back and top. To place the components inside

7.1 Power Up

1. Insert a fresh 9V battery into the snap clip
2. The ESP32 boots (takes approximately 1 second)
3. The OLED displays the boot screen, then transitions to the main reading screen

7.2 Verify with a Known Battery

1. Use a multimeter to measure a fresh AA battery — note the voltage (e.g., 1.57V)
2. Insert the same AA into the holder
3. Compare the multimeter reading to the B.A.T.T.E.R.Y. display

7.3 If Readings Are Off

If the displayed voltage differs from the multimeter by more than 2%:

Check 1: 0.1µF capacitor

• Verify the capacitor is soldered between GPIO 34 and GND
• Verify continuity with a multimeter
• A missing capacitor causes fresh batteries to read 2–3V too high

Check 2: eFuse calibration

• Open the Serial Monitor at 115200 baud
• If the message reads ADC: no eFuse calibration -using default Vref, the ESP32 is a clone without factory calibration
• Tune the VOLTAGE_CALIBRATION constant in BATTERY.ino:

// If DMM reads 1.55V but display shows 1.62V: #define VOLTAGE_CALIBRATION (1.55f / 1.62f) // ≈ 0.957

Re-upload the sketch and re-test

Display stays blank

• Verify OLED VCC is connected to 3.3V (not 5V)
• Verify I2C address is 0x3C (some OLEDs use 0x3D — check the back of the module for a solder jumper)
• Run an I2C scanner sketch to confirm the OLED is detected

Display shows garbage characters

• Verify the OLED is SSD1306 (not SH1106 — different driver)
• Verify SDA and SCL are not swapped

Voltage reads 0V always

• Check AA holder red wire is connected to GPIO 34
• Check AA holder black wire is connected to GND
• Check the 0.1µF capacitor is not shorting GPIO 34 to GND

Voltage reads 3.3V always

• GPIO 34 is floating (no battery inserted, no pull-down)
• This is normal for an empty slot if the slot is open-circuit

ESP32 won't boot

• Verify the 9V battery is fresh (measure with multimeter — should be ≥ 8V)
• Verify the 9V snap red wire is on VIN, black on GND
• Disconnect the AA holder temporarily to isolate the issue

Animation stutters or freezes

• Verify the U8g2 library is installed and up to date
• Check that charging_battery_64_64_28f.h is in the same folder as BATTERY.ino
• The animation frame counter must advance before firstPage(), not inside the page loop