Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
3c36a1e66This 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 "shadow.h"
#include <Preferences.h>
#include <esp_random.h>
#include <esp_timer.h>
#include "ade7953.h"
#include "app_image_descriptor.h"
#include "awsconfig.h"
#include "custometh.h"
#include "customwifi.h"
#include "factory_keys.h"
#include "globals.h"
#include "hardware_profile.h"
#include "issueregistry.h"
#include "led.h"
#include "mqtt.h"
#include "shadow_logic.h"
#include "utils.h"
namespace Shadow {
// Up to 6 named shadows: info, issues, wifi (reported-only), system, meter,
// channels (writable).
#define SHADOW_MAX_COUNT 6
#define SHADOW_NAME_PREFIX "shadow/name/"
#define SHADOW_INFO_REFRESH_INTERVAL_US (24ULL * 60ULL * 60ULL * 1000000ULL) // 24 h
// Drift-detect cadence: each writable shadow's reported state is rebuilt and
// compared to its last publish on this interval; any change (REST, command,
// internal, the log-level revert timer) is republished. Replaces per-call-site
// notify hooks, which can't cover lib-owned fields like the log levels.
#define SHADOW_DRIFT_CHECK_INTERVAL_MS 3000
// Per-shadow runtime state.
// - reportPending: benign volatile flag; any task may set it true, the MQTT
// task clears it in checkPublish(). No mutex needed (idempotent set; a lost
// race just defers one publish by one loop).
// - pendingDelta: ps_malloc'd payload copy handed from the RX callback to the
// MQTT task. Pointer ownership is swapped under _mutex (the only genuinely
// cross-task shared state here).
// - version / lastReported: MQTT-task-only (touched only in the checkPublish
// drain), so no mutex. lastReported holds the serialized reported state at the
// last publish; the drift check diffs against it to catch local changes.
struct ShadowEntry {
Descriptor desc;
uint32_t version;
volatile bool reportPending;
char* pendingDelta;
char* lastReported;
};
static ShadowEntry _shadows[SHADOW_MAX_COUNT];
static uint8_t _count = 0;
static SemaphoreHandle_t _mutex = nullptr;
static esp_timer_handle_t _infoRefreshTimer = nullptr;
// Report/apply callbacks (defined further down, registered in begin()).
static void _reportInfo(JsonDocument& doc);
static void _reportIssues(JsonDocument& doc);
static void _reportWifi(JsonDocument& doc);
static void _onIssuesChanged();
static void _reportSystem(JsonDocument& doc);
static bool _applySystem(JsonObjectConst delta, JsonObject reported);
static void _reportMeter(JsonDocument& doc);
static bool _applyMeter(JsonObjectConst delta, JsonObject reported);
static void _reportChannels(JsonDocument& doc);
static bool _applyChannels(JsonObjectConst delta, JsonObject reported);
// system shadow: transient (VERBOSE/DEBUG) mqtt_log_level auto-revert. The timer
// callback (esp_timer task) only flips a flag; the MQTT task does the revert +
// report (PubSubClient is single-task). _logLevelBaseline is the persisted level
// to restore to.
#define SHADOW_LOG_LEVEL_REVERT_INTERVAL_US (5ULL * 60ULL * 1000000ULL) // 5 min
static esp_timer_handle_t _logLevelRevertTimer = nullptr;
static volatile bool _logLevelRevertPending = false;
static int _logLevelBaseline = 2; // INFO
static void _logLevelRevertCallback(void* arg);
static void _checkSystemLogLevelRevert();
static void _applyMqttLogLevel(int level); // defined below; called from begin() for reboot-restore
// ============================================================================
// Registration
// ============================================================================
static void _registerShadow(const Descriptor& desc) {
if (_count >= SHADOW_MAX_COUNT) {
LOG_ERROR("Shadow table full, cannot register '%s'", desc.name);
return;
}
if (desc.writable && desc.apply == nullptr) {
LOG_ERROR("Writable shadow '%s' has no apply callback", desc.name);
return;
}
_shadows[_count] = {desc, 0, false, nullptr, nullptr};
_count++;
LOG_DEBUG("Registered shadow '%s' (%s)", desc.name, desc.writable ? "writable" : "reported-only");
}
static int _findShadow(const char* name, size_t nameLen) {
for (uint8_t i = 0; i < _count; i++) {
if (strlen(_shadows[i].desc.name) == nameLen &&
strncmp(_shadows[i].desc.name, name, nameLen) == 0) {
return (int)i;
}
}
return -1;
}
static void _infoRefreshCallback(void* arg) {
(void)arg;
requestReport("info"); // flag only; MQTT task publishes
}
void begin() {
if (!createMutexIfNeeded(&_mutex)) {
LOG_ERROR("Failed to create shadow mutex");
return;
}
_count = 0;
_registerShadow({"info", false, _reportInfo, nullptr});
_registerShadow({"issues", false, _reportIssues, nullptr});
_registerShadow({"wifi", false, _reportWifi, nullptr});
_registerShadow({"system", true, _reportSystem, _applySystem});
_registerShadow({"meter", true, _reportMeter, _applyMeter});
_registerShadow({"channels", true, _reportChannels, _applyChannels});
// Refresh the issues shadow on every registry transition/ack (flag only).
IssueRegistry::setChangeCallback(_onIssuesChanged);
// Low-priority periodic refresh so identity shadow's lastUpdated stays fresh
// even though the values rarely change. Callback only sets a flag.
if (_infoRefreshTimer == nullptr) {
const esp_timer_create_args_t timerArgs = {
.callback = _infoRefreshCallback,
.arg = nullptr,
.dispatch_method = ESP_TIMER_TASK,
.name = "shadow_info_refresh",
.skip_unhandled_events = true};
if (esp_timer_create(&timerArgs, &_infoRefreshTimer) == ESP_OK) {
esp_timer_start_periodic(_infoRefreshTimer, SHADOW_INFO_REFRESH_INTERVAL_US);
} else {
LOG_WARNING("Failed to create info shadow refresh timer");
}
}
// One-shot timer for the transient mqtt_log_level auto-revert (created idle).
if (_logLevelRevertTimer == nullptr) {
const esp_timer_create_args_t revertArgs = {
.callback = _logLevelRevertCallback,
.arg = nullptr,
.dispatch_method = ESP_TIMER_TASK,
.name = "shadow_loglevel_revert",
.skip_unhandled_events = true};
if (esp_timer_create(&revertArgs, &_logLevelRevertTimer) != ESP_OK) {
LOG_WARNING("Failed to create mqtt_log_level revert timer");
}
}
// Restore a transient (VERBOSE/DEBUG) mqtt_log_level across a reboot so a debug
// session keeps boot-time logs. Mqtt::begin() loaded the persisted baseline
// before this, so _applyMqttLogLevel captures the correct baseline and restarts
// the 5-min timer. Persistent levels never write the marker, so this only fires
// for a genuine transient window.
int transientLevel = Mqtt::getTransientLogLevel();
if (transientLevel >= 0 && ShadowLogic::isTransientLogLevel(transientLevel)) {
LOG_INFO("Restoring transient mqtt_log_level %s after reboot",
ShadowLogic::logLevelToString(transientLevel));
_applyMqttLogLevel(transientLevel);
}
LOG_DEBUG("Shadow module initialized with %u shadow(s)", _count);
}
// ============================================================================
// Topic helpers
// ============================================================================
static void _topicUpdate(const char* name, char* out, size_t outSize) {
snprintf(out, outSize, SHADOW_NAME_PREFIX "%s/update", name);
}
// ============================================================================
// Connect: subscribe writable shadows, queue initial reports
// ============================================================================
void onMqttConnected() {
char suffix[MQTT_TOPIC_BUFFER_SIZE];
for (uint8_t i = 0; i < _count; i++) {
if (_shadows[i].desc.writable) {
snprintf(suffix, sizeof(suffix), SHADOW_NAME_PREFIX "%s/update/delta", _shadows[i].desc.name);
Mqtt::subscribeReservedThings(suffix);
snprintf(suffix, sizeof(suffix), SHADOW_NAME_PREFIX "%s/update/rejected", _shadows[i].desc.name);
Mqtt::subscribeReservedThings(suffix);
}
// Publish-reported-first on every (re)connect. A still-pending cloud
// desired survives (we send no desired here) -> AWS re-sends the delta.
_shadows[i].reportPending = true;
}
LOG_DEBUG("Shadow subscriptions set; initial reports queued for %u shadow(s)", _count);
}
// ============================================================================
// Inbound routing (RX callback context: copy + flag only, never apply/publish)
// ============================================================================
bool routeMessage(const char* topic, const char* payload) {
const char* marker = strstr(topic, "/" SHADOW_NAME_PREFIX);
if (marker == nullptr) return false; // not a shadow topic
const char* nameStart = marker + strlen("/" SHADOW_NAME_PREFIX);
const char* nameEnd = strchr(nameStart, '/');
if (nameEnd == nullptr) {
LOG_WARNING("Malformed shadow topic: %s", topic);
return true; // it is a shadow topic, just unusable - do not fall through
}
int idx = _findShadow(nameStart, (size_t)(nameEnd - nameStart));
if (idx < 0) {
LOG_WARNING("Delta for unknown shadow in topic: %s", topic);
return true;
}
if (endsWith(topic, "/update/delta")) {
size_t len = strlen(payload) + 1;
char* copy = (char*)ps_malloc(len);
if (copy == nullptr) {
LOG_ERROR("Failed to allocate shadow delta buffer (%zu bytes)", len);
return true;
}
memcpy(copy, payload, len);
if (acquireMutex(&_mutex)) {
if (_shadows[idx].pendingDelta != nullptr) free(_shadows[idx].pendingDelta); // newer delta wins
_shadows[idx].pendingDelta = copy;
releaseMutex(&_mutex);
LOG_DEBUG("Queued delta for shadow '%s' (%zu bytes)", _shadows[idx].desc.name, len - 1);
} else {
free(copy);
LOG_ERROR("Failed to acquire shadow mutex queuing delta for '%s'", _shadows[idx].desc.name);
}
} else if (endsWith(topic, "/update/rejected")) {
// 409 (version conflict) recovery is a reported-first re-publish (carries
// no version); for any rejection that is a safe resync. Log the payload.
LOG_WARNING("Shadow '%s' update rejected: %s", _shadows[idx].desc.name, payload);
_shadows[idx].reportPending = true;
} else {
LOG_DEBUG("Ignoring shadow topic (not delta/rejected): %s", topic);
}
return true;
}
// ============================================================================
// Publishing primitives (MQTT task context only)
// ============================================================================
// Snapshot the reported object as the drift baseline (MQTT-task-only field, no
// mutex). The periodic drift check diffs against this, so refreshing it after a
// publish - or after a cloud-delta apply - stops that change from being treated
// as a fresh local edit and re-published. OOM leaves the baseline stale, which
// just costs one redundant republish on the next tick.
static void _storeBaseline(uint8_t idx, JsonObjectConst reported) {
size_t len = measureJson(reported) + 1;
char* snap = (char*)ps_malloc(len);
if (snap == nullptr) return;
serializeJson(reported, snap, len);
if (_shadows[idx].lastReported != nullptr) free(_shadows[idx].lastReported);
_shadows[idx].lastReported = snap;
}
// Publish an already-built reported doc and refresh the drift baseline from it.
// Split out of _publishReported so the drift check can hand over the doc it just
// built to detect the change, instead of rebuilding the full report a second time.
static void _publishReportedDoc(uint8_t idx, JsonDocument& doc) {
char topic[MQTT_TOPIC_BUFFER_SIZE];
_topicUpdate(_shadows[idx].desc.name, topic, sizeof(topic));
if (!Mqtt::publishReservedThings(doc, topic)) {
LOG_WARNING("Failed to publish reported state for shadow '%s'", _shadows[idx].desc.name);
return;
}
LOG_DEBUG("Published reported state for shadow '%s'", _shadows[idx].desc.name);
_storeBaseline(idx, doc["state"]["reported"].as<JsonObjectConst>());
}
static void _publishReported(uint8_t idx) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
_shadows[idx].desc.report(doc); // fills doc["state"]["reported"]
_publishReportedDoc(idx, doc);
}
static void _addClientToken(JsonDocument& doc) {
char token[24];
if (ShadowLogic::formatClientToken(token, sizeof(token), esp_random(), esp_random()) > 0) {
doc["clientToken"] = token; // copied (mutable buffer)
}
}
static void _applyDelta(uint8_t idx, const char* payload) {
if (_shadows[idx].desc.apply == nullptr) {
LOG_WARNING("Delta for reported-only shadow '%s' ignored", _shadows[idx].desc.name);
return;
}
SpiRamAllocator inAllocator;
JsonDocument inDoc(&inAllocator);
DeserializationError error = deserializeJson(inDoc, payload);
if (error) {
LOG_ERROR("Failed to parse delta for shadow '%s' (%s)", _shadows[idx].desc.name, error.c_str());
return;
}
uint32_t version = inDoc["version"] | 0u;
_shadows[idx].version = version; // MQTT-task-only field
JsonObjectConst delta = inDoc["state"].as<JsonObjectConst>();
if (delta.isNull()) {
LOG_WARNING("Delta for shadow '%s' has no 'state' object", _shadows[idx].desc.name);
return;
}
SpiRamAllocator outAllocator;
JsonDocument outDoc(&outAllocator);
JsonObject reported = outDoc["state"]["reported"].to<JsonObject>();
JsonObject desired = outDoc["state"]["desired"].to<JsonObject>();
_shadows[idx].desc.apply(delta, reported);
// Ack/clear: null every top-level field the cloud sent so the delta clears
// (the cloud owns any further desired lifecycle). Channels are object-keyed,
// so this nulls the whole channel object - intentional: keeping a partial
// desired would re-trigger a delta storm for any field the device cannot
// converge (e.g. channel 0 stays active even if a delta tried to disable it).
for (JsonPairConst kv : delta) {
desired[kv.key()] = nullptr;
}
if (ShadowLogic::shouldSendVersion(version)) outDoc["version"] = version;
_addClientToken(outDoc);
char topic[MQTT_TOPIC_BUFFER_SIZE];
_topicUpdate(_shadows[idx].desc.name, topic, sizeof(topic));
if (Mqtt::publishReservedThings(outDoc, topic)) {
LOG_INFO("Applied delta for shadow '%s' (version %lu)", _shadows[idx].desc.name, (unsigned long)version);
// Refresh the drift baseline so the 3 s drift check does not see this
// cloud-applied change as a fresh local edit and republish it. The ack
// above carries only the changed fields (partial), so rebuild the full
// report here rather than reusing outDoc.
SpiRamAllocator repAllocator;
JsonDocument repDoc(&repAllocator);
_shadows[idx].desc.report(repDoc);
_storeBaseline(idx, repDoc["state"]["reported"].as<JsonObjectConst>());
} else {
LOG_WARNING("Failed to publish delta ack for shadow '%s'", _shadows[idx].desc.name);
}
}
// ============================================================================
// Drain (MQTT task body)
// ============================================================================
// Republish a writable shadow if its reported state changed since the last
// publish (any source: REST, command, internal logic, the log-level revert
// timer). Build a fresh report, compare its serialized reported object to the
// stored baseline; on a difference, publish (which refreshes the baseline).
static void _reportIfDrifted(uint8_t idx) {
SpiRamAllocator allocator;
JsonDocument doc(&allocator);
_shadows[idx].desc.report(doc);
JsonObjectConst reported = doc["state"]["reported"].as<JsonObjectConst>();
size_t len = measureJson(reported) + 1;
char* cur = (char*)ps_malloc(len);
if (cur == nullptr) return; // out of PSRAM; retry next tick
serializeJson(reported, cur, len);
bool changed = _shadows[idx].lastReported == nullptr ||
strcmp(cur, _shadows[idx].lastReported) != 0;
free(cur);
if (changed) _publishReportedDoc(idx, doc); // reuse the doc we just built
}
void checkPublish() {
_checkSystemLogLevelRevert(); // transient mqtt_log_level revert (flag set by timer task)
for (uint8_t i = 0; i < _count; i++) {
char* delta = nullptr;
bool report = false;
if (acquireMutex(&_mutex)) {
delta = _shadows[i].pendingDelta;
_shadows[i].pendingDelta = nullptr;
releaseMutex(&_mutex);
}
// reportPending is a benign volatile flag; read+clear without the mutex.
report = _shadows[i].reportPending;
if (report) _shadows[i].reportPending = false;
if (delta != nullptr) {
_applyDelta(i, delta);
free(delta);
}
if (report) _publishReported(i);
}
// Drift detect (gated): republish any writable shadow whose reported state
// changed since its last publish, regardless of source. One periodic diff
// replaces per-call-site notify hooks and covers lib-owned fields too.
static uint64_t lastDriftCheck = 0;
if ((millis64() - lastDriftCheck) > SHADOW_DRIFT_CHECK_INTERVAL_MS) {
lastDriftCheck = millis64();
for (uint8_t i = 0; i < _count; i++) {
if (_shadows[i].desc.writable) _reportIfDrifted(i);
}
}
}
// ============================================================================
// Public cross-task entry points
// ============================================================================
void requestReport(const char* name) {
// Before begin() registers the shadows (_count == 0) callers like the
// ADE7953 channel-config load fire this during setup; ignore quietly - the
// shadow reports its full state on MQTT connect anyway, so a dropped early
// flag costs nothing. After init an unknown name is a real bug, so warn.
if (_count == 0) return;
int idx = _findShadow(name, strlen(name));
if (idx >= 0) _shadows[idx].reportPending = true; // benign volatile set
else LOG_WARNING("requestReport for unknown shadow '%s'", name);
}
#ifdef ENV_DEV
bool injectDelta(const char* name, const char* payload) {
char topic[MQTT_TOPIC_BUFFER_SIZE];
snprintf(topic, sizeof(topic), "%s/%s/" SHADOW_NAME_PREFIX "%s/update/delta", MQTT_THINGS, DEVICE_ID, name);
LOG_INFO("Injecting synthetic delta for shadow '%s'", name);
return routeMessage(topic, payload);
}
#endif
// ============================================================================
// info shadow (reported-only): static device identity
// ============================================================================
static void _reportInfo(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
rep["firmware_version"] = FIRMWARE_BUILD_VERSION; // string literal: linked
rep["firmware_build_date"] = FIRMWARE_BUILD_DATE;
char md5[MD5_BUFFER_SIZE];
snprintf(md5, sizeof(md5), "%s", ESP.getSketchMD5().c_str());
rep["sketch_md5"] = md5; // mutable buffer: copied
char hwProfile[VERSION_BUFFER_SIZE];
uint8_t v = (globalHwProfile != nullptr) ? globalHwProfile->version : 0;
snprintf(hwProfile, sizeof(hwProfile), "v%u.%u", v / 10, v % 10);
rep["hardware_profile"] = hwProfile;
rep["community_mode"] = globalCommunityMode;
rep["device_id"] = DEVICE_ID;
// Rollback target fingerprint: lets the fleet pick a firmware_rollback
// command's expected_sha256 from the shadow without querying the device
// mid-incident. null when the passive slot is empty/invalid.
char otherSha[SHA256_HEX_BUFFER_SIZE];
if (getOtherPartitionSha256(otherSha, sizeof(otherSha))) {
rep["other_partition_sha256"] = otherSha; // mutable buffer: copied
} else {
rep["other_partition_sha256"] = nullptr;
}
// Running image's own descriptor: fleet-wide PSRAM/build inventory without
// per-device polling.
rep["image_psram_mb"] = ENERGYME_APP_DESC.psramMb;
rep["image_build_env"] = ENERGYME_APP_DESC.buildEnv;
rep["image_git_rev"] = ENERGYME_APP_DESC.gitRev;
rep["image_partition_layout_id"] = ENERGYME_APP_DESC.partitionLayoutId;
// Passive/"other" partition's descriptor: what firmware_rollback or the
// crash ladder would actually activate. null when the slot holds no valid
// descriptor (empty, erased, or a legacy pre-2.4 image).
ImageDescriptor::Descriptor otherDesc;
if (getOtherPartitionImageDescriptor(otherDesc)) {
// otherDesc is a non-const local, so ArduinoJson copies these (parse NUL-terminates them)
rep["other_image_product"] = otherDesc.product;
rep["other_image_psram_mb"] = otherDesc.psramMb;
rep["other_image_fw_version"] = otherDesc.fwVersion;
} else {
rep["other_image_product"] = nullptr;
rep["other_image_psram_mb"] = nullptr;
rep["other_image_fw_version"] = nullptr;
}
char serial[NAME_BUFFER_SIZE] = {0};
char pcbRev[VERSION_BUFFER_SIZE] = {0};
uint64_t mfgTs = 0;
Preferences prefs;
if (prefs.begin(PREFERENCES_NAMESPACE_FACTORY, true)) {
prefs.getString(FACTORY_KEY_SERIAL_NUMBER, serial, sizeof(serial));
prefs.getString(FACTORY_KEY_PCB_REVISION, pcbRev, sizeof(pcbRev));
mfgTs = prefs.getULong64(FACTORY_KEY_MFG_TS, 0);
prefs.end();
}
// Assign the bare char[] (ArduinoJson copies it). A ternary with the
// "Unknown" literal would decay to const char* and be stored by pointer,
// leaving a dangling pointer into this stack frame once we return.
if (serial[0] == '\0') snprintf(serial, sizeof(serial), "Unknown");
if (pcbRev[0] == '\0') snprintf(pcbRev, sizeof(pcbRev), "Unknown");
rep["serial_number"] = serial;
rep["pcb_revision"] = pcbRev;
rep["manufacturing_unix"] = mfgTs;
}
// ============================================================================
// wifi shadow (reported-only): non-secret network state + mode
// ============================================================================
static void _reportWifi(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
char buf[64]; // SSID <=32, IP <=15, MAC 17 - all fit; reused (ArduinoJson copies char[])
rep["connected"] = WiFi.isConnected();
// SSID only - the WiFi password is never placed in a shadow (AWS forbids
// secrets in shadow docs, and we keep credentials local-only).
snprintf(buf, sizeof(buf), "%s", WiFi.SSID().c_str());
rep["ssid"] = buf;
snprintf(buf, sizeof(buf), "%s", WiFi.localIP().toString().c_str());
rep["ip"] = buf;
snprintf(buf, sizeof(buf), "%s", WiFi.gatewayIP().toString().c_str());
rep["gateway"] = buf;
snprintf(buf, sizeof(buf), "%s", WiFi.subnetMask().toString().c_str());
rep["subnet"] = buf;
snprintf(buf, sizeof(buf), "%s", WiFi.dnsIP().toString().c_str());
rep["dns"] = buf;
snprintf(buf, sizeof(buf), "%s", WiFi.macAddress().c_str());
rep["mac"] = buf;
// Network mode (DHCP vs static) for visibility. Reported-only: static IP is
// configured locally via REST, never written from the cloud - a bad remote
// static IP would risk locking the device off the LAN (see customwifi.h).
WifiConfiguration cfg;
if (CustomWifi::getConfiguration(cfg)) {
rep["static_ip"] = cfg.useStaticIp;
rep["fallback_to_dhcp"] = cfg.fallbackToDhcp;
}
// RSSI is intentionally omitted: it's volatile (would churn the shadow
// version) and is already on the system/dynamic telemetry topic.
// Ethernet rides in this shadow rather than its own: the cloud allowlists the
// six shadow names, and stores reported state opaquely. Failover forces an MQTT
// reconnect, which republishes every shadow; Ethernet link/IP events flag this one.
if (globalHwProfile == nullptr || !globalHwProfile->hasEthernet) return;
SpiRamAllocator allocator;
JsonDocument eth(&allocator);
CustomEth::getStatusAsJson(eth);
rep["active_interface"] = eth["activeInterface"];
JsonObject ethRep = rep["ethernet"].to<JsonObject>();
ethRep["enabled"] = eth["enabled"];
if (!eth["enabled"].as<bool>()) return;
ethRep["link_up"] = eth["linkUp"];
ethRep["static_ip"] = eth["staticApplied"];
ethRep["ip"] = eth["ip"];
ethRep["gateway"] = eth["gateway"];
ethRep["subnet"] = eth["subnet"];
ethRep["dns1"] = eth["dns1"];
ethRep["dns2"] = eth["dns2"];
ethRep["mac"] = eth["mac"];
}
// ============================================================================
// issues shadow (reported-only): runtime issue registry mirror
// ============================================================================
static void _onIssuesChanged() {
requestReport("issues"); // flag only; the MQTT task publishes
}
static void _reportIssues(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
rep["active_count"] = IssueRegistry::activeCount();
SpiRamAllocator allocator;
JsonDocument tmp(&allocator);
if (IssueRegistry::issuesToJson(tmp)) {
rep["issues"] = tmp["issues"]; // deep-copied into doc's pool
} else {
rep["issues"].to<JsonArray>(); // empty array if the registry was busy
}
}
// ============================================================================
// system shadow (writable): behavioural config + mqtt_log_level auto-revert
// ============================================================================
// esp_timer task: flag only. PubSubClient is single-task, so the MQTT task does
// the actual revert + report (in _checkSystemLogLevelRevert).
static void _logLevelRevertCallback(void* arg) {
(void)arg;
_logLevelRevertPending = true;
}
static void _checkSystemLogLevelRevert() {
if (!_logLevelRevertPending) return;
_logLevelRevertPending = false;
Mqtt::setRuntimeLogLevel(_logLevelBaseline);
Mqtt::clearTransientLogLevel(); // window closed; nothing to restore on next boot
LOG_INFO("mqtt_log_level auto-reverted to baseline %s", ShadowLogic::logLevelToString(_logLevelBaseline));
requestReport("system");
}
static void _applyMqttLogLevel(int level) {
if (ShadowLogic::isTransientLogLevel(level)) {
// Capture the persisted baseline once: if the current runtime level is
// itself transient we are already inside a window, so keep the stored
// baseline rather than overwriting it with another transient.
int current = Mqtt::getMqttLogLevel();
if (!ShadowLogic::isTransientLogLevel(current)) _logLevelBaseline = current;
_logLevelRevertPending = false; // (re)entering transient
Mqtt::setRuntimeLogLevel(level); // runtime only, not persisted
if (_logLevelRevertTimer != nullptr) {
esp_timer_stop(_logLevelRevertTimer); // harmless if not running
esp_timer_start_once(_logLevelRevertTimer, SHADOW_LOG_LEVEL_REVERT_INTERVAL_US);
}
// Persist a marker so a reboot mid-window restores the transient level and
// restarts the timer - a debug session keeps boot-time logs (the baseline
// key is left untouched).
Mqtt::saveTransientLogLevel(level);
LOG_INFO("mqtt_log_level transient %s (auto-revert in 5 min to %s)",
ShadowLogic::logLevelToString(level), ShadowLogic::logLevelToString(_logLevelBaseline));
} else {
if (_logLevelRevertTimer != nullptr) esp_timer_stop(_logLevelRevertTimer);
_logLevelBaseline = level; // track the new baseline so a late timer flag is a no-op
_logLevelRevertPending = false;
Mqtt::clearTransientLogLevel(); // leaving the transient window
Mqtt::setMqttLogLevel(ShadowLogic::logLevelToString(level)); // persisted baseline
}
}
static void _reportSystem(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
rep["led_brightness"] = Led::getBrightness();
rep["send_power_data"] = Mqtt::getSendPowerData();
rep["send_grid_data"] = Mqtt::getSendGridData();
rep["meter_publish_threshold_bytes"] = Mqtt::getMeterPublishThresholdBytes();
rep["meter_publish_max_interval_ms"] = Mqtt::getMeterPublishMaxIntervalMs();
rep["mqtt_log_level"] = ShadowLogic::logLevelToString(Mqtt::getMqttLogLevel());
rep["log_level_print"] = AdvancedLogger::logLevelToString(AdvancedLogger::getPrintLevel());
rep["log_level_save"] = AdvancedLogger::logLevelToString(AdvancedLogger::getSaveLevel());
}
// Parse a string log-level delta field. Returns the level (>=0) to apply, or -1
// if the field is absent or invalid (warns on an unknown level). Shared by the
// three log-level fields below, which differ only in their setter/getter.
static int _parseLogLevelDelta(JsonObjectConst delta, const char* key) {
JsonVariantConst v = delta[key];
if (v.isNull()) return -1;
int level = ShadowLogic::logLevelFromString(v.as<const char*>());
if (level < 0) LOG_WARNING("Rejected %s: unknown level", key);
return level;
}
static bool _applySystem(JsonObjectConst delta, JsonObject reported) {
bool applied = false;
JsonVariantConst v = delta["led_brightness"];
if (!v.isNull()) {
if (v.is<int>()) {
int b = v.as<int>();
if (b >= 0 && b <= 0xFF && Led::isBrightnessValid((uint8_t)b)) {
Led::setBrightness((uint8_t)b); // persists
reported["led_brightness"] = Led::getBrightness();
applied = true;
} else {
LOG_WARNING("Rejected led_brightness %d (out of range)", b);
}
} else {
LOG_WARNING("Rejected led_brightness: not an integer");
}
}
v = delta["send_power_data"];
if (!v.isNull()) {
if (v.is<bool>()) {
bool e = v.as<bool>();
Mqtt::setSendPowerData(e); // persists
reported["send_power_data"] = e;
applied = true;
} else {
LOG_WARNING("Rejected send_power_data: not a boolean");
}
}
v = delta["send_grid_data"];
if (!v.isNull()) {
if (v.is<bool>()) {
bool e = v.as<bool>();
Mqtt::setSendGridData(e); // persists
reported["send_grid_data"] = e;
applied = true;
} else {
LOG_WARNING("Rejected send_grid_data: not a boolean");
}
}
// meter_publish_threshold_bytes / meter_publish_max_interval_ms: the setters
// clamp to their valid range (and WARN-log if a clamp occurred), so the
// reported value here is always the actual applied value, not the raw request.
v = delta["meter_publish_threshold_bytes"];
if (!v.isNull()) {
if (v.is<int>() && v.as<int>() >= 0) {
Mqtt::setMeterPublishThresholdBytes((uint32_t)v.as<int>()); // persists, clamped
reported["meter_publish_threshold_bytes"] = Mqtt::getMeterPublishThresholdBytes();
applied = true;
} else {
LOG_WARNING("Rejected meter_publish_threshold_bytes: not a non-negative integer");
}
}
v = delta["meter_publish_max_interval_ms"];
if (!v.isNull()) {
if (v.is<int>() && v.as<int>() >= 0) {
Mqtt::setMeterPublishMaxIntervalMs((uint32_t)v.as<int>()); // persists, clamped
reported["meter_publish_max_interval_ms"] = Mqtt::getMeterPublishMaxIntervalMs();
applied = true;
} else {
LOG_WARNING("Rejected meter_publish_max_interval_ms: not a non-negative integer");
}
}
int level = _parseLogLevelDelta(delta, "mqtt_log_level");
if (level >= 0) {
_applyMqttLogLevel(level);
reported["mqtt_log_level"] = ShadowLogic::logLevelToString(Mqtt::getMqttLogLevel());
applied = true;
}
level = _parseLogLevelDelta(delta, "log_level_print");
if (level >= 0) {
AdvancedLogger::setPrintLevel((LogLevel)level); // persists (lib-internal)
reported["log_level_print"] = AdvancedLogger::logLevelToString(AdvancedLogger::getPrintLevel());
applied = true;
}
level = _parseLogLevelDelta(delta, "log_level_save");
if (level >= 0) {
AdvancedLogger::setSaveLevel((LogLevel)level); // persists (lib-internal)
reported["log_level_save"] = AdvancedLogger::logLevelToString(AdvancedLogger::getSaveLevel());
applied = true;
}
return applied;
}
// ============================================================================
// meter shadow (writable): ADE7953 calibration + sample time
// ============================================================================
// The 19 calibration keys (camelCase) as serialized by getConfigurationAsJson and
// accepted by Ade7953::configurationFromJson - keep this list in sync with that
// setter's key set. Kept as an explicit allow-list (rather than handing the raw
// delta to setConfigurationFromJson) so the meter delta's sample_time - applied
// separately below - is filtered out before it reaches _validateJsonConfiguration.
static const char* const METER_CAL_KEYS[] = {
"aVGain", "aIGain", "bIGain", "aIRmsOs", "bIRmsOs",
"aWGain", "bWGain", "aWattOs", "bWattOs",
"aVarGain", "bVarGain", "aVarOs", "bVarOs",
"aVaGain", "bVaGain", "aVaOs", "bVaOs",
"phCalA", "phCalB"};
static constexpr size_t METER_CAL_KEY_COUNT = sizeof(METER_CAL_KEYS) / sizeof(METER_CAL_KEYS[0]);
static void _reportMeter(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
SpiRamAllocator allocator;
JsonDocument cfg(&allocator);
Ade7953::getConfigurationAsJson(cfg);
for (JsonPairConst kv : cfg.as<JsonObjectConst>()) rep[kv.key()] = kv.value();
rep["sample_time"] = Ade7953::getSampleTime();
}
static bool _applyMeter(JsonObjectConst delta, JsonObject reported) {
bool applied = false;
// Collect the calibration fields present in the delta into a partial config.
SpiRamAllocator allocator;
JsonDocument cfg(&allocator);
for (size_t i = 0; i < METER_CAL_KEY_COUNT; i++) {
JsonVariantConst v = delta[METER_CAL_KEYS[i]];
if (v.isNull()) continue;
if (v.is<int>()) {
cfg[METER_CAL_KEYS[i]] = v.as<int32_t>();
} else {
LOG_WARNING("Rejected meter calibration '%s': not an integer", METER_CAL_KEYS[i]);
}
}
if (cfg.size() > 0) { // at least one calibration field present
if (Ade7953::setConfigurationFromJson(cfg, /*partial=*/true)) {
for (JsonPairConst kv : cfg.as<JsonObjectConst>()) reported[kv.key()] = kv.value();
applied = true;
} else {
LOG_WARNING("Meter calibration apply rejected by ADE7953");
}
}
// sample_time is not part of the calibration struct - applied separately.
JsonVariantConst st = delta["sample_time"];
if (!st.isNull()) {
if (st.is<int>() && st.as<int>() > 0 && Ade7953::setSampleTime((uint64_t)st.as<int>())) {
reported["sample_time"] = Ade7953::getSampleTime();
applied = true;
} else {
LOG_WARNING("Rejected sample_time (not a positive integer >= minimum)");
}
}
return applied;
}
// ============================================================================
// channels shadow (writable): per-channel config, object-keyed by index
// ============================================================================
// Overlay src onto dst, recursing into nested objects (e.g. ctSpecification) so
// a delta touching one subfield does not drop the channel's other CT params.
static void _deepMerge(JsonObject dst, JsonObjectConst src) {
for (JsonPairConst kv : src) {
if (kv.value().is<JsonObjectConst>()) {
JsonObject child = dst[kv.key()].is<JsonObject>() ? dst[kv.key()].as<JsonObject>()
: dst[kv.key()].to<JsonObject>();
_deepMerge(child, kv.value().as<JsonObjectConst>());
} else {
dst[kv.key()] = kv.value();
}
}
}
static void _reportChannels(JsonDocument& doc) {
JsonObject rep = doc["state"]["reported"].to<JsonObject>();
char key[4]; // up to "16" + null
for (uint8_t i = 0; i < globalHwProfile->totalChannelCount; i++) {
SpiRamAllocator allocator;
JsonDocument ch(&allocator);
if (!Ade7953::getChannelDataAsJson(ch, i)) continue;
ch.remove("index"); // index is the object key, not a field
snprintf(key, sizeof(key), "%u", i);
rep[key] = ch; // object-keyed so the cloud can patch one channel
}
}
static bool _applyChannels(JsonObjectConst delta, JsonObject reported) {
bool applied = false;
uint8_t channelCount = globalHwProfile->totalChannelCount;
for (JsonPairConst kv : delta) {
uint8_t idx = 0;
if (!ShadowLogic::parseChannelIndex(kv.key().c_str(), channelCount, &idx)) {
LOG_WARNING("Rejected channel key '%s' (not a valid index)", kv.key().c_str());
continue;
}
if (!kv.value().is<JsonObjectConst>()) {
LOG_WARNING("Rejected channel %u delta (value is not an object)", idx);
continue;
}
// Start from the current channel, overlay the changed subfields, apply.
SpiRamAllocator mergeAlloc;
JsonDocument merged(&mergeAlloc);
if (!Ade7953::getChannelDataAsJson(merged, idx)) {
LOG_WARNING("Failed to read channel %u for merge", idx);
continue;
}
JsonObject mergedObj = merged.as<JsonObject>();
_deepMerge(mergedObj, kv.value().as<JsonObjectConst>());
merged["index"] = idx; // setChannelDataFromJson keys off this; never let a delta change it
bool roleChanged = false;
if (!Ade7953::setChannelDataFromJson(merged, /*partial=*/true, &roleChanged)) {
LOG_WARNING("Channel %u apply rejected by ADE7953", idx);
continue;
}
// Echo the channel as actually applied (e.g. channel 0 stays active even
// if a delta tried to disable it), keyed by index, index field dropped.
SpiRamAllocator afterAlloc;
JsonDocument after(&afterAlloc);
if (Ade7953::getChannelDataAsJson(after, idx)) {
after.remove("index");
char key[4];
snprintf(key, sizeof(key), "%u", idx);
reported[key] = after;
}
applied = true;
}
return applied;
}
} // namespace Shadow