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.1One 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.
#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(); }desk-lamp/status{"name":"desk-lamp","online":true,…}retaineddesk-lamp/manifest/msgpackuptime_s · brightness · identifyretaineddesk-lamp/resource/uptime_s/state3612retaineddesk-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.
Getting started · Every topic · Resource protocol · examples/basic
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
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/mcpConnect the MCPWhere 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.
Recent changes
- fix(gateway): size the ESP-NOW RX and MQTT outbound queues for reconnect bursts
- feat(esp32): NM_ESPNOW_AUTO lets the application start ESP-NOW itself
- fix: gateway reasserts its retained status and network topics
- fix: deliver other devices' manifests, states and events to OnMessage
- fix: include <cstring> for std::strlen in the STATUS table