AGENT SKILL

esp32-embedded-dev

Expert ESP32 development with ESP-IDF 5.3.x, covering FreeRTOS patterns, peripheral drivers, WiFi/BLE networking, power management, and hardware optimization. Use when developing ESP32 firmware, implementing FreeRTOS tasks, configuring WiFi/BLE, optimizing memory and power, or working with ESP32-S3 hardware like T-Embed.

License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
esp32-embedded-dev
description
Expert ESP32 development with ESP-IDF 5.3.x, covering FreeRTOS patterns, peripheral drivers, WiFi/BLE networking, power management, and hardware optimization. Use when developing ESP32 firmware, implementing FreeRTOS tasks, configuring WiFi/BLE, optimizing memory and power, or working with ESP32-S3 hardware like T-Embed.

02 资源文件 12

03 SKILL.md 正文

ESP32 Embedded Development

Overview

Provides comprehensive ESP-IDF 5.3.x development guidance for ESP32/ESP32-S3 microcontrollers, covering real-time operating system patterns, wireless networking, peripheral drivers, and production-grade firmware development.

Use this skill when:

  • Developing ESP32/ESP32-S3 firmware with ESP-IDF framework
  • Implementing FreeRTOS tasks, queues, semaphores, or mutexes
  • Configuring WiFi station/AP modes or BLE GATT services
  • Integrating MQTT over WiFi/WebSocket
  • Working with SPI, I2C, UART, GPIO, ADC, or PWM peripherals
  • Optimizing power consumption with sleep modes
  • Implementing OTA firmware updates
  • Debugging memory issues or optimizing flash/RAM usage
  • Working with T-Embed hardware (ESP32-S3, 1.9" display, rotary encoder, RGB LEDs)

Quick Start

Project Structure

ESP-IDF projects follow this standard structure:

project/
├── main/
│   ├── CMakeLists.txt
│   ├── main.c (or .cpp)
│   └── Kconfig.projbuild (optional)
├── components/
│   └── custom_component/
│       ├── CMakeLists.txt
│       ├── include/
│       └── src/
├── CMakeLists.txt
├── sdkconfig
└── partitions.csv (optional)

Essential idf.py Commands

# Set target chip
idf.py set-target esp32s3

# Configure project (menuconfig)
idf.py menuconfig

# Build project
idf.py build

# Flash and monitor
idf.py -p /dev/ttyUSB0 flash monitor

# Clean build
idf.py fullclean

# Size analysis
idf.py size-components
idf.py size-files

Component Registration

# components/my_component/CMakeLists.txt
idf_component_register(
    SRCS "src/my_component.c"
    INCLUDE_DIRS "include"
    REQUIRES driver nvs_flash esp_wifi
)

FreeRTOS Task Management

Task Creation Patterns

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "freertos/semphr.h"

// Task priorities (0 = lowest, configMAX_PRIORITIES-1 = highest)
// ESP-IDF reserves priority 19+ for system tasks
#define NETWORK_TASK_PRIORITY    5  // Network tasks
#define DISPLAY_TASK_PRIORITY    4  // UI updates
#define SENSOR_TASK_PRIORITY     3  // Sensor reading
#define LED_TASK_PRIORITY        2  // LED animations
#define IDLE_TASK_PRIORITY       1  // Background tasks

// Recommended stack sizes
#define NETWORK_STACK_SIZE  4096  // Network/MQTT tasks
#define DISPLAY_STACK_SIZE  3072  // Display rendering
#define SENSOR_STACK_SIZE   2048  // Sensor tasks
#define LED_STACK_SIZE      2048  // LED control

// Task handle for later control
static TaskHandle_t display_task_handle = NULL;

void display_task(void *pvParameters) {
    TickType_t last_wake_time = xTaskGetTickCount();
    const TickType_t frequency = pdMS_TO_TICKS(33); // 30 FPS

    while (1) {
        // Update display
        update_display();

        // Delay until next frame (absolute timing)
        vTaskDelayUntil(&last_wake_time, frequency);
    }
}

// Create task pinned to specific core (ESP32-S3 has 2 cores)
xTaskCreatePinnedToCore(
    display_task,           // Task function
    "display_task",         // Name
    DISPLAY_STACK_SIZE,     // Stack size
    NULL,                   // Parameters
    DISPLAY_TASK_PRIORITY,  // Priority
    &display_task_handle,   // Task handle
    1                       // Core ID (0 or 1, or tskNO_AFFINITY)
);

Queue Communication

// Create queue (typically as global or passed via parameters)
static QueueHandle_t event_queue = NULL;

typedef struct {
    uint8_t event_type;
    uint32_t value;
    uint64_t timestamp;
} event_data_t;

void init_queues(void) {
    event_queue = xQueueCreate(10, sizeof(event_data_t));
    if (event_queue == NULL) {
        ESP_LOGE("INIT", "Failed to create event queue");
    }
}

// Producer task
void sensor_task(void *pvParameters) {
    event_data_t event;

    while (1) {
        event.event_type = SENSOR_EVENT;
        event.value = read_sensor();
        event.timestamp = esp_timer_get_time();

        // Send to queue (wait up to 100ms if full)
        if (xQueueSend(event_queue, &event, pdMS_TO_TICKS(100)) != pdPASS) {
            ESP_LOGW("SENSOR", "Queue full, event dropped");
        }

        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

// Consumer task
void processing_task(void *pvParameters) {
    event_data_t event;

    while (1) {
        // Wait indefinitely for event
        if (xQueueReceive(event_queue, &event, portMAX_DELAY) == pdPASS) {
            process_event(&event);
        }
    }
}

Mutex and Semaphore Patterns

// Mutex for protecting shared resources
static SemaphoreHandle_t i2c_mutex = NULL;

void init_synchronization(void) {
    i2c_mutex = xSemaphoreCreateMutex();
}

esp_err_t safe_i2c_read(uint8_t addr, uint8_t *data, size_t len) {
    esp_err_t ret = ESP_FAIL;

    // Take mutex (wait up to 1 second)
    if (xSemaphoreTake(i2c_mutex, pdMS_TO_TICKS(1000)) == pdTRUE) {
        ret = i2c_master_read_from_device(I2C_NUM_0, addr, data, len, pdMS_TO_TICKS(100));
        xSemaphoreGive(i2c_mutex);
    } else {
        ESP_LOGE("I2C", "Failed to acquire mutex");
    }

    return ret;
}

// Binary semaphore for task synchronization
static SemaphoreHandle_t sync_semaphore = NULL;

void init_sync(void) {
    sync_semaphore = xSemaphoreCreateBinary();
}

// ISR gives semaphore
void IRAM_ATTR gpio_isr_handler(void *arg) {
    BaseType_t higher_priority_task_woken = pdFALSE;
    xSemaphoreGiveFromISR(sync_semaphore, &higher_priority_task_woken);

    if (higher_priority_task_woken) {
        portYIELD_FROM_ISR();
    }
}

// Task waits for semaphore
void event_handler_task(void *pvParameters) {
    while (1) {
        if (xSemaphoreTake(sync_semaphore, portMAX_DELAY) == pdTRUE) {
            handle_interrupt_event();
        }
    }
}

WiFi & BLE Networking

WiFi Station Mode (Complete Example)

#include "esp_wifi.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"

#define WIFI_SSID      "your_ssid"
#define WIFI_PASSWORD  "your_password"
#define MAX_RETRY      5

static EventGroupHandle_t wifi_event_group;
static const int WIFI_CONNECTED_BIT = BIT0;
static const int WIFI_FAIL_BIT = BIT1;
static int retry_count = 0;

static void wifi_event_handler(void *arg, esp_event_base_t event_base,
                               int32_t event_id, void *event_data) {
    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) {
        esp_wifi_connect();
        ESP_LOGI("WIFI", "Station started, connecting...");
    } else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
        if (retry_count < MAX_RETRY) {
            esp_wifi_connect();
            retry_count++;
            ESP_LOGI("WIFI", "Retry connection %d/%d", retry_count, MAX_RETRY);
        } else {
            xEventGroupSetBits(wifi_event_group, WIFI_FAIL_BIT);
            ESP_LOGE("WIFI", "Failed to connect after %d retries", MAX_RETRY);
        }
    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
        ip_event_got_ip_t *event = (ip_event_got_ip_t *)event_data;
        ESP_LOGI("WIFI", "Got IP: " IPSTR, IP2STR(&event->ip_info.ip));
        retry_count = 0;
        xEventGroupSetBits(wifi_event_group, WIFI_CONNECTED_BIT);
    }
}

esp_err_t wifi_init_sta(void) {
    wifi_event_group = xEventGroupCreate();

    // Initialize network interface
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    esp_netif_create_default_wifi_sta();

    // WiFi configuration
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
    ESP_ERROR_CHECK(esp_wifi_init(&cfg));

    // Register event handlers
    ESP_ERROR_CHECK(esp_event_handler_instance_register(
        WIFI_EVENT, ESP_EVENT_ANY_ID, &wifi_event_handler, NULL, NULL));
    ESP_ERROR_CHECK(esp_event_handler_instance_register(
        IP_EVENT, IP_EVENT_STA_GOT_IP, &wifi_event_handler, NULL, NULL));

    // Configure WiFi
    wifi_config_t wifi_config = {
        .sta = {
            .ssid = WIFI_SSID,
            .password = WIFI_PASSWORD,
            .threshold.authmode = WIFI_AUTH_WPA2_PSK,
            .pmf_cfg = {
                .capable = true,
                .required = false
            },
        },
    };

    ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));
    ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &wifi_config));
    ESP_ERROR_CHECK(esp_wifi_start());

    // Wait for connection or failure
    EventBits_t bits = xEventGroupWaitBits(wifi_event_group,
        WIFI_CONNECTED_BIT | WIFI_FAIL_BIT, pdFALSE, pdFALSE, portMAX_DELAY);

    if (bits & WIFI_CONNECTED_BIT) {
        ESP_LOGI("WIFI", "Connected successfully");
        return ESP_OK;
    } else {
        ESP_LOGE("WIFI", "Connection failed");
        return ESP_FAIL;
    }
}

