NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

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():

  1. mounts the ESP-IDF SPIFFS partition, formatting it if the old LittleFS data cannot be mounted,
  2. updates SystemFlag::PersistentStorageReady,
  3. loads /configs.json,
  4. 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.

Last updated · Edit this page on GitHub