# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ESP32-C3 firmware for measuring power consumption across different sleep states using a PowerProfiler Kit II. The firmware cycles between active periods (5s, LED on) and deep sleep (30s, minimal power), with optional WiFi enabling for A/B testing.

## Build & Development

All commands use PlatformIO. Board: `esp32-c3-devkitm-1`, Framework: Arduino

```bash
# Build firmware
pio run -e esp32-c3-devkitm-1

# Upload to device
pio run -e esp32-c3-devkitm-1 -t upload

# Monitor serial output (115200 baud)
pio device monitor -b 115200

# Clean build artifacts
pio run -e esp32-c3-devkitm-1 -t clean
```

## Architecture

**Single-purpose firmware** with execution entirely in `setup()` — `loop()` is never reached due to `esp_deep_sleep_start()`.

**Key design pattern**: RTC memory persistence via `RTC_DATA_ATTR` variables (e.g., `bootCount`) survive deep sleep resets, allowing multi-cycle experiments without external state.

**Control flow**:
1. Boot → increment RTC counter
2. Report reset reason and cycle status
3. LED on for `ACTIVE_DURATION_MS`
4. Configure timer wakeup for `SLEEP_DURATION_S`
5. Enter deep sleep (CPU halts, only RTC timer remains)
6. Auto-wakeup via RTC timer → restart from boot

**Configuration** (all in `include/config.h`):
- `SLEEP_DURATION_S`: Deep sleep interval
- `ACTIVE_DURATION_MS`: Time spent awake (measurement window)
- `TOTAL_CYCLES`: Number of complete cycles to run
- `WIFI_ENABLED_CYCLE_1/2`: Alternating WiFi on/off for A/B measurement comparison

Serial debug output includes reset reason code (5 = DEEPSLEEP_RESET) for timing validation and cycle tracking.

## Power Measurement Setup

Device connects via PowerProfiler Kit II (supplies power + measures current). Use nRF Power Profiler app on host to record measurements. Firmware will cycle autonomously once uploaded; each boot generates serial output for correlation with profiler traces.