BLE GATT Server Example

#include "esp_bt.h"
#include "esp_gap_ble_api.h"
#include "esp_gatts_api.h"
#include "esp_bt_main.h"

#define GATTS_SERVICE_UUID   0x00FF
#define GATTS_CHAR_UUID      0xFF01
#define GATTS_NUM_HANDLE     4

static uint8_t service_uuid[16] = {
    0xfb, 0x34, 0x9b, 0x5f, 0x80, 0x00, 0x00, 0x80,
    0x00, 0x10, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
};

static esp_gatt_char_prop_t char_property =
    ESP_GATT_CHAR_PROP_BIT_READ |
    ESP_GATT_CHAR_PROP_BIT_WRITE |
    ESP_GATT_CHAR_PROP_BIT_NOTIFY;

static uint8_t char_value[20] = {0};

static void gatts_event_handler(esp_gatts_cb_event_t event,
                               esp_gatt_if_t gatts_if,
                               esp_ble_gatts_cb_param_t *param) {
    switch (event) {
        case ESP_GATTS_REG_EVT:
            ESP_LOGI("BLE", "GATT server registered, status %d", param->reg.status);

            esp_ble_gap_set_device_name("ESP32_TIMER");

            esp_ble_gap_config_adv_data_raw(adv_data, sizeof(adv_data));

            esp_ble_gatts_create_service(gatts_if, &service_id, GATTS_NUM_HANDLE);
            break;

        case ESP_GATTS_WRITE_EVT:
            ESP_LOGI("BLE", "Write event, value length %d", param->write.len);
            if (param->write.len <= sizeof(char_value)) {
                memcpy(char_value, param->write.value, param->write.len);
                // Process received data
                handle_ble_command(char_value, param->write.len);
            }

            // Send response if needed
            if (param->write.need_rsp) {
                esp_ble_gatts_send_response(gatts_if, param->write.conn_id,
                                           param->write.trans_id, ESP_GATT_OK, NULL);
            }
            break;

        case ESP_GATTS_READ_EVT:
            ESP_LOGI("BLE", "Read event");
            esp_gatt_rsp_t rsp;
            memset(&rsp, 0, sizeof(esp_gatt_rsp_t));
            rsp.attr_value.handle = param->read.handle;
            rsp.attr_value.len = sizeof(char_value);
            memcpy(rsp.attr_value.value, char_value, sizeof(char_value));

            esp_ble_gatts_send_response(gatts_if, param->read.conn_id,
                                       param->read.trans_id, ESP_GATT_OK, &rsp);
            break;

        default:
            break;
    }
}

