Docs / Modules / Config
Config
Config<T> represents durable application configuration. Declaring a Config
means the application intentionally exposes that value to the Config command
surface and expects accepted changes to survive reboot.
Configs are not Resources. They have no MQTT, publication, subscription, or
freshness semantics; persistence is local through PersistentSettings.
Declaration and registration#
Declare Configs with the lifetime their availability should have. Construction automatically binds each object to the global manager, and destruction unbinds it:
#include <NightMare/Config.h>
Config<uint32_t> maxDoorOpen("door:max_open_time", 300000);
Config<bool> autoOffEnabled("door:auto_off", true);
Config<uint32_t> restartRequiredOption("system:some_option", 10, true);
Config<TimeType> quietStart("schedule:quiet_start", TimeType(22, 30));
Config<ColourType> statusColour("status:colour", ColourType(255, 0, 0));
The manager stores non-owning pointers. Automatic unbinding makes scoped Configs
safe. Names must be non-empty and contain no command whitespace; names and
pointers may only be bound once. Up to 64 Configs may be bound. Failed automatic
binding leaves the value readable but absent from persistence, command ingress,
and the manifest; its set() therefore returns false. This includes a Config
whose immediate post-restore initialization cannot be persisted.
configManager().bind() and configManager().unbind() remain public for
explicit runtime registration. A Config that is already auto-bound is rejected
by bind() under the same duplicate pointer/name rules as any other binding.
Every Config declares its firmware default in the constructor. That value is
installed immediately. During startup, a valid persisted value overwrites the
default before normal framework use. require_reboot is the optional third
argument; this ordering avoids ambiguity for Config<bool>.
The built-in typed surface includes TimeType and ColourType through the
same NetCodec<T> path as primitive types. No Config-specific encoding exists.
Local access#
const uint32_t current = maxDoorOpen.value(); // 300000 initially
maxDoorOpen.set(300000);
Local set() first persists the canonical NetCodec<T> encoding and then
updates the typed runtime value. It does not call either ingress handler,
publish, or reboot. If persistence fails, set() returns false and leaves
the runtime value unchanged.
Each Config may also install a typed handler for ConfigManager writes:
bool acceptPeriod(Config<int> &config, const int &requested)
{
return requested >= 15 && requested <= 86400;
}
Config<int> heartbeatPeriod("heartbeat:period", 15);
void setup()
{
heartbeatPeriod.onWrite = acceptPeriod;
}
Returning false rejects the write and leaves the current value unchanged.
Like the global handler, onWrite is an ingress policy: a local set() does
not invoke it.
Restore and storage lifecycle#
Global/static Config construction never mounts the filesystem. The lifecycle is deliberately split:
Config construction
-> install firmware default
-> bind to ConfigManager
NightMare startup
-> initialize PersistentSettings
-> ConfigManager.restore()
-> replace defaults with valid saved values
Before restore, Config values contain firmware defaults. After
startNightMareESP() (or an explicit successful configManager().restore()),
they contain persisted values when available. Applications should not treat
them as fully initialized before that phase completes.
Storage keys use the reserved _config: prefix. Values use the same canonical
NetCodec<T> encoding as command ingress. Missing values keep and persist the
firmware default. Invalid saved values log a warning, restore the default, and
replace the invalid storage entry. Restore does not invoke write handlers and
is idempotent after success.
Configs bound after a successful manager restore are restored individually
before bind() returns. A valid saved value is immediately visible; a missing
value causes the firmware default to be persisted. If that initialization
fails, registration is undone and bind() returns false. This preserves the
persistent Config invariant for dynamically created Configs without accessing
the filesystem during static construction.
Local writes also verify that the codec can decode its own canonical encoding before anything is persisted. A value whose encoding cannot be restored is rejected, protecting both built-in and future custom codecs.
std::string ingress#
The common command path accepts:
CONFIG LIST
CONFIG LIST JSON
CONFIG GET max_door_open_time
CONFIG SET max_door_open_time 300000
CONFIG MANIFEST
It redirects everything after CONFIG to configManager().handle(command),
whose direct API accepts the same command without the prefix:
list
list json
get max_door_open_time
set max_door_open_time 300000
manifest
list returns a text table with the columns TYPE, NAME, REBOOT and
VALUE, one Config per row, like >list does for Resources. list json
returns compact JSON containing declaration metadata and each Config's
current value in its canonical NetCodec<T> std::string form. get returns that
same encoded value for one Config. set treats everything after the name
separator as the payload. manifest returns Base64 of the declaration-only
binary manifest.
Example list item:
{
"name": "heartbeat:period",
"type": "integer",
"require_reboot": false,
"value": "15"
}
The application may install one global ingress handler:
bool onConfigChange(const std::string &key, const std::string &rawValue)
{
if (key == "max_door_open_time" && std::strtol(rawValue.c_str(), nullptr, 10) < 1000)
return false;
return true;
}
configManager().setChangeHandler(onConfigChange);
Ingress first decodes the payload to the Config's declared type, calls the
global handler with the original payload, then calls that Config's typed
onWrite handler when present. It then persists the canonical value and only
afterward commits the runtime value. Decode, handler, or persistence failure
leaves the current runtime value unchanged and reports an error.
Naming related declarations#
When related values naturally belong to one subsystem, prefer names such as
<group>:<value> or <group>:<subgroup>:<value>:
led_strip:colour
led_strip:brightness
climate:bedroom:target_temperature
climate:bedroom:fan_speed
This is only a convention. NightMare does not enforce it or interpret : as a
protocol delimiter. It gives backend tools a stable hint for future visual
grouping and relationship inference; existing flat names remain valid.
Manifest#
The version 1 MessagePack layout is positional:
[
encodingVersion,
manifestVersion,
[
[name, NetValueType, requireReboot],
...
]
]
Current values are intentionally absent: the manifest describes declarations,
not runtime state. buildManifestMsgPack() writes the canonical bytes into a
caller buffer. If capacity is insufficient it returns false, leaves the
buffer untouched, and reports the required length in written.
buildManifestBase64() and handle("manifest") directly encode those same
bytes. The manager never publishes the result.
require_reboot is informational only. Accepted values apply immediately;
the application or surrounding tooling decides whether and when to reboot.