aZholtikov/zh_ota_server

0 Fork 0

Files

T

aZholtikov 9521a78d13 doc: updated wiki

2026-08-16 09:08:43 +03:00

13 KiB

Raw Blame History

zh_ota_server — Компонент OTA-сервера для обновления прошивки в ESP-IDF

Содержание

Обзор
Возможности
Установка
Справочник API
Примеры использования
Технические характеристики
Коды ошибок
Вклад в проект
Лицензия

Обзор

zh_ota_server — это легковесный компонент для обновления прошивки по воздуху (OTA — Over-the-Air) для ESP-IDF (Espressif IoT Development Framework), разработанный для микроконтроллеров ESP32. Компонент предоставляет HTTP-сервер, который принимает бинарные файлы прошивки через POST-запросы, записывает их в следующий доступный OTA-раздел и автоматически активирует новую прошивку.

Компонент обрабатывает весь процесс OTA: приём данных прошивки кусками, запись во флеш-память, валидацию обновления, установку загрузочного раздела и перезагрузку устройства. Встроенный веб-интерфейс предоставляет удобный интерфейс для загрузки прошивки через браузер.

Этот компонент идеален для устройств, размещённых на объектах и нуждающихся в удалённом обновлении прошивки без физического доступа.

Возможности

OTA-обновления через HTTP: Загрузка прошивки через стандартные HTTP POST-запросы
Автоматическое управление разделами: Автоматическое определение и использование следующего доступного OTA-раздела
Встроенный веб-интерфейс: Встроенная HTML-страница для загрузки прошивки через браузер
Автоматическая активация загрузки: Устройство перезагружается и загружается с нового раздела после успешного обновления
Приём данных частями: Эффективная обработка данных прошивки блоками по 1000 байт
Интеграция с ESP-IDF: Бесшовная интеграция с HTTP-сервером и OTA-API ESP-IDF
Обработка ошибок: Комплексная проверка ошибок с детальным логированием через ESP_LOGE
Минимальное потребление памяти: Низкое использование ОЗУ с локальным буферизированием

Установка

Перейдите в каталог компонентов вашего проекта:

cd ../ваш_проект/components

Клонируйте репозиторий:

git clone https://github.com/aZholtikov/zh_ota_server

В вашем приложении подключите заголовочный файл:

#include "zh_ota_server.h"

Компонент будет автоматически собран вместе с вашим проектом.

Справочник API

zh_ota_server_init()

Инициализирует и регистрирует OTA-сервер в экземпляре HTTP-сервера ESP-IDF.

Параметры:

server — дескриптор HTTP-сервера, полученный из httpd_start(). Не должен быть NULL
path — URI-путь для endpoints OTA-сервера (например, "/ota")

Возвращает:

ESP_OK — OTA-сервер успешно инициализирован и зарегистрирован
ESP_ERR_INVALID_ARG — Неверный дескриптор или путь (NULL-указатель)
ESP_ERR_NO_MEM — Не удалось выделить память для хранения пути
ESP_FAIL — Не удалось зарегистрировать URI-обработчик в HTTP-сервере

Пример:

httpd_handle_t http_server_handle = NULL;
httpd_config_t config = HTTPD_DEFAULT_CONFIG();
httpd_start(&http_server_handle, &config);
zh_ota_server_init(http_server_handle, "/ota");

Примечание: Строка пути копируется внутри компонента и управляется им. Вызывающая сторона не должна освобождать или изменять путь после возвращения этой функции.

Предупреждение: Память, выделенная для пути, никогда не освобождается. Вызывайте эту функцию только один раз за время работы приложения.

Примеры использования

Базовая настройка OTA-сервера

Этот пример показывает, как настроить точку доступа Wi-Fi и запустить OTA-сервер:

#include "nvs_flash.h"
#include "esp_wifi.h"
#include "zh_ota_server.h"

#define WIFI_SSID "MyDevice"
#define WIFI_PASS "secure_password"

static httpd_handle_t http_server_handle = NULL;

void app_main(void)
{
    esp_log_level_set("zh_ota_server", ESP_LOG_ERROR);
    // Инициализация NVS и Wi-Fi
    nvs_flash_init();
    esp_event_loop_create_default();
    esp_netif_init();
    esp_netif_create_default_wifi_ap();
    // Настройка Wi-Fi AP
    wifi_init_config_t wifi_config = WIFI_INIT_CONFIG_DEFAULT();
    esp_wifi_init(&wifi_config);
    wifi_config_t ap_config = {
        .ap = {
            .ssid = WIFI_SSID,
            .password = WIFI_PASS,
            .max_connection = 4,
            .authmode = WIFI_AUTH_WPA2_PSK,
        },
    };
    esp_wifi_set_mode(WIFI_MODE_AP);
    esp_wifi_set_config(WIFI_IF_AP, &ap_config);
    esp_wifi_start();
    // Запуск HTTP-сервера и регистрация OTA-обработчика
    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
    httpd_start(&http_server_handle, &config);
    zh_ota_server_init(http_server_handle, "/ota");
}

Рабочий процесс обновления прошивки

Типичный рабочий процесс обновления:

Устройство запускается в режиме точки доступа (SSID: "MyDevice", IP: 192.168.4.1)
Пользователь подключается по Wi-Fi к устройству
Пользователь открывает браузер и переходит по адресу http://192.168.4.1/ota
Пользователь выбирает бинарный файл прошивки (.bin)
Устройство получает, проверяет и записывает прошивку
Устройство перезагружается и загружается с нового раздела

Технические характеристики

Параметр	Значение
Макс. размер прошивки	Ограничивается размером доступного OTA-раздела
Размер буфера	1000 байт на часть
Параметры памяти	MALLOC_CAP_8BIT
Потокобезопасность	Не является потокобезопасным
Версия ESP-IDF	>= 5.0
Платформа	Серия ESP32
Язык	C (C99)
Зависимости	esp_http_server, esp_ota_ops, esp_log

Коды ошибок

Код ошибки	Описание
`ESP_OK`	Операция выполнена успешно
`ESP_ERR_INVALID_ARG`	Неверный аргумент (NULL-дескриптор или путь)
`ESP_ERR_NO_MEM`	Не удалось выделить память (не хватает свободной памяти)
`ESP_FAIL`	Общая ошибка (регистрация URI, операция OTA или HTTP-ответ)

Вклад в проект

Вклад приветствуется! Чтобы внести свой вклад:

Сделайте форк репозитория
Создайте ветку функции (git checkout -b feature/AmazingFeature)
Закоммитьте ваши изменения (git commit -m 'Add some AmazingFeature')
Отправьте в ветку (git push origin feature/AmazingFeature)
Откройте Pull Request

Пожалуйста, убедитесь, что ваш код следует существующему стилю и включает соответствующую документацию.

Лицензия

Этот проект лицензирован по лицензии Apache, версия 2.0 — см. файл LICENSE для подробной информации.

Apache License, Version 2.0

Лицензировано по лицензии Apache License, Version 2.0 (далее — "Лицензия"); вы не можете использовать этот файл, кроме случаев, предусмотренных Лицензией. Копию Лицензии можно получить по адресу:

http://www.apache.org/licenses/LICENSE-2.0

Если иное не требуется действующим законодательством или не согласовано в письменном виде, программное обеспечение, распространяемое по Лицензии, распространяется на условиях "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, явных или подразумеваемых, включая, но не ограничиваясь, гарантии ТОВАРНОГО СОСТОЯНИЯ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. Смотрите Лицензию для получения конкретных прав и ограничений.

Дополнительные заметки

Управление памятью: Путь URI выделяется один раз при инициализации и никогда не освобождается. Это приемлемо для встраиваемых систем со стабильным объёмом доступной памяти
Безопасность: Этот компонент не предоставляет аутентификацию или шифрование. Используйте только в доверенной сети. Для продакшена добавьте HTTPS и аутентификацию
Риск блокировки устройства: Загрузка недействительной или повреждённой прошивки сделает устройство незагружаемым, пока не будет загружена валидная образ через другой механизм (например, через UART bootloader)
Лучшие практики:
- Всегда проверяйте контрольные суммы прошивки перед записью
- Реализуйте механизм отката (например, dual-bank OTA с резервным разделом)
- Добавьте аутентификацию для предотвращения несанкционированной загрузки прошивки
- Рассмотрите возможность добавления функции отката в случае неудачного обновления
- Контролируйте свободную память перед началом больших OTA-передач

Сгенерировано для zh_ota_server v1.0.0

13 KiB Raw Blame History