esp_err_t ble_init(void) {
    esp_err_t ret;

    ESP_ERROR_CHECK(esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT));

    esp_bt_controller_config_t bt_cfg = BT_CONTROLLER_INIT_CONFIG_DEFAULT();
    ret = esp_bt_controller_init(&bt_cfg);
    if (ret) {
        ESP_LOGE("BLE", "Bluetooth controller init failed");
        return ret;
    }

    ret = esp_bt_controller_enable(ESP_BT_MODE_BLE);
    if (ret) {
        ESP_LOGE("BLE", "Bluetooth controller enable failed");
        return ret;
    }

    ret = esp_bluedroid_init();
    if (ret) {
        ESP_LOGE("BLE", "Bluedroid init failed");
        return ret;
    }

    ret = esp_bluedroid_enable();
    if (ret) {
        ESP_LOGE("BLE", "Bluedroid enable failed");
        return ret;
    }

    esp_ble_gatts_register_callback(gatts_event_handler);
    esp_ble_gatts_app_register(0);

    return ESP_OK;
}

MQTT Integration

MQTT Client with WiFi (esp-mqtt)

#include "mqtt_client.h"

static esp_mqtt_client_handle_t mqtt_client = NULL;

static void mqtt_event_handler(void *handler_args, esp_event_base_t base,
                               int32_t event_id, void *event_data) {
    esp_mqtt_event_handle_t event = (esp_mqtt_event_handle_t)event_data;

    switch ((esp_mqtt_event_id_t)event_id) {
        case MQTT_EVENT_CONNECTED:
            ESP_LOGI("MQTT", "Connected to broker");

            // Subscribe to topics
            esp_mqtt_client_subscribe(mqtt_client, "productivity/timer/control/#", 1);
            esp_mqtt_client_subscribe(mqtt_client, "productivity/alert/visual/#", 1);

            // Publish online status
            esp_mqtt_client_publish(mqtt_client, "productivity/device/status",
                                   "online", 0, 1, 1);
            break;

        case MQTT_EVENT_DISCONNECTED:
            ESP_LOGW("MQTT", "Disconnected from broker");
            break;

        case MQTT_EVENT_DATA:
            ESP_LOGI("MQTT", "Received: %.*s = %.*s",
                    event->topic_len, event->topic,
                    event->data_len, event->data);

            // Route message to handler
            handle_mqtt_message(event->topic, event->topic_len,
                              event->data, event->data_len);
            break;

        case MQTT_EVENT_ERROR:
            ESP_LOGE("MQTT", "Error: type=%d", event->error_handle->error_type);
            break;

        default:
            break;
    }
}

