NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Modules / Device identity

Device identity

DeviceIdentity owns the address NightMare uses for this device on MQTT and its persisted local-time timezone.

The public singleton is:

gDeviceIdentity

Identity separates the logical network name, physical board identifiers, and local-time presentation because those values answer different questions.

Device name#

const std::string &getDeviceName();

The device name is the current logical/network identity.

Example:

bedroom-ac

It is used as the root of device-scoped MQTT topics:

bedroom-ac/status
bedroom-ac/manifest
bedroom-ac/info

The name is adoptable.

Hardware signature#

const std::string &getHardwareSignature();

The hardware signature is the generated name the board was born with.

Example:

Esp32-nm-6ca172e0

It is based on the board's hardware ID and is the same value used as the default logical device name before adoption.

It does not change when the logical device name changes.

This is why status can identify both:

{
  "name": "bedroom-ac",
  "hardware": "Esp32-nm-6ca172e0",
  "timezone": "<-03>3",
  "online": true
}

Device ID#

const std::string &getDeviceId();

The device ID is a raw machine-oriented hardware identifier derived from ESP.getEfuseMac().

It is formatted as 16 hexadecimal characters representing the 64-bit value.

Use it where a low-level stable identifier is required.

Do not treat it as the human-facing MQTT name.

Timezone#

const std::string &getTimezone();
bool setTimezone(const std::string &timezone);
static bool validTimezone(const std::string &timezone);

The timezone is a persisted POSIX TZ string. It is applied to the process with setenv("TZ", ...) and tzset(), so local formatting and local wall-clock calculations change immediately.

Examples:

UTC0
<-03>3
EST5EDT,M3.2.0,M11.1.0

validTimezone() accepts a non-empty printable string up to 128 characters. It checks the storage/wire boundary, not the semantic meaning of every POSIX timezone rule.

Unix epoch values remain UTC-based.

Initialization#

gDeviceIdentity.begin();

Initialization:

  1. reads the ESP hardware ID,
  2. derives the hardware signature/default name,
  3. initializes persistent settings when available,
  4. loads the persisted logical name,
  5. validates it,
  6. falls back to the generated default when invalid,
  7. loads and applies the persisted timezone, falling back to NM_TIMEZONE,
  8. loads any pending identity-cleanup record.

The getters call begin() internally, so explicit initialization is normally handled by the framework lifecycle.

Default name#

The default name is generated as:

Esp32-nm-<low-32-bits-of-MAC-in-hex>

The exact example depends on the board.

This default is also the hardware signature.

Valid device names#

Use:

DeviceIdentity::validDeviceName(name);

A valid device name:

  • contains 1 to 64 characters,
  • is not exactly all,
  • contains no /,
  • contains no +,
  • contains no #,
  • contains no control character below 0x20.

The reserved value:

all

is used by the broadcast command topic:

all/console/in

Topic helpers#

Build a device-relative topic with:

gDeviceIdentity.topic("status");

For device name bedroom-ac:

bedroom-ac/status

A leading slash is also accepted:

gDeviceIdentity.topic("/status");

and produces the same logical shape.

Testing whether a topic belongs to this device#

gDeviceIdentity.isDevice(fullTopic);

returns true for the exact device name or a child topic under it.

Example for bedroom-ac:

bedroom-ac
bedroom-ac/status
bedroom-ac/resource/power/state

Relative topic#

std::string relative;

if (gDeviceIdentity.relativeTopic(fullTopic, relative))
{
    // relative has the device prefix removed
}

Example:

full:
bedroom-ac/custom/state

relative:
custom/state

The exact bare device root does not produce a relative child path.

Address locking#

gDeviceIdentity.lockAddress();

marks the current logical address as already in active use for this boot.

NightMare calls this when network identity begins to matter, including Managed Resource binding and WiFi/MQTT initialization.

Address locking prevents adoption from trying to migrate a live topic namespace in place.

Adoption#

Request a new logical name with:

