GS32ReportWeb

GS32ReportWeb — это легковесная и надежная библиотека для микроконтроллеров ESP32 (Arduino IDE / PlatformIO), предназначенная для регулярного сбора системной телеметрии и пользовательских данных датчиков с последующей отправкой в формате JSON по протоколам HTTP или HTTPS (POST).

Отлично подходит для удаленного мониторинга IoT-устройств, сбора диагностических метрик «умного дома» и отслеживания состояния оперативной памяти ESP32 в реальном времени.

---

Основные возможности

• Полная совместимость с HTTP и HTTPS: Автоматически выбирает защищенное соединение (WiFiClientSecure) при указании URL с https://.
• Гибкая настройка метрик: Включайте и отключайте любые системные параметры по отдельности (память, ядра, частота, Uptime, Flash и т.д.).
• Fluent Interface (Method Chaining): Настраивайте параметры контроллера в лаконичную цепочку прямо в setup().
• Поддержка пользовательских данных: Удобная callback-функция позволяет передавать в отчет данные со своих датчиков (температура, реле, статус сети).
• Оптимизирована под ArduinoJson v7: Нулевая фрагментация памяти, корректное владение строками и отсутствие скрытых утечек RAM.

---

Установка и зависимости

Зависимости

• Arduino core for ESP32 (версии 2.x или 3.x)
• ArduinoJson (строго версии 7.x и выше)

Установка вручную

1. Создайте папку GS32ReportWeb в директории с библиотеками вашей Arduino IDE:
   Documents/Arduino/libraries/GS32ReportWeb/
2. Поместите туда файлы библиотеки (library.properties, README.md, папку src с .h и .cpp файлами).
3. Убедитесь, что через Library Manager установлена библиотека ArduinoJson 7.
4. Перезапустите Arduino IDE.

---

Настраиваемые системные параметры

Параметры можно включать или выключать как индивидуально, так и цепочкой:

Метод настройки	Тип	Описание параметра	По умолчанию
chipModel(bool)	bool	Модель микроконтроллера (например, ESP32-D0WDQ6)	true
chipCores(bool)	bool	Количество активных ядер CPU	true
chipRevision(bool)	bool	Ревизия чипа	true
cpuFreq(bool)	bool	Частота работы CPU (МГц)	true
chipId(bool)	bool	Уникальный аппаратный ID чипа (на базе eFuse MAC)	true
heap(bool)	bool	Текущий объем свободной памяти (Free Heap, байт)	true
minHeap(bool)	bool	Минимальный зафиксированный остаток RAM с момента старта	true
maxAllocHeap(bool)	bool	Максимальный непрерывный блок свободной памяти в Heap	false
flashSize(bool)	bool	Физический объем Flash-памяти (байт)	true
flashSpeed(bool)	bool	Частота шины Flash-памяти (Гц)	false
sdkVersion(bool)	bool	Версия базового фреймворка ESP-IDF	false
sketchSize(bool)	bool	Размер загруженной прошивки (байт)	false
freeSketch(bool)	bool	Свободное место во Flash под прошивку	false
uptime(bool)	bool	Время непрерывной работы устройства (миллисекунды)	true

---

Пример использования (Arduino IDE)

#include <WiFi.h>
#include <GS32ReportWeb.h>

const char* ssid     = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

GS32ReportWeb reporter;

// Пользовательский callback для добавления показаний датчиков
// В ArduinoJson v7 объект JsonObject передается по значению
void addMyCustomData(JsonObject custom) {
    custom["temperature"] = 24.5;
    custom["humidity"]    = 52.1;
    custom["device_mode"] = "active";

    // Создание вложенных объектов в ArduinoJson v7:
    JsonObject sensors = custom["sensors"].to<JsonObject>();
    sensors["sensor1_status"] = "OK";
}

void setup() {
    Serial.begin(115200);
    delay(1000);

    WiFi.begin(ssid, password);
    Serial.print("Connecting to WiFi");
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("\nWiFi connected!");

    // Поддерживаются как HTTP, так и HTTPS адреса:
    reporter.begin("https://my-server.com/api/esp32-report");

    // Настройка флагов цепочкой (Fluent API):
    reporter.chipModel(true)
            .chipId(true)
            .heap(true)
            .uptime(true)
            .flashSize(true)
            .sdkVersion(false); // Отключаем ненужное

    // Подключаем пользовательские данные
    reporter.onCustomData(addMyCustomData);
}

void loop() {
    static unsigned long lastReportTime = 0;

    // Отправка отчета каждые 30 секунд
    if (millis() - lastReportTime >= 30000) {
        lastReportTime = millis();

        Serial.println("Sending report...");
        if (reporter.sendReport()) {
            Serial.println("Report successfully delivered!");
        } else {
            Serial.println("Failed to send report.");
        }
    }
}

---

Формат отправляемого JSON

Библиотека сериализует данные в стандартизированную структуру:

{
  "system": {
    "chip_model": "ESP32",
    "chip_cores": 2,
    "chip_revision": 3,
    "cpu_freq_mhz": 240,
    "chip_id": "000078E36D12",
    "free_heap": 215432,
    "min_free_heap": 198210,
    "flash_size": 4194304,
    "uptime_ms": 30214
  },
  "custom": {
    "temperature": 24.5,
    "humidity": 52.1,
    "device_mode": "active",
    "sensors": {
      "sensor1_status": "OK"
    }
  }
}

---

##️ Пример серверного обработчика (PHP)

Скрипт report_handler.php для приема и сохранения отчетов:

<?php
header("Content-Type: application/json; charset=UTF-8");

// Принимаем только POST
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(["status" => "error", "message" => "Method Not Allowed"]);
    exit;
}

// Получаем сырое тело запроса
$rawInput = file_get_contents("php://input");
$data = json_decode($rawInput, true);

if (!$data) {
    http_response_code(400);
    echo json_encode(["status" => "error", "message" => "Invalid JSON payload"]);
    exit;
}

$chipId = $data['system']['chip_id'] ?? 'Unknown';
$heap   = $data['system']['free_heap'] ?? 0;
$uptime = $data['system']['uptime_ms'] ?? 0;

// Логируем в файл
$logEntry = sprintf("[%s] ID: %s | Free RAM: %d bytes | Uptime: %d ms\n", date('Y-m-d H:i:s'), $chipId, $heap, $uptime);
file_put_contents("esp32_reports.log", $logEntry, FILE_APPEND);

// Успешный ответ
http_response_code(200);
echo json_encode(["status" => "ok"]);

---

Лицензия

Проект распространяется под открытой лицензией MIT. Разрешено свободное использование в коммерческих и некоммерческих проектах.