esp_err_t mqtt_init(void) {
    // MQTT configuration
    esp_mqtt_client_config_t mqtt_cfg = {
        .broker.address.uri = "mqtt://192.168.1.100:1883",  // TCP MQTT
        .credentials.client_id = "esp32_tembed",
        .session.keepalive = 60,
        .network.reconnect_timeout_ms = 5000,
        .network.disable_auto_reconnect = false,
    };

    mqtt_client = esp_mqtt_client_init(&mqtt_cfg);
    if (mqtt_client == NULL) {
        ESP_LOGE("MQTT", "Failed to initialize client");
        return ESP_FAIL;
    }

    esp_mqtt_client_register_event(mqtt_client, ESP_EVENT_ANY_ID,
                                   mqtt_event_handler, NULL);

    esp_err_t ret = esp_mqtt_client_start(mqtt_client);
    if (ret != ESP_OK) {
        ESP_LOGE("MQTT", "Failed to start client");
    }

    return ret;
}

// Publish with QoS
void mqtt_publish_timer_state(uint32_t remaining_seconds) {
    char payload[64];
    snprintf(payload, sizeof(payload),
             "{\"remaining\":%lu,\"timestamp\":%llu}",
             remaining_seconds, esp_timer_get_time() / 1000000);

    esp_mqtt_client_publish(mqtt_client,
                           "productivity/timer/state/current",
                           payload, 0, 1, 0);  // QoS 1, no retain
}

Peripheral Drivers

SPI Display Driver Pattern

#include "driver/spi_master.h"
#include "driver/gpio.h"

#define LCD_HOST       SPI2_HOST
#define LCD_MOSI_PIN   GPIO_NUM_35
#define LCD_SCLK_PIN   GPIO_NUM_36
#define LCD_CS_PIN     GPIO_NUM_37
#define LCD_DC_PIN     GPIO_NUM_34
#define LCD_RST_PIN    GPIO_NUM_38
#define LCD_BL_PIN     GPIO_NUM_33

static spi_device_handle_t spi_device;

esp_err_t lcd_spi_init(void) {
    // Configure GPIO
    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << LCD_DC_PIN) | (1ULL << LCD_RST_PIN) | (1ULL << LCD_BL_PIN),
        .mode = GPIO_MODE_OUTPUT,
        .pull_up_en = GPIO_PULLUP_DISABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE,
    };
    gpio_config(&io_conf);

    // SPI bus configuration
    spi_bus_config_t buscfg = {
        .mosi_io_num = LCD_MOSI_PIN,
        .miso_io_num = -1,  // Display only (no MISO)
        .sclk_io_num = LCD_SCLK_PIN,
        .quadwp_io_num = -1,
        .quadhd_io_num = -1,
        .max_transfer_sz = 320 * 240 * 2 + 8,  // Full screen buffer + overhead
    };

    ESP_ERROR_CHECK(spi_bus_initialize(LCD_HOST, &buscfg, SPI_DMA_CH_AUTO));

    // SPI device configuration
    spi_device_interface_config_t devcfg = {
        .clock_speed_hz = 40 * 1000 * 1000,  // 40 MHz
        .mode = 0,
        .spics_io_num = LCD_CS_PIN,
        .queue_size = 7,
        .pre_cb = NULL,
        .post_cb = NULL,
    };

    ESP_ERROR_CHECK(spi_bus_add_device(LCD_HOST, &devcfg, &spi_device));

    // Reset display
    gpio_set_level(LCD_RST_PIN, 0);
    vTaskDelay(pdMS_TO_TICKS(100));
    gpio_set_level(LCD_RST_PIN, 1);
    vTaskDelay(pdMS_TO_TICKS(100));

    return ESP_OK;
}

