1. Detect door/window open and closed state changes using the reed switch.
2. Report events reliably over a low-power wireless path.
3. Spend nearly all time in deep sleep to maximize AA battery life.
4. Provide simple bring-up/setup feedback through serial logs and the RGB LED.
5. Support production flashing/debug through the existing UART/programming header.

• Arduino IDE: 2.3.x or newer
• Board package: esp32 by Espressif Systems 2.0.17 or newer
• Board selection: ESP32C3 Dev Module or ESP32-C3 DevKitM-1 equivalent
• Serial monitor: 115200 baud
• Upload speed: start with 460800, fall back to 115200 if upload is unreliable
• Flash mode: DIO
• USB CDC on boot: enable if using native USB serial

Ini
[env:esp32-c3-mini-door-sensor]
platform = espressif32@6.10.0
board = esp32-c3-devkitm-1
framework = arduino
monitor_speed = 115200
upload_speed = 460800
board_build.mcu = esp32c3
board_build.f_cpu = 160000000L
lib_deps =
  h2zero/NimBLE-Arduino@^2.2.1
build_flags =
  -D ARDUINO_USB_MODE=1
  -D ARDUINO_USB_CDC_ON_BOOT=1

• Reed input is connected to GPIO0 through a 50 Ω series resistor.
• R2 is a 1 MΩ pull-up to 3.3 V.
• Reed switch closes to GND.
• Expected firmware interpretation:
  • GPIO0 = LOW → door/window closed / magnet present.
  • GPIO0 = HIGH → door/window open / magnet absent.

• User button is active LOW.
• The button should be used for setup mode, test mode, pairing/provisioning, or factory reset gestures.
• Because deep sleep wake is level-based and the reed wake polarity changes, the user button may not be simultaneously wake-armed in all reed states without a more advanced wake strategy.

• LED is common-anode tied to 3.3 V (VOUT).
• GPIO pins sink current through resistors.
• Logic:
  • GPIO LOW → LED channel ON.
  • GPIO HIGH → LED channel OFF.
• LED must remain off except during boot, setup, pairing, error indication, and manual test because LED current dominates sleep current.

• Battery is a single AA primary cell.
• The boost regulator is TPS613221ADBVR with 3.3 V output.
• TPS613221A quiescent current into VOUT is approximately 6.5 µA typical, 10 µA max.
• ESP32-C3 deep sleep with RTC timer + RTC memory is approximately 5 µA typical.
• Expected base sleep current estimate: about 11.5 µA before reed pull-up conduction.
• If the reed is closed and R2 is pulled to GND, the 1 MΩ pull-up adds approximately 3.3 µA.

1. Device wakes from deep sleep on reed state change or user interaction.
2. Firmware reads reed/user state after debounce/settle.
3. Firmware broadcasts a compact BLE event payload.
4. Firmware returns to deep sleep immediately after a short advertising window.
5. Target BLE active time: 0.2–0.5 s if the hub reliably receives events.
6. Initial bring-up advertising window may be 700 ms; increase to 1.5–3 s only if reliability requires it.
7. Use the lowest BLE TX power that passes range/reliability testing; start with 0 dBm or 9 dBm for margin, then reduce if possible.

1. Store WiFi credentials securely using ESP32 NVS/Preferences.
2. Avoid continuous WiFi association.
3. Wake, connect, report, and sleep as fast as possible.
4. Use static IP or other fast reconnect techniques if acceptable.
5. Minimize DHCP, DNS, TLS handshake, and retry time.
6. Target less than 2 seconds active time per event; ideally less than 1 second.
7. Use lowest TX power that reliably reaches the access point without increasing retries.
8. Include brownout/retry logging during development.
9. If reporting fails, use a bounded retry count and go back to sleep rather than draining the AA cell indefinitely.

• Use ESP32-C3 deep sleep for normal idle.
• Preserve small state in RTC memory, including last reed state, boot count, and event count.
• Turn LED pins to off state before sleeping.
• Disable unused peripherals before sleep.
• Keep GPIO pulls consistent with the external hardware to minimize leakage.

• If reed is open and firmware arms LOW wake, USER can also be armed as LOW wake.
• If reed is closed and firmware arms HIGH wake to detect opening, USER cannot always be simultaneously armed using the same simple level-wake mode.
• EN/reset remains physically available at all times.