gDeviceIdentity.beginAdoption("bedroom-ac");

Adoption is treated as a migration, not as an ordinary std::string assignment.

The operation records:

new logical name
old logical name
which old retained artifacts still need cleanup

Only one migration can be pending at a time.

A second adoption is refused until cleanup of the previous identity has completed.

Adoption before address lock#

If the address has not yet been locked, a successful adoption can change the in-memory device name immediately:

old -> new

The old identity is still recorded for cleanup.

Adoption after address lock#

If the address is already locked, NightMare does not attempt a live migration.

Instead:

persist new name
remember old identity
continue current boot under old name
reboot
start next boot under new name
clean old retained network state

This avoids trying to atomically migrate:

  • MQTT Last Will,
  • subscriptions,
  • queued traffic,
  • Resource state,
  • manifest,
  • status,
  • application assumptions.

Persistence keys#

The current implementation stores framework identity state in PersistentSettings under private keys including:

_device_name
_timezone
_pending_identity_cleanup

These are implementation details.

Applications should use the DeviceIdentity API rather than editing these keys directly.

Identity commands#

Adopt a logical name with either command spelling:

ADOPT bedroom-ac
CHANGE NAME bedroom-ac

Both use beginAdoption() and therefore preserve the normal migration and cleanup rules. The JSON response contains name, active_name, and reboot_required.

Query or change timezone with:

TIMEZONE
TIMEZONE SET "EST5EDT,M3.2.0,M11.1.0"
CHANGE TIMEZONE "EST5EDT,M3.2.0,M11.1.0"

Timezone changes are persisted and applied immediately. When MQTT is connected, NightMare refreshes retained /status and /info identity data.

Pending cleanup#

Public cleanup state is represented by:

struct PendingIdentityCleanup
{
    std::string oldName;
    uint8_t pendingFlags;
};

Current cleanup participants are:

CLEANUP_RESOURCES
CLEANUP_STATUS

The pending record is persistent when settings are enabled.

Cleanup lifecycle#

The network-side coordinator is:

processPendingIdentityCleanup();

It asks DeviceIdentity which parts still need cleanup and performs them through the appropriate network owners.

DeviceIdentity stores state.

It does not publish MQTT itself.

Resource cleanup#

Resource cleanup removes retained state under the old identity for:

  • every currently declared Managed Value,
  • the old Resource provider and consume manifests.

Actions need no retained cleanup because /invoke is transient.

A Managed Value removed from the firmware before cleanup cannot be discovered from the current registry and therefore cannot be automatically tombstoned.

Status cleanup#

Old status cleanup intentionally does two publications.

First:

{
  "name": "<old-name>",
  "hardware": "<same-physical-board>",
  "timezone": "<current-posix-timezone>",
  "online": false
}

is published retained.

Then an empty retained payload tombstones:

<old-name>/status

This lets active observers see a normal offline transition before the retained ghost is removed.

Retry behavior#

startNightMareESP() checks for pending cleanup.

When Scheduler + MQTT are enabled, it installs a MANAGED recurring callback job:

_nm_identity_cleanup

at:

NM_IDENTITY_CLEANUP_RETRY_MS

default:

60000 ms

The job stays installed while cleanup is pending.

It removes itself when cleanup completes or there is nothing left to do.

Because it is MANAGED, JOB CLEAR cannot remove it.

Cleanup waits for the new identity to be active#

Immediately after a locked adoption, the current boot still runs under the old name.

At that point the old retained state is still live and must not be deleted.

getPendingIdentityCleanup() therefore reports no actionable cleanup while:

pendingOldName == current deviceName

Cleanup becomes actionable after reboot when the current name is the new identity.

Transactional cleanup bits#

Each cleanup participant clears its own bit only after its operation succeeds.

If persisting the updated cleanup record fails, the in-memory state is rolled back so the next attempt still knows that cleanup is pending.

The migration is considered complete only when all pending bits are cleared.

Last updated · Edit this page on GitHub