void lcd_send_cmd(uint8_t cmd) {
    spi_transaction_t t = {
        .length = 8,
        .tx_buffer = &cmd,
        .user = (void *)0,  // D/C = 0 for command
    };
    gpio_set_level(LCD_DC_PIN, 0);
    spi_device_polling_transmit(spi_device, &t);
}

void lcd_send_data(const uint8_t *data, size_t len) {
    if (len == 0) return;

    spi_transaction_t t = {
        .length = len * 8,
        .tx_buffer = data,
        .user = (void *)1,  // D/C = 1 for data
    };
    gpio_set_level(LCD_DC_PIN, 1);
    spi_device_polling_transmit(spi_device, &t);
}

// DMA transfer for large buffers (non-blocking)
void lcd_send_framebuffer(const uint16_t *buffer, size_t pixel_count) {
    static spi_transaction_t trans[6];
    static int trans_in_flight = 0;

    // Wait for previous transactions to complete
    while (trans_in_flight) {
        spi_transaction_t *rtrans;
        spi_device_get_trans_result(spi_device, &rtrans, portMAX_DELAY);
        trans_in_flight--;
    }

    gpio_set_level(LCD_DC_PIN, 1);

    // Queue transaction
    trans[0].length = pixel_count * 16;
    trans[0].tx_buffer = buffer;
    spi_device_queue_trans(spi_device, &trans[0], portMAX_DELAY);
    trans_in_flight++;
}

I2C Sensor Reading

#include "driver/i2c.h"

#define I2C_MASTER_NUM      I2C_NUM_0
#define I2C_MASTER_SDA      GPIO_NUM_21
#define I2C_MASTER_SCL      GPIO_NUM_22
#define I2C_MASTER_FREQ_HZ  400000

esp_err_t i2c_master_init(void) {
    i2c_config_t conf = {
        .mode = I2C_MODE_MASTER,
        .sda_io_num = I2C_MASTER_SDA,
        .scl_io_num = I2C_MASTER_SCL,
        .sda_pullup_en = GPIO_PULLUP_ENABLE,
        .scl_pullup_en = GPIO_PULLUP_ENABLE,
        .master.clk_speed = I2C_MASTER_FREQ_HZ,
    };

    ESP_ERROR_CHECK(i2c_param_config(I2C_MASTER_NUM, &conf));
    return i2c_driver_install(I2C_MASTER_NUM, conf.mode, 0, 0, 0);
}

// Read sensor register
esp_err_t sensor_read_register(uint8_t sensor_addr, uint8_t reg_addr,
                               uint8_t *data, size_t len) {
    return i2c_master_write_read_device(I2C_MASTER_NUM, sensor_addr,
                                       &reg_addr, 1, data, len,
                                       pdMS_TO_TICKS(1000));
}

GPIO Interrupt with Debouncing (Rotary Encoder)

#include "driver/gpio.h"

#define ROTARY_A_PIN    GPIO_NUM_3
#define ROTARY_B_PIN    GPIO_NUM_46
#define ROTARY_BTN_PIN  GPIO_NUM_0

static volatile int32_t encoder_count = 0;
static SemaphoreHandle_t encoder_mutex;

void IRAM_ATTR rotary_isr_handler(void *arg) {
    static uint8_t last_state = 0;
    static int64_t last_interrupt_time = 0;

    // Debounce: 1ms
    int64_t now = esp_timer_get_time();
    if ((now - last_interrupt_time) < 1000) {
        return;
    }
    last_interrupt_time = now;

    uint8_t a = gpio_get_level(ROTARY_A_PIN);
    uint8_t b = gpio_get_level(ROTARY_B_PIN);
    uint8_t state = (a << 1) | b;

    // Quadrature decoding
    int8_t dir = 0;
    if (last_state == 0b00 && state == 0b01) dir = 1;
    else if (last_state == 0b01 && state == 0b11) dir = 1;
    else if (last_state == 0b11 && state == 0b10) dir = 1;
    else if (last_state == 0b10 && state == 0b00) dir = 1;
    else if (last_state == 0b00 && state == 0b10) dir = -1;
    else if (last_state == 0b10 && state == 0b11) dir = -1;
    else if (last_state == 0b11 && state == 0b01) dir = -1;
    else if (last_state == 0b01 && state == 0b00) dir = -1;

    encoder_count += dir;
    last_state = state;
}