1. On wake, wait 20–50 ms for input settling.
2. Sample reed multiple times over a short window.
3. Accept a state change only if readings are stable.
4. Suppress duplicate reports where the state equals the last reported state unless the wake cause is boot/timer/manual test.

1. Connect 3.3 V UART adapter GND, TX, RX.
2. Hold BOOT low.
3. Pulse EN/reset low, then release EN.
4. Release BOOT after the upload begins.
5. Use 115200 baud if upload at higher speed is unreliable.

• Firmware version/build date.
• Wake cause.
• Reed raw level and interpreted state.
• User button state.
• Event code.
• Wireless report result.
• Sleep wake configuration.
• Brownout/reset reason if available.

1. Boot/init
   • Initialize GPIOs.
   • Initialize serial if debug build.
   • Read reset/wake cause.
2. Input settle/debounce
   • Wait 20–50 ms.
   • Read reed and user button.
3. Mode decision
   • If USER held, enter setup/test/provisioning.
   • Else determine event from current reed state vs RTC last state.
4. Indication
   • Optional short LED feedback.
5. Report
   • BLE advertising by default, optional WiFi report if configured.
6. Persist state
   • Update RTC/NVS as needed.
7. Arm wake
   • Configure reed opposite-level wake.
   • Configure user wake if compatible with selected wake mode.
8. Deep sleep

• Do not implement battery voltage reporting unless a valid ADC input path is confirmed on the PCB.
• Do not enable internal pulls or repurpose strap pins for battery measurement.
• If a future PCB revision adds a divider, ensure the divider is switched or high impedance enough for AA sleep current targets, and account for ADC source impedance/acquisition time.

1. Wireless retries must be bounded.
2. If report fails, optionally send a failure LED indication only during manual/setup mode, then sleep.
3. Maintain event counters to help detect missed reports.
4. Avoid long blocking setup/connect loops on every reed wake.
5. Do not keep WiFi/BLE active while waiting indefinitely for a hub/AP.
6. Include a periodic failsafe wake only if useful; if implemented, use a long interval such as once per day.

• Compile for ESP32-C3 target.
• Confirm selected Arduino-ESP32 core version.
• Confirm NimBLE-Arduino version.
• Flash through J1/UART or native USB method used for bring-up.
• Confirm serial boot log at 115200 baud.

• Confirm reed closed reports GPIO0 LOW and closed=true.
• Confirm reed open reports GPIO0 HIGH and closed=false.
• Confirm USER button reports active LOW.
• Confirm BOOT/EN still work for flashing/reset.
• Confirm RGB LED channel polarity and colors.
• Confirm GPIO2 is not driven by firmware.

• Closed → open transition wakes and reports open.
• Open → closed transition wakes and reports closed.
• Device returns to deep sleep after report.
• LED is off in deep sleep.
• Wake cause logging matches expected behavior.
• USER wake/setup behavior is documented and tested for both reed states.

• BLE advertisement payload decodes correctly.
• Hub receives events at intended distance and enclosure orientation.
• Advertising window is minimized after reliability testing.
• TX power is reduced only after packet reliability remains acceptable.
• If WiFi is used, active time and retry count are measured.

• Measure deep-sleep current with LED off.
• Measure current with reed closed and open to quantify R2 contribution.
• Measure active current during BLE and/or WiFi report.
• Test with fresh and partially depleted AA cells.
• Test cold/aged cell behavior if product environment requires it.
• Confirm no brownouts during RF transmit.

• ledcAttach not declared.
• NimBLEAdvertising has no setScanResponse member.
• ESP32-C3 EXT1 wake symbols unavailable.

1. Use Arduino-ESP32 2.x compatible ledcSetup() + ledcAttachPin() or guard LEDC calls by core version.
2. Avoid adv->setScanResponse(false) unless confirmed available in the installed NimBLE-Arduino version.
3. Use ESP32-C3-compatible GPIO wake APIs for the selected Arduino/IDF version.

1. It compiles with the documented Arduino/PlatformIO environment.
2. It flashes successfully through the available programming method.
3. Serial logs identify firmware version, wake cause, reed state, and event type.
4. Reed open/closed events are correctly detected and reported.
5. RGB LED status works and remains off during sleep.
6. Device returns to deep sleep after each event.
7. BLE reporting works with a documented payload and hub decode method, or WiFi reporting works with bounded retries.
8. Deep sleep current and RF burst behavior are measured on assembled hardware.
9. The firmware does not use GPIO2 as a runtime output and does not interfere with BOOT/EN programming behavior.