diff --git a/wiki_ru.md b/wiki_ru.md new file mode 100644 index 0000000..56d7fe8 --- /dev/null +++ b/wiki_ru.md @@ -0,0 +1,214 @@ +# Описание компонента zh_syslog + +## Общие сведения + +**zh_syslog** — это лёгкий UDP-клиент syslog для ESP-IDF, отправляющий сообщения на удалённый syslog-сервер в формате [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424). + +Компонент оборачивает стандартный BSD-сокет UDP и предоставляет несколько функций для инициализации, отправки сообщений и освобождения ресурсов. + +## Основные возможности + +1. **Все коды facility (0–23)** — поддержка стандартных значений по RFC 5424, включая `LOCAL0`–`LOCAL7` для локального использования. +2. **Все уровни severity (0–7)** — от `ZH_EMERG` до `ZH_DEBUG`. +3. **Формат RFC 5424** — автоматический расчёт приоритета `` и генерация заголовка сообщения. +4. **Отправка по UDP** — сокеты не устанавливают соединения, сообщения доставляются дейтаграммами. +5. **Двухуровневая работа с памятью** — короткие сообщения форматируются в стековом буфере, длинные аллоцируются в куче точным размером. +6. **Проверка входных аргументов** — валидация IP-адреса, порта и диапазона кодов на этапе вызова. +7. **Потокобезопасные `init`/`deinit`** — защита состояния флагом инициализации (см. раздел «Ограничения» для `send`). + +## Внутреннее устройство + +### Структура `zh_syslog_init_config_t` + +Публичная конфигурационная структура, передаваемая в `zh_syslog_init()`. + +| Поле | Тип | Описание | +|------|-----|----------| +| `syslog_ip` | `char[16]` | IPv4-адрес syslog-сервера в виде строки (макс. 15 символов + `'\0'`) | +| `syslog_port` | `uint32_t` | UDP-порт сервера (диапазон 1–65535, по умолчанию 514) | + +Для заполнения значений по умолчанию используется макрос `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` (IP `192.168.0.1`, порт `514`). + +### Внутренние переменные модуля + +Не входят в публичный API и хранятся как `static` в `zh_syslog.c`. + +| Переменная | Тип | Описание | +|------------|-----|----------| +| `_syslog_server` | `struct sockaddr_in` | Адрес сервера: IPv4, порт в сетевом порядке, семья `AF_INET` | +| `_socket` | `volatile int` | Дескриптор UDP-сокета, `-1` когда клиент не инициализирован | +| `_is_initialized` | `volatile bool` | Флаг состояния: `true` после успешного `init` | + +Флаг `_is_initialized` используется как простой сторож состояния: `init` отказывает при уже инициализированном клиенте, `deinit` и `send` отказывают при неинициализированном. + +### Управление памятью + +- Короткое сообщение (помещающееся в стековый буфер `char stack_buf[256]`) форматируется прямо в стеке — аллокации в куче не происходит. +- Если `snprintf` вернул `len >= 256` (строка обрезана), память выделяется в куче ровно под `len + 1` байт через `heap_caps_calloc(..., MALLOC_CAP_8BIT)`. +- Флаг `heap_allocated` отслеживает, нужно ли освобождать буфер: `heap_caps_free()` вызывается владением только для кучного буфера — и при успехе, и при ошибке форматирования. + +## API (интерфейс) + +### Инициализация и освобождение + +| Функция | Описание | +|---------|----------| +| `zh_syslog_init()` | Создаёт UDP-сокет и настраивает параметры соединения с сервером. | +| `zh_syslog_deinit()` | Закрывает сокет и сбрасывает состояние клиента. | + +### Отправка сообщений + +| Функция | Описание | +|---------|----------| +| `zh_syslog_send()` | Форматирует сообщение по RFC 5424 и отправляет его на настроенный сервер. | + +### Типы и значения + +| Элемент | Описание | +|---------|----------| +| `zh_syslog_facility_code_t` | Перечисление кодов facility `ZH_KERN`…`ZH_LOCAL7` (0–23). | +| `zh_syslog_severity_code_t` | Перечисление уровней severity `ZH_EMERG`…`ZH_DEBUG` (0–7). | +| `zh_syslog_init_config_t` | Структура конфигурации (IP и порт сервера). | +| `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` | Макрос значений конфигурации по умолчанию. | + +## Потокобезопасность + +1. **Флаг состояния `_is_initialized`** — `volatile bool`, используется как сторож в `init`/`deinit`/`send` для защиты от повторной инициализации и от работы без инициализации. +2. **Дескриптор сокета `_socket`** — `volatile int`, обновляется при `init`/`deinit`. + +Мьютексы и критические секции не используются. Проверка флага и последующая работа с сокетом не образуют атомарной операции, поэтому `zh_syslog_send()` **не является потокобезопасной** — подробности в разделе «Ограничения». + +## Алгоритмы + +### Расчёт приоритета + +- Приоритет `` считается по формуле RFC 5424: `pri = facility * 8 + severity`. +- Значение подставляется в начало сообщения в угловых скобках: `<%d>1 - ...`. + +### Формат сообщения + +Шаблон генерируемого сообщения: + +``` +1 - HOSTNAME APP-NAME - - - MESSAGE +``` + +Поля `PROCID`, `MSGID` и `STRUCTURED-DATA` не заполняются и заменяются на `-` согласно RFC 5424. + +### Выбор буфера под размер сообщения + +- Сообщение форматируется в стековый буфер `stack_buf[256]` через `snprintf`, который возвращает полную длину строки. +- Если возвращённая длина меньше размера буфера — сокету передаётся стековый буфер. +- Если длина `>= 256` — выделяется кучный буфер точного размера `len + 1`, сообщение форматируется повторно и отправляется, после чего буфер освобождается. + +## Примеры использования + +### Базовый пример + +```c +#include "zh_syslog.h" + +void app_main(void) +{ + // Сеть (Wi-Fi/Ethernet) должна быть поднята до init + zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT(); + strcpy(config.syslog_ip, "192.168.1.100"); + config.syslog_port = 514; + + if (zh_syslog_init(&config) == ESP_OK) + { + // Отправка сообщения с приоритетом USER/INFO + zh_syslog_send(ZH_USER, ZH_INFO, "esp32_node", "my_app", "Hello syslog"); + } + + // Освобождение ресурсов + zh_syslog_deinit(); +} +``` + +### Работа с разными уровнями и facility + +```c +#include "zh_syslog.h" + +void log_events(void) +{ + zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT(); + strcpy(config.syslog_ip, "10.0.0.5"); + zh_syslog_init(&config); + + // Разные facility и severity для разных событий + zh_syslog_send(ZH_KERN, ZH_ERR, "dev1", "fw", "kernel error"); + zh_syslog_send(ZH_LOCAL0, ZH_WARNING, "dev1", "fw", "sensor timeout"); + zh_syslog_send(ZH_DAEMON, ZH_DEBUG, "dev1", "fw", "loop tick"); + + zh_syslog_deinit(); +} +``` + +### Отправка длинного сообщения + +```c +#include "zh_syslog.h" + +void send_long_message(void) +{ + zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT(); + strcpy(config.syslog_ip, "10.0.0.5"); + zh_syslog_init(&config); + + // Сообщение длиннее стекового буфера уходит через кучу + char big[512]; + memset(big, 'A', sizeof(big) - 1); + big[sizeof(big) - 1] = '\0'; + zh_syslog_send(ZH_USER, ZH_INFO, "dev1", "app", big); + + zh_syslog_deinit(); +} +``` + +## Логирование + +Компонент использует ESP-IDF логирование с тегом `"zh_syslog"`. + +```c +esp_log_level_set("zh_syslog", ESP_LOG_ERROR); +``` + +Ошибки логируются с указанием файла, строки и имени кода ошибки (`esp_err_to_name`). + +## Ошибки + +| Код | Описание | +|-----|----------| +| `ESP_OK` | Успех | +| `ESP_ERR_INVALID_ARG` | Неверный аргумент: `NULL`-указатель, порт вне диапазона, некорректный IP или код вне диапазона | +| `ESP_ERR_INVALID_STATE` | Клиент уже инициализирован (`init`) либо ещё не инициализирован (`deinit`/`send`) | +| `ESP_ERR_NO_MEM` | Не удалось выделить память под длинное сообщение | +| `ESP_FAIL` | Ошибка создания сокета, форматирования или отправки UDP | + +## Ограничения + +1. **`zh_syslog_send()` не потокобезопасна** — проверка флага и работа с сокетом не атомарны; при конкурентном вызове из нескольких задач нужна внешняя синхронизация. +2. **Только IPv4** — адрес сервера задаётся строкой и разбирается через `inet_pton(AF_INET, ...)`, IPv6 не поддерживается. +3. **Без гарантии доставки** — UDP не подтверждает доставку, потерю сообщений компонент не отслеживает. +4. **Длина IP ограничена 15 символами** — поле `syslog_ip[16]` вмещает только IPv4-строку. +5. **Требуется активная сеть** — вызывать `zh_syslog_init()` можно только после установления сетевого соединения. +6. **Стек 256 байт на сообщение** — сообщения длиннее буфера приводят к аллокации в куче на каждую отправку. + +## Требования для сборки + +- ESP-IDF версии 5.0 и выше. +- FreeRTOS (входит в состав ESP-IDF). +- lwIP (стек сокетов, входит в состав ESP-IDF). + +## Установка + +```bash +cd ваш_проект/components +git clone https://github.com/aZholtikov/zh_syslog +``` + +```c +#include "zh_syslog.h" +```