esp_err_t rotary_encoder_init(void) {
    encoder_mutex = xSemaphoreCreateMutex();

    // Configure GPIO
    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << ROTARY_A_PIN) | (1ULL << ROTARY_B_PIN),
        .mode = GPIO_MODE_INPUT,
        .pull_up_en = GPIO_PULLUP_ENABLE,
        .intr_type = GPIO_INTR_ANYEDGE,
    };
    gpio_config(&io_conf);

    // Install ISR service
    gpio_install_isr_service(0);
    gpio_isr_handler_add(ROTARY_A_PIN, rotary_isr_handler, NULL);
    gpio_isr_handler_add(ROTARY_B_PIN, rotary_isr_handler, NULL);

    return ESP_OK;
}

int32_t rotary_encoder_get_count(void) {
    int32_t count;
    xSemaphoreTake(encoder_mutex, portMAX_DELAY);
    count = encoder_count;
    xSemaphoreGive(encoder_mutex);
    return count;
}

WS2812B RGB LED Control (RMT)

#include "driver/rmt_tx.h"
#include "led_strip_encoder.h"

#define LED_GPIO        GPIO_NUM_4
#define LED_COUNT       8
#define LED_RMT_RES_HZ  (10 * 1000 * 1000)  // 10 MHz

static rmt_channel_handle_t led_chan = NULL;
static rmt_encoder_handle_t led_encoder = NULL;

typedef struct {
    uint8_t g;
    uint8_t r;
    uint8_t b;
} rgb_t;

esp_err_t ws2812_init(void) {
    // RMT TX channel config
    rmt_tx_channel_config_t tx_chan_config = {
        .clk_src = RMT_CLK_SRC_DEFAULT,
        .gpio_num = LED_GPIO,
        .mem_block_symbols = 64,
        .resolution_hz = LED_RMT_RES_HZ,
        .trans_queue_depth = 4,
    };
    ESP_ERROR_CHECK(rmt_new_tx_channel(&tx_chan_config, &led_chan));

    // LED strip encoder
    led_strip_encoder_config_t encoder_config = {
        .resolution = LED_RMT_RES_HZ,
    };
    ESP_ERROR_CHECK(rmt_new_led_strip_encoder(&encoder_config, &led_encoder));

    ESP_ERROR_CHECK(rmt_enable(led_chan));

    return ESP_OK;
}

void ws2812_set_colors(const rgb_t *colors, size_t count) {
    rmt_transmit_config_t tx_config = {
        .loop_count = 0,
    };

    ESP_ERROR_CHECK(rmt_transmit(led_chan, led_encoder, colors,
                                 count * sizeof(rgb_t), &tx_config));
}

// Example: Smooth color transition
void led_breathe_effect(void) {
    rgb_t leds[LED_COUNT];

    for (int brightness = 0; brightness < 255; brightness += 5) {
        for (int i = 0; i < LED_COUNT; i++) {
            leds[i].r = brightness;
            leds[i].g = 0;
            leds[i].b = brightness / 2;
        }
        ws2812_set_colors(leds, LED_COUNT);
        vTaskDelay(pdMS_TO_TICKS(20));
    }
}

Power Management

Deep Sleep with Wake Sources

#include "esp_sleep.h"
#include "driver/rtc_io.h"

// Configure deep sleep with multiple wake sources
void enter_deep_sleep(uint32_t sleep_seconds) {
    ESP_LOGI("POWER", "Entering deep sleep for %lu seconds", sleep_seconds);

    // Timer wake
    esp_sleep_enable_timer_wakeup(sleep_seconds * 1000000ULL);

    // GPIO wake (button press on GPIO0)
    esp_sleep_enable_ext0_wakeup(GPIO_NUM_0, 0);  // Wake on LOW

    // GPIO wake (any of multiple pins)
    const uint64_t ext1_mask = (1ULL << GPIO_NUM_1) | (1ULL << GPIO_NUM_2);
    esp_sleep_enable_ext1_wakeup(ext1_mask, ESP_EXT1_WAKEUP_ANY_HIGH);

    // Disable WiFi/BT before sleep
    esp_wifi_stop();
    esp_bluedroid_disable();
    esp_bt_controller_disable();

    // Enter deep sleep
    esp_deep_sleep_start();
}

// Check wake cause on boot
void check_wake_cause(void) {
    esp_sleep_wakeup_cause_t cause = esp_sleep_get_wakeup_cause();

    switch (cause) {
        case ESP_SLEEP_WAKEUP_TIMER:
            ESP_LOGI("POWER", "Woke from timer");
            break;
        case ESP_SLEEP_WAKEUP_EXT0:
            ESP_LOGI("POWER", "Woke from EXT0 (button)");
            break;
        case ESP_SLEEP_WAKEUP_EXT1:
            ESP_LOGI("POWER", "Woke from EXT1, pins: 0x%llx",
                    esp_sleep_get_ext1_wakeup_status());
            break;
        default:
            ESP_LOGI("POWER", "Power-on reset");
            break;
    }
}

Light Sleep for Power Saving

// Enter light sleep (wakes on GPIO or timer)
void enter_light_sleep(uint32_t sleep_ms) {
    esp_sleep_enable_timer_wakeup(sleep_ms * 1000);
    esp_sleep_enable_gpio_wakeup();

    ESP_LOGI("POWER", "Entering light sleep");
    esp_light_sleep_start();
    ESP_LOGI("POWER", "Woke from light sleep");
}

// Automatic light sleep (modem sleep)
void enable_auto_light_sleep(void) {
    // Automatically enter light sleep when idle
    esp_pm_config_t pm_config = {
        .max_freq_mhz = 240,
        .min_freq_mhz = 80,
        .light_sleep_enable = true,
    };
    ESP_ERROR_CHECK(esp_pm_configure(&pm_config));
}

Memory Optimization

Flash vs RAM Placement

// Store constant data in flash (saves RAM)
static const uint8_t DRAM_ATTR lookup_table[256] = { /* ... */ };

// Keep frequently accessed data in RAM
static DRAM_ATTR uint8_t frame_buffer[320 * 240 * 2];

// Place ISR code in IRAM for fast access
void IRAM_ATTR gpio_fast_isr(void *arg) {
    // Time-critical interrupt code
}

// Place large read-only data in flash
static const char TAG[] = "MAIN";  // Automatically in flash

// Explicitly place string in flash
ESP_LOGI(TAG, "This string is in flash");

Memory Monitoring

void print_memory_info(void) {
    ESP_LOGI("MEM", "Free heap: %lu bytes", esp_get_free_heap_size());
    ESP_LOGI("MEM", "Minimum free heap: %lu bytes", esp_get_minimum_free_heap_size());
    ESP_LOGI("MEM", "Largest free block: %lu bytes", heap_caps_get_largest_free_block(MALLOC_CAP_8BIT));

    // PSRAM info (ESP32-S3 can have external PSRAM)
    ESP_LOGI("MEM", "Free PSRAM: %lu bytes", heap_caps_get_free_size(MALLOC_CAP_SPIRAM));
}

// Allocate from PSRAM if available
void *buffer = heap_caps_malloc(1024 * 1024, MALLOC_CAP_SPIRAM);
if (buffer == NULL) {
    ESP_LOGE("MEM", "Failed to allocate PSRAM");
}

Custom Partition Tables

# partitions.csv - Optimize flash layout
# Name,   Type, SubType, Offset,  Size,     Flags
nvs,      data, nvs,     0x9000,  0x4000,
otadata,  data, ota,     0xd000,  0x2000,
phy_init, data, phy,     0xf000,  0x1000,
factory,  app,  factory, 0x10000, 1M,
ota_0,    app,  ota_0,   ,        1M,
ota_1,    app,  ota_1,   ,        1M,
storage,  data, spiffs,  ,        1M,

OTA Firmware Updates

HTTPS OTA Update

#include "esp_https_ota.h"
#include "esp_ota_ops.h"

#define FIRMWARE_URL "https://example.com/firmware.bin"

esp_err_t perform_ota_update(void) {
    ESP_LOGI("OTA", "Starting OTA update");

    esp_http_client_config_t config = {
        .url = FIRMWARE_URL,
        .cert_pem = NULL,  // Use server_cert_pem for production
        .timeout_ms = 5000,
        .keep_alive_enable = true,
    };

    esp_https_ota_config_t ota_config = {
        .http_config = &config,
    };

    esp_https_ota_handle_t https_ota_handle = NULL;
    esp_err_t err = esp_https_ota_begin(&ota_config, &https_ota_handle);
    if (err != ESP_OK) {
        ESP_LOGE("OTA", "OTA begin failed");
        return err;
    }

    // Get image info
    esp_app_desc_t new_app_info;
    err = esp_https_ota_get_img_desc(https_ota_handle, &new_app_info);
    if (err != ESP_OK) {
        ESP_LOGE("OTA", "Failed to get image descriptor");
        esp_https_ota_abort(https_ota_handle);
        return err;
    }

    ESP_LOGI("OTA", "New firmware version: %s", new_app_info.version);

    // Download and write firmware
    while (1) {
        err = esp_https_ota_perform(https_ota_handle);
        if (err != ESP_ERR_HTTPS_OTA_IN_PROGRESS) {
            break;
        }

        // Progress reporting
        int progress = esp_https_ota_get_image_len_read(https_ota_handle);
        ESP_LOGI("OTA", "Downloaded: %d bytes", progress);
    }

    if (err != ESP_OK) {
        ESP_LOGE("OTA", "OTA failed: %s", esp_err_to_name(err));
        esp_https_ota_abort(https_ota_handle);
        return err;
    }

    // Finalize OTA
    err = esp_https_ota_finish(https_ota_handle);
    if (err == ESP_OK) {
        ESP_LOGI("OTA", "OTA successful, restarting...");
        vTaskDelay(pdMS_TO_TICKS(1000));
        esp_restart();
    } else {
        ESP_LOGE("OTA", "OTA finish failed");
    }

    return err;
}

Debugging & Logging

Log Levels and Tags

#include "esp_log.h"

static const char *TAG = "MAIN";

void logging_examples(void) {
    // Set log level for specific tag
    esp_log_level_set("WIFI", ESP_LOG_WARN);
    esp_log_level_set("MQTT", ESP_LOG_INFO);

    // Different log levels
    ESP_LOGE(TAG, "Error: %d", error_code);         // Red
    ESP_LOGW(TAG, "Warning: %s", warning_msg);      // Yellow
    ESP_LOGI(TAG, "Info: operation complete");      // Green
    ESP_LOGD(TAG, "Debug: value=%d", debug_val);    // Normal (only if DEBUG)
    ESP_LOGV(TAG, "Verbose: detailed trace");       // Normal (only if VERBOSE)

    // Conditional compilation (saves flash space)
    #if CONFIG_LOG_MAXIMUM_LEVEL >= ESP_LOG_DEBUG
    ESP_LOGD(TAG, "This is only compiled in debug builds");
    #endif
}

Watchdog Timer Configuration

#include "esp_task_wdt.h"

#define WDT_TIMEOUT_S  5

void watchdog_init(void) {
    // Configure task watchdog
    esp_task_wdt_config_t wdt_config = {
        .timeout_ms = WDT_TIMEOUT_S * 1000,
        .idle_core_mask = (1 << 0) | (1 << 1),  // Monitor both cores
        .trigger_panic = true,
    };
    ESP_ERROR_CHECK(esp_task_wdt_init(&wdt_config));

    // Subscribe current task
    ESP_ERROR_CHECK(esp_task_wdt_add(NULL));
}

void long_running_task(void *pvParameters) {
    watchdog_init();

    while (1) {
        do_work();

        // Reset watchdog
        esp_task_wdt_reset();

        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Stack Overflow Detection

// In sdkconfig or menuconfig:
// CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK=y
// CONFIG_FREERTOS_CHECK_STACKOVERFLOW_CANARY=y

void app_main(void) {
    // Monitor stack usage
    UBaseType_t stack_high_water = uxTaskGetStackHighWaterMark(NULL);
    ESP_LOGI("STACK", "Free stack: %lu bytes", stack_high_water * sizeof(StackType_t));
}

T-Embed Specific Patterns

See references/t_embed_hardware.md for complete T-Embed ESP32-S3 hardware specifications, pinout, and initialization examples.

Resources

This skill includes reference documentation and example code:

references/

  • freertos_patterns.md - Advanced FreeRTOS patterns and best practices
  • wifi_ble_advanced.md - Advanced WiFi/BLE configuration and troubleshooting
  • t_embed_hardware.md - Complete T-Embed hardware reference
  • power_optimization.md - Detailed power consumption optimization strategies

scripts/

  • create_component.sh - Generate new ESP-IDF component boilerplate
  • partition_calculator.py - Calculate optimal partition layout

assets/

  • component_template/ - ESP-IDF component template structure
  • platformio_template/ - PlatformIO project template for ESP32-S3

Development Environment Setup

# Install ESP-IDF (recommended: v5.3.x or v5.1.x LTS)
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32,esp32s3

# Activate IDF environment
. ./export.sh

# Or use PlatformIO
pip install platformio
pio platform install espressif32@6.5.0

Common Troubleshooting

Task watchdog timeout: Increase task priority or add esp_task_wdt_reset() calls

Stack overflow: Increase task stack size or optimize local variable usage

WiFi disconnects: Implement reconnection logic in event handler, check power supply

BLE pairing fails: Verify security settings, check MTU size

MQTT messages dropped: Increase queue sizes, check network stability, use QoS 1

Display flicker: Use double buffering, ensure adequate SPI clock speed

Deep sleep current high: Disable all peripherals, check GPIO pull configurations

Refer to references/ files for detailed troubleshooting and optimization guides.

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3