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 "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
f4329a85eThis file is pinned to the selected release. Download the original to open it in your design tool.