All work

Product

NightMare Network

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 Network does that part. You declare what the device offers, Values, Actions and Events, and your firmware keeps the hardware: pins, drivers, timing and what each value means.

Open-source framework · alpha

WebsiteGitHubNightMare System

The devices running it

  • Adler

    Infrared controller for an old air conditioner. Each command counts only when the unit is heard beeping back.

  • Watson

    Acoustic observer with a microphone: publishes the fan, the compressor and each beep. It decides nothing.

  • NightMare Dashboard

    Touchscreen wall panel that owns no hardware: it drives the AC and lights on other devices, over ESP-NOW.

  • NightMare Gateway

    ESP32-S3 bridge between ESP-NOW and MQTT, itself a NightMare device, managed like everything it carries.

  • Mycroft

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

  • Sherlock

    Room sensor and light: temperature, humidity, board voltage, LED power and colour.

  • NightMare System

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

From repeated helpers to a framework

It started as helpers I kept copying between my own firmware projects. As those devices needed to talk to their microcontrollers the same way, the helpers became a shared command resolver and MQTT addressing conventions.

Then came a request/response pattern over MQTT, so a command from an operator, another device or a service follows one grammar. The current model makes capabilities explicit: typed Values, Actions and Events, described in manifests. The library now builds with Arduino or ESP-IDF.

What a device gets from the framework

  • Declare it once

    No topic strings, no subscribe calls, no reconnect logic. Topics, retained state and subscriptions are handled, and re-announced after every reconnect.

  • State every device can see

    The latest value is retained, so a device that boots later sees it at once. Others consume it by name and can switch its source at runtime.

  • Devices that call each other

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

  • One command language

    The same commands work over serial, the MQTT console, correlated request/response over MQTT and scheduled jobs.

  • MQTT or ESP-NOW, with failover

    Local or remote MQTT, or ESP-NOW through a gateway at 5 to 8 ms per hop in testing. It falls back and recovers on its own.

  • Docs your AI can read

    A public, read-only MCP endpoint lets an AI assistant search the docs, look up the exact API and read the active source before writing a device.

Framework at a glance

Team
Solo, design to deploy
Period
2023-10 – now
Status
v1.0.0-alpha.1, MIT
Stack
C++ on ESP32, Arduino or ESP-IDF, MQTT, ESP-NOW

State, contracts and reconnection

  • Register once, participate automatically

    A Resource should not need custom MQTT code in every application. Once declared, the framework publishes its description, keeps its state, routes writes and calls, and restores everything after a reconnect. The cost: the topic layout is the framework's, and it is the 1.0 contract.

  • Retained MQTT state, not a sync protocol

    Current state lives in retained topics wherever MQTT already gives the right semantics. A manifest describes; the state topic tells the truth, so a missing or late manifest never invalidates a value.

  • A healthy fallback stays put

    ESP-NOW is preferred, but a working MQTT link is kept until ESP-NOW is eligible: a retained gateway announcement plus a secure session whose identity matches it. Probing or a failed handshake never interrupts a healthy connection.

  • The owner is the truth

    A read-only remote sensor shows exactly what its owner published. A writable remote state shows the written value right away, optimistically, and then yields to the owner's confirmed state.

From firmware to MQTT

Devices running NightMare Network reach an MQTT broker either over Wi-Fi or over ESP-NOW through the gateway, which is itself a NightMare device. The TLS-only broker runs on Stackport. NightMare System, the home dashboard and history service, reads and writes through the same broker.Runs NightMare NetworkESP-NOWMQTTMQTTreads · writesDeviceESP-NOWDeviceWi-FiGatewayESP32-S3 · HolmesMQTT brokerTLS · StackportNightMare Systemdashboard · history
  • A C++ library every device links: identity, Resources, commands, scheduler, settings, telemetry and time sync.
  • Devices reach MQTT over Wi-Fi, or over ESP-NOW through the gateway, which is itself a NightMare device.
  • Production runs on a TLS-only Mosquitto broker hosted on Stackport.
  • Framework documents are MessagePack-first; one status shape covers online, offline and Last Will.

Alpha scope and known gaps

  • Alpha: the 1.0 contract is set, the release process is new. Pin the tag.
  • ESP32 is the only supported platform.
  • ESP-NOW sessions use a pre-shared key, with known limits documented.
  • Only wall-clock command jobs survive a reboot; callback and monotonic jobs do not.
  • The full list is on the site, under known gaps.