Architecture and Modules

For file paths and main.cpp flow, see Source Layout.

Firmware module overview

WiFiManager (wifi_manager.cpp)

Manages Wi-Fi connectivity with reconnect handling and exponential backoff behavior when association fails.

NTPSync (ntp_sync.cpp)

Attempts NTP time synchronization with an approximately 30-second timeout window; if sync fails, payload timestamp fallback behavior uses ts=0.

MQTTManager (mqtt_manager.cpp)

Establishes TLS MQTT MQTT
Message Queuing Telemetry Transport — lightweight publish/subscribe protocol used between ESP32 and AWS IoT Core. sessions to AWS IoT Core AWS IoT Core
AWS IoT Core — managed MQTT broker with X.509 device authentication for ESP32 telemetry and events. using X.509 X.509
X.509 certificate standard — device identity format used for AWS IoT Core mutual authentication. auth and QoS 1 QoS 1
Quality of Service — firmware publishes with MQTT QoS 1 (at least once delivery). publish semantics.

TelemetryPublisher (telemetry_publisher.cpp)

Publishes connectivity telemetry on a fixed interval (about every 60 seconds), including RSSI, uptime, heap, chip temperature, board metadata, Wi-Fi association details, and NTP clock offset.

EventPublisher (event_publisher.cpp)

Publishes button press events from GPIO0 using debounced input handling to avoid duplicate edge noise.

StatusLed (status_led.cpp)

Drives onboard RGB status indication; blue flash indicates a successful publish path.

WatchdogSupervisor (watchdog_supervisor.cpp)

Uses task watchdog supervision and connectivity timeout guards to recover from stuck runtime states.

Logger (logger.h)

Emits serial-tagged logs for Wi-Fi, MQTT, telemetry, and event status checks during bring-up and troubleshooting.