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

## Содержание

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

---

## Обзор

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

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

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

---

## Возможности

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

---

## Установка

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

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

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

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

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

```c
#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-сервере

**Пример:**

```c
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-сервер:

```c
#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");
}
```

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

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

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

---

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

| Параметр | Значение |
| ---------- | ---------- |
| **Макс. размер прошивки** | Ограничивается размером доступного 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-ответ) |

---

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

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

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

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

---

## Лицензия

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

### Apache License, Version 2.0

Авторское право (c) 2026 Алексей Жолтиков

Лицензировано по лицензии 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*