ESP32 Reference

ESP-IDF (Espressif IoT Development Framework) is the official native SDK for ESP32, providing full access to all hardware peripherals, FreeRTOS, and advanced features like secure boot and flash encryption. Arduino-ESP32 is a compatibility layer that wraps ESP-IDF with the familiar Arduino API. ESP-IDF gives more control and better performance but requires more boilerplate; use it for production firmware. Arduino is better for quick prototyping.

Use the gpio_config_t struct and set mode to GPIO_MODE_INPUT, pull_up_en to GPIO_PULLUP_ENABLE, pull_down_en to GPIO_PULLDOWN_DISABLE, and set pin_bit_mask to (1ULL << GPIO_NUM_X). Call gpio_config(&io_conf) to apply the configuration. For interrupt-driven input, also set intr_type to GPIO_INTR_POSEDGE or GPIO_INTR_NEGEDGE, then register a handler with gpio_isr_handler_add().

Initialize the network interface with esp_netif_init() and create the default WiFi STA netif. Fill a wifi_config_t struct with the ssid and password fields, call esp_wifi_set_mode(WIFI_MODE_STA), esp_wifi_set_config(WIFI_IF_STA, &wifi_config), esp_wifi_start(), and then esp_wifi_connect(). Listen for WIFI_EVENT_STA_GOT_IP using the event loop to know when you have an IP address.

esp_timer is a software timer built on top of a hardware timer, designed for one-shot or periodic callbacks with microsecond resolution. It is simple to use for application-level timing. gptimer is the low-level hardware General Purpose Timer API introduced in ESP-IDF v5, offering direct control over timer count direction, alarm events, and capture. Use esp_timer for most application code; use gptimer when you need precise hardware-level timing or capture functionality.

Call esp_sleep_enable_timer_wakeup(us) to set a wakeup timer, or use esp_sleep_enable_ext0_wakeup() for GPIO wakeup. Then call esp_deep_sleep_start() to enter deep sleep immediately. The chip consumes around 10 µA in deep sleep. On wakeup, execution restarts from app_main(). Use RTC memory (RTC_DATA_ATTR) to preserve variables across deep sleep cycles.

NVS stores key-value pairs in a dedicated flash partition. Open a namespace with nvs_open(), then use nvs_set_i32/str/blob() to write values and nvs_get_i32/str/blob() to read them. Always call nvs_commit() after writing to persist changes. NVS handles wear leveling automatically. It is ideal for storing WiFi credentials, configuration parameters, and counters that must survive power loss.

ESP32 supports both Classic Bluetooth (BR/EDR) for audio profiles like A2DP and SPP serial, and Bluetooth Low Energy (BLE) for low-power sensor and IoT applications. BLE uses the GAP layer for device advertising and discovery, and the GATT layer for defining services and characteristics. The ESP32 BLE stack supports two implementations: the default Bluedroid stack and the lighter-weight NimBLE stack, which uses significantly less RAM.

Use the esp_https_ota() function with an esp_http_client_config_t pointing to your HTTPS firmware binary URL. ESP-IDF handles downloading the firmware, writing it to the passive OTA partition, verifying the hash, and marking the new partition as bootable. On the next restart, the bootloader switches to the new firmware. Configure two OTA app partitions in your partition table (factory, ota_0, ota_1) to enable rollback on failure.

Initialize an esp_mqtt_client_config_t struct with the broker URI (e.g., mqtt://broker.example.com or mqtts:// for TLS). Call esp_mqtt_client_init() to get a handle, then esp_mqtt_client_start() to connect. Register an event handler for MQTT_EVENT_CONNECTED to subscribe to topics and MQTT_EVENT_DATA to receive messages. Use esp_mqtt_client_publish() to send messages and esp_mqtt_client_subscribe() to subscribe to topics.