Docs / Modules / Settings and runtime state
Settings and runtime state
NightMare has two generic std::string key/value types and one typed runtime facility:
RuntimeState
RAM only
StateStore
RuntimeState behavior + optional persistence
SystemStateStore
allocation-free framework facts and pending requests
The standard global instances are:
SystemState
PersistentSettings
SystemState is not a key/value store. PersistentSettings remains a
StateStore backed by the existing std::string model.
Runtime state still exists through RuntimeState, but there is intentionally
no global runtime configuration controller. Applications own their runtime
state; SystemState is reserved for framework runtime facts and requests.
RuntimeState#
RuntimeState is a small in-memory std::string key/value store.
RuntimeState state;
It never accesses filesystem storage.
Current capacity:
RuntimeState::MaxEntries == 128
The persistent store shares this capacity with Config values. Sixty-four slots
match ConfigManagerMaxConfigs; the other sixty-four provide explicit headroom
for framework-private and application settings. Increasing the former requires
increasing this capacity too and carries a corresponding RAM cost.
Set#
state.set("mode", "cool");
A key must be non-empty.
Setting an existing key replaces its value.
Adding a new key fails when the store already contains 128 entries.
Get#
std::string mode = state.get("mode", "off");
The default is returned when the key does not exist.
Flags#
Convenience helpers store booleans as:
"1"
"0"
Use:
state.setFlag("ready", true);
if (state.getFlag("ready"))
{
// ...
}
Exists and remove#
state.exists("mode");
state.remove("mode");
remove() returns false when the key does not exist.
Clear#
state.clear();
removes all entries.
JSON#
std::string json = state.toJson();
Values are serialized as JSON Strings.
For example:
{
"mode": "cool",
"ready": "1"
}
RuntimeState is not a typed JSON object store. Its stored values are Strings.
SystemState#
The global:
SystemState
is an allocation-free SystemStateStore. Runtime facts use typed flags:
if (!SystemState.get(SystemFlag::OtaRunning))
readSensor();
SystemState.set(SystemFlag::TimeSynced);
SystemState.clear(SystemFlag::TimeSynced);
Pending framework work is kept in a separate typed bank:
SystemState.request(SystemRequest::PublishHardware);
if (SystemState.take(SystemRequest::PublishHardware))
{
if (!publishHardwareJson())
SystemState.request(SystemRequest::PublishHardware);
}
pending() observes a request without clearing it. take() atomically tests
and clears one. Operations are task-safe, not ISR-safe. Disabled modules leave
their flags false. The storage size is derived from the enum Count members;
the API does not expose raw masks.
StateStore#
StateStore derives from RuntimeState.
StateStore store(true);
The constructor parameter selects whether that instance is persistent.
The global:
PersistentSettings
is constructed as persistent.
Persistent file#
The current persistent file is:
/configs.json
This path is an implementation detail, not an application protocol.
Begin#
PersistentSettings.begin();
For a persistent store, begin():
- mounts the ESP-IDF SPIFFS partition, formatting it if the old LittleFS data cannot be mounted,
- updates
SystemFlag::PersistentStorageReady, - loads
/configs.json, - creates/saves an empty settings file if none exists.
Initialization is idempotent.
Invalid settings file#
If the file exists but cannot be parsed as the expected JSON object, begin() clears the in-memory RuntimeState view.
The invalid file is left untouched until settings are later written.
This avoids silently overwriting the only copy merely because loading failed.
Set and automatic save#
For a persistent StateStore:
PersistentSettings.set("name", "value");
performs the RuntimeState update and immediately calls save().
The returned bool reflects both the in-memory operation and the save. If the
save fails, set() restores the previous in-memory entry (or removes a newly
added one), so callers do not observe a successful RAM-only mutation.
For a nonpersistent StateStore, set() only changes RAM.
Get#
PersistentSettings.get("name", "default");
ensures the store has been initialized first.
If initialization fails, the supplied default is returned.
Exists#
PersistentSettings.exists("name");
also initializes first.
Initialization failure makes the result false.
Remove#
PersistentSettings.remove("name");
removes the key and automatically saves when persistent.
Clear#
Normal clear:
PersistentSettings.clear();
clears RAM and saves the empty store.
There is also:
PersistentSettings.clear(false);
which clears the in-memory copy without immediately saving.
This is an implementation-level escape hatch; normal application code should prefer the ordinary persistent semantics.
Explicit save#
PersistentSettings.save();
serializes the current RuntimeState as JSON and writes:
/configs.json
The implementation writes /configs.json.tmp, moves the old document to
/configs.json.bak, then renames the complete temporary file into place.
If startup finds the backup without the live file, it restores the backup.
A failed or partial temporary write leaves the previous durable document in
place.
Because normal persistent set() and remove() already save, explicit save is mainly useful after an intentional in-memory-only mutation path.
Explicit load#
PersistentSettings.load();
replaces the current in-memory entries with the file contents.
Settings loading uses ArduinoJson 7's dynamically sized JsonDocument;
there is no fixed 4096-byte parsing buffer.
The RuntimeState entry limit of 128 still applies while loading, and allocation failure or invalid JSON causes the load to fail.
Framework-private settings#
NightMare currently stores internal values in PersistentSettings.
Examples include:
_device_name
_timezone
_pending_identity_cleanup
_ssid
_password
_config:<Config name>
These names are implementation details.
NightMare source refers to them through NightMare::PersistentKey constants;
the std::string values on disk remain unchanged for existing devices.
Application code should use the owning module APIs:
DeviceIdentity
WiFi helpers
rather than editing private keys directly.
ConfigManager owns _config: keys. It stores canonical NetCodec<T> text,
restores bound Configs during framework startup, creates missing entries from
firmware defaults, and replaces invalid entries with those defaults. Application
code should use Config<T> rather than reading or writing these keys directly.
ResourcesManager keeps Managed Value advertisement policy and remotely
configurable hardware poll overrides in a separate
/resourcesettings.json document keyed by stable local Resource name. That file
does not consume RuntimeState entries and is not part of ConfigManager or
PersistentSettings; application code should use Resource commands rather than
editing it directly. Advertisement is stored as signed advertise_ms. The old
enabled plus seconds-based period representation is migrated on load.
Hardware records persist only poll_ms, never flags, notes, connection state,
or firmware defaults.
Command access#
PersistentSettings is not exposed through a generic command. The CONFIG
command namespace belongs to declared Config<T> values and ConfigManager.
Module-specific settings remain behind their owning APIs and commands. For example, device-name adoption and timezone changes must use the identity APIs or their dedicated commands so their side effects cannot be bypassed.
Current coupling#
The current persistence implementation uses ESP-IDF SPIFFS and std::string key/value data.
A future persistence abstraction may separate generic settings semantics from ESP32 filesystem storage.
Until then, applications should depend on the public store/module APIs rather than the backing-file implementation.