NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

ESP32 · MQTT · ESP-NOW · v1.0.0-alpha.1

Declare it once. Your device joins the network.

Every networked ESP32 project rebuilds the same plumbing: an identity, MQTT topics, retained state, reconnects, remote commands, schedules. NightMare does that part. You declare what the device offers; your firmware keeps the hardware.

Register once, participate automatically.

lib_deps =
    https://github.com/vtmattedi/NightMareNetwork.git#v1.0.0-alpha.1

One device, start to finish

You write the code. The network sees the topics.

Three declarations and two handlers. No topic strings, no subscribe calls, no reconnect logic. After ADOPT desk-lamp on its console, this is what any other device, dashboard or script finds on the broker.

src/main.cpp
#include <Arduino.h>
#include <NightMare.h>

ManagedSensor<uint32_t> uptime("uptime_s");
ManagedState<uint8_t>   brightness("brightness");
ManagedAction           identify("identify");

bool onBrightness(ManagedState<uint8_t> &, const uint8_t &level) {
    return level <= 100;          // false rejects the write
}

ActionResult onIdentify(ManagedAction &, const std::string &) {
    blinkLed();                   // your hardware, your code
    return {true, "OK"};
}

void publishUptime() { uptime.setValue(millis() / 1000); }

void setup() {
    brightness.onWrite = onBrightness;
    identify.onInvoke  = onIdentify;
    gScheduler.everyMonotonic("app.uptime", publishUptime, 1000);
    startNightMareESP();
}

void loop() { tickNightMareESP(); }
MQTT
  • desk-lamp/status{"name":"desk-lamp","online":true,…}retained
  • desk-lamp/manifest/msgpackuptime_s · brightness · identifyretained
  • desk-lamp/resource/uptime_s/state3612retained
  • desk-lamp/resource/brightness/state40retained
  • → desk-lamp/resource/brightness/set80onWrite → accepted
  • → desk-lamp/resource/identify/invokeonInvoke → blink

A write of 180 is rejected by onBrightness, so the retained state stays at the last accepted value. The device reboots, the broker drops, the Wi-Fi comes back: the manifests and state are re-announced without a line of your code.

Who owns what

NightMare takes the plumbing. The device stays yours.

NightMare handles

  • Device identity, naming and renaming, with cleanup of the old name's retained data
  • Topics, retained manifests and state, subscriptions, re-announcing after reconnect
  • Routing writes, Action calls and commands to your handlers
  • Local or remote MQTT, ESP-NOW through a gateway, and failover between them
  • Scheduling, persisted settings, telemetry and time sync

Your firmware decides

  • The hardware: pins, drivers, sensors, timing
  • What each Value means and when it changes
  • Whether a write is accepted, and what an Action does
  • Which devices it listens to, and what it does with what it hears
  • Everything the device is actually for
The full split

Share state with every device

A Value's latest reading is retained, so a device that boots later sees it immediately. Another device consumes it by name with a Remote Resource and can switch the source at runtime.

Call other devices and react to them

Actions are typed remote calls with a result; Events are things that happened. Both are routed for you, in both directions.

One command language everywhere

The same commands work over serial, the MQTT console, correlated MQTTP requests and scheduled jobs. Rename a device, change a setting or inspect it from any of them.

Schedules that survive reboots

Wall-clock or monotonic, one-shot or recurring, callbacks or commands; command jobs can be persisted and edited remotely.

Built with NightMare

Real devices, each its own project

NightMare grew out of these projects: the same helpers kept reappearing in each one until they became a framework. How it grew

  • Adler-IR

    Infrared air-conditioner controller for ESP32, C3 and C6 boards.

    Exposes ir:send and ir:recv, a temperature sensor and an RGB state. It consumes the AC's fan, compressor and beep as Remote Resources bound at runtime, which is how it hears from Watson.

  • Watson

    Acoustic observer: an ESP32 with an INMP441 microphone listening to the air conditioner.

    Publishes fan and compressor noise as retained Sensors and each accepted beep as an Event. It decides nothing; the conclusion is left to the controller that binds to it.

  • NightMare Dashboard

    Touchscreen wall panel on a Sunton ESP32-3248S035C.

    Owns none of what it controls: it drives the AC, a light and an RGB light that live on other devices through Remote Resources, over ESP-NOW via the Gateway.

  • Mycroft

    Door, light and temperature node for ESP32 and ESP32-C3.

    A door contact and a temperature as Managed Sensors; the light and an I/O-expander output as writable State.

  • Sherlock

    Room sensor and light on ESP32.

    Temperature, humidity and board voltage as Managed Sensors; LED power and colour as writable State.

  • NightMare Gateway

    ESP32-S3 bridge between ESP-NOW devices and MQTT.

    Pairs ESP-NOW's speed, under 10 ms per hop*, with MQTT's reach. Itself a NightMare device, with an identity, Configs, Resources and a console, so it is managed like everything it carries.

    * Device to gateway over ESP-NOW; 5–8 ms in our testing. Radio conditions vary.

  • MwNightmareSystem

    Home dashboard and history service.

    A backend that reads manifests, sends writes and Actions, and stores sensor history: a consumer of the protocol, not a part of it.

Your AI assistant can read the exact source

A public, read-only MCP endpoint lets Claude or any MCP client search these docs, look up the exact API, read the active C++ source and examples, and say which revision it answered from. Ask it to write a device; it checks the real headers instead of guessing.

claude mcp add --transport http nightmare https://nightmare.mattediworks.com/mcp
Connect the MCP

Where it is

v1.0.0-alpha.1

The Resource model, the topic layout and the command grammar are the 1.0 contract. Alpha means the release process is new: pin the tag above, and read the known gaps for what is deliberately not done yet.

It is built and used continuously in the devices above, so it changes often. Every page here says when it last changed.