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
#pragma once
#include <AdvancedLogger.h>
#include <Arduino.h>
#include <ArduinoJson.h>
#include <FS.h>
#include <HTTPClient.h>
#include <LittleFS.h>
#include <Preferences.h>
#include <esp_system.h>
#include <rom/rtc.h>
#include <vector>
#include <esp_mac.h> // For the MAC address
#include <ESPmDNS.h>
#include <WiFi.h>
#include <Preferences.h>
#include <nvs.h> // For low-level NVS statistics
#include <nvs_flash.h> // For erasing ALL the NVS
#include <esp_ota_ops.h>
#include "esp_efuse.h"
#include "esp_efuse_table.h"
#include <ESP32-targz.h>
#include "binaries.h"
#include "buttonhandler.h"
#include "constants.h"
#include "factory_keys.h"
#include "image_descriptor.h"
#include "customlog.h"
#include "customtime.h"
#include "customwifi.h"
#include "crashmonitor.h"
#include "custommqtt.h"
#include "influxdbclient.h"
#include "issueregistry.h"
#include "customserver.h"
#include "modbustcp.h"
#include "led.h"
#include "structs.h"
#include "globals.h"
#include "ringbufferstream.h"
#define TASK_RESTART_NAME "restart_task"
#define TASK_RESTART_STACK_SIZE (6 * 1024)
#define TASK_RESTART_PRIORITY 5
#define TASK_MAINTENANCE_NAME "maintenance_task"
#define TASK_MAINTENANCE_STACK_SIZE (6 * 1024) // Week-long min free hit 11.6% (~594 bytes) at 5 KB - bumped to 6 KB for safer margin during flash I/O bursts
#define TASK_MAINTENANCE_PRIORITY 3
#define MAINTENANCE_CHECK_INTERVAL (60 * 1000)
#define TASK_TAR_PACKER_NAME "tar_packer"
#define TASK_TAR_PACKER_STACK_SIZE (8 * 1024)
#define TASK_TAR_PACKER_PRIORITY 3
// System restart thresholds
#define MINIMUM_FREE_HEAP_SIZE (1 * 1024) // Below this value (in bytes), the system will restart. This value can get very low due to the presence of the PSRAM to support
#define MINIMUM_FREE_PSRAM_SIZE (10 * 1024) // Below this value (in bytes), the system will restart
#define MINIMUM_FREE_LITTLEFS_SIZE (10 * 1024) // Below this value (in bytes), the system will clear the log
#define SYSTEM_RESTART_FAILSAFE_TIMER_NAME "restart_failsafe"
#define SYSTEM_RESTART_FAILSAFE_TIMEOUT (10 * 1000) // Failsafe timeout - if restart doesn't complete within this time, force restart via timer
// A factory reset formats the whole LittleFS partition (7.36 MB), which alone
// outruns the plain-restart failsafe: at 10 s the timer fired mid-format and
// ESP.restart() truncated the erase. The format is the long pole, so the
// factory-reset path gets its own, far looser ceiling.
#define SYSTEM_FACTORY_RESET_FAILSAFE_TIMEOUT (120 * 1000)
#define MINIMUM_FIRMWARE_SIZE (100 * 1024) // Minimum firmware size in bytes (100KB) - prevents empty/invalid uploads
// First boot
#define IS_FIRST_BOOT_DONE_KEY "first_boot"
// NVS to JSON
#define NVS_STRING_MAX_SIZE 512 // Reasonable size for string values going in the JSON from the NVS
// Even though the ArduinoJson automatically allocates the JSON documents to PSRAM when the heap is exhausted,
// it still leads to defragmentation here. Thus, to avoid this, we explicitly use a custom allocator.
struct SpiRamAllocator : ArduinoJson::Allocator {
void* allocate(size_t size) override {
return ps_malloc(size);
}
void deallocate(void* pointer) override {
free(pointer);
}
void* reallocate(void* ptr, size_t new_size) override {
return ps_realloc(ptr, new_size);
}
};
// Time utilities (high precision 64-bit alternatives)
// Come one, on this ESP32S3 and in 2025 can we still use 32bits millis
// that will overflow in just 49 days?
// esp_timer_get_time() returns microseconds since boot in 64-bit format,
inline uint64_t millis64() {
return esp_timer_get_time() / 1000ULL;
}
// Same reason as above
inline uint64_t micros64() {
return esp_timer_get_time();
}
// Validation utilities
inline bool isChannelValid(uint8_t channel) { return channel < globalHwProfile->totalChannelCount; }
// String validation utilities
inline bool isStringLengthValid(const char* str, size_t minLength, size_t maxLength) {
if (str == nullptr) return false;
size_t len = strlen(str);
return len >= minLength && len <= maxLength;
}
// Dotted-quad IPv4 validation. allowZero accepts "0.0.0.0" (an optional field
// left unset); without it 0.0.0.0 is rejected like any other non-address.
inline bool isValidIpv4(const char* str, bool allowZero) {
if (str == nullptr || str[0] == '\0') return false;
IPAddress addr;
if (!addr.fromString(str)) return false;
if (!allowZero && addr == IPAddress(0, 0, 0, 0)) return false;
return true;
}
// Numeric range validation utilities
inline bool isValueInRange(float value, float min, float max) {
return value >= min && value <= max;
}
inline bool isValueInRange(int32_t value, int32_t min, int32_t max) {
return value >= min && value <= max;
}
// Mathematical utilities
uint64_t calculateExponentialBackoff(uint64_t attempt, uint64_t initialInterval, uint64_t maxInterval, uint64_t multiplier);
inline float roundToDecimals(float value, uint8_t decimals = 3) {
float factor = powf(10.0f, decimals);
return roundf(value * factor) / factor;
}
inline double roundToDecimals(double value, uint8_t decimals = 3) {
double factor = pow(10.0, decimals);
return round(value * factor) / factor;
}
// Device identification
void getDeviceId(char* deviceId, size_t maxLength);
// Plain TCP connect-and-close over the default route: the lightweight internet
// probe every connectivity check ends with. Interface-agnostic - the socket
// follows whichever interface holds the default route (WiFi or Ethernet).
bool probeTcp(const char* host, uint16_t port, uint32_t timeoutMs);
// Fills out with a 16-char lowercase-hex random token (e.g. for an event/correlation
// id) plus null terminator; outSize must be >= 17, else out is left untouched.
// Free function rather than ShadowLogic::formatClientToken (lib/shadow_logic) -
// that helper is Shadow-owned; this avoids coupling unrelated features to it.
void generateHexToken(char* out, size_t outSize);
// System information and monitoring
void populateSystemStaticInfo(SystemStaticInfo& info);
void populateSystemDynamicInfo(SystemDynamicInfo& info);
void systemStaticInfoToJson(SystemStaticInfo& info, JsonDocument &doc);
void systemDynamicInfoToJson(SystemDynamicInfo& info, JsonDocument &doc);
void getJsonDeviceStaticInfo(JsonDocument &doc);
void getJsonDeviceDynamicInfo(JsonDocument &doc);
// Statistics management
void updateStatistics();
void statisticsToJson(Statistics& statistics, JsonDocument &jsonDocument);
void printStatistics();
// System status printing
void printDeviceStatusStatic();
void printDeviceStatusDynamic();
// FreeRTOS task management
void stopTaskGracefully(TaskHandle_t* taskHandle, const char* taskName);
void startMaintenanceTask();
void stopMaintenanceTask();
// Task information utilities
inline TaskInfo getTaskInfoSafely(TaskHandle_t taskHandle, uint32_t stackSize, const TaskHeartbeat* heartbeat = nullptr)
{
// Defensive check against corrupted or invalid task handles
if (taskHandle != NULL && eTaskGetState(taskHandle) != eInvalid) {
TaskInfo info(stackSize, uxTaskGetStackHighWaterMark(taskHandle));
if (heartbeat) {
info.lastTickMillis = heartbeat->lastTickMillis;
info.loopCount = heartbeat->loopCount;
}
return info;
}
return TaskInfo(); // Return empty/default TaskInfo if task is not running or invalid
}
TaskInfo getMaintenanceTaskInfo();
// System restart and maintenance
bool setRestartSystem(const char* reason, bool factoryReset = false);
// Firmware rollback: boot the passive OTA partition without a download (#237).
// esp_app_desc_t.version is a frozen arduino-lib-builder constant on this
// toolchain, so app_elf_sha256 is the only per-build identity a partition has.
enum class FirmwareRollbackResult {
SUCCESS, // boot partition switched, restart scheduled
INVALID_IMAGE, // passive slot has no valid bootable image
// (esp_ota_set_boot_partition's image_validate failed)
RESTART_BLOCKED, // restart already scheduled or uptime/safe-mode gate closed:
// refused up front (or undone, in the residual race) so a
// failure report never leaves a pending silent partition switch
};
void sha256BytesToHex(const uint8_t sha256[32], char* out, size_t outSize); // outSize >= SHA256_HEX_BUFFER_SIZE
// 64-hex app_elf_sha256 of a slot's app descriptor. Return false when the
// descriptor is unreadable (erased/partial slot). Buffers must be >= 65 bytes.
bool getRunningPartitionSha256(char* out, size_t outSize);
bool getOtherPartitionSha256(char* out, size_t outSize);
// Reads the passive/"other" OTA partition's image descriptor without executing
// it. False when unreadable or the image carries no valid descriptor (legacy
// pre-2.4 image, erased/partial slot).
bool getOtherPartitionImageDescriptor(ImageDescriptor::Descriptor& out);
// One flash sector: erasing the image header is enough to make a rejected
// image fail esp_image_verify, so it can never become a rollback target.
#define OTA_PARTITION_SCRUB_SIZE 4096
// Erase the header of a complete-but-rejected staged OTA image. Both OTA
// write paths call this on a post-download rejection (signature or image
// descriptor); the rollback consumers are not descriptor-gated, so a rejected
// image left intact could be activated later and brick the device.
bool scrubOtaImageHeader(const esp_partition_t* partition);
// Switch the boot partition to the passive slot and restart. Validation is
// esp_ota_set_boot_partition's own image_validate - deliberately NOT
// Update.canRollBack(), whose only check is flash[0] == 0xE9 (true even for a
// half-downloaded image). On success, marks the crash monitor's rollback-tried
// state and clears the pending-OTA validation record before the restart.
FirmwareRollbackResult attemptFirmwareRollback(const char* reason);
inline const char* getResetReasonString(esp_reset_reason_t reason) {
switch (reason) {
case ESP_RST_UNKNOWN: return "Unknown";
case ESP_RST_POWERON: return "Power on";
case ESP_RST_EXT: return "External pin";
case ESP_RST_SW: return "Software";
case ESP_RST_PANIC: return "Exception/panic";
case ESP_RST_INT_WDT: return "Interrupt watchdog";
case ESP_RST_TASK_WDT: return "Task watchdog";
case ESP_RST_WDT: return "Other watchdog";
case ESP_RST_DEEPSLEEP: return "Deep sleep";
case ESP_RST_BROWNOUT: return "Brownout";
case ESP_RST_SDIO: return "SDIO";
case ESP_RST_USB: return "USB peripheral";
case ESP_RST_JTAG: return "JTAG";
case ESP_RST_EFUSE: return "eFuse error";
case ESP_RST_PWR_GLITCH: return "Power glitch";
case ESP_RST_CPU_LOCKUP: return "CPU lockup";
default: return "Undefined";
}
}
// JSON utilities
bool safeSerializeJson(JsonDocument &jsonDocument, char* buffer, size_t bufferSize, bool truncateOnError = false);
// Preferences management
bool isFirstBootDone();
void setFirstBootDone();
void createAllNamespaces();
void clearAllPreferences();
// LittleFS file operations
bool listLittleFsFiles(JsonDocument &doc, const char* folderPath = nullptr); // Optional folder path to filter files
bool getLittleFsFileContent(const char* filepath, char* buffer, size_t bufferSize);
const char* getContentTypeFromFilename(const char* filename);
bool compressFile(const char* filepath);
void migrateCsvToGzip(const char* dirPath, const char* excludePrefix = nullptr); // Migrates CSV files to gzip, excluding files with the specified prefix (optional)
// Energy file consolidation
bool migrateEnergyFilesToDailyFolder(); // One-time migration of existing /energy/*.csv.gz to /energy/daily/
bool consolidateDailyFilesToMonthly(const char* yearMonth, const char* excludeDate = nullptr); // Consolidate daily files for YYYY-MM into monthly archive (optionally exclude a specific date)
bool consolidateMonthlyFilesToYearly(const char* year, const char* excludeMonth = nullptr); // Consolidate monthly files for YYYY into yearly archive (optionally exclude a specific month)
// Backup utilities
bool nvsDataToJson(JsonObject &doc);
RingBufferStream* startStreamingBackup(); // Start async TAR creation to RingBufferStream (no temp file, true streaming)
// Restore utilities
bool isNvsRestorePending(); // Check if configuration restore is pending (boot-time check)
void performNvsRestore(); // Perform configuration restore from staged file (boot-time)
bool restoreNvsFromJson(JsonDocument &doc); // Restore NVS from JSON document (inverse of nvsDataToJson)
bool isBackupVersionCompatible(const char* backupVersion); // Check if backup version is compatible with current firmware
int compareVersions(const char* current, const char* available); // Compare "X.Y.Z" version strings: >0 if current newer, 0 if equal, <0 if current older
// String utilities
inline bool endsWith(const char* s, const char* suffix) {
size_t ls = strlen(s), lsf = strlen(suffix);
return lsf <= ls && strcmp(s + ls - lsf, suffix) == 0;
}
inline bool startsWith(const char* s, const char* prefix) {
size_t ls = strlen(s), lsp = strlen(prefix);
return lsp <= ls && strncmp(s, prefix, lsp) == 0;
}
// Mutex utilities
inline bool createMutexIfNeeded(SemaphoreHandle_t* mutex) {
if (!mutex) return false;
if (*mutex == nullptr) {
*mutex = xSemaphoreCreateMutex();
if (*mutex == nullptr) {
LOG_ERROR("Failed to create mutex");
return false;
}
}
return true;
}
inline void deleteMutex(SemaphoreHandle_t* mutex) {
if (mutex && *mutex) {
vSemaphoreDelete(*mutex);
*mutex = nullptr;
}
}
inline bool acquireMutex(SemaphoreHandle_t* mutex, uint64_t timeout = CONFIG_MUTEX_TIMEOUT_MS) {
return mutex && *mutex && xSemaphoreTake(*mutex, pdMS_TO_TICKS(timeout)) == pdTRUE;
}
inline void releaseMutex(SemaphoreHandle_t* mutex) {
if (mutex && *mutex) xSemaphoreGive(*mutex);
}
inline static void* ota_calloc_psram(size_t n, size_t size) {
// Use SPIRAM; still 8-bit addressable.
return heap_caps_calloc(n, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
}
inline static void ota_free_psram(void* p) {
heap_caps_free(p);
}f4329a85eThis file is pinned to the selected release. Download the original to open it in your design tool.