Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2025 Jibril Sharafi
#include "customserver.h"
#include "app_image_descriptor.h"
#include "custometh.h"
#include "modbustcp.h" // Local integrations are started/stopped to follow the STA link
#include "taskprofiler.h"
#include "duration_format.h"
#include "shadow.h"
#include "factory_keys.h"
#include <Preferences.h>
#include "nvs.h"
#include "nvs_flash.h"
#include <esp_random.h>
namespace CustomServer
{
static TaskHeartbeat _healthCheckHeartbeat;
// Private variables
// ==============================
// ==============================
static AsyncWebServer server(WEBSERVER_PORT);
static AsyncAuthenticationMiddleware digestAuth;
static AsyncRateLimitMiddleware rateLimit;
static CustomMiddleware customMiddleware;
static DefaultPasswordGuardMiddleware defaultPasswordGuard;
static AuthLockoutMiddleware authLockout;
static UnauthenticatedRateLimitMiddleware unauthRateLimit;
// Whether the stored web password is still the shipped default. Read on the AsyncTCP
// task for every request to every path, so it must never become an NVS read: it is
// refreshed only when the password can actually have changed (boot, and
// updateAuthPasswordWithOneFromPreferences(), which is already the single funnel
// through which a change reaches the live digestAuth object).
//
// volatile rather than a mutex, matching how CustomWifi publishes getProvisioningState()
// and isApAddress() across tasks: one aligned byte, written by the API or button task,
// read by AsyncTCP. A one-request-stale read is harmless in either direction because the
// guard re-evaluates on the next request.
//
// Starts true and stays true if NVS cannot be read - a device that cannot prove its
// password was changed is treated as not having changed it.
static volatile bool _usingDefaultPassword = true;
// Health check task variables
static TaskHandle_t _healthCheckTaskHandle = NULL;
static bool _healthCheckTaskShouldRun = false;
static uint32_t _consecutiveFailures = 0;
// OTA timeout task variables
static TaskHandle_t _otaTimeoutTaskHandle = NULL;
static bool _otaTimeoutTaskShouldRun = false;
// The request that owns the firmware upload in progress, and whether Update.end(true) went
// through for it. The upload callback runs for every client and before authentication, so state
// that is not tied to a request let any host on the LAN reset somebody else's upload: the
// remaining chunks were skipped and the completion handler still answered "success".
// Only touched from the AsyncTCP task.
static AsyncWebServerRequest *_otaOwner = nullptr;
static bool _otaFinalized = false;
// API request synchronization
static SemaphoreHandle_t _apiMutex = NULL;
// ETag for proper caching
static char _cachedEtag[MD5_BUFFER_SIZE + 3] = {0}; // +3 for quotes and null terminator
static bool _etagComputed = false;
// Private functions declarations
// ==============================
// ==============================
// Handlers and middlewares
static void _setupMiddleware();
static void _refreshDefaultPasswordFlag();
static bool _isApOrigin(AsyncWebServerRequest *request);
static void _serveStaticContent();
static void _serveApi();
// Tasks
static void _startHealthCheckTask();
static void _stopHealthCheckTask();
static void _healthCheckTask(void *parameter);
static bool _performHealthCheck();
// OTA timeout task
static void _startOtaTimeoutTask();
static void _stopOtaTimeoutTask();
static void _otaTimeoutTask(void *parameter);
// Authentication management
static bool _setWebPassword(const char *password);
static bool _getWebPasswordFromPreferences(char *buffer, size_t bufferSize);
static bool _validatePasswordStrength(const char *password);
// Helper functions for common response patterns
static void _sendJsonResponse(AsyncWebServerRequest *request, const JsonDocument &doc, int32_t statusCode = HTTP_CODE_OK);
static void _sendSuccessResponse(AsyncWebServerRequest *request, const char *message);
static void _sendErrorResponse(AsyncWebServerRequest *request, int32_t statusCode, const char *message);
// API request synchronization helpers
static bool _acquireApiMutex(AsyncWebServerRequest *request);
// API endpoint groups
static void _serveSystemEndpoints();
static void _serveIssueEndpoints();
static void _serveNetworkEndpoints();
static void _serveLoggingEndpoints();
static void _serveHealthEndpoints();
static void _serveAuthEndpoints();
static void _serveOtaEndpoints();
static void _serveAde7953Endpoints();
static void _serveCustomMqttEndpoints();
static void _serveInfluxDbEndpoints();
static void _serveCrashEndpoints();
static void _serveLedEndpoints();
static void _serveBackupEndpoints();
static void _serveRestoreEndpoints();
static void _serveFileEndpoints();
#ifdef ENV_DEV
static void _serveShadowDevEndpoints();
static void _serveCrashTestEndpoints();
static void __attribute__((noinline)) _crashTestStackOverflow(uint32_t depth);
static void _serveNvsDebugEndpoints();
#endif
// Authentication endpoints
static void _serveAuthStatusEndpoint();
static void _serveChangePasswordEndpoint();
static void _serveResetPasswordEndpoint();
// OTA endpoints
static void _serveOtaUploadEndpoint();
static void _serveOtaStatusEndpoint();
static void _serveOtaRollbackEndpoint();
static bool _fetchGitHubReleaseInfo(JsonDocument &doc);
static void _serveFirmwareStatusEndpoint();
static void _handleOtaUploadComplete(AsyncWebServerRequest *request);
static void _handleOtaUploadData(AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final);
// File upload handler
static void _handleFileUploadData(AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final);
// OTA helper functions
static bool _initializeOtaUpload(AsyncWebServerRequest *request, const String& filename);
static void _setupOtaMd5Verification(AsyncWebServerRequest *request);
static bool _writeOtaChunk(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index);
static bool _finalizeOtaUpload(AsyncWebServerRequest *request);
// Logging helper functions
static bool _parseLogLevel(const char *levelStr, LogLevel &level);
// HTTP method validation helper
static bool _validateRequest(AsyncWebServerRequest *request, const char *expectedMethod, size_t maxContentLength = 0);
static bool _requireEthernet(AsyncWebServerRequest *request);
static bool _isPartialUpdate(AsyncWebServerRequest *request);
// ETag validation helper
static bool _checkEtagAndSend304(AsyncWebServerRequest *request, const char* etag);
static void _sendResponseWithEtag(AsyncWebServerRequest *request, AsyncWebServerResponse *response, const char* etag);
// Public functions
// ================
// ================
void begin()
{
LOG_DEBUG("Setting up web server...");
// Initialize API synchronization mutex
if (!createMutexIfNeeded(&_apiMutex)) {
LOG_ERROR("Failed to create API mutex");
return;
}
LOG_DEBUG("API mutex created successfully");
// Route registration makes hundreds of small, permanent allocations (one handler
// object plus its URI and std::function per route), all below the PSRAM malloc
// threshold, so they would pin tens of KB of internal RAM for good. They are only
// walked on the AsyncTCP task while matching a request, which PSRAM is fine for:
// lower the threshold for the registration only. It is a global switch, so other
// tasks' malloc() calls land in PSRAM too during these few tens of ms - harmless,
// anything that needs internal or DMA memory asks for it explicitly via heap_caps.
heap_caps_malloc_extmem_enable(WEBSERVER_ROUTE_ALLOC_PSRAM_THRESHOLD);
_setupMiddleware();
_serveStaticContent();
_serveApi();
heap_caps_malloc_extmem_enable(CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL);
server.begin();
LOG_INFO("Web server started on port %d", WEBSERVER_PORT);
// Start health check task to ensure the web server is responsive, and if it is not, restart the ESP32
_startHealthCheckTask();
}
void stop()
{
LOG_DEBUG("Stopping web server...");
// Stop health check task
_stopHealthCheckTask();
// Stop OTA timeout task
_stopOtaTimeoutTask();
// Stop the server
server.end();
// Delete API mutex
deleteMutex(&_apiMutex);
LOG_DEBUG("Web server stopped");
}
void updateAuthPasswordWithOneFromPreferences()
{
char webPassword[WEB_PASSWORD_BUFFER_SIZE];
if (_getWebPasswordFromPreferences(webPassword, sizeof(webPassword)))
{
digestAuth.setPassword(webPassword);
digestAuth.generateHash(); // regenerate hash with new password
LOG_DEBUG("Authentication password updated");
}
else
{
LOG_ERROR("Failed to load new password for authentication");
}
// Every path that changes the password comes through here - the change-password
// handler, the reset-password handler, and the physical button - so this is the
// one place the lockdown flag needs refreshing. Deliberately outside the branch
// above: a failed read must still be reflected, and it fails closed.
_refreshDefaultPasswordFlag();
}
// Recomputes the cached lockdown flag. The only NVS read behind it, and it happens
// once per password change rather than once per request.
static void _refreshDefaultPasswordFlag()
{
char storedPassword[WEB_PASSWORD_BUFFER_SIZE];
if (!_getWebPasswordFromPreferences(storedPassword, sizeof(storedPassword)))
{
// Fail closed. _setupMiddleware() already writes the default back when the read
// fails, so the next boot reads cleanly and this becomes truthful rather than
// merely conservative.
_usingDefaultPassword = true;
LOG_WARNING("Could not read the stored password - assuming the default is still in use");
return;
}
_usingDefaultPassword = (strcmp(storedPassword, WEBSERVER_DEFAULT_PASSWORD) == 0);
if (_usingDefaultPassword) LOG_WARNING("Default web password is in use - the device will refuse to serve anything but the password change");
else LOG_DEBUG("Web password is not the default");
}
bool resetWebPassword()
{
LOG_DEBUG("Resetting web password to default");
return _setWebPassword(WEBSERVER_DEFAULT_PASSWORD);
}
// Private functions
// =================
// =================
static void _setupMiddleware()
{
// ---- Statistics Middleware Setup ----
// Add statistics tracking middleware first to capture all requests
server.addMiddleware(&customMiddleware);
LOG_DEBUG("Statistics middleware configured");
// ---- Authentication Middleware Setup ----
// Configure digest authentication (more secure than basic auth)
digestAuth.setUsername(WEBSERVER_DEFAULT_USERNAME);
// Load password from Preferences or use default
char webPassword[WEB_PASSWORD_BUFFER_SIZE];
if (_getWebPasswordFromPreferences(webPassword, sizeof(webPassword)))
{
digestAuth.setPassword(webPassword);
LOG_DEBUG("Web password loaded from Preferences");
}
else
{
// Fallback to default password if Preferences failed
digestAuth.setPassword(WEBSERVER_DEFAULT_PASSWORD);
LOG_INFO("Failed to load web password, using default");
// Try to initialize the password in Preferences for next time
if (_setWebPassword(WEBSERVER_DEFAULT_PASSWORD)) { LOG_DEBUG("Default password saved to Preferences for future use"); }
}
digestAuth.setRealm(WEBSERVER_REALM);
digestAuth.setAuthFailureMessage("The password is incorrect. Please try again.");
digestAuth.setAuthType(AsyncAuthType::AUTH_DIGEST);
digestAuth.generateHash(); // precompute hash for better performance
// Known limitation (accepted risk, issue #222): ESPAsyncWebServer issues a fresh
// nonce/opaque per 401 but AsyncWebServerRequest::authenticate() passes them as NULL
// into checkDigestAuthentication(), which skips validating any field it receives as
// NULL (WebRequest.cpp / WebAuthentication.cpp in the library). So a captured
// Authorization header for a given request is replayable indefinitely. No easy fix
// without the firmware tracking issued nonces itself; the LAN link is the trust
// boundary for this device. No action taken here.
// ---- Auth Lockout Setup ----
// Ahead of everything else that can refuse a request, so a source already locked out
// for guessing costs a table scan rather than a digest MD5.
authLockout.begin([]() { return millis64(); });
server.addMiddleware(&authLockout);
LOG_DEBUG("Auth lockout configured: %d consecutive failures -> %d s, doubling to %d s",
AUTH_LOCKOUT_MAX_FAILURES, AUTH_LOCKOUT_BASE_SECONDS, AUTH_LOCKOUT_MAX_SECONDS);
// ---- Rate Limiting Middleware Setup ----
// BEFORE digestAuth, deliberately. AsyncAuthenticationMiddleware::run short-circuits
// with requestAuthentication() instead of calling next() (Middleware.cpp:143), so
// anything registered after it never runs on a 401 - which meant the limiter was not
// merely mistuned on the failed-login path, it was unreachable. Measured before this
// change: 400 consecutive failed logins, zero 429 (issue #197).
rateLimit.setMaxRequests(WEBSERVER_MAX_REQUESTS);
rateLimit.setWindowSize(WEBSERVER_WINDOW_SIZE_SECONDS);
// Only unauthenticated requests count toward the ceiling - the owner's authenticated
// traffic is never throttled. See UnauthenticatedRateLimitMiddleware.
unauthRateLimit.setInner(&rateLimit);
server.addMiddleware(&unauthRateLimit);
LOG_DEBUG("Rate limiting (unauthenticated only) configured: max requests = %d, window size = %d seconds", WEBSERVER_MAX_REQUESTS, WEBSERVER_WINDOW_SIZE_SECONDS);
server.addMiddleware(&digestAuth);
LOG_DEBUG("Digest authentication configured");
// ---- Default Password Lockdown Setup ----
// Registered last, and that position is load-bearing in both directions.
//
// After digestAuth: a caller who does not authenticate must get the ordinary 401 and
// learn nothing. Only a caller who HAS authenticated with the published default is
// told, via 403, why the device will not serve them. Putting this first would
// advertise the device's password state to any unauthenticated scanner on the LAN.
//
// After rateLimit: refused requests still count against the limiter, so the lockdown
// cannot be used as a cheap way around it.
//
// Note this covers only routes that run the server chain. The provisioning twins and
// /api/v1/health call skipServerMiddlewares(), which replaces the whole server chain
// (WebRequest.cpp:877-891), so the guard never runs on them. That is correct - a
// factory-fresh device is by definition on the default password, and a lockdown that
// blocked WiFi setup would strand it before it ever had a network - but it is
// emergent rather than written down anywhere, so do not "tidy" those registrations
// back onto the server chain.
_refreshDefaultPasswordFlag();
defaultPasswordGuard.setStateReader([]() { return _usingDefaultPassword; });
defaultPasswordGuard.setApOriginReader(_isApOrigin);
server.addMiddleware(&defaultPasswordGuard);
LOG_DEBUG("Default password guard configured");
LOG_DEBUG("Logging middleware configured");
}
// True only when the device has no stored credentials AND the request was addressed to
// the SoftAP's own address. This is the whole auth carve-out (D3/D9).
//
// Runs on the AsyncTCP task for every request to every path, so it must stay a state
// read plus an address compare: no mutex, no NVS, no logging, no allocation. Both reads
// are volatile loads of values the WiFi task publishes, which is why isApAddress() exists
// instead of WiFi.softAPIP() - the latter reads the netif through esp_netif_get_ip_info()
// on every request to every path.
//
// IMPORTANT, do not build on a guarantee this does not give: client()->localIP() reads
// _pcb->local_ip (AsyncTCP.cpp:1341-1352), the destination address lwIP recorded for the
// accepted connection. That is NOT proof of which physical netif the packet arrived on,
// and it is the same field ON_AP_FILTER reads. What makes this safe is the state check
// below, not the address compare. Bench-4 exists precisely because only hardware can
// show whether a LAN host static-routed to the AP subnet satisfies the compare.
//
// Still preferred over ON_AP_FILTER (`WiFi.localIP() != client()->localIP()`), which
// returns true for the device's own 127.0.0.1 health probe and true for EVERYTHING
// whenever WiFi.localIP() is 0.0.0.0 - exactly the unprovisioned case, so it would open
// the entire UI on the LAN the moment STA dropped. Comparing against the SoftAP address
// fixes both of those; it does not turn the check into an interface check.
static bool _isProvisioningOrigin(AsyncWebServerRequest *request)
{
// The state check carries the safety: outside UNPROVISIONED there is no bypass at
// all, whatever the address comparison says.
if (CustomWifi::getProvisioningState() != WifiProvisioning::State::UNPROVISIONED) return false;
AsyncClient *client = request->client();
if (client == nullptr) return false;
// False whenever no AP is up, so there is nothing to carve out until one exists.
return CustomWifi::isApConnection(client->localIP(), client->remoteIP());
}
// Same origin test, but also true during GRACE: the window right after credentials are
// accepted, while the AP is deliberately held up so the user can see where the meter
// went. Without this the setup page 401s the moment it succeeds - reloading it gets a
// browser password prompt, and the grace window has nothing to show, which defeats its
// entire purpose.
//
// Used only for reading: the page, its assets, the captive probes and the status
// endpoint. Anything that changes the device (credentials, scan) stays on the strict
// UNPROVISIONED test above, and AP_ASSIST remains fully closed either way.
static bool _isProvisioningSession(AsyncWebServerRequest *request)
{
WifiProvisioning::State state = CustomWifi::getProvisioningState();
if (state != WifiProvisioning::State::UNPROVISIONED &&
state != WifiProvisioning::State::GRACE) return false;
AsyncClient *client = request->client();
if (client == nullptr) return false;
return CustomWifi::isApConnection(client->localIP(), client->remoteIP());
}
// True whenever the request was addressed to the device's own SoftAP, in ANY provisioning
// state. Deliberately weaker than the two tests above: it does not authorise a bypass of
// anything, it only tells the default-password guard to widen its allowlist to the WiFi
// provisioning surface (see lib/web_auth_gate).
//
// The state-carrying tests above cannot serve that purpose. They are UNPROVISIONED-only
// (and GRACE for reads), which is precisely the gap: in GRACE and AP_ASSIST the
// provisioning routes run the full middleware chain, so a meter on the default password
// whose router changed would raise its assist AP and then refuse the credentials endpoint
// it exists to offer.
//
// Same cost rules as the others - volatile load plus address compare, on the AsyncTCP task.
static bool _isApOrigin(AsyncWebServerRequest *request)
{
// Restricted to the states where the device has NO working network of its own, which
// is the entire justification for the widening. GRACE is deliberately excluded: STA is
// connected there, so the user can reach the meter on the LAN and change the password
// the ordinary way - widening would buy nothing and would cost something real.
//
// That matters because localIP() is the destination lwIP recorded for the connection,
// not proof of arrival interface (see the comment on _isProvisioningOrigin). GRACE and
// AP_ASSIST are the states where AP and STA are up simultaneously, so a LAN host that
// can get a packet addressed to the AP address is only conceivable there. Excluding
// GRACE removes the case where that host could re-point a *connected* meter at another
// SSID; AP_ASSIST keeps it, but there the meter is already off the network, which is
// the situation the widening exists to fix.
WifiProvisioning::State state = CustomWifi::getProvisioningState();
if (state != WifiProvisioning::State::UNPROVISIONED &&
state != WifiProvisioning::State::AP_ASSIST) return false;
AsyncClient *client = request->client();
if (client == nullptr) return false;
// False whenever no AP is up.
return CustomWifi::isApConnection(client->localIP(), client->remoteIP());
}
// Registers a route twice: an open handler that only matches provisioning-origin
// requests, then the normal authenticated one.
//
// Insertion order is what makes this work - the first handler whose filter passes wins
// (WebServer.cpp:145-154). skipServerMiddlewares() drops the whole server chain, which
// includes rate limiting as well as auth, so the rate limiter is added back explicitly:
// an unauthenticated route still must not be floodable.
static void _onOpenDuringProvisioning(const char *uri, WebRequestMethodComposite method,
ArRequestHandlerFunction handler)
{
server.on(uri, method, handler)
.setFilter(_isProvisioningOrigin)
.skipServerMiddlewares()
.addMiddleware(&rateLimit);
server.on(uri, method, handler);
}
// As above, but open for the whole provisioning session including GRACE. Read-only
// routes only.
static void _onOpenDuringSession(const char *uri, WebRequestMethodComposite method,
ArRequestHandlerFunction handler)
{
server.on(uri, method, handler)
.setFilter(_isProvisioningSession)
.skipServerMiddlewares()
.addMiddleware(&rateLimit);
server.on(uri, method, handler);
}
// Helper functions for common response patterns
// The stream buffer starts at 1460 bytes of internal RAM and is re-created one size up on
// every write that does not fit, so a multi-KB document churned internal RAM on every
// request. Size it once from the document instead, and always above the PSRAM malloc
// threshold (malloc() keeps sizes up to and INCLUDING the threshold internal), so the
// buffer is a single PSRAM allocation.
static AsyncResponseStream *_beginJsonResponseStream(AsyncWebServerRequest *request, const JsonDocument &doc)
{
const size_t minPsramSize = (size_t)CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL + 1;
size_t size = measureJson(doc);
if (size < minPsramSize) size = minPsramSize;
return request->beginResponseStream("application/json", size);
}
static void _sendJsonResponse(AsyncWebServerRequest *request, const JsonDocument &doc, int32_t statusCode)
{
AsyncResponseStream *response = _beginJsonResponseStream(request, doc);
response->setCode(statusCode);
serializeJson(doc, *response);
request->send(response);
}
static void _sendSuccessResponse(AsyncWebServerRequest *request, const char *message)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["success"] = true;
doc["message"] = message;
_sendJsonResponse(request, doc, HTTP_CODE_OK);
releaseMutex(&_apiMutex);
}
static void _sendErrorResponse(AsyncWebServerRequest *request, int32_t statusCode, const char *message)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["success"] = false;
doc["error"] = message;
_sendJsonResponse(request, doc, statusCode);
releaseMutex(&_apiMutex);
}
static bool _acquireApiMutex(AsyncWebServerRequest *request)
{
if (!acquireMutex(&_apiMutex, API_MUTEX_TIMEOUT_MS)) {
LOG_WARNING("Failed to acquire API mutex within timeout");
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Server busy, please try again");
return false;
}
LOG_DEBUG("API mutex acquired for request: %s", request->url().c_str());
return true;
}
// Helper function to parse log level strings
static bool _parseLogLevel(const char *levelStr, LogLevel &level)
{
if (!levelStr) return false;
if (strcmp(levelStr, "VERBOSE") == 0)
level = LogLevel::VERBOSE;
else if (strcmp(levelStr, "DEBUG") == 0)
level = LogLevel::DEBUG;
else if (strcmp(levelStr, "INFO") == 0)
level = LogLevel::INFO;
else if (strcmp(levelStr, "WARNING") == 0)
level = LogLevel::WARNING;
else if (strcmp(levelStr, "ERROR") == 0)
level = LogLevel::ERROR;
else if (strcmp(levelStr, "FATAL") == 0)
level = LogLevel::FATAL;
else
return false;
return true;
}
// 404 for the Ethernet surface on products without the hardware. Runs after
// the middleware chain, so auth still comes first - an unauthenticated scanner
// cannot fingerprint the product.
static bool _requireEthernet(AsyncWebServerRequest *request)
{
if (globalHwProfile->hasEthernet) return true;
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "Ethernet is not available on this product");
return false;
}
// Helper function to validate HTTP method
// We cannot do setMethod since it makes all PUT requests fail (404) for some weird reason
// It is not too bad anyway since like this we have full control over the response
static bool _validateRequest(AsyncWebServerRequest *request, const char *expectedMethod, size_t maxContentLength)
{
if (maxContentLength > 0 && request->contentLength() > maxContentLength)
{
char errorMsg[STATUS_BUFFER_SIZE];
snprintf(errorMsg, sizeof(errorMsg), "Payload Too Large. Max: %zu", maxContentLength);
_sendErrorResponse(request, HTTP_CODE_PAYLOAD_TOO_LARGE, errorMsg);
return false;
}
if (strcmp(request->methodToString(), expectedMethod) != 0)
{
char errorMsg[STATUS_BUFFER_SIZE];
snprintf(errorMsg, sizeof(errorMsg), "Method Not Allowed. Use %s.", expectedMethod);
_sendErrorResponse(request, HTTP_CODE_METHOD_NOT_ALLOWED, errorMsg);
return false;
}
return _acquireApiMutex(request);
}
static bool _isPartialUpdate(AsyncWebServerRequest *request)
{
// Check if the request method is PATCH (partial update) or PUT (full update)
if (!request) return false; // Safety check
const char* method = request->methodToString();
bool isPartialUpdate = (strcmp(method, "PATCH") == 0);
return isPartialUpdate;
}
static void _startHealthCheckTask()
{
if (_healthCheckTaskHandle != NULL)
{
LOG_DEBUG("Health check task is already running");
return;
}
LOG_DEBUG("Starting health check task with %d bytes stack", HEALTH_CHECK_TASK_STACK_SIZE);
_consecutiveFailures = 0;
BaseType_t result = xTaskCreate(
_healthCheckTask,
HEALTH_CHECK_TASK_NAME,
HEALTH_CHECK_TASK_STACK_SIZE,
NULL,
HEALTH_CHECK_TASK_PRIORITY,
&_healthCheckTaskHandle);
if (result != pdPASS) {
LOG_ERROR("Failed to create health check task");
}
}
static void _stopHealthCheckTask() {
stopTaskGracefully(&_healthCheckTaskHandle, "Health check task");
}
static void _startOtaTimeoutTask()
{
if (_otaTimeoutTaskHandle != NULL)
{
LOG_DEBUG("OTA timeout task is already running");
return;
}
LOG_DEBUG("Starting OTA timeout task with %d bytes stack", OTA_TIMEOUT_TASK_STACK_SIZE);
BaseType_t result = xTaskCreate(
_otaTimeoutTask,
OTA_TIMEOUT_TASK_NAME,
OTA_TIMEOUT_TASK_STACK_SIZE,
NULL,
OTA_TIMEOUT_TASK_PRIORITY,
&_otaTimeoutTaskHandle);
if (result != pdPASS) {
LOG_ERROR("Failed to create OTA timeout task");
_otaTimeoutTaskHandle = NULL;
}
}
static void _stopOtaTimeoutTask() {
stopTaskGracefully(&_otaTimeoutTaskHandle, "OTA timeout task");
}
static void _otaTimeoutTask(void *parameter)
{
LOG_DEBUG("OTA timeout task started - system will reboot in %d seconds if OTA doesn't complete", OTA_TIMEOUT / 1000);
_otaTimeoutTaskShouldRun = true;
uint32_t notificationValue = ulTaskNotifyTake(pdTRUE, pdMS_TO_TICKS(OTA_TIMEOUT));
// If everything goes well, we will never reach here
if (notificationValue == 0 && _otaTimeoutTaskShouldRun) {
// Timeout occurred and task wasn't stopped - force reboot
LOG_ERROR("OTA timeout exceeded (%d seconds), forcing system restart", OTA_TIMEOUT / 1000);
setRestartSystem("OTA process timeout - forcing restart for system recovery");
} else {
LOG_DEBUG("OTA timeout task stopped normally");
}
_otaTimeoutTaskHandle = NULL;
vTaskDelete(NULL);
}
static void _healthCheckTask(void *parameter)
{
LOG_DEBUG("Health check task started");
_healthCheckTaskShouldRun = true;
while (_healthCheckTaskShouldRun)
{
TASK_HEARTBEAT(_healthCheckHeartbeat);
// Perform health check
if (_performHealthCheck())
{
// Reset failure counter on success
if (_consecutiveFailures > 0)
{
LOG_INFO("Health check recovered after %d failures", _consecutiveFailures);
_consecutiveFailures = 0;
}
LOG_DEBUG("Health check passed");
}
else
{
_consecutiveFailures++;
LOG_WARNING("Health check failed (attempt %d/%d)", _consecutiveFailures, HEALTH_CHECK_MAX_FAILURES);
if (_consecutiveFailures >= HEALTH_CHECK_MAX_FAILURES)
{
LOG_ERROR("Health check failed %d consecutive times, requesting system restart", HEALTH_CHECK_MAX_FAILURES);
setRestartSystem("Server health check failures exceeded maximum threshold");
break; // Exit the task as we're restarting
}
}
// Wait for stop notification with timeout (blocking) - zero CPU usage while waiting
if (ulTaskNotifyTake(pdTRUE, pdMS_TO_TICKS(HEALTH_CHECK_INTERVAL_MS)) > 0)
{
_healthCheckTaskShouldRun = false;
break;
}
}
LOG_DEBUG("Health check task stopping");
_healthCheckTaskHandle = NULL;
vTaskDelete(NULL);
}
static bool _performHealthCheck()
{
// Serving on the SoftAP with no upstream network is a working device, not a
// sick one. Gating on isFullyConnected() here fails every 30 s during AP-only
// operation, and five failures request a restart: at ~150 s uptime that is
// above QUICK_RESTART_THRESHOLD so safe mode never arms, and below
// COUNTERS_RESET_TIMEOUT so the consecutive-reset counter never clears. About
// 25 minutes of that reaches MAX_RESET_COUNT, which rolls the firmware back
// and wipes the user's NVS.
if (!CustomNet::isNetworkServiceable())
{
LOG_DEBUG("Health check: no serviceable network interface");
return false;
}
// Follow the station link with the unauthenticated local integrations. This runs on
// the periodic health-check task rather than from the WiFi task so customwifi keeps
// no knowledge of the services layered on top of it. Idempotent, so the worst case
// is Modbus appearing up to one check interval after STA comes up.
ModbusTcp::syncWithNetwork(CustomNet::isFullyConnected(), CustomWifi::isApServing());
// Perform a simple HTTP self-request to verify server responsiveness
WiFiClient client;
client.setTimeout(HEALTH_CHECK_TIMEOUT_MS);
if (!client.connect("127.0.0.1", WEBSERVER_PORT))
{
LOG_WARNING("Health check failed: Cannot connect to local web server");
return false;
}
// Send a simple GET request to the health endpoint
client.print("GET /api/v1/health HTTP/1.1\r\n");
client.print("Host: 127.0.0.1\r\n");
client.print("Connection: close\r\n\r\n");
// Wait for response with timeout
uint64_t startTime = millis64();
uint32_t loops = 0;
while (client.connected() && (millis64() - startTime) < HEALTH_CHECK_TIMEOUT_MS && loops < MAX_LOOP_ITERATIONS)
{
loops++;
// Reset task watchdog periodically during HTTP wait
if (loops % 50 == 0) {
esp_task_wdt_reset();
}
if (client.available())
{
char line[HTTP_HEALTH_CHECK_RESPONSE_BUFFER_SIZE];
size_t bytesRead = client.readBytesUntil('\n', line, sizeof(line) - 1);
line[bytesRead] = '\0';
if (strncmp(line, "HTTP/1.1 ", 9) == 0 && bytesRead >= 12)
{
// Extract status code from characters 9-11
char statusStr[4] = {line[9], line[10], line[11], '\0'};
int32_t statusCode = atoi(statusStr);
client.stop();
if (statusCode == HTTP_CODE_OK)
{
LOG_DEBUG("Health check passed: HTTP OK");
return true;
}
else
{
LOG_WARNING("Health check failed: HTTP status code %d", statusCode);
return false;
}
}
}
delay(10); // Small delay to prevent busy waiting
}
client.stop();
LOG_WARNING("Health check failed: HTTP request timeout");
return false;
}
// Password management functions
// ------------------------------
static bool _setWebPassword(const char *password)
{
if (!_validatePasswordStrength(password))
{
LOG_ERROR("Password does not meet strength requirements");
return false;
}
Preferences prefs;
if (!prefs.begin(PREFERENCES_NAMESPACE_AUTH, false))
{
LOG_ERROR("Failed to open auth preferences for writing");
return false;
}
bool success = prefs.putString(PREFERENCES_KEY_PASSWORD, password) > 0;
prefs.end();
if (success) { LOG_INFO("Web password updated successfully"); }
else { LOG_ERROR("Failed to save web password"); }
return success;
}
static bool _getWebPasswordFromPreferences(char *buffer, size_t bufferSize)
{
LOG_DEBUG("Getting web password");
if (buffer == nullptr || bufferSize == 0)
{
LOG_ERROR("Invalid buffer for getWebPassword");
return false;
}
Preferences prefs;
if (!prefs.begin(PREFERENCES_NAMESPACE_AUTH, true))
{
LOG_ERROR("Failed to open auth preferences for reading");
return false;
}
size_t res = prefs.getString(PREFERENCES_KEY_PASSWORD, buffer, bufferSize);
prefs.end();
return res > 0 && res < bufferSize; // Ensure we don't return true if the password is actually null or too long
}
// Only check length - there is no need to be picky here
static bool _validatePasswordStrength(const char *password)
{
if (password == nullptr) { return false; }
size_t length = strlen(password);
// Check minimum length
if (length < MIN_PASSWORD_LENGTH)
{
LOG_WARNING("Password too short (min %d characters)", MIN_PASSWORD_LENGTH);
return false;
}
// Check maximum length
if (length > MAX_PASSWORD_LENGTH)
{
LOG_WARNING("Password too long (max %d characters)", MAX_PASSWORD_LENGTH);
return false;
}
return true;
}
static void _serveApi()
{
// Group endpoints by functionality
_serveSystemEndpoints();
_serveIssueEndpoints();
_serveNetworkEndpoints();
_serveLoggingEndpoints();
_serveHealthEndpoints();
_serveAuthEndpoints();
_serveOtaEndpoints();
_serveAde7953Endpoints();
#ifdef ENV_DEV
_serveShadowDevEndpoints();
_serveCrashTestEndpoints();
_serveNvsDebugEndpoints();
#endif
_serveCustomMqttEndpoints();
_serveInfluxDbEndpoints();
_serveCrashEndpoints();
_serveLedEndpoints();
_serveBackupEndpoints();
_serveRestoreEndpoints();
_serveFileEndpoints();
}
// ETag helper functions for caching
// =================================
/**
* Check ETag validity and send 304 Not Modified if matched
* Returns true if 304 was sent (caller should return), false otherwise (continue processing)
*/
static bool _checkEtagAndSend304(AsyncWebServerRequest *request, const char* etag)
{
if (request->hasHeader("If-None-Match")) {
const String& clientEtag = request->header("If-None-Match");
if (clientEtag == etag) {
request->send(HTTP_CODE_NOT_MODIFIED);
return true;
}
}
return false;
}
/**
* Add ETag and Cache-Control headers, then send response
*/
static void _sendResponseWithEtag(AsyncWebServerRequest *request, AsyncWebServerResponse *response, const char* etag)
{
response->addHeader("Cache-Control", "no-cache"); // Always validate with server
response->addHeader("ETag", etag);
request->send(response);
}
/**
* Get sketch MD5 hash as ETag for cache busting
* Cached in static variable - computed once on first call
* Returns ETag in format: "abc123def456..."
*/
static const char* _getSketchEtag()
{
if (!_etagComputed) {
snprintf(_cachedEtag, sizeof(_cachedEtag), "\"%s\"", ESP.getSketchMD5().c_str());
_etagComputed = true;
LOG_DEBUG("Sketch ETag created (and saved in static variable): %s", _cachedEtag);
}
return _cachedEtag;
}
/**
* Get a sketch ETag qualified by which body is being served.
*
* "/" is registered three times and serves three different documents - the WiFi setup
* page, the password gate, and the dashboard - chosen by filters that change at runtime.
* The plain sketch ETag identifies the FIRMWARE, not the body, so all three would share
* one validator at one URL. A browser holding the gate page then sends
* If-None-Match after the password changes, the dashboard twin answers 304, and the
* browser re-renders the cached gate - which probes auth/status, sees the password is no
* longer default, and navigates to "/" again. That is an unbreakable reload loop, and the
* mirror case (cached dashboard, password reset by the button) hides the gate entirely.
*
* Only routes whose body varies at a fixed URL need this; everything else keeps the plain
* sketch ETag, which is still correct because their content is fixed per firmware.
*/
static const char* _getVariantEtag(const char* variant)
{
// One buffer per variant, so each returned pointer stays valid for the server's
// lifetime - the route lambdas capture it once at registration.
static char gateEtag[MD5_BUFFER_SIZE + 16] = {0};
static char dashEtag[MD5_BUFFER_SIZE + 16] = {0};
static char wifiEtag[MD5_BUFFER_SIZE + 16] = {0};
char* buffer;
if (strcmp(variant, "gate") == 0) buffer = gateEtag;
else if (strcmp(variant, "dash") == 0) buffer = dashEtag;
else buffer = wifiEtag;
if (buffer[0] == '\0') {
// _getSketchEtag() is already quoted, so splice the variant inside the quotes
// rather than appending after them.
const char* sketchEtag = _getSketchEtag();
size_t length = strlen(sketchEtag);
if (length >= 2 && sketchEtag[length - 1] == '"') {
snprintf(buffer, MD5_BUFFER_SIZE + 16, "%.*s-%s\"", (int)(length - 1), sketchEtag, variant);
} else {
snprintf(buffer, MD5_BUFFER_SIZE + 16, "\"%s-%s\"", sketchEtag, variant);
}
}
return buffer;
}
/**
* Generate ETag from file metadata
* Uses file size as primary identifier
* Should be very accurate for append-only files like csv energy data and txt logs)
*/
static const char* _generateFileEtag(const char* filename) {
File file = LittleFS.open(filename, "r");
if (!file) return "";
size_t fileSize = file.size();
file.close();
// Use file size as ETag - simple and effective for append-only files
// Format: "size-{bytes}" e.g. "size-59635"
static char etagBuffer[32];
snprintf(etagBuffer, sizeof(etagBuffer), "\"size-%u\"", (unsigned)fileSize);
return etagBuffer;
}
/**
* Send static content with ETag validation
* If client sends matching If-None-Match header, responds with 304 Not Modified (no body)
* Otherwise sends full content with ETag and Cache-Control headers
*/
static void _sendStaticWithEtag(AsyncWebServerRequest *request, const char* contentType, const uint8_t* content, size_t len, const char* etag)
{
// Check if client sent matching ETag
if (_checkEtagAndSend304(request, etag)) return;
// ETag doesn't match or not provided - stream full content from flash
// (uint8_t* + size_t overload constructs AsyncProgmemResponse, which reads
// chunks directly from flash via memcpy_P; no heap copy of the body, vs
// the const char* overload that copies the entire file into a String and
// can corrupt under concurrent parallel requests on a fragmented heap)
AsyncWebServerResponse *response = request->beginResponse(HTTP_CODE_OK, contentType, content, len);
_sendResponseWithEtag(request, response, etag);
}
/**
* Send file with ETag validation
* If client sends matching If-None-Match header, responds with 304 Not Modified
* Otherwise streams file content with ETag and Cache-Control headers
*/
static void _sendFileWithEtag(AsyncWebServerRequest *request, const char* filename, const char* contentType, bool forceDownload = false)
{
// Generate ETag from file metadata
const char* etag = _generateFileEtag(filename);
if (strlen(etag) == 0) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to generate ETag");
return;
}
// Check if client sent matching ETag
if (_checkEtagAndSend304(request, etag)) return;
// ETag doesn't match or not provided - send full file
AsyncWebServerResponse *response = request->beginResponse(LittleFS, filename, contentType, forceDownload);
if (!response) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to create response");
return;
}
_sendResponseWithEtag(request, response, etag);
}
// === STATIC CONTENT SERVING ===
static void _serveStaticContent()
{
// Cache strategy: "no-cache" with ETag validation
// - Browser always asks server before using cache
// - Server responds 304 Not Modified (no body) if ETag matches → fast
// - Server responds 200 OK with full content if ETag differs → always fresh
// When firmware is updated, sketch MD5 changes → ETag differs → fresh content
// This needs to be a solid pointer, so we need a static variable
// that will persist for the server's lifetime
const char* etag = _getSketchEtag();
// CSS files
_onOpenDuringSession("/css/button.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(button_css), etag);
});
_onOpenDuringSession("/css/forms.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(forms_css), etag);
});
_onOpenDuringSession("/css/index.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(index_css), etag);
});
_onOpenDuringSession("/css/styles.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(styles_css), etag);
});
_onOpenDuringSession("/css/section.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(section_css), etag);
});
_onOpenDuringSession("/css/tooltip.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(tooltip_css), etag);
});
_onOpenDuringSession("/css/typography.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(typography_css), etag);
});
_onOpenDuringSession("/css/reboot-wait.css", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/css", EMBEDDED(reboot_wait_css), etag);
});
// JavaScript files
_onOpenDuringSession("/js/api-client.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(api_client_js), etag);
});
_onOpenDuringSession("/js/chart-helpers.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(chart_helpers_js), etag);
});
_onOpenDuringSession("/js/data-helpers.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(data_helpers_js), etag);
});
_onOpenDuringSession("/js/issues.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(issues_js), etag);
});
_onOpenDuringSession("/js/power-flow.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(power_flow_js), etag);
});
_onOpenDuringSession("/js/tooltip.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(tooltip_js), etag);
});
_onOpenDuringSession("/js/reboot-wait.js", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "application/javascript", EMBEDDED(reboot_wait_js), etag);
});
// Resources
_onOpenDuringSession("/favicon.svg", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "image/svg+xml", EMBEDDED(favicon_svg), etag);
});
// Main dashboard
// "/" is the one route whose twins differ. An unprovisioned device reached over its
// own SoftAP lands on WiFi setup - which is what makes the captive-portal redirect
// useful, since the OS opens "/" and nothing else. Everywhere else "/" is the
// dashboard, unchanged.
// Each twin carries its own validator - see _getVariantEtag(). Sharing one would let a
// browser revalidate a cached gate page against the dashboard twin, get 304, and loop.
const char* wifiEtag = _getVariantEtag("wifi");
const char* gateEtag = _getVariantEtag("gate");
const char* dashEtag = _getVariantEtag("dash");
server.on("/", HTTP_GET, [wifiEtag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(wifi_setup_html), wifiEtag);
}).setFilter(_isProvisioningSession)
.skipServerMiddlewares()
.addMiddleware(&rateLimit);
// Then, on a device that has a network but is still holding the shipped default
// password, the gate. Ordered between the two: provisioning comes first because an
// unprovisioned device is necessarily also on the default password, and stranding it
// here - before it has a network at all - would leave no way forward.
//
// Deliberately no skipServerMiddlewares(): the user must still authenticate to see the
// gate, and the guard allows "/" anyway.
server.on("/", HTTP_GET, [gateEtag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(password_setup_html), gateEtag);
}).setFilter([](AsyncWebServerRequest *request) { (void)request; return _usingDefaultPassword; });
server.on("/", HTTP_GET, [dashEtag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(index_html), dashEtag);
});
// Also reachable by name, so a provisioned device can be re-pointed at another
// network from the normal UI without erasing its credentials first.
_onOpenDuringSession("/wifi-setup.html", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(wifi_setup_html), etag);
});
// Configuration pages
server.on("/ade7953-tester", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(ade7953_tester_html), etag);
});
server.on("/configuration", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(configuration_html), etag);
});
server.on("/calibration", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(calibration_html), etag);
});
server.on("/channel", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(channel_html), etag);
});
server.on("/info", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(info_html), etag);
});
server.on("/integrations", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(integrations_html), etag);
});
server.on("/log", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(log_html), etag);
});
server.on("/update", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(update_html), etag);
});
server.on("/waveform", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(waveform_html), etag);
});
// Swagger UI
server.on("/swagger-ui", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/html", EMBEDDED(swagger_ui_html), etag);
});
server.on("/swagger.yaml", HTTP_GET, [etag](AsyncWebServerRequest *request) {
_sendStaticWithEtag(request, "text/yaml", EMBEDDED(swagger_yaml), etag);
});
}
// === HEALTH ENDPOINTS ===
static void _serveHealthEndpoints()
{
server.on("/api/v1/health", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["status"] = "ok";
doc["uptime"] = millis64();
char timestamp[TIMESTAMP_ISO_BUFFER_SIZE];
CustomTime::getTimestampIso(timestamp, sizeof(timestamp));
doc["timestamp"] = timestamp;
_sendJsonResponse(request, doc);
}).skipServerMiddlewares(); // For the health endpoint, no authentication or rate limiting
}
// === AUTHENTICATION ENDPOINTS ===
static void _serveAuthEndpoints()
{
_serveAuthStatusEndpoint();
_serveChangePasswordEndpoint();
_serveResetPasswordEndpoint();
}
static void _serveAuthStatusEndpoint()
{
server.on("/api/v1/auth/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// The same cached flag the lockdown enforces on, not a second NVS read and
// strcmp. Two independent computations of "is this the default password" could
// disagree, and the one the user can see would be the one that is wrong.
doc["usingDefaultPassword"] = _usingDefaultPassword;
// Lets the gate page decide whether to offer the WiFi setup link. That link is
// only reachable from the SoftAP while locked down - on the LAN it redirects
// straight back to the gate - so offering it there would be a dead end.
doc["apOrigin"] = _isApOrigin(request);
doc["username"] = WEBSERVER_DEFAULT_USERNAME;
// For the pages that show the product name before (or without) a system-info fetch.
doc["productName"] = PRODUCT_NAME;
_sendJsonResponse(request, doc);
});
}
static void _serveChangePasswordEndpoint()
{
static AsyncCallbackJsonWebHandler *changePasswordHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/auth/change-password",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_PASSWORD)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
const char *currentPassword = doc["currentPassword"];
const char *newPassword = doc["newPassword"];
if (!currentPassword || !newPassword)
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing currentPassword or newPassword");
return;
}
// Validate current password
char storedPassword[WEB_PASSWORD_BUFFER_SIZE];
if (!_getWebPasswordFromPreferences(storedPassword, sizeof(storedPassword)))
{
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve current password");
return;
}
if (strcmp(currentPassword, storedPassword) != 0)
{
_sendErrorResponse(request, HTTP_CODE_UNAUTHORIZED, "Current password is incorrect");
return;
}
// Nothing else stops a user from "changing" the password to the published
// default and staying exactly where they started. Checked here rather than in
// _validatePasswordStrength() because resetWebPassword() sets the default on
// purpose and must keep working - it backs the physical button, which is the
// only recovery path for a forgotten password.
if (strcmp(newPassword, WEBSERVER_DEFAULT_PASSWORD) == 0)
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "The new password cannot be the default password");
return;
}
// Validate and save new password
if (!_setWebPassword(newPassword))
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "New password must be between 8 and 64 characters");
return;
}
LOG_INFO("Password changed successfully via API");
_sendSuccessResponse(request, "Password changed successfully");
// Update authentication middleware with new password
updateAuthPasswordWithOneFromPreferences();
});
server.addHandler(changePasswordHandler);
}
static void _serveResetPasswordEndpoint()
{
server.on("/api/v1/auth/reset-password", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (resetWebPassword()) {
updateAuthPasswordWithOneFromPreferences();
LOG_WARNING("Password reset to default via API");
_sendSuccessResponse(request, "Password reset to default");
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to reset password");
}
});
}
// === OTA UPDATE ENDPOINTS ===
static void _serveOtaEndpoints()
{
_serveOtaUploadEndpoint();
_serveOtaStatusEndpoint();
_serveOtaRollbackEndpoint();
_serveFirmwareStatusEndpoint();
}
static void _serveOtaUploadEndpoint()
{
server.on("/api/v1/ota/upload", HTTP_POST,
_handleOtaUploadComplete,
_handleOtaUploadData);
}
static void _handleOtaUploadComplete(AsyncWebServerRequest *request)
{
// Handle the completion of the upload
bool isOwner = (request == _otaOwner);
if (isOwner) _otaOwner = nullptr;
if (request->getResponse()) return; // Response already set due to error
// No file part at all, or not the request whose image was written: nothing here says
// an update happened, so never answer success (or restart) on its behalf.
if (!isOwner) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "No firmware image was received");
return;
}
// Stop OTA timeout task since OTA process is completing
_stopOtaTimeoutTask();
if (Update.hasError() || !_otaFinalized) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["success"] = false;
doc["message"] = Update.hasError() ? Update.errorString() : "Firmware upload did not complete";
_sendJsonResponse(request, doc);
LOG_ERROR("OTA update failed: %s", Update.errorString());
Update.printError(Serial);
Led::blinkRedFast(Led::PRIO_CRITICAL, 5000ULL);
// Schedule restart even on failure for system recovery
setRestartSystem("Restart needed after failed firmware update for system recovery");
} else {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["success"] = true;
doc["message"] = "Firmware update completed successfully";
doc["md5"] = Update.md5String();
_sendJsonResponse(request, doc);
LOG_INFO("OTA update completed successfully");
LOG_DEBUG("New firmware MD5: %s", Update.md5String().c_str());
// Distinct from the MQTT/cloud OTA success log: local uploads have no
// cryptographic signature check (see ota-firmware-signature-verification spec)
LOG_WARNING("Firmware installed via local web upload - not cryptographically verified");
// Fresh image in the partition - give it its own rollback chance,
// independent of whatever the previous firmware already consumed
CrashMonitor::clearRollbackTried();
Led::blinkGreenFast(Led::PRIO_CRITICAL, 3000ULL);
setRestartSystem("Restart needed after firmware update");
}
}
// Upload and body callbacks run DURING body parsing - WebRequest.cpp calls
// _handler->handleUpload() at :612 and :783 while _parseState is PARSE_REQ_BODY, and only
// reaches _runMiddlewareChain() at :233 once _parsedLength == _contentLength. Every server
// middleware therefore fires AFTER the bytes have already been handled, digestAuth
// included. For a firmware image that is far too late: Update.begin() has erased the
// partition and Update.end(true) has already called esp_ota_set_boot_partition().
//
// The library knows: WebRequest.cpp:610 carries a "check if authenticated before calling
// the upload" comment and then does not do it.
//
// So the upload routes must check for themselves, on the first chunk, before anything is
// written. Returns true when the caller should stop; the response is already set, and
// _handleOtaUploadComplete/_handleFileUploadData bail on request->getResponse().
static bool _rejectUploadIfNotPermitted(AsyncWebServerRequest *request)
{
// Throttle before authenticating. This runs during body parsing, ahead of the lockout
// middleware, so without this an attacker could move password guessing to the upload
// routes and never be slowed: every attempt would run a full digest check here, and a
// correct guess would reach Update.begin() before the middleware's 429 could mask it.
// The middleware still records the failure afterwards from the 401 this leaves set.
uint32_t retryAfterSeconds = 0;
if (authLockout.isSourceLocked(request, retryAfterSeconds))
{
LOG_WARNING("Refused an upload from a locked-out source before authenticating");
AsyncWebServerResponse *response = request->beginResponse(HTTP_CODE_TOO_MANY_REQUESTS, "application/json",
"{\"success\":false,\"error\":\"Too many failed login attempts. Try again later.\"}");
response->addHeader("Retry-After", String(retryAfterSeconds));
request->send(response);
return true;
}
char storedPassword[WEB_PASSWORD_BUFFER_SIZE];
bool passwordReadable = _getWebPasswordFromPreferences(storedPassword, sizeof(storedPassword));
if (!passwordReadable || !request->authenticate(WEBSERVER_DEFAULT_USERNAME, storedPassword, WEBSERVER_REALM))
{
LOG_WARNING("Refused an unauthenticated upload from %s before any data was written",
request->client()->remoteIP().toString().c_str());
request->requestAuthentication(AsyncAuthType::AUTH_DIGEST, WEBSERVER_REALM, "The password is incorrect. Please try again.");
return true;
}
// The same allowlist the middleware applies, for the same reason - just early enough
// to matter.
if (WebAuthGate::evaluate(_usingDefaultPassword, _isApOrigin(request), request->url().c_str()) != WebAuthGate::Action::ALLOW)
{
LOG_WARNING("Refused an upload while the default password is still in use");
sendDefaultPasswordDeniedResponse(request);
return true;
}
return false;
}
// The owner's connection closed. After a completed upload the completion handler has
// already let go; anything else is a transfer that died half way.
static void _releaseOtaOwner(AsyncWebServerRequest *request)
{
if (request != _otaOwner) return;
_otaOwner = nullptr;
if (_otaFinalized) return;
LOG_WARNING("Firmware upload connection closed before completion - aborting the update");
Update.abort();
_stopOtaTimeoutTask();
}
static void _handleOtaUploadData(AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final)
{
if (!index) {
// Before Update.begin() erases anything. See _rejectUploadIfNotPermitted().
// A refused request never touches the upload in progress.
if (_rejectUploadIfNotPermitted(request)) return;
if (_otaOwner != nullptr) {
LOG_WARNING("Refused a firmware upload while another one is in progress");
_sendErrorResponse(request, HTTP_CODE_CONFLICT, "Another firmware upload is in progress");
return;
}
// First chunk - initialize OTA
if (!_initializeOtaUpload(request, filename)) {
return;
}
_otaOwner = request;
_otaFinalized = false;
request->onDisconnect([request]() { _releaseOtaOwner(request); });
// Fail fast when the first chunk already covers the descriptor
// region (it normally does): a wrong-hardware image is rejected
// before a single byte is written. The authoritative re-check in
// _finalizeOtaUpload() covers a first chunk too small for this.
if (ImageDescriptor::coversDescriptor(len)) {
ImageDescriptor::Verdict verdict = AppImageDescriptor::validateImageBuffer(data, len, false);
if (!ImageDescriptor::accepts(verdict)) {
LOG_ERROR("Firmware image rejected on first chunk: %s", ImageDescriptor::verdictToString(verdict));
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Firmware image is not compatible with this device");
Update.abort();
_stopOtaTimeoutTask();
_otaOwner = nullptr;
return;
}
}
}
// Refused on its first chunk, already failed, or not the upload in progress
if (request != _otaOwner) return;
// Write chunk to flash
if (len) {
if (!_writeOtaChunk(request, data, len, index)) {
_otaOwner = nullptr;
return;
}
}
// Final chunk - complete the update. Ownership is released by the completion handler.
if (final) _otaFinalized = _finalizeOtaUpload(request);
}
static bool _initializeOtaUpload(AsyncWebServerRequest *request, const String& filename)
{
LOG_INFO("Starting OTA update with file: %s", filename.c_str());
// Validate file extension
if (!filename.endsWith(".bin")) {
LOG_ERROR("Invalid file type. Only .bin files are supported");
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "File must be in .bin format");
return false;
}
// Cross-product gate: a wrong-product image fails PSRAM init at boot (quad vs
// octal, fixed at compile time). A positive token mismatch is rejected before
// any flash write; a name with no token (self-built image) passes as today.
ProductLine artifactProduct;
if (productFromArtifactName(filename.c_str(), artifactProduct) &&
artifactProduct != globalHwProfile->product) {
LOG_ERROR("Firmware artifact %s is built for %s but this device is %s - rejected",
filename.c_str(), productLineToString(artifactProduct),
productLineToString(globalHwProfile->product));
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Firmware image is built for a different product");
return false;
}
// Get content length from header
size_t contentLength = request->header("Content-Length").toInt();
if (contentLength == 0) {
LOG_ERROR("No Content-Length header found or empty file");
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing Content-Length header or empty file");
return false;
}
// Validate minimum firmware size
if (contentLength < MINIMUM_FIRMWARE_SIZE) {
LOG_ERROR("Firmware file too small: %zu bytes (minimum: %d bytes)", contentLength, MINIMUM_FIRMWARE_SIZE);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Firmware file too small");
return false;
}
// Check free heap
size_t freeHeap = ESP.getFreeHeap();
LOG_DEBUG("Free heap before OTA: %zu bytes", freeHeap);
if (freeHeap < MINIMUM_FREE_HEAP_OTA) {
LOG_ERROR("Insufficient memory for OTA update");
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Insufficient memory for update");
return false;
}
// Start OTA timeout watchdog task before beginning the actual OTA process
_startOtaTimeoutTask();
// Begin OTA update with known size
if (!Update.begin(contentLength, U_FLASH)) {
LOG_ERROR("Failed to begin OTA update: %s", Update.errorString());
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Failed to begin update");
Led::doubleBlinkYellow(Led::PRIO_URGENT, 1000ULL);
_stopOtaTimeoutTask(); // Stop timeout task on failure
return false;
}
// Handle MD5 verification if provided
_setupOtaMd5Verification(request);
// Start LED indication for OTA progress
Led::blinkPurpleFast(Led::PRIO_MEDIUM);
LOG_DEBUG("OTA update started, expected size: %zu bytes", contentLength);
return true;
}
static void _setupOtaMd5Verification(AsyncWebServerRequest *request)
{
if (!request->hasHeader("X-MD5")) {
LOG_WARNING("No MD5 header provided, skipping verification");
return;
}
const char* md5HeaderCStr = request->header("X-MD5").c_str();
size_t headerLength = strlen(md5HeaderCStr);
if (headerLength == MD5_BUFFER_SIZE - 1) {
char md5Header[MD5_BUFFER_SIZE];
snprintf(md5Header, sizeof(md5Header), "%s", md5HeaderCStr);
// Convert to lowercase
for (size_t i = 0; md5Header[i]; i++) {
md5Header[i] = (char)tolower((unsigned char)md5Header[i]);
}
Update.setMD5(md5Header);
LOG_DEBUG("MD5 verification enabled: %s", md5Header);
} else if (headerLength > 0) {
LOG_WARNING("Invalid MD5 length (%zu), skipping verification", headerLength);
} else {
LOG_WARNING("No MD5 header provided, skipping verification");
}
}
static bool _writeOtaChunk(AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index)
{
// Reset watchdog before flash write
size_t written = Update.write(data, len);
if (written != len) {
LOG_ERROR("OTA write failed: expected %zu bytes, wrote %zu bytes", len, written);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Write failed");
Update.abort();
_stopOtaTimeoutTask(); // Stop timeout task on write failure
return false;
}
// Log progress periodically
static size_t lastProgressIndex = 0;
if (index >= lastProgressIndex + SIZE_REPORT_UPDATE_OTA || index == 0) {
esp_task_wdt_reset(); // Only do it once in a while
float progress = Update.size() > 0UL ? (float)Update.progress() / (float)Update.size() * 100.0f : 0.0f;
LOG_DEBUG("OTA progress: %.1f%% (%zu / %zu bytes)", progress, Update.progress(), Update.size());
lastProgressIndex = index;
}
return true;
}
// True only when the staged image passed every check and Update.end(true) activated it.
static bool _finalizeOtaUpload(AsyncWebServerRequest *request)
{
LOG_DEBUG("Finalizing OTA update...");
// Validate that we actually received data
if (Update.progress() == 0) {
LOG_ERROR("OTA finalization failed: No data received");
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "No firmware data received");
Update.abort();
_stopOtaTimeoutTask(); // Stop timeout task on failure
return false;
}
// Validate minimum size
if (Update.progress() < MINIMUM_FIRMWARE_SIZE) {
LOG_ERROR("OTA finalization failed: Firmware too small (%zu bytes)", Update.progress());
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Firmware file too small");
Update.abort();
_stopOtaTimeoutTask(); // Stop timeout task on failure
return false;
}
// Authoritative compatibility gate: read the staged image's descriptor
// back off the passive partition before Update.end(true) activates it.
// A wrong-PSRAM image fails PSRAM init before any application code runs,
// so nothing post-boot can recover from activating one.
const esp_partition_t* stagedPartition = esp_ota_get_next_update_partition(NULL);
ImageDescriptor::Verdict verdict = AppImageDescriptor::validatePartition(stagedPartition, false);
if (!ImageDescriptor::accepts(verdict)) {
LOG_ERROR("Staged firmware image rejected: %s", ImageDescriptor::verdictToString(verdict));
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Firmware image is not compatible with this device");
Update.abort();
// The rejected image is complete and structurally valid in the passive
// slot; Update.abort() does not touch flash. Scrub it or the rollback
// consumers - none of which are descriptor-gated - could later activate
// it and brick the device. (Not done on the first-chunk reject: nothing
// was written there and the passive slot still holds a legitimate
// rollback target.)
scrubOtaImageHeader(stagedPartition);
_stopOtaTimeoutTask();
return false;
}
if (verdict == ImageDescriptor::Verdict::ACCEPT_DEV_ON_PROD) {
LOG_WARNING("Accepting a dev-built image on a prod device via manual upload");
} else if (verdict == ImageDescriptor::Verdict::ACCEPT_LEGACY_NO_DESCRIPTOR) {
LOG_WARNING("Staged image carries no descriptor (pre-2.4 release or self-built) - accepted on Home");
}
// Reset watchdog before flash verification and finalization
bool success = Update.end(true);
if (!success) {
LOG_ERROR("OTA finalization failed: %s", Update.errorString());
_stopOtaTimeoutTask(); // Stop timeout task on failure
// Error response will be handled in the main handler
} else {
LOG_DEBUG("OTA update finalization successful");
Led::blinkGreenFast(Led::PRIO_CRITICAL, 3000ULL);
// Note: timeout task will be stopped in _handleOtaUploadComplete
}
return success;
}
static void _handleFileUploadData(AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final)
{
static File uploadFile;
static String targetPath;
if (!index) {
// Before any file is opened or truncated. See _rejectUploadIfNotPermitted().
if (_rejectUploadIfNotPermitted(request)) return;
// First chunk - extract path from URL and create file
String url = request->url();
targetPath = url.substring(url.indexOf("/api/v1/files/") + 14); // Remove "/api/v1/files/" prefix
if (targetPath.length() == 0) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "File path cannot be empty");
return;
}
// URL decode the filename to handle encoded slashes properly
targetPath.replace("%2F", "/");
targetPath.replace("%2f", "/");
// Ensure filename starts with "/"
if (!targetPath.startsWith("/")) {
targetPath = "/" + targetPath;
}
LOG_DEBUG("Starting file upload to: %s", targetPath.c_str());
// Check available space
size_t freeSpace = LittleFS.totalBytes() - LittleFS.usedBytes();
if (freeSpace < MINIMUM_FREE_LITTLEFS_SIZE) { // Require at least 1KB free space
LOG_WARNING("Insufficient storage space for file upload: %zu bytes free", freeSpace);
_sendErrorResponse(request, HTTP_CODE_INSUFFICIENT_STORAGE, "Insufficient storage space");
return;
}
// Create file for writing
uploadFile = LittleFS.open(targetPath, FILE_WRITE);
if (!uploadFile) {
LOG_ERROR("Failed to create file for upload: %s", targetPath.c_str());
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to create file");
return;
}
}
// Write data chunk
if (len && uploadFile) {
size_t written = uploadFile.write(data, len);
if (written != len) {
LOG_ERROR("Failed to write data chunk at index %zu", index);
uploadFile.close();
LittleFS.remove(targetPath); // Clean up partial file
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to write file data");
return;
}
}
// Final chunk - complete the upload
if (final) {
if (uploadFile) {
uploadFile.close();
LOG_INFO("File upload completed successfully: %s (%zu bytes)", targetPath.c_str(), index + len);
_sendSuccessResponse(request, "File uploaded successfully");
} else {
LOG_ERROR("File upload failed: file handle not available");
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "File upload failed");
}
}
}
static void _serveOtaStatusEndpoint()
{
server.on("/api/v1/ota/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["status"] = Update.isRunning() ? "running" : "idle";
const esp_partition_t *running = esp_ota_get_running_partition();
doc["currentPartition"] = running->label;
doc["hasError"] = Update.hasError();
doc["lastError"] = Update.errorString();
doc["size"] = Update.size();
doc["progress"] = Update.progress();
doc["remaining"] = Update.remaining();
doc["progressPercent"] = Update.size() > 0 ? (float)Update.progress() / (float)Update.size() * 100.0 : 0.0;
// Add current firmware info
doc["currentVersion"] = FIRMWARE_BUILD_VERSION;
doc["currentMD5"] = ESP.getSketchMD5();
// Rollback target fingerprint; null when the passive slot holds no
// valid descriptor. Not read mid-upload: Update.write() is streaming
// into that very partition (2 s poll would race the flash writes and
// report a half-overwritten descriptor), and canRollback derives from
// the same read so status and actuator agree on one predicate.
char otherSha[SHA256_HEX_BUFFER_SIZE];
bool otherShaReadable = !Update.isRunning() && getOtherPartitionSha256(otherSha, sizeof(otherSha));
doc["canRollback"] = otherShaReadable;
if (otherShaReadable) {
doc["otherPartitionSha256"] = otherSha;
} else {
doc["otherPartitionSha256"] = nullptr;
}
_sendJsonResponse(request, doc);
});
}
static void _serveOtaRollbackEndpoint()
{
server.on("/api/v1/ota/rollback", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (Update.isRunning()) {
Update.abort();
LOG_INFO("Aborted running OTA update");
_stopOtaTimeoutTask(); // Stop timeout task when aborting OTA
}
// Act first, respond from the actual outcome. The old shape gated on
// Update.canRollBack() (a one-byte flash[0]==0xE9 check, true even for
// a half-downloaded image) and reported success before switching.
LOG_WARNING("Firmware rollback requested via API");
FirmwareRollbackResult result = attemptFirmwareRollback("Firmware rollback requested via API");
switch (result) {
case FirmwareRollbackResult::SUCCESS:
_sendSuccessResponse(request, "Rollback initiated. Device will restart.");
break;
case FirmwareRollbackResult::INVALID_IMAGE:
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "No valid firmware in the other partition");
break;
case FirmwareRollbackResult::RESTART_BLOCKED:
_sendErrorResponse(request, HTTP_CODE_LOCKED, "Restart currently blocked. Boot partition unchanged");
break;
}
});
}
static bool _fetchGitHubReleaseInfo(JsonDocument &doc)
{
// Check internet connectivity before attempting API call
if (!CustomNet::isFullyConnected(true)) {
LOG_DEBUG("Cannot fetch GitHub release info: no internet connectivity");
return false;
}
HTTPClient http;
http.begin(GITHUB_API_LATEST_RELEASE_URL);
http.addHeader("User-Agent", "EnergyMe-Home-ESP32");
http.addHeader("Accept", "application/vnd.github.v3+json");
// Reset watchdog before network call
int httpCode = http.GET();
if (httpCode != HTTP_CODE_OK) {
LOG_WARNING("GitHub API request failed with code: %d", httpCode);
http.end();
return false;
}
// Parse GitHub API response - reset before and after data fetch
String response = http.getString();
http.end();
// Create the JSON document for parsing the response (different from the function argument doc)
SpiRamAllocator allocator;
JsonDocument responseDoc(&allocator);
DeserializationError error = deserializeJson(responseDoc, response);
if (error) {
LOG_WARNING("Failed to parse GitHub API response: %s", error.c_str());
return false;
}
if (!responseDoc.is<JsonObject>()) {
LOG_WARNING("Invalid GitHub API response: expected object");
return false;
}
// /releases/latest returns the newest published release repo-wide and already
// excludes drafts and prereleases, so no filtering loop is needed here.
JsonObject release = responseDoc.as<JsonObject>();
const char* tagName = release["tag_name"].as<const char*>();
if (!tagName) {
LOG_WARNING("No tag_name in GitHub latest release response");
return false;
}
const char* releaseDate = release["published_at"].as<const char*>();
const char* changelog = release["html_url"].as<const char*>();
const char* downloadUrl = nullptr;
// Releases carry one .bin per product: pick the asset whose token matches the
// running product, never simply the first match (the Home token is a substring
// of the Pro token, so productFromArtifactName resolves Pro first).
for (JsonObject asset : release["assets"].as<JsonArray>()) {
const char* name = asset["name"].as<const char*>();
if (name == nullptr) continue;
// The application image only: a release also carries <name>_bootloader.bin and
// <name>_partitions.bin under the same product token.
size_t nameLength = strlen(name);
if (nameLength < 4 || strcmp(name + nameLength - 4, ".bin") != 0) continue;
if (strstr(name, "bootloader") != nullptr || strstr(name, "partitions") != nullptr) continue;
ProductLine assetProduct;
if (productFromArtifactName(name, assetProduct) && assetProduct == globalHwProfile->product) {
downloadUrl = asset["browser_download_url"].as<const char*>();
break;
}
}
// Compare versions to determine if update is available
bool isLatest = compareVersions(FIRMWARE_BUILD_VERSION, tagName) >= 0;
doc["isLatest"] = isLatest;
// Only populate update fields when a newer version is available
if (!isLatest) {
doc["availableVersion"] = tagName;
if (releaseDate) doc["releaseDate"] = releaseDate;
if (downloadUrl) doc["updateUrl"] = downloadUrl;
if (changelog) doc["changelogUrl"] = changelog;
}
LOG_DEBUG("GitHub release info fetched: version=%s, isLatest=%s",
tagName, isLatest ? "true" : "false");
return true;
}
static void _serveFirmwareStatusEndpoint()
{
// Get firmware update information
server.on("/api/v1/firmware/update-info", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// Get current firmware info
doc["currentVersion"] = FIRMWARE_BUILD_VERSION;
doc["buildDate"] = FIRMWARE_BUILD_DATE;
// In non-community mode, we assume updates are handled via app/cloud, so we consider it always up to date
if (!globalCommunityMode) doc["isLatest"] = true;
else if (CustomNet::isFullyConnected(true)) { // Check internet connectivity before checking anything
// Fetch from GitHub API in community mode
bool githubInfoFetched = _fetchGitHubReleaseInfo(doc);
if (!githubInfoFetched) {
doc["isLatest"] = true; // Assume latest since we can't check
// Here we log the warning since internet should be present, but most likely GitHub/the logic broke
LOG_WARNING("Failed to fetch GitHub release info, assuming current version is latest");
}
} else {
doc["isLatest"] = true; // Assume latest since we can't check
LOG_DEBUG("No internet connectivity, cannot check for firmware updates"); // Only debug since internet may not be available
}
_sendJsonResponse(request, doc);
});
}
// === SYSTEM MANAGEMENT ENDPOINTS ===
static void _serveSystemEndpoints()
{
// System information
server.on("/api/v1/system/info", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// Get both static and dynamic info
SpiRamAllocator allocatorStatic, allocatorDynamic;
JsonDocument docStatic(&allocatorStatic);
JsonDocument docDynamic(&allocatorDynamic);
getJsonDeviceStaticInfo(docStatic);
getJsonDeviceDynamicInfo(docDynamic);
// Combine into a single response
doc["static"] = docStatic;
doc["dynamic"] = docDynamic;
_sendJsonResponse(request, doc); });
// Statistics
server.on("/api/v1/system/statistics", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
statisticsToJson(statistics, doc);
_sendJsonResponse(request, doc); });
// Raw CPU ring samples - forensic timeline endpoint
// Query params: lastSeconds (1..3600, default 600), core (0|1|both, default both)
server.on("/api/v1/system/cpu/samples", HTTP_GET, [](AsyncWebServerRequest *request)
{
uint32_t lastSeconds = TaskProfiler::CPU_DEFAULT_FETCH_LAST_SECONDS;
if (request->hasParam("lastSeconds")) {
long parsed = request->getParam("lastSeconds")->value().toInt();
if (parsed <= 0) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "lastSeconds must be a positive integer");
return;
}
lastSeconds = (uint32_t)parsed;
if (lastSeconds > TaskProfiler::CPU_RING_CAPACITY_SECONDS)
lastSeconds = TaskProfiler::CPU_RING_CAPACITY_SECONDS;
}
bool wantCore0 = true, wantCore1 = true;
if (request->hasParam("core")) {
const String& coreParam = request->getParam("core")->value();
if (coreParam == "0") { wantCore1 = false; }
else if (coreParam == "1") { wantCore0 = false; }
else if (coreParam != "both") {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "core must be 0, 1, or both");
return;
}
}
// Allocate temp buffer on heap (max 3600 entries x 8 B = 28.8 KB).
// ESPAsyncWebServer dispatches handlers serially so the buffer never
// overlaps with another invocation of this handler.
size_t maxSamples = lastSeconds > 0 ? lastSeconds : TaskProfiler::CPU_RING_CAPACITY_SECONDS;
TaskProfiler::CpuSample* buf = (TaskProfiler::CpuSample*)ps_malloc(maxSamples * sizeof(TaskProfiler::CpuSample));
if (buf == nullptr) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Out of PSRAM");
return;
}
size_t count = TaskProfiler::getRawSamples(buf, maxSamples, lastSeconds);
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["intervalSeconds"] = 1;
doc["fromEpoch"] = count > 0 ? buf[0].epochSecond : 0;
doc["toEpoch"] = count > 0 ? buf[count - 1].epochSecond : 0;
doc["samplesReturned"] = count;
if (wantCore0) {
JsonArray a0 = doc["core0"].to<JsonArray>();
for (size_t i = 0; i < count; i++) a0.add(buf[i].core0Percent);
}
if (wantCore1) {
JsonArray a1 = doc["core1"].to<JsonArray>();
for (size_t i = 0; i < count; i++) a1.add(buf[i].core1Percent);
}
free(buf);
_sendJsonResponse(request, doc); });
// System restart
server.on("/api/v1/system/restart", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (setRestartSystem("System restart requested via API")) {
_sendSuccessResponse(request, "System restart initiated");
} else {
_sendErrorResponse(request, HTTP_CODE_LOCKED, "Failed to initiate restart. Another restart may already be in progress or restart is currently locked");
} });
// Factory reset
server.on("/api/v1/system/factory-reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
_sendSuccessResponse(request, "Factory reset initiated");
setRestartSystem("Factory reset requested via API", true); });
// Safe mode info
server.on("/api/v1/system/safe-mode", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["active"] = CrashMonitor::isInSafeMode();
doc["canRestartNow"] = CrashMonitor::canRestartNow();
doc["minimumUptimeRemainingMs"] = CrashMonitor::getMinimumUptimeRemaining();
if (CrashMonitor::isInSafeMode()) {
doc["message"] = "Device in safe mode - restart protection active to prevent loops";
doc["action"] = "Wait for minimum uptime or perform OTA update to fix underlying issue";
}
_sendJsonResponse(request, doc); });
// Clear safe mode
server.on("/api/v1/system/safe-mode/clear", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (CrashMonitor::isInSafeMode()) {
CrashMonitor::clearSafeModeCounters();
_sendSuccessResponse(request, "Safe mode cleared. Device will restart.");
setRestartSystem("Safe mode manually cleared via API");
} else {
_sendSuccessResponse(request, "Device is not in safe mode");
} });
// Check if secrets exist
server.on("/api/v1/system/secrets", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["hasSecrets"] = !globalCommunityMode;
_sendJsonResponse(request, doc); });
// Get system time
server.on("/api/v1/system/time", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["synced"] = CustomTime::isTimeSynched();
doc["unixTime"] = CustomTime::getUnixTime();
char isoBuffer[TIMESTAMP_BUFFER_SIZE];
CustomTime::getTimestampIso(isoBuffer, sizeof(isoBuffer));
doc["isoTime"] = isoBuffer;
_sendJsonResponse(request, doc); });
// Set system time (for devices without internet connectivity)
server.on(
"/api/v1/system/time",
HTTP_POST,
[](AsyncWebServerRequest *request) {},
NULL,
[](AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total)
{
if (!_validateRequest(request, "POST")) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
DeserializationError error = deserializeJson(doc, data, len);
if (error || !doc["unixTime"].is<uint64_t>())
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid JSON. Required: {\"unixTime\": <unix_seconds>}");
return;
}
uint64_t unixTime = doc["unixTime"].as<uint64_t>();
if (CustomTime::setUnixTime(unixTime))
{
SpiRamAllocator respAllocator;
JsonDocument respDoc(&respAllocator);
respDoc["success"] = true;
respDoc["message"] = "Time synchronized";
char isoBuffer[TIMESTAMP_BUFFER_SIZE];
CustomTime::getTimestampIso(isoBuffer, sizeof(isoBuffer));
respDoc["newTime"] = isoBuffer;
_sendJsonResponse(request, respDoc);
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Failed to set time. Value out of valid range.");
}
});
}
// === NETWORK MANAGEMENT ENDPOINTS ===
// === ISSUE REGISTRY ENDPOINTS ===
static void _serveIssueEndpoints()
{
// Currently visible device issues (issue #145)
server.on("/api/v1/system/issues", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (!IssueRegistry::issuesToJson(doc)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve issues");
return;
}
_sendJsonResponse(request, doc); });
// Acknowledge issues: {"all": true} or {"code": "...", "channel": <optional>}
static AsyncCallbackJsonWebHandler *ackIssueHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/system/issues/ack",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_ISSUES_ACK)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (doc["all"].is<bool>() && doc["all"].as<bool>()) {
uint32_t ackedCount = IssueRegistry::ackAll();
char message[STATUS_BUFFER_SIZE];
snprintf(message, sizeof(message), "Acknowledged %lu issue(s)", (unsigned long)ackedCount);
_sendSuccessResponse(request, message);
return;
}
if (!doc["code"].is<const char*>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'code' (or 'all') parameter");
return;
}
uint8_t channel = ISSUE_GLOBAL_SCOPE;
if (doc["channel"].is<uint8_t>()) channel = doc["channel"].as<uint8_t>();
if (IssueRegistry::ack(doc["code"].as<const char*>(), channel)) {
_sendSuccessResponse(request, "Issue acknowledged");
} else {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "No such issue instance");
} });
server.addHandler(ackIssueHandler);
}
// Captive-portal detection probes. Registered as explicit handlers rather than relying
// on onNotFound, which ignores filters (so it could not be limited to the AP netif) but
// still runs middleware (so it would demand auth on a probe that cannot authenticate).
//
// Answering with a redirect rather than the expected 204/success is what makes the OS
// show its "sign in to network" sheet.
static void _serveCaptivePortalProbes()
{
static const char *const kProbePaths[] = {
"/generate_204", // Android
"/gen_204", // Android, older
"/hotspot-detect.html", // iOS / macOS
"/library/test/success.html",
"/ncsi.txt", // Windows
"/connecttest.txt", // Windows 10+
"/redirect", // Windows, follow-up
};
for (size_t i = 0; i < sizeof(kProbePaths) / sizeof(kProbePaths[0]); i++) {
_onOpenDuringSession(kProbePaths[i], HTTP_GET, [](AsyncWebServerRequest *request) {
char location[IP_ADDRESS_BUFFER_SIZE + 16];
snprintf(location, sizeof(location), "http://%s/", WiFi.softAPIP().toString().c_str());
AsyncWebServerResponse *response = request->beginResponse(302, "text/plain", "");
response->addHeader("Location", location);
request->send(response);
});
}
}
static void _serveNetworkEndpoints()
{
_serveCaptivePortalProbes();
// Provisioning status: what the device is doing, and where to reach it afterwards.
// Open on the AP while unprovisioned because the setup page polls this before any
// password could have been entered.
_onOpenDuringSession("/api/v1/network/wifi/status", HTTP_GET, [](AsyncWebServerRequest *request) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["state"] = (uint8_t)CustomWifi::getProvisioningState();
doc["connected"] = CustomWifi::isFullyConnected();
doc["apServing"] = CustomWifi::isApServing();
char ssid[WIFI_SSID_BUFFER_SIZE];
CustomWifi::getStoredSsid(ssid, sizeof(ssid));
doc["ssid"] = ssid;
doc["ip"] = WiFi.localIP().toString();
doc["apIp"] = WiFi.softAPIP().toString();
doc["hostname"] = MDNS_HOSTNAME ".local";
doc["rssi"] = WiFi.RSSI();
// Identity, so the setup page can show which meter you are talking to before
// any of the authenticated endpoints are reachable. Nothing sensitive: the
// device id is already the SoftAP's SSID suffix.
doc["deviceId"] = DEVICE_ID;
doc["productName"] = PRODUCT_NAME;
doc["firmwareVersion"] = FIRMWARE_BUILD_VERSION;
doc["uptime"] = millis64();
// The credentials POST answers as soon as the request is queued, so its 200 says
// nothing about whether the driver accepted the write. This is where the client
// finds that out, which is why the POST's message points here.
doc["credentialWriteFailed"] = CustomWifi::lastCredentialWriteFailed();
_sendJsonResponse(request, doc);
});
// Network scan. Async and cached in customwifi; this just relays state so the client
// can poll rather than hold a request open for the length of a scan.
_onOpenDuringProvisioning("/api/v1/network/wifi/scan", HTTP_GET, [](AsyncWebServerRequest *request) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// ?refresh is the "Scan again" press, which must touch the radio rather than
// re-serve the cached set. The client's polling requests deliberately omit it.
CustomWifi::getScanResultsAsJson(doc, request->hasParam("refresh"));
_sendJsonResponse(request, doc);
});
// Why the last association failed. Replaces the WiFiManager /diagnostic page (D11);
// nothing else ever exposed these fields.
_onOpenDuringProvisioning("/api/v1/network/wifi/diagnostics", HTTP_GET, [](AsyncWebServerRequest *request) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
CustomWifi::getDisconnectDiagnosticsAsJson(doc);
_sendJsonResponse(request, doc);
});
// WiFi reset
server.on("/api/v1/network/wifi/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
_sendSuccessResponse(request, "WiFi credentials reset. Device will restart and enter configuration mode.");
CustomWifi::resetWifi();
});
// Set WiFi credentials.
//
// Registered twice like the routes above, and this one is load-bearing: submitting
// credentials is the ONE thing an unprovisioned user must be able to do, and they
// cannot authenticate to do it. A single authenticated handler here would 401 the
// whole provisioning flow at its last step.
//
// JSON body handlers are AsyncWebHandler subclasses, so they take the same filter
// and middleware treatment; they just cannot go through the server.on() helper.
ArJsonRequestHandlerFunction credentialsCallback =
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST")) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Validate required fields
if (!doc["ssid"].is<const char*>())
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing or invalid 'ssid' field");
return;
}
if (!doc["password"].is<const char*>())
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'password' field");
return;
}
const char* ssid = doc["ssid"];
const char* password = doc["password"];
// Validate SSID length (1-31 characters)
if (!isStringLengthValid(ssid, 1, WIFI_SSID_BUFFER_SIZE - 1))
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "SSID must be 1-31 characters");
return;
}
// Validate password length (0-63 characters)
if (!isStringLengthValid(password, 0, WIFI_PASSWORD_BUFFER_SIZE - 1))
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Password must be 0-63 characters");
return;
}
LOG_INFO("Received request to set WiFi credentials for SSID: %s", ssid);
if (CustomWifi::setCredentials(ssid, password)) _sendSuccessResponse(request, "WiFi credentials saved. Connecting to the new network without restarting - poll /api/v1/network/wifi/status for the result.");
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to save credentials for the specified network. Please verify them and try again.");
};
// Open twin first, so it wins by insertion order when the filter passes.
AsyncCallbackJsonWebHandler *openCredentialsHandler =
new AsyncCallbackJsonWebHandler("/api/v1/network/wifi/credentials", credentialsCallback);
openCredentialsHandler->setFilter(_isProvisioningOrigin);
openCredentialsHandler->skipServerMiddlewares();
openCredentialsHandler->addMiddleware(&rateLimit);
server.addHandler(openCredentialsHandler);
AsyncCallbackJsonWebHandler *wifiCredentialsHandler =
new AsyncCallbackJsonWebHandler("/api/v1/network/wifi/credentials", credentialsCallback);
server.addHandler(wifiCredentialsHandler);
// Get network configuration (static IP)
server.on("/api/v1/network/config", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (CustomWifi::getConfigurationAsJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to get network configuration");
});
// Set network configuration (full PUT or partial PATCH). The device restarts to apply.
// Exact match, here and on every JSON handler whose URL has sub-routes: a plain string
// also matches "<url>/...", so this handler used to take POST <url>/reset whenever the
// request carried a JSON content type (the web UI always sends one) and answer 400 for
// the missing body, before the reset route registered after it was ever consulted.
static AsyncCallbackJsonWebHandler *setNetworkConfigHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/network/config"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_NETWORK)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (CustomWifi::setConfigurationFromJson(doc, isPartialUpdate)) {
LOG_INFO("Network configuration %s via API", isPartialUpdate ? "partially updated" : "updated");
_sendSuccessResponse(request, "Network configuration updated successfully. The device will restart to apply the new settings.");
setRestartSystem("Restart to apply new network configuration");
} else {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid network configuration");
}
});
server.addHandler(setNetworkConfigHandler);
// Reset network configuration to defaults (DHCP)
server.on("/api/v1/network/config/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (CustomWifi::resetConfiguration()) {
_sendSuccessResponse(request, "Network configuration reset successfully. The device will restart to apply the defaults.");
setRestartSystem("Restart to apply network configuration reset");
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to reset network configuration");
}
});
// === Ethernet (Home Pro) ===
// Mirrors the wifi config surface. On products without Ethernet every route
// answers 4xx and touches no NVS - the feature does not exist there.
server.on("/api/v1/network/ethernet/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
if (!_requireEthernet(request)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
CustomEth::getStatusAsJson(doc);
_sendJsonResponse(request, doc);
});
server.on("/api/v1/network/ethernet/config", HTTP_GET, [](AsyncWebServerRequest *request)
{
if (!_requireEthernet(request)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (CustomEth::getConfigurationAsJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to get Ethernet configuration");
});
// Set Ethernet configuration (full PUT or partial PATCH). The device restarts to apply.
static AsyncCallbackJsonWebHandler *setEthConfigHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/network/ethernet/config"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_requireEthernet(request)) return;
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_NETWORK)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (CustomEth::setConfigurationFromJson(doc, isPartialUpdate)) {
LOG_INFO("Ethernet configuration %s via API", isPartialUpdate ? "partially updated" : "updated");
_sendSuccessResponse(request, "Ethernet configuration updated successfully. The device will restart to apply the new settings.");
setRestartSystem("Restart to apply new Ethernet configuration");
} else {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid Ethernet configuration");
}
});
server.addHandler(setEthConfigHandler);
server.on("/api/v1/network/ethernet/config/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_requireEthernet(request)) return;
if (!_validateRequest(request, "POST")) return;
if (CustomEth::resetConfiguration()) {
_sendSuccessResponse(request, "Ethernet configuration reset successfully. The device will restart to apply the defaults.");
setRestartSystem("Restart to apply Ethernet configuration reset");
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to reset Ethernet configuration");
}
});
}
// === LOGGING ENDPOINTS ===
static void _serveLoggingEndpoints()
{
// Get log levels
server.on("/api/v1/logs/level", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["print"] = AdvancedLogger::logLevelToString(AdvancedLogger::getPrintLevel());
doc["save"] = AdvancedLogger::logLevelToString(AdvancedLogger::getSaveLevel());
_sendJsonResponse(request, doc);
});
// Set log levels (using AsyncCallbackJsonWebHandler for JSON body)
static AsyncCallbackJsonWebHandler *setLogLevelHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/logs/level",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_LOGS_LEVEL)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
const char *printLevel = doc["print"].as<const char *>();
const char *saveLevel = doc["save"].as<const char *>();
if (!printLevel && !saveLevel)
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "At least one of 'print' or 'save' level must be specified");
return;
}
char resultMsg[STATUS_BUFFER_SIZE];
snprintf(resultMsg, sizeof(resultMsg), "Log levels %s:", isPartialUpdate ? "partially updated" : "updated");
bool success = true;
// Set print level if provided
if (printLevel && success)
{
LogLevel level;
if (_parseLogLevel(printLevel, level))
{
AdvancedLogger::setPrintLevel(level);
snprintf(resultMsg + strlen(resultMsg), sizeof(resultMsg) - strlen(resultMsg),
" print=%s", printLevel);
}
else
{
success = false;
}
}
// Set save level if provided
if (saveLevel && success)
{
LogLevel level;
if (_parseLogLevel(saveLevel, level))
{
AdvancedLogger::setSaveLevel(level);
snprintf(resultMsg + strlen(resultMsg), sizeof(resultMsg) - strlen(resultMsg),
" save=%s", saveLevel);
}
else
{
success = false;
}
}
if (success)
{
_sendSuccessResponse(request, resultMsg);
LOG_INFO("Log levels %s via API", isPartialUpdate ? "partially updated" : "updated");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid log level specified. Valid levels: VERBOSE, DEBUG, INFO, WARNING, ERROR, FATAL");
}
});
server.addHandler(setLogLevelHandler);
// Get all logs
server.on("/api/v1/logs", HTTP_GET, [](AsyncWebServerRequest *request)
{
request->send(LittleFS, LOG_PATH, "text/plain");
});
// Clear logs
server.on("/api/v1/logs/clear", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (!AdvancedLogger::clearLog()) {
_sendErrorResponse(request, HTTP_CODE_SERVICE_UNAVAILABLE, "Log file is busy (rotation in progress), retry in a few seconds");
return;
}
_sendSuccessResponse(request, "Logs cleared successfully");
LOG_INFO("Logs cleared via API");
});
// Get UDP log destination (cannot use logs/ as it interferes with the previous /logs endpoint)
server.on("/api/v1/logs-udp-destination", HTTP_GET, [](AsyncWebServerRequest *request)
{
char ipAddress[IP_ADDRESS_BUFFER_SIZE];
if (CustomLog::getUdpDestination(ipAddress, sizeof(ipAddress))) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["destination"] = ipAddress;
_sendJsonResponse(request, doc);
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve UDP destination");
}
});
// Set UDP log destination
static AsyncCallbackJsonWebHandler *setUdpDestinationHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/logs-udp-destination",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_UDP_DESTINATIONS)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
const char* destination = doc["destination"].as<const char*>();
if (!destination) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'destination' field");
return;
}
if (CustomLog::setUdpDestination(destination)) {
_sendSuccessResponse(request, "UDP destination updated successfully");
LOG_INFO("UDP destination updated via API: %s", destination);
} else {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid IP address format");
}
});
server.addHandler(setUdpDestinationHandler);
}
#ifdef ENV_DEV
// Shared by the dev-only inject-* endpoints below: re-serializes a JsonVariant
// out of the request's SpiRamAllocator document into its own PSRAM buffer, since
// each injector hands the payload to a Mqtt/Shadow function that outlives the
// request's JsonDocument. Returns nullptr (and has already sent the error
// response) on allocation failure, so callers only need to check for that.
static char* _jsonVariantToPsramString(AsyncWebServerRequest *request, JsonVariant variant) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(variant);
size_t len = measureJson(doc) + 1;
char *payload = (char *)ps_malloc(len);
if (!payload) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Allocation failed");
return nullptr;
}
serializeJson(doc, payload, len);
return payload;
}
// Dev-only: feed a synthetic shadow delta through the real inbound path
// (routeMessage -> task drain -> ApplyFn -> ack publish) so the apply logic
// can be exercised on hardware without a cloud desired-state writer. Never
// compiled into the production firmware.
// Body: {"name":"system","doc":{"version":1,"state":{"led_brightness":20}}}
static void _serveShadowDevEndpoints() {
static AsyncCallbackJsonWebHandler *injectShadowDeltaHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/shadow/inject-delta",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA * MAX_CHANNEL_COUNT)) return;
const char *name = json["name"].as<const char *>();
if (!name || json["doc"].isNull()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Body requires 'name' and 'doc'");
return;
}
char *payload = _jsonVariantToPsramString(request, json["doc"]);
if (!payload) return;
bool ok = Shadow::injectDelta(name, payload);
free(payload);
if (ok) _sendSuccessResponse(request, "Synthetic shadow delta injected");
else _sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Unknown shadow name");
});
server.addHandler(injectShadowDeltaHandler);
// Dev-only: inject a synthetic IoT Command execution through the real
// handler (no cloud dispatcher needed). The device acts on the operation;
// the response publish targets a synthetic execution id.
// Body: {"executionId":"dev-1","payload":{"operation":"energy_reset","channels":[3]}}
static AsyncCallbackJsonWebHandler *injectCommandHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/shadow/inject-command",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA)) return;
const char *execId = json["executionId"].as<const char *>();
if (!execId || json["payload"].isNull()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Body requires 'executionId' and 'payload'");
return;
}
char *payload = _jsonVariantToPsramString(request, json["payload"]);
if (!payload) return;
Mqtt::injectCommandExecution(execId, payload);
free(payload);
_sendSuccessResponse(request, "Synthetic command injected");
});
server.addHandler(injectCommandHandler);
// Dev-only: inject a synthetic AWS IoT job execution document so the OTA
// download path can be driven with an arbitrary (unreachable, refused, or
// real) firmware URL without minting a job. The body IS the notify-next
// payload, so the real validator and version guard run unchanged.
// Body: {"execution":{"jobId":"dev-1","jobDocument":{"operation":"ota_update",
// "force":true,"firmware":{"url":"https://...","version":"9.9.9"}}}}
static AsyncCallbackJsonWebHandler *injectJobHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ota/inject-job",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA * MAX_CHANNEL_COUNT)) return;
if (json["execution"].isNull()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Body requires an 'execution' object");
return;
}
char *payload = _jsonVariantToPsramString(request, json);
if (!payload) return;
Mqtt::injectJobExecution(payload);
free(payload);
_sendSuccessResponse(request, "Synthetic job execution injected");
});
server.addHandler(injectJobHandler);
LOG_DEBUG("Registered dev-only shadow delta + command + job injection endpoints");
}
static const char* _nvsTypeToString(nvs_type_t type) {
switch (type) {
case NVS_TYPE_U8: return "u8";
case NVS_TYPE_I8: return "i8";
case NVS_TYPE_U16: return "u16";
case NVS_TYPE_I16: return "i16";
case NVS_TYPE_U32: return "u32";
case NVS_TYPE_I32: return "i32";
case NVS_TYPE_U64: return "u64";
case NVS_TYPE_I64: return "i64";
case NVS_TYPE_STR: return "str";
case NVS_TYPE_BLOB: return "blob";
default: return "unknown";
}
}
// Keys never returned by value (only presence/type) - private key material,
// certs and anything whose name marks it as a credential. Matched on the key
// name rather than an explicit allowlist so a newly added password key is
// redacted by default instead of leaking until someone remembers it: the
// endpoint is gated by the very admin password it would otherwise hand out.
static bool _isNvsValueSensitive(const char* key) {
static const char* const SENSITIVE_FRAGMENTS[] = {
"pass", "pwd", "token", "secret", "key", "cert", "cred"
};
char lowered[NVS_NAME_BUFFER_SIZE];
size_t i = 0;
for (; key[i] != '\0' && i < sizeof(lowered) - 1; i++) {
char c = key[i];
lowered[i] = (c >= 'A' && c <= 'Z') ? (char)(c + ('a' - 'A')) : c;
}
lowered[i] = '\0';
for (size_t f = 0; f < sizeof(SENSITIVE_FRAGMENTS) / sizeof(SENSITIVE_FRAGMENTS[0]); f++) {
if (strstr(lowered, SENSITIVE_FRAGMENTS[f]) != nullptr) return true;
}
return false;
}
// Dev-only: generic NVS namespace/key browser and editor, for inspecting and
// recovering bench devices without a full manufacturing reflash.
// GET /api/v1/debug/nvs/namespaces -> [{"namespace":"factory_ns","entryCount":3}, ...]
// GET /api/v1/debug/nvs/entries?namespace=X -> [{"key":"pcb_revision","type":"str","value":"v5.0"}, ...]
// POST /api/v1/debug/nvs/entry {"namespace":"factory_ns","key":"pcb_revision","type":"string","value":"v5.0"}
// type: string (default) | i32 | u32 | i64 | u64 | float | bool
// DELETE /api/v1/debug/nvs/entry?namespace=X&key=Y
// DELETE /api/v1/debug/nvs/namespace?namespace=X -> clears every key in the namespace
static void _serveNvsDebugEndpoints() {
server.on("/api/v1/debug/nvs/namespaces", HTTP_GET, [](AsyncWebServerRequest *request)
{
char names[NVS_DEBUG_MAX_NAMESPACES][NVS_NAME_BUFFER_SIZE];
uint32_t counts[NVS_DEBUG_MAX_NAMESPACES];
size_t namespaceCount = 0;
nvs_iterator_t it = nullptr;
esp_err_t err = nvs_entry_find(NVS_DEFAULT_PART_NAME, NULL, NVS_TYPE_ANY, &it);
size_t iterations = 0;
while (err == ESP_OK && it != nullptr && iterations < NVS_DEBUG_MAX_ENTRIES) {
nvs_entry_info_t info;
nvs_entry_info(it, &info);
bool found = false;
for (size_t i = 0; i < namespaceCount; i++) {
if (strcmp(names[i], info.namespace_name) == 0) {
counts[i]++;
found = true;
break;
}
}
if (!found && namespaceCount < NVS_DEBUG_MAX_NAMESPACES) {
snprintf(names[namespaceCount], NVS_NAME_BUFFER_SIZE, "%s", info.namespace_name);
counts[namespaceCount] = 1;
namespaceCount++;
}
err = nvs_entry_next(&it);
iterations++;
}
nvs_release_iterator(it);
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
JsonArray arr = doc.to<JsonArray>();
for (size_t i = 0; i < namespaceCount; i++) {
JsonObject obj = arr.add<JsonObject>();
obj["namespace"] = names[i];
obj["entryCount"] = counts[i];
}
_sendJsonResponse(request, doc); });
server.on("/api/v1/debug/nvs/entries", HTTP_GET, [](AsyncWebServerRequest *request)
{
if (!request->hasParam("namespace")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'namespace' query parameter");
return;
}
char targetNamespace[NVS_NAME_BUFFER_SIZE];
snprintf(targetNamespace, sizeof(targetNamespace), "%s", request->getParam("namespace")->value().c_str());
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
JsonArray arr = doc.to<JsonArray>();
nvs_iterator_t it = nullptr;
esp_err_t err = nvs_entry_find(NVS_DEFAULT_PART_NAME, targetNamespace, NVS_TYPE_ANY, &it);
size_t iterations = 0;
while (err == ESP_OK && it != nullptr && iterations < NVS_DEBUG_MAX_ENTRIES) {
nvs_entry_info_t info;
nvs_entry_info(it, &info);
JsonObject obj = arr.add<JsonObject>();
obj["key"] = info.key;
obj["type"] = _nvsTypeToString(info.type);
if (_isNvsValueSensitive(info.key)) {
obj["value"] = "<redacted>";
} else if (info.type == NVS_TYPE_STR) {
Preferences prefs;
if (prefs.begin(targetNamespace, true)) {
// getString() returns 0 without touching the buffer when
// the stored string is longer than it, so the buffer must
// be primed and the result checked - otherwise 512 bytes
// of uninitialised stack get serialised into the reply.
char value[NVS_DEBUG_STRING_VALUE_BUFFER_SIZE];
value[0] = '\0';
if (prefs.getString(info.key, value, sizeof(value)) > 0) {
obj["value"] = value;
} else {
obj["value"] = "<unreadable or too long>";
}
prefs.end();
}
} else if (info.type == NVS_TYPE_I32) {
Preferences prefs;
if (prefs.begin(targetNamespace, true)) { obj["value"] = prefs.getInt(info.key); prefs.end(); }
} else if (info.type == NVS_TYPE_U32) {
Preferences prefs;
if (prefs.begin(targetNamespace, true)) { obj["value"] = prefs.getUInt(info.key); prefs.end(); }
} else if (info.type == NVS_TYPE_I64) {
Preferences prefs;
if (prefs.begin(targetNamespace, true)) { obj["value"] = prefs.getLong64(info.key); prefs.end(); }
} else if (info.type == NVS_TYPE_U64) {
Preferences prefs;
if (prefs.begin(targetNamespace, true)) { obj["value"] = prefs.getULong64(info.key); prefs.end(); }
}
// Narrower int types and blobs: key/type only, value decode not worth the branches here.
err = nvs_entry_next(&it);
iterations++;
}
nvs_release_iterator(it);
_sendJsonResponse(request, doc); });
static AsyncCallbackJsonWebHandler *writeEntryHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/debug/nvs/entry",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_NVS_ENTRY)) return;
const char *ns = json["namespace"].as<const char *>();
const char *key = json["key"].as<const char *>();
if (!ns || !key || json["value"].isNull()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Body requires 'namespace', 'key', 'value'");
return;
}
const char *type = json["type"].is<const char *>() ? json["type"].as<const char *>() : "string";
Preferences prefs;
if (!prefs.begin(ns, false)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to open namespace");
return;
}
bool ok = true;
if (strcmp(type, "string") == 0) {
ok = prefs.putString(key, json["value"].as<const char *>()) > 0;
} else if (strcmp(type, "i32") == 0) {
ok = prefs.putInt(key, json["value"].as<int32_t>()) > 0;
} else if (strcmp(type, "u32") == 0) {
ok = prefs.putUInt(key, json["value"].as<uint32_t>()) > 0;
} else if (strcmp(type, "i64") == 0) {
ok = prefs.putLong64(key, json["value"].as<int64_t>()) > 0;
} else if (strcmp(type, "u64") == 0) {
ok = prefs.putULong64(key, json["value"].as<uint64_t>()) > 0;
} else if (strcmp(type, "float") == 0) {
ok = prefs.putFloat(key, json["value"].as<float>()) > 0;
} else if (strcmp(type, "bool") == 0) {
ok = prefs.putBool(key, json["value"].as<bool>()) > 0;
} else {
ok = false;
}
prefs.end();
if (ok) {
LOG_WARNING("Dev endpoint: wrote NVS %s::%s (type=%s)", ns, key, type);
// This is the one writer of auth_ns that does not go through
// _setWebPassword, so the cached lockdown flag and the live digestAuth
// credential would both go stale until the next boot - silently
// disabling the lockdown on a device someone just set back to the
// default password.
if (strcmp(ns, PREFERENCES_NAMESPACE_AUTH) == 0) {
LOG_WARNING("Dev endpoint touched the auth namespace - reloading the web password");
updateAuthPasswordWithOneFromPreferences();
}
_sendSuccessResponse(request, "NVS entry written");
} else {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Unknown type, or write failed");
}
});
server.addHandler(writeEntryHandler);
server.on("/api/v1/debug/nvs/entry", HTTP_DELETE, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "DELETE")) return;
if (!request->hasParam("namespace") || !request->hasParam("key")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'namespace' or 'key' query parameter");
return;
}
char ns[NVS_NAME_BUFFER_SIZE];
char key[NVS_NAME_BUFFER_SIZE];
snprintf(ns, sizeof(ns), "%s", request->getParam("namespace")->value().c_str());
snprintf(key, sizeof(key), "%s", request->getParam("key")->value().c_str());
Preferences prefs;
if (!prefs.begin(ns, false)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to open namespace");
return;
}
bool ok = prefs.remove(key);
prefs.end();
if (ok) {
LOG_WARNING("Dev endpoint: removed NVS %s::%s", ns, key);
// Same reason as the write path above.
if (strcmp(ns, PREFERENCES_NAMESPACE_AUTH) == 0) {
LOG_WARNING("Dev endpoint removed an auth entry - reloading the web password");
updateAuthPasswordWithOneFromPreferences();
}
_sendSuccessResponse(request, "NVS entry removed");
} else {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "Key not found");
} });
server.on("/api/v1/debug/nvs/namespace", HTTP_DELETE, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "DELETE")) return;
if (!request->hasParam("namespace")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'namespace' query parameter");
return;
}
char ns[NVS_NAME_BUFFER_SIZE];
snprintf(ns, sizeof(ns), "%s", request->getParam("namespace")->value().c_str());
Preferences prefs;
if (!prefs.begin(ns, false)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to open namespace");
return;
}
bool ok = prefs.clear();
prefs.end();
if (ok) {
LOG_WARNING("Dev endpoint: cleared NVS namespace %s", ns);
_sendSuccessResponse(request, "NVS namespace cleared");
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to clear namespace");
} });
LOG_DEBUG("Registered dev-only NVS management endpoints");
}
// noinline so an optimising build can't flatten the recursion into a loop.
// Deliberately unbounded - the MAX_LOOP_ITERATIONS convention doesn't apply
// here since running out of stack IS the point.
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Winfinite-recursion"
static void __attribute__((noinline)) _crashTestStackOverflow(uint32_t depth) {
volatile uint8_t padding[512]; // Real per-frame stack consumption, not just a return address
memset((void *)padding, (int)depth, sizeof(padding));
_crashTestStackOverflow(depth + 1);
}
#pragma GCC diagnostic pop
// Dev-only: crash the device on purpose to exercise the archive and publish
// pipeline on real hardware. Each route faults through a different mechanism
// so the panic handler and backtrace unwinder are exercised more than one
// way. No response is ever sent - the device resets before the handler can
// return, so a client just sees the connection drop.
static void _serveCrashTestEndpoints() {
server.on("/api/v1/debug/crash/null-deref", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
LOG_WARNING("Debug endpoint: forcing a null pointer dereference");
volatile uint32_t *nullPtr = nullptr;
*nullPtr = 0xDEADBEEF;
});
server.on("/api/v1/debug/crash/abort", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
LOG_WARNING("Debug endpoint: forcing abort()");
abort();
});
server.on("/api/v1/debug/crash/stack-overflow", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
LOG_WARNING("Debug endpoint: forcing a stack overflow");
_crashTestStackOverflow(0);
});
LOG_DEBUG("Registered dev-only crash test endpoints: null-deref, abort, stack-overflow");
}
#endif
// === ADE7953 ENDPOINTS ===
static void _serveAde7953Endpoints() {
// === CONFIGURATION ENDPOINTS ===
// Get ADE7953 configuration
server.on("/api/v1/ade7953/config", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
Ade7953::getConfigurationAsJson(doc);
_sendJsonResponse(request, doc);
});
// Set ADE7953 configuration (PUT/PATCH)
static AsyncCallbackJsonWebHandler *setAde7953ConfigHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/ade7953/config"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_CONFIG)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (Ade7953::setConfigurationFromJson(doc, isPartialUpdate))
{
LOG_INFO("ADE7953 configuration %s via API", isPartialUpdate ? "partially updated" : "updated");
_sendSuccessResponse(request, "ADE7953 configuration updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid ADE7953 configuration");
}
});
server.addHandler(setAde7953ConfigHandler);
// Reset ADE7953 configuration
server.on("/api/v1/ade7953/config/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
Ade7953::resetConfiguration();
_sendSuccessResponse(request, "ADE7953 configuration reset successfully");
});
// === SAMPLE TIME ENDPOINTS ===
// Get sample time
server.on("/api/v1/ade7953/sample-time", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["sampleTime"] = Ade7953::getSampleTime();
_sendJsonResponse(request, doc);
});
// Set sample time
static AsyncCallbackJsonWebHandler *setSampleTimeHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ade7953/sample-time",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_SAMPLE_TIME)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (!doc["sampleTime"].is<uint64_t>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "sampleTime field must be a positive integer");
return;
}
uint64_t sampleTime = doc["sampleTime"].as<uint64_t>();
if (Ade7953::setSampleTime(sampleTime))
{
char sampleTimeHuman[DURATION_FORMAT_BUFFER_SIZE];
DurationFormat::humanizeDuration(sampleTime, sampleTimeHuman, sizeof(sampleTimeHuman));
LOG_INFO("ADE7953 sample time updated to %s via API", sampleTimeHuman);
_sendSuccessResponse(request, "ADE7953 sample time updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid sample time value");
}
});
server.addHandler(setSampleTimeHandler);
// === CHANNEL DATA ENDPOINTS ===
// Get single channel data
server.on("/api/v1/ade7953/channel", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (request->hasParam("index")) {
// Get single channel data
uint8_t channelIndex = (uint8_t)(request->getParam("index")->value().toInt());
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
} else {
if (Ade7953::getChannelDataAsJson(doc, channelIndex)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching single channel data");
}
} else {
// Get all channels data - with ETag caching
uint32_t configHash = Ade7953::computeAllChannelDataHash();
if (configHash == 0) {
// Error computing hash, send data without caching
if (Ade7953::getAllChannelDataAsJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching all channels data");
return;
}
// Generate ETag
char etag[16];
snprintf(etag, sizeof(etag), "\"%08x\"", configHash); // It says the format is incorrect but it works in the end
// Check If-None-Match header and send 304 if matched
if (_checkEtagAndSend304(request, etag)) {
return;
}
// Data has changed or no cached version, send full response with ETag
if (Ade7953::getAllChannelDataAsJson(doc)) {
AsyncResponseStream *response = _beginJsonResponseStream(request, doc);
serializeJson(doc, *response);
_sendResponseWithEtag(request, response, etag);
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching all channels data");
}
}
});
// Set single channel data (PUT/PATCH)
static AsyncCallbackJsonWebHandler *setChannelDataHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ade7953/channel",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
bool roleChanged = false;
if (Ade7953::setChannelDataFromJson(doc, isPartialUpdate, &roleChanged))
{
uint8_t channelIndex = doc["index"].as<uint8_t>();
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
return;
}
LOG_INFO("ADE7953 channel %u data %s via API", channelIndex, isPartialUpdate ? "partially updated" : "updated");
if (roleChanged) {
Ade7953::resetChannelEnergyValues(channelIndex);
LOG_DEBUG("Auto-reset energy and cleared history for channel %u due to role change", channelIndex);
}
_sendSuccessResponse(request, "ADE7953 channel data updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid ADE7953 channel data");
}
});
server.addHandler(setChannelDataHandler);
// Set all channels data (PUT only - bulk update)
static AsyncCallbackJsonWebHandler *setAllChannelsDataHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ade7953/channels",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_CHANNEL_DATA * MAX_CHANNEL_COUNT)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Validate that it's an array
if (!doc.is<JsonArrayConst>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Request body must be an array of channel configurations");
return;
}
// Update all channels - let setChannelDataFromJson handle all validation
SpiRamAllocator channelAllocator;
JsonDocument channelDoc(&channelAllocator);
for (JsonDocument channelDoc : doc.as<JsonArrayConst>()) {
bool roleChanged = false;
if (!Ade7953::setChannelDataFromJson(channelDoc, false, &roleChanged)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel configuration in array");
return;
}
if (roleChanged) {
uint8_t idx = channelDoc["index"].as<uint8_t>();
Ade7953::resetChannelEnergyValues(idx);
LOG_INFO("Auto-reset energy and cleared history for channel %u due to role change", idx);
}
}
LOG_INFO("Bulk updated %u ADE7953 channels via API", doc.size());
_sendSuccessResponse(request, "All channels updated successfully");
});
server.addHandler(setAllChannelsDataHandler);
// Reset single channel data
server.on("/api/v1/ade7953/channel/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (!request->hasParam("index")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing channel index parameter");
return;
}
uint8_t channelIndex = (uint8_t)(request->getParam("index")->value().toInt());
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
return;
}
if (!Ade7953::resetChannelData(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to reset channel data");
return;
}
LOG_INFO("ADE7953 channel %u data reset via API", channelIndex);
_sendSuccessResponse(request, "ADE7953 channel data reset successfully");
});
// === REGISTER ENDPOINTS ===
// Read single register
server.on("/api/v1/ade7953/register", HTTP_GET, [](AsyncWebServerRequest *request)
{
if (!request->hasParam("address")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing register address parameter");
return;
}
if (!request->hasParam("bits")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing register bits parameter");
return;
}
int32_t addressValue = request->getParam("address")->value().toInt();
int32_t bitsValue = request->getParam("bits")->value().toInt();
if (!isValueInRange(addressValue, 0, (int32_t)UINT16_MAX)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Register address out of range (0-65535)");
return;
}
if (!isValueInRange(bitsValue, 0, (int32_t)UINT8_MAX)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Register bits out of range (0-255)");
return;
}
uint16_t address = (uint16_t)(addressValue);
uint8_t bits = (uint8_t)(bitsValue);
bool signedData = request->hasParam("signed") ? request->getParam("signed")->value().equals("true") : false;
int32_t value = Ade7953::readRegister(address, bits, signedData);
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["address"] = address;
doc["bits"] = bits;
doc["signed"] = signedData;
doc["value"] = value;
_sendJsonResponse(request, doc);
});
// Write single register
static AsyncCallbackJsonWebHandler *writeRegisterHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ade7953/register",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_REGISTER)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (!doc["address"].is<int32_t>() || !doc["bits"].is<int32_t>() || !doc["value"].is<int32_t>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "address, bits, and value fields must be integers");
return;
}
int32_t addressValue = doc["address"].as<int32_t>();
int32_t bitsValue = doc["bits"].as<int32_t>();
if (!isValueInRange(addressValue, 0, (int32_t)UINT16_MAX)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Register address out of range (0-65535)");
return;
}
if (!isValueInRange(bitsValue, 0, (int32_t)UINT8_MAX)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Register bits out of range (0-255)");
return;
}
uint16_t address = (uint16_t)(addressValue);
uint8_t bits = (uint8_t)(bitsValue);
int32_t value = doc["value"].as<int32_t>();
Ade7953::writeRegister(address, bits, value);
LOG_INFO("ADE7953 register 0x%X (%d bits) written with value 0x%X via API", address, bits, value);
_sendSuccessResponse(request, "ADE7953 register written successfully");
});
server.addHandler(writeRegisterHandler);
// === METER VALUES ENDPOINTS ===
// Get meter values (all channels or single channel with optional index parameter)
server.on("/api/v1/ade7953/meter-values", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (request->hasParam("index")) {
// Get single channel meter values
long indexValue = request->getParam("index")->value().toInt();
uint8_t channelIndex = (uint8_t)(indexValue);
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
} else {
if (Ade7953::singleMeterValuesToJson(doc, channelIndex)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching single meter values");
}
} else {
// Get all meter values
if (Ade7953::fullMeterValuesToJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching all meter values");
}
});
// === GRID FREQUENCY ENDPOINT ===
// Get grid frequency
server.on("/api/v1/ade7953/grid-frequency", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["gridFrequency"] = Ade7953::getGridFrequency();
_sendJsonResponse(request, doc);
});
// === ENERGY VALUES ENDPOINTS ===
// Reset energy values (all channels, or single channel with ?index=N)
server.on("/api/v1/ade7953/energy/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
if (request->hasParam("index")) {
uint8_t channelIndex = static_cast<uint8_t>(request->getParam("index")->value().toInt());
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
return;
}
Ade7953::resetChannelEnergyValues(channelIndex);
LOG_INFO("ADE7953 energy values reset for channel %u via API", channelIndex);
_sendSuccessResponse(request, "ADE7953 energy values reset for channel");
} else {
Ade7953::resetEnergyValues();
LOG_INFO("ADE7953 energy values reset via API");
_sendSuccessResponse(request, "ADE7953 energy values reset successfully");
}
});
// Set energy values for a specific channel
static AsyncCallbackJsonWebHandler *setEnergyValuesHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/ade7953/energy"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_ADE7953_ENERGY)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (!doc["channel"].is<uint8_t>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "channel field must be a positive integer");
return;
}
uint8_t channel = doc["channel"].as<uint8_t>();
if (!isChannelValid(channel)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
return;
}
if (!doc["activeEnergyImported"].is<double>() ||
!doc["activeEnergyExported"].is<double>() ||
!doc["reactiveEnergyImported"].is<double>() ||
!doc["reactiveEnergyExported"].is<double>() ||
!doc["apparentEnergy"].is<double>())
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "All energy value fields must be present and of type double");
return;
}
double activeEnergyImported = doc["activeEnergyImported"].as<double>();
double activeEnergyExported = doc["activeEnergyExported"].as<double>();
double reactiveEnergyImported = doc["reactiveEnergyImported"].as<double>();
double reactiveEnergyExported = doc["reactiveEnergyExported"].as<double>();
double apparentEnergy = doc["apparentEnergy"].as<double>();
if (Ade7953::setEnergyValues(channel, activeEnergyImported, activeEnergyExported,
reactiveEnergyImported, reactiveEnergyExported, apparentEnergy))
{
LOG_INFO("ADE7953 energy values set for channel %lu via API", channel);
_sendSuccessResponse(request, "ADE7953 energy values updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid energy values or channel");
}
});
server.addHandler(setEnergyValuesHandler);
}
// === CUSTOM MQTT ENDPOINTS ===
static void _serveCustomMqttEndpoints()
{
server.on("/api/v1/custom-mqtt/config", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (CustomMqtt::getConfigurationAsJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to get Custom MQTT configuration");
});
static AsyncCallbackJsonWebHandler *setCustomMqttHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/custom-mqtt/config"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_CUSTOM_MQTT)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (CustomMqtt::setConfigurationFromJson(doc, isPartialUpdate))
{
LOG_INFO("Custom MQTT configuration %s via API", isPartialUpdate ? "partially updated" : "updated");
_sendSuccessResponse(request, "Custom MQTT configuration updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid Custom MQTT configuration");
}
});
server.addHandler(setCustomMqttHandler);
// Reset configuration
server.on("/api/v1/custom-mqtt/config/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
CustomMqtt::resetConfiguration();
_sendSuccessResponse(request, "Custom MQTT configuration reset successfully");
});
server.on("/api/v1/custom-mqtt/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// Add runtime status information
// Zeroed: getRuntimeStatus() leaves them untouched while the module is not set up
char statusBuffer[STATUS_BUFFER_SIZE] = "";
char timestampBuffer[TIMESTAMP_BUFFER_SIZE] = "";
CustomMqtt::getRuntimeStatus(statusBuffer, sizeof(statusBuffer), timestampBuffer, sizeof(timestampBuffer));
doc["status"] = statusBuffer;
doc["statusTimestamp"] = timestampBuffer;
_sendJsonResponse(request, doc);
});
// === WAVEFORM CAPTURE ENDPOINTS ===
// Arm waveform capture for a channel
static AsyncCallbackJsonWebHandler *armWaveformCaptureHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/ade7953/waveform/arm",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_ADE7953_WAVEFORM_ARM)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (!doc["channelIndex"].is<uint8_t>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing or invalid channelIndex");
return;
}
uint8_t channelIndex = doc["channelIndex"].as<uint8_t>();
if (!isChannelValid(channelIndex)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid channel index");
return;
}
Ade7953::startWaveformCapture(channelIndex);
Ade7953::CaptureState state = Ade7953::getWaveformCaptureStatus();
switch (state) {
case Ade7953::CaptureState::IDLE:
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to arm waveform capture due to unknown error");
break;
case Ade7953::CaptureState::ARMED:
LOG_DEBUG("Waveform capture armed via API for channel %u", channelIndex);
_sendSuccessResponse(request, "Waveform capture armed successfully");
break;
case Ade7953::CaptureState::CAPTURING:
_sendErrorResponse(request, HTTP_CODE_CONFLICT, "Waveform capture already in progress");
break;
case Ade7953::CaptureState::COMPLETE:
_sendErrorResponse(request, HTTP_CODE_CONFLICT, "Previous waveform capture complete. Please retrieve data before arming a new capture");
break;
case Ade7953::CaptureState::ERROR:
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Waveform capture buffer allocation failed");
break;
default:
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to arm waveform capture due to unknown error");
break;
}
return;
});
server.addHandler(armWaveformCaptureHandler);
// Get waveform capture status
server.on("/api/v1/ade7953/waveform/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
Ade7953::CaptureState state = Ade7953::getWaveformCaptureStatus();
switch (state) {
case Ade7953::CaptureState::IDLE:
doc["state"] = "idle";
break;
case Ade7953::CaptureState::ARMED:
doc["state"] = "armed";
break;
case Ade7953::CaptureState::CAPTURING:
doc["state"] = "capturing";
break;
case Ade7953::CaptureState::COMPLETE:
doc["state"] = "complete";
break;
case Ade7953::CaptureState::ERROR:
doc["state"] = "error";
break;
}
doc["channel"] = Ade7953::getWaveformCaptureChannel();
LOG_DEBUG("Waveform capture status retrieved via API. Status for channel %u: %s",
doc["channel"].as<uint8_t>(),
doc["state"].as<const char *>());
_sendJsonResponse(request, doc);
});
// Get waveform capture data
server.on("/api/v1/ade7953/waveform/data", HTTP_GET, [](AsyncWebServerRequest *request)
{
Ade7953::CaptureState state = Ade7953::getWaveformCaptureStatus();
if (state != Ade7953::CaptureState::COMPLETE) {
JsonDocument doc;
doc["message"] = "Waveform capture data not available";
_sendJsonResponse(request, doc, HTTP_CODE_NO_CONTENT);
return;
}
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
bool success = Ade7953::getWaveformCaptureAsJson(doc);
if (!success) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve waveform data");
return;
}
LOG_DEBUG("Waveform data retrieved via API");
_sendJsonResponse(request, doc);
});
// Get cloud services status
server.on("/api/v1/mqtt/cloud-services", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["enabled"] = !globalCommunityMode && Mqtt::isCloudServicesEnabled();
_sendJsonResponse(request, doc);
});
// Set cloud services status
static AsyncCallbackJsonWebHandler *setCloudServicesHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/mqtt/cloud-services",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (globalCommunityMode) {
_sendErrorResponse(request, HTTP_CODE_FORBIDDEN, "Cloud services are not available in community mode");
return;
}
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_MQTT_CLOUD_SERVICES)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Validate JSON structure
if (!doc.is<JsonObject>() || !doc["enabled"].is<bool>())
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid JSON structure. Expected: {\"enabled\": true/false}");
return;
}
bool enabled = doc["enabled"];
Mqtt::setCloudServicesEnabled(enabled);
LOG_INFO("Cloud services %s via API", enabled ? "enabled" : "disabled");
_sendSuccessResponse(request, enabled ? "Cloud services enabled successfully" : "Cloud services disabled successfully");
});
server.addHandler(setCloudServicesHandler);
}
// === INFLUXDB ENDPOINTS ===
static void _serveInfluxDbEndpoints()
{
// Get InfluxDB configuration
server.on("/api/v1/influxdb/config", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (InfluxDbClient::getConfigurationAsJson(doc)) _sendJsonResponse(request, doc);
else _sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Error fetching InfluxDB configuration");
});
// Set InfluxDB configuration
static AsyncCallbackJsonWebHandler *setInfluxDbHandler = new AsyncCallbackJsonWebHandler(
AsyncURIMatcher::exact("/api/v1/influxdb/config"),
[](AsyncWebServerRequest *request, JsonVariant &json)
{
bool isPartialUpdate = _isPartialUpdate(request);
if (!_validateRequest(request, isPartialUpdate ? "PATCH" : "PUT", HTTP_MAX_CONTENT_LENGTH_INFLUXDB)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
if (InfluxDbClient::setConfigurationFromJson(doc, isPartialUpdate))
{
LOG_INFO("InfluxDB configuration updated via API");
_sendSuccessResponse(request, "InfluxDB configuration updated successfully");
}
else
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid InfluxDB configuration");
}
});
server.addHandler(setInfluxDbHandler);
// Reset configuration
server.on("/api/v1/influxdb/config/reset", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
InfluxDbClient::resetConfiguration();
_sendSuccessResponse(request, "InfluxDB configuration reset successfully");
});
// Get InfluxDB status
server.on("/api/v1/influxdb/status", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// Add runtime status information
// Zeroed: getRuntimeStatus() leaves them untouched while the module is not set up
char statusBuffer[STATUS_BUFFER_SIZE] = "";
char timestampBuffer[TIMESTAMP_BUFFER_SIZE] = "";
InfluxDbClient::getRuntimeStatus(statusBuffer, sizeof(statusBuffer), timestampBuffer, sizeof(timestampBuffer));
doc["status"] = statusBuffer;
doc["statusTimestamp"] = timestampBuffer;
_sendJsonResponse(request, doc);
});
}
// === CRASH MONITOR ENDPOINTS ===
// These read the on-flash archive, not the coredump partition: dumps are
// copied off the partition on the boot they are detected.
static void _serveCrashEndpoints()
{
server.on("/api/v1/crash/info", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (CrashMonitor::listArchivedCrashes(doc)) {
_sendJsonResponse(request, doc);
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve crash information");
}
});
// Serves the stored gzip bytes directly, with no JSON wrapper
server.on("/api/v1/crash/dump", HTTP_GET, [](AsyncWebServerRequest *request)
{
char baseName[CRASH_ARCHIVE_NAME_BUFFER_SIZE];
bool found = false;
if (request->hasParam("id")) {
found = CrashMonitor::findArchivedCrashById(
request->getParam("id")->value().c_str(), baseName, sizeof(baseName));
} else {
found = CrashMonitor::getArchivedCrashAt(0, baseName, sizeof(baseName));
}
if (!found) {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "No matching core dump available");
return;
}
char path[CRASH_ARCHIVE_PATH_BUFFER_SIZE];
CrashMonitor::buildArchivedCrashDumpPath(baseName, path, sizeof(path));
AsyncWebServerResponse *response = request->beginResponse(LittleFS, path, "application/gzip");
if (!response) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to open the archived core dump");
return;
}
// Deliberately no Content-Encoding: gzip here. The body IS a gzip
// file, not a gzip-encoded representation of something else, and the
// header would be sent regardless of Accept-Encoding - browsers would
// inflate it and save the raw dump under a .gz name, while a client
// that never asked for gzip (plain curl) would get a body it does not
// decode. application/gzip + a .gz filename says exactly that.
char disposition[CRASH_ARCHIVE_NAME_BUFFER_SIZE + 40];
snprintf(disposition, sizeof(disposition), "attachment; filename=\"%s%s\"", baseName, CRASH_ARCHIVE_DUMP_SUFFIX);
response->addHeader("Content-Disposition", disposition);
request->send(response);
});
server.on("/api/v1/crash/clear", HTTP_POST, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "POST")) return;
uint32_t removed = CrashMonitor::clearArchivedCrashes();
if (removed == 0) {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "No archived crashes to clear");
return;
}
LOG_INFO("Cleared %lu archived crash record(s) via API", removed);
char message[STATUS_BUFFER_SIZE];
snprintf(message, sizeof(message), "Cleared %lu archived crash record(s)", removed);
_sendSuccessResponse(request, message);
});
// The item endpoint: /crash/info is the collection (list, no id), this is
// one entry addressed by id - GET to read it, DELETE to remove it. Same
// ?id= param as /crash/dump.
server.on("/api/v1/crash/entry", HTTP_GET, [](AsyncWebServerRequest *request)
{
if (!request->hasParam("id")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'id' query parameter");
return;
}
char baseName[CRASH_ARCHIVE_NAME_BUFFER_SIZE];
if (!CrashMonitor::findArchivedCrashById(request->getParam("id")->value().c_str(), baseName, sizeof(baseName))) {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "No archived crash with that id");
return;
}
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
if (!CrashMonitor::getArchivedCrashMetadata(baseName, doc)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to read archived crash metadata");
return;
}
_sendJsonResponse(request, doc);
});
server.on("/api/v1/crash/entry", HTTP_DELETE, [](AsyncWebServerRequest *request)
{
if (!_validateRequest(request, "DELETE")) return;
if (!request->hasParam("id")) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing 'id' query parameter");
return;
}
char baseName[CRASH_ARCHIVE_NAME_BUFFER_SIZE];
if (!CrashMonitor::findArchivedCrashById(request->getParam("id")->value().c_str(), baseName, sizeof(baseName))) {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "No archived crash with that id");
return;
}
if (!CrashMonitor::removeArchivedCrash(baseName)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to remove the archived crash");
return;
}
LOG_INFO("Removed archived crash %s via API", baseName);
_sendSuccessResponse(request, "Archived crash removed");
});
}
// === LED ENDPOINTS ===
// Reads one 0-255 channel out of the body. Rejects anything that is not an
// integer in range, including a float that happens to land on a whole number -
// an automation sending 255.0 has a bug worth surfacing.
static bool _readColorChannel(AsyncWebServerRequest *request, const JsonDocument &doc,
const char *key, uint8_t &out)
{
char errorMsg[STATUS_BUFFER_SIZE];
if (!doc[key].is<int32_t>())
{
snprintf(errorMsg, sizeof(errorMsg), "Missing or invalid %s parameter", key);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, errorMsg);
return false;
}
const int32_t value = doc[key].as<int32_t>();
if (value < 0 || value > UINT8_MAX)
{
snprintf(errorMsg, sizeof(errorMsg), "Parameter %s out of range (0-%d)", key, UINT8_MAX);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, errorMsg);
return false;
}
out = (uint8_t)value;
return true;
}
// Reads an optional 0..maxValue integer, leaving `out` at its caller-supplied
// default when the field is absent. Same shape as _readColorChannel above, for
// the two fields on this endpoint that are optional rather than required.
static bool _readOptionalRangedInt(AsyncWebServerRequest *request, const JsonDocument &doc,
const char *key, int64_t maxValue, int64_t &out)
{
if (doc[key].isNull()) return true;
char errorMsg[STATUS_BUFFER_SIZE];
if (!doc[key].is<int64_t>() || doc[key].as<int64_t>() < 0 || doc[key].as<int64_t>() > maxValue)
{
snprintf(errorMsg, sizeof(errorMsg), "Invalid %s parameter", key);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, errorMsg);
return false;
}
out = doc[key].as<int64_t>();
return true;
}
static void _serveLedEndpoints()
{
// Current LED state: what is actually being shown, not what the user asked
// for. An automation needs to see that a system indication has taken over.
//
// exact(), not the plain string: a matcher built from a string is
// BackwardCompatible, which matches the path *and everything under it*, and
// _attachHandler() takes the first match in registration order - so
// "/api/v1/led" would otherwise swallow GET /api/v1/led/brightness.
server.on(AsyncURIMatcher::exact("/api/v1/led"), HTTP_GET, [](AsyncWebServerRequest *request)
{
const Led::Snapshot state = Led::getState();
if (!state.valid) {
// Could not read the layer table. Reporting that as "off" would put a
// wrong answer on the wire, which is worse than no answer.
_sendErrorResponse(request, HTTP_CODE_SERVICE_UNAVAILABLE, "LED state temporarily unavailable");
return;
}
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["pattern"] = LedState::patternName(state.active.pattern);
doc["layer"] = state.active.any ? LedState::layerName(state.active.layer) : nullptr;
JsonObject color = doc["color"].to<JsonObject>();
color["red"] = state.active.color.red;
color["green"] = state.active.color.green;
color["blue"] = state.active.color.blue;
if (state.active.indefinite) { doc["remaining_ms"] = nullptr; }
else { doc["remaining_ms"] = state.active.remainingMs; }
doc["is_lit"] = state.isLit;
doc["brightness"] = state.brightness;
_sendJsonResponse(request, doc);
});
// Set the user layer. It sits just above the ambient status layer, so it
// replaces the healthy indication but is still overridden by anything
// eventful, and it is deliberately not persisted: a device must not boot
// into a colour that hides its own status.
static AsyncCallbackJsonWebHandler *setLedColorHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/led/color",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_LED_COLOR)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Parsed before the channels: disco picks its own colours, so it is the
// pattern that decides whether they are required at all.
LedPattern pattern = LedPattern::SOLID;
if (!doc["pattern"].isNull())
{
if (!doc["pattern"].is<const char *>() ||
!LedState::patternFromName(doc["pattern"].as<const char *>(), pattern))
{
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Unknown pattern");
return;
}
}
const bool isDisco = pattern == LedPattern::DISCO;
uint8_t red = 0, green = 0, blue = 0;
if (!isDisco)
{
if (!_readColorChannel(request, doc, "red", red)) return;
if (!_readColorChannel(request, doc, "green", green)) return;
if (!_readColorChannel(request, doc, "blue", blue)) return;
}
int64_t durationValue = 0; // Indefinite
if (!_readOptionalRangedInt(request, doc, "duration_ms", INT64_MAX, durationValue)) return;
uint64_t durationMs = (uint64_t)durationValue;
// Disco always ends on its own. Over-long values are clamped rather
// than rejected: no other pattern has an upper bound, so a 400 here
// would surprise a caller who read the rest of the contract.
if (isDisco)
{
if (durationMs == 0) { durationMs = DISCO_DEFAULT_DURATION_MS; }
if (durationMs > DISCO_MAX_DURATION_MS) { durationMs = DISCO_MAX_DURATION_MS; }
}
// Absent seed means "surprise me", so two presses of the same button do
// not replay the same sequence. esp_random() rather than millis(): two
// requests in the same millisecond would otherwise get the same seed.
int64_t seedValue = (int64_t)esp_random();
if (!_readOptionalRangedInt(request, doc, "seed", (int64_t)UINT32_MAX, seedValue)) return;
uint32_t seed = (uint32_t)seedValue;
Led::setPattern(LedState::Layer::USER, pattern, Led::Color(red, green, blue), durationMs, seed);
_sendSuccessResponse(request, "LED color updated successfully");
});
server.addHandler(setLedColorHandler);
// Release the user layer, revealing whatever layer is occupied beneath it.
server.on("/api/v1/led/color", HTTP_DELETE, [](AsyncWebServerRequest *request)
{
// Not optional: _sendSuccessResponse() releases the API mutex, so a
// handler that skips the acquire here gives back a lock it never took.
if (!_validateRequest(request, "DELETE")) return;
Led::clearLayer(LedState::Layer::USER);
_sendSuccessResponse(request, "LED color cleared successfully");
});
// Get LED brightness
server.on("/api/v1/led/brightness", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc["brightness"] = Led::getBrightness();
doc["max_brightness"] = LED_MAX_BRIGHTNESS_PERCENT;
_sendJsonResponse(request, doc);
});
// Set LED brightness
static AsyncCallbackJsonWebHandler *setLedBrightnessHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/led/brightness",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "PUT", HTTP_MAX_CONTENT_LENGTH_LED_BRIGHTNESS)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Check if brightness field is provided and is a number
if (!doc["brightness"].is<uint8_t>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing or invalid brightness parameter");
return;
}
uint8_t brightness = doc["brightness"].as<uint8_t>();
// Validate brightness range
if (!Led::isBrightnessValid(brightness)) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Brightness value out of range");
return;
}
// Set the brightness
Led::setBrightness(brightness);
_sendSuccessResponse(request, "LED brightness updated successfully");
});
server.addHandler(setLedBrightnessHandler);
}
// === BACKUP ENDPOINTS ===
static void _serveBackupEndpoints()
{
server.on("/api/v1/backup/configuration", HTTP_GET, [](AsyncWebServerRequest *request)
{
// nvsDataToJson() resets watchdog periodically during iteration
AsyncJsonResponse * response = new AsyncJsonResponse();
JsonObject doc = response->getRoot().to<JsonObject>();
if (!nvsDataToJson(doc)) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to retrieve NVS data");
LOG_ERROR("Failed to retrieve NVS data for backup request via API");
delete response;
return;
}
// Add download headers
char deviceId[DEVICE_ID_BUFFER_SIZE];
getDeviceId(deviceId, sizeof(deviceId));
char timestamp[TIMESTAMP_BUFFER_SIZE];
CustomTime::getTimestampIso(timestamp, sizeof(timestamp));
char filename[128];
snprintf(filename, sizeof(filename), "attachment; filename=\"config_backup_%s_%s.json\"",
deviceId, timestamp);
response->addHeader("Content-Disposition", filename);
LOG_INFO("Configuration backup requested via API: config_backup_%s_%s.json", deviceId, timestamp);
response->setLength();
request->send(response);
});
// LittleFS filesystem backup (tar) - streams directly to HTTP response, no temp files
server.on("/api/v1/backup/filesystem", HTTP_GET, [](AsyncWebServerRequest *request) {
LOG_DEBUG("LittleFS streaming backup requested");
// Start async TAR creation task
RingBufferStream* stream = startStreamingBackup();
if (!stream) {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to start backup stream");
LOG_ERROR("Failed to start LittleFS backup stream via API");
return;
}
// Set up chunked response that reads from RingBufferStream
// Use simpler callback to avoid compiler memory issues
AsyncWebServerResponse *response = request->beginChunkedResponse("application/x-tar",
[stream](uint8_t *buffer, size_t maxLen, size_t index) -> size_t {
// Feed watchdog on every callback to prevent timeout during semaphore waits
esp_task_wdt_reset();
if (stream->hasError()) {
delete stream;
return 0;
}
size_t bytesRead = stream->readBytes(buffer, maxLen);
if (bytesRead == 0) {
delete stream;
}
return bytesRead;
}
);
// Add download headers with device ID and timestamp
char deviceId[DEVICE_ID_BUFFER_SIZE];
getDeviceId(deviceId, sizeof(deviceId));
char timestamp[TIMESTAMP_BUFFER_SIZE];
CustomTime::getTimestampIso(timestamp, sizeof(timestamp));
char filename[128];
snprintf(filename, sizeof(filename), "attachment; filename=\"littlefs_backup_%s_%s.tar\"",
deviceId, timestamp);
response->addHeader("Content-Disposition", filename);
LOG_INFO("LittleFS backup streaming started: littlefs_backup_%s_%s.tar", deviceId, timestamp);
request->send(response);
});
}
// === RESTORE ENDPOINTS ===
static void _serveRestoreEndpoints()
{
// POST - Restore configuration from JSON backup file (multipart upload)
server.on("/api/v1/restore/configuration", HTTP_POST,
[](AsyncWebServerRequest *request) {
// Final response after file upload completes
if (request->_tempObject) {
bool* success = (bool*)request->_tempObject;
if (*success) {
_sendSuccessResponse(request, "Configuration restore initiated. Device will restart.");
} else {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Failed to process backup file. Check logs");
}
delete success;
request->_tempObject = nullptr;
}
},
[](AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final) {
static File restoreFile;
static String tempPath = "/restore/nvs_restore_upload.json";
static bool isValid = true;
static bool restoreInProgress = false;
if (!index) {
// Before any file is opened. See _rejectUploadIfNotPermitted().
if (_rejectUploadIfNotPermitted(request)) return;
// First chunk - check if restore already in progress
if (restoreInProgress) {
LOG_WARNING("Configuration restore already in progress, rejecting new request");
_sendErrorResponse(request, HTTP_CODE_CONFLICT,
"Restore already in progress. Please wait for current restore to complete.");
return;
}
restoreInProgress = true;
// First chunk - create restore directory and file
LOG_INFO("Starting configuration restore upload");
if (!LittleFS.exists("/restore")) {
LittleFS.mkdir("/restore");
}
// Remove old temp file if exists
if (LittleFS.exists(tempPath)) {
LittleFS.remove(tempPath);
}
restoreFile = LittleFS.open(tempPath, FILE_WRITE);
if (!restoreFile) {
LOG_ERROR("Failed to create temp restore file");
isValid = false;
restoreInProgress = false;
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to create restore file");
return;
}
isValid = true;
}
// Write chunk
if (len && isValid && restoreFile) {
size_t written = restoreFile.write(data, len);
if (written != len) {
LOG_ERROR("Failed to write restore file chunk");
isValid = false;
restoreFile.close();
LittleFS.remove(tempPath);
restoreInProgress = false;
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to write restore data");
return;
}
}
// Final chunk - validate and process JSON
if (final && isValid && restoreFile) {
restoreInProgress = false;
restoreFile.close();
LOG_DEBUG("Backup file upload complete, validating...");
// Parse and validate JSON
File uploadedFile = LittleFS.open(tempPath, FILE_READ);
if (!uploadedFile) {
LOG_ERROR("Failed to read uploaded restore file");
isValid = false;
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to read restore file");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
DeserializationError jsonError = deserializeJson(doc, uploadedFile);
uploadedFile.close();
if (jsonError) {
LOG_ERROR("Invalid JSON in backup: %s", jsonError.c_str());
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid JSON format");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
// Validate backup structure
if (!doc["version"].is<int>() || doc["version"] != 1 ||
!doc["type"].is<const char*>() || strcmp(doc["type"], "configuration") != 0 ||
!doc["nvs"].is<JsonObject>()) {
LOG_ERROR("Invalid backup format or version");
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Invalid backup format");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
// Check firmware version compatibility
if (!doc["firmwareVersion"].is<const char*>()) {
LOG_ERROR("Backup missing firmware version");
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Backup missing firmware version");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
const char* backupFwVersion = doc["firmwareVersion"];
if (!isBackupVersionCompatible(backupFwVersion)) {
char msg[256];
snprintf(msg, sizeof(msg),
"Firmware version incompatible: backup from %s, current %s. "
"Can only restore backups from same major version <= current.",
backupFwVersion, FIRMWARE_BUILD_VERSION);
LOG_WARNING("%s", msg);
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, msg);
bool* result = new bool(false);
request->_tempObject = result;
return;
}
// Check device ID mismatch (warn but allow with ?force=true)
bool forceRestore = request->hasParam("force") &&
request->getParam("force")->value() == "true";
const char* backupDeviceId = doc["deviceId"];
char currentDeviceId[DEVICE_ID_BUFFER_SIZE];
getDeviceId(currentDeviceId, sizeof(currentDeviceId));
if (backupDeviceId && strcmp(backupDeviceId, currentDeviceId) != 0 && !forceRestore) {
char msg[200];
snprintf(msg, sizeof(msg),
"Device ID mismatch: backup from %s, current device %s. Use ?force=true to override.",
backupDeviceId, currentDeviceId);
LOG_WARNING("%s", msg);
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, msg);
bool* result = new bool(false);
request->_tempObject = result;
return;
}
// Validate namespace exclusions (ensure no sensitive data)
const char* excludedNamespaces[] = {EXCLUDED_NVS_NAMESPACES_LIST};
for (JsonPair nsPair : doc["nvs"].as<JsonObject>()) {
for (const char* excluded : excludedNamespaces) {
if (strcmp(nsPair.key().c_str(), excluded) == 0) {
LOG_ERROR("Backup contains excluded namespace: %s", nsPair.key().c_str());
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST,
"Backup contains excluded namespace (security/device-specific data)");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
}
}
// All validation passed - save for boot-time restore
File finalRestoreFile = LittleFS.open("/restore/nvs_restore.json", FILE_WRITE);
if (!finalRestoreFile) {
LOG_ERROR("Failed to create final restore file");
LittleFS.remove(tempPath);
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to save restore file");
bool* result = new bool(false);
request->_tempObject = result;
return;
}
serializeJson(doc, finalRestoreFile);
finalRestoreFile.close();
LittleFS.remove(tempPath);
// Set restore pending flag in NVS
Preferences prefs;
if (prefs.begin(PREFERENCES_NAMESPACE_GENERAL, false)) {
prefs.putBool("restore_pending", true);
prefs.end();
}
LOG_INFO("Configuration restore staged. Device will restart.");
bool* result = new bool(true);
request->_tempObject = result;
// Trigger restart after response sent
setRestartSystem("Configuration restore");
}
}
);
// POST - Restore filesystem from TAR file upload (saves to LittleFS then extracts)
server.on("/api/v1/restore/filesystem", HTTP_POST,
[](AsyncWebServerRequest *request) {
// Final response after file upload completes
if (request->_tempObject) {
bool* success = (bool*)request->_tempObject;
if (*success) {
_sendSuccessResponse(request, "Filesystem restored successfully");
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Filesystem restore failed");
}
delete success;
request->_tempObject = nullptr;
}
},
[](AsyncWebServerRequest *request, const String& filename,
size_t index, uint8_t *data, size_t len, bool final) {
static File restoreFile;
static String tempPath = "/restore/filesystem_restore.tar";
static bool isValid = true;
static bool restoreInProgress = false;
if (!index) {
// Before any file is opened. See _rejectUploadIfNotPermitted().
if (_rejectUploadIfNotPermitted(request)) return;
// First chunk - check if restore already in progress
if (restoreInProgress) {
LOG_WARNING("Filesystem restore already in progress, rejecting new request");
_sendErrorResponse(request, HTTP_CODE_CONFLICT,
"Restore already in progress. Please wait for current restore to complete.");
return;
}
restoreInProgress = true;
// First chunk - create restore directory and file
LOG_INFO("Starting filesystem restore upload: %s", filename.c_str());
if (!LittleFS.exists("/restore")) {
LittleFS.mkdir("/restore");
}
// Remove old temp file if exists
if (LittleFS.exists(tempPath)) {
LittleFS.remove(tempPath);
}
restoreFile = LittleFS.open(tempPath, FILE_WRITE);
if (!restoreFile) {
LOG_ERROR("Failed to create temp restore file");
isValid = false;
restoreInProgress = false;
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to create restore file");
return;
}
isValid = true;
}
// Write chunk
if (len && isValid && restoreFile) {
size_t written = restoreFile.write(data, len);
if (written != len) {
LOG_ERROR("Failed to write restore file chunk");
isValid = false;
restoreFile.close();
LittleFS.remove(tempPath);
restoreInProgress = false;
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR,
"Failed to write restore data");
return;
}
}
// Final chunk - extract TAR to filesystem
if (final && isValid && restoreFile) {
restoreInProgress = false;
restoreFile.close();
LOG_DEBUG("TAR file upload complete, extracting...");
bool extractSuccess = false;
TarUnpacker *tarUnpacker = new TarUnpacker();
tarUnpacker->haltOnError(true);
tarUnpacker->setTarVerify(true);
// Feed watchdog on each file extracted to prevent HTTP timeout during long extraction
tarUnpacker->setTarStatusProgressCallback([](const char* name, size_t size, size_t total_unpacked) {
esp_task_wdt_reset();
LOG_DEBUG("Extracting: %s (%zu bytes, total unpacked: %zu)", name, size, total_unpacked);
});
// Extract: sourceFS, sourcePath, destFS, destPath
if (tarUnpacker->tarExpander(LittleFS, tempPath.c_str(), LittleFS, "/")) {
LOG_INFO("Filesystem restore extraction successful");
extractSuccess = true;
} else {
LOG_ERROR("TAR extraction failed with error code: %d", tarUnpacker->tarGzGetError());
}
delete tarUnpacker;
// Clean up temp file
LittleFS.remove(tempPath);
// Store result for completion handler
bool* result = new bool(extractSuccess);
request->_tempObject = result;
}
}
);
}
// === FILE OPERATION ENDPOINTS ===
static void _serveFileEndpoints()
{
// List files in LittleFS. The endpoint cannot be only "files" as it conflicts with the file serving endpoint (defined below)
// Optional query parameter: folder (e.g., /api/v1/list-files?folder=energy/daily)
server.on("/api/v1/list-files", HTTP_GET, [](AsyncWebServerRequest *request)
{
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
// Check for optional folder parameter
const char* folderPath = nullptr;
if (request->hasParam("folder")) {
folderPath = request->getParam("folder")->value().c_str();
}
if (listLittleFsFiles(doc, folderPath)) {
_sendJsonResponse(request, doc);
} else {
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to list LittleFS files");
}
});
// GET - Download file from LittleFS
server.on("/api/v1/files/*", HTTP_GET, [](AsyncWebServerRequest *request)
{
String url = request->url();
String filename = url.substring(url.indexOf("/api/v1/files/") + 14);
if (filename.length() == 0) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "File path cannot be empty");
return;
}
// URL decode the filename
filename.replace("%2F", "/");
filename.replace("%2f", "/");
// Ensure filename starts with "/"
if (!filename.startsWith("/")) {
filename = "/" + filename;
}
// Check if file exists
if (!LittleFS.exists(filename)) {
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, "File not found");
return;
}
// Determine content type
const char* contentType = getContentTypeFromFilename(filename.c_str());
// Check if download is forced
bool forceDownload = request->hasParam("download");
// Determine if this file should use caching
bool shouldCache = filename.endsWith(".csv") ||
filename.endsWith(".csv.gz") ||
filename.startsWith("/energy/monthly/") ||
filename.startsWith("/energy/yearly/");
if (shouldCache) {
// Send with ETag caching
_sendFileWithEtag(request, filename.c_str(), contentType, forceDownload);
} else {
// Send directly without caching (for frequently changing files)
request->send(LittleFS, filename, contentType, forceDownload);
}
});
// POST - Upload file to LittleFS
server.on("/api/v1/files/*", HTTP_POST,
[](AsyncWebServerRequest *request) {
// Final response is handled in _handleFileUploadData
},
[](AsyncWebServerRequest *request, const String& filename, size_t index, uint8_t *data, size_t len, bool final) {
_handleFileUploadData(request, filename, index, data, len, final);
}
);
// DELETE - Remove file from LittleFS
// HACK: using POST with JSON body to avoid wildcard DELETE issues with AsyncWebServer, and also not using the same endpoint as the * would catch files/delete
static AsyncCallbackJsonWebHandler *deleteFileHandler = new AsyncCallbackJsonWebHandler(
"/api/v1/delete-file",
[](AsyncWebServerRequest *request, JsonVariant &json)
{
if (!_validateRequest(request, "POST", HTTP_MAX_CONTENT_LENGTH_CUSTOM_MQTT)) return;
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
doc.set(json);
// Validate path field
if (!doc["path"].is<const char*>()) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "Missing or invalid 'path' field in JSON body");
return;
}
String filename = doc["path"].as<const char*>();
if (filename.length() == 0) {
_sendErrorResponse(request, HTTP_CODE_BAD_REQUEST, "File path cannot be empty");
return;
}
// Ensure filename starts with "/"
if (!filename.startsWith("/")) {
filename = "/" + filename;
}
// Check if file exists
if (!LittleFS.exists(filename)) {
LOG_DEBUG("Tried to delete non-existent file: %s", filename.c_str());
char buffer[NAME_BUFFER_SIZE];
snprintf(buffer, sizeof(buffer), "File not found: %s", filename.c_str());
_sendErrorResponse(request, HTTP_CODE_NOT_FOUND, buffer);
return;
}
// Attempt to delete the file
if (LittleFS.remove(filename)) {
LOG_INFO("File deleted successfully: %s", filename.c_str());
_sendSuccessResponse(request, "File deleted successfully");
} else {
LOG_ERROR("Failed to delete file: %s", filename.c_str());
_sendErrorResponse(request, HTTP_CODE_INTERNAL_SERVER_ERROR, "Failed to delete file");
}
});
server.addHandler(deleteFileHandler);
}
TaskInfo getHealthCheckTaskInfo()
{
return getTaskInfoSafely(_healthCheckTaskHandle, HEALTH_CHECK_TASK_STACK_SIZE, &_healthCheckHeartbeat);
}
TaskInfo getOtaTimeoutTaskInfo()
{
return getTaskInfoSafely(_otaTimeoutTaskHandle, OTA_TIMEOUT_TASK_STACK_SIZE);
}
}f4329a85eThis file is pinned to the selected release. Download the original to open it in your design tool.