partition_monitor.h

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file partition_monitor.h
 * @brief Flash partition-map monitor (DETWS_ENABLE_PARTITION_MONITOR).
 *
 * Reports the device's flash partition table as JSON for diagnostics / OTA
 * dashboards: each entry's label, a human "kind" (factory / ota / nvs / spiffs /
 * littlefs / coredump / ...), the raw type/subtype, flash offset, size, and which
 * app slot is currently running. The partition walk uses esp_partition /
 * esp_ota_ops (ESP32-only); the kind classifier and the JSON serializer are pure
 * and host-tested.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef DETERMINISTICESPASYNCWEBSERVER_PARTITION_MONITOR_H
#define DETERMINISTICESPASYNCWEBSERVER_PARTITION_MONITOR_H
 
#include "ServerConfig.h"
#include <stddef.h>
#include <stdint.h>
 
#if DETWS_ENABLE_PARTITION_MONITOR
 
class DetWebServer;
 
/** @brief One flash partition entry. */
struct DetwsPartitionInfo
{
    char label[17];   ///< partition label (null-terminated).
    uint8_t type;     ///< esp_partition type (0 = app, 1 = data).
    uint8_t subtype;  ///< esp_partition subtype.
    uint32_t address; ///< flash offset (bytes).
    uint32_t size;    ///< partition size (bytes).
    bool running;     ///< true for the currently-running app partition.
};
 
// ---------------------------------------------------------------------------
// Host-testable core
// ---------------------------------------------------------------------------
 
/** @brief Human name for a partition type/subtype (e.g. "factory", "ota", "nvs", "littlefs"). */
const char *detws_partition_kind(uint8_t type, uint8_t subtype);
 
/**
 * @brief Serialize a partition array as JSON `{"partitions":[...]}` into @p out.
 * @return characters written, or 0 if @p cap is too small.
 */
int detws_partition_json(const DetwsPartitionInfo *parts, uint8_t count, char *out, size_t cap);
 
/**
 * @brief Walk the flash partition table into @p out (ESP32; 0 on host builds).
 * @return number of partitions written (<= @p max).
 */
uint8_t detws_partition_collect(DetwsPartitionInfo *out, uint8_t max);
 
// ---------------------------------------------------------------------------
// Server integration
// ---------------------------------------------------------------------------
 
/** @brief Serve the partition map as JSON at @p path (GET). Default "/partitions". */
void detws_partition_monitor_begin(DetWebServer &server, const char *path);
 
#endif // DETWS_ENABLE_PARTITION_MONITOR
#endif // DETERMINISTICESPASYNCWEBSERVER_PARTITION_MONITOR_H