NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Architecture / Hardware configuration v2 model

Hardware configuration v2 model

Hardware configuration v2 is the firmware's current physical-hardware model and the source-of-truth contract for editor implementation. It replaces the former flat topology/positional MessagePack model. The v2 source document is intended for maintenance, validation, tooling, and reconstruction of a deployed physical system.

The four central concepts are:

assemblies   physical composition
connectors   physical boundaries
connections actual wiring
inferred nets connected components of the endpoint graph

Vocabulary#

An assembly is a physically meaningful unit. A PCB is an assembly whose kind is custom_board or market_board; boards are not a separate container type. Enclosures, modules, probes, panels, and external equipment use the same composition model.

A device is a functional physical component contained directly by one assembly. It exposes terminals.

A connector is a physical boundary of an assembly. It exposes one or more contacts. A soldered wire or PCB pad that leaves an assembly is represented by direct_wire or direct_pin, so it remains visible as a maintenance point.

A connection is an undirected physical conductor between exactly two endpoint references. A connection may carry optional wire metadata, but it does not name an electrical net. Its two endpoint references must be different; self-connections are invalid.

An endpoint reference is a structured stable identity:

{
  "assembly": "controller/logic_board",
  "kind": "device_terminal",
  "owner": "mcu",
  "endpoint": "GPIO10"
}

assembly is the slash-delimited path of assembly instance IDs from a deployment root. IDs cannot contain /. owner is a device or connector ID in that exact assembly. endpoint is a terminal or contact ID. Names are presentation metadata and are never used by references.

A hardware definition describes reusable, immutable physical structure. An assembly instance describes a deployed physical unit and may refer to one definition. Definition members and connections are expanded in the instance's namespace. Instances may add members and wiring, but v2 deliberately has no member override or inheritance mechanism. Hardware that differs materially should use a different definition revision.

Document shape#

{
  "version": 2,
  "host_assembly": "controller/esp32",
  "definitions": [],
  "roots": [],
  "connections": []
}

A deployment has one or more roots. Multiple roots represent separate physical units without inventing a common enclosure. Nested assemblies represent real physical containment, not electrical connectivity.

host_assembly is the absolute path of the assembly running this firmware and feeds the board model in /info. Definitions use the same member shapes as instances and may contain nested assembly templates. A nested template can itself reference another definition. Recursive definition references are invalid.

Physical-boundary invariant#

Endpoints in the same exact assembly may connect freely. Endpoints in different assemblies, including a parent and child assembly, may connect only when both are connector contacts.

Therefore this is invalid:

controller/mcu.GPIO10 -> probe/sensor.DATA

and this is valid:

controller/mcu.GPIO10 -> controller/J3.2
controller/J3.2       -> probe/J1.2
probe/J1.2            -> probe/sensor.DATA

This rule applies to deployment wiring and reusable-definition wiring. There is no exception for directly soldered wires; those exits are connectors.

Inferred nets and canonical identities#

Each terminal/contact is a graph node and each connection is an undirected edge. Every connected component is an inferred electrical net. Normal nets are never declared or manually maintained.

An endpoint may declare one canonical identity:

GND VCC +3V3 +5V AC_PHASE AC_NEUTRAL PE

The identity propagates across its inferred net. Two different canonical identities in one component are conservatively diagnosed as a conflict. A defined conversion or isolation device must be represented by distinct terminals; device behavior does not implicitly connect terminals.

Canonical identities are exact electrical identities, not classifications or wildcards. In particular, VCC means a rail literally identified as VCC and is distinct from both +3V3 and +5V. When the positive rail is not known, omit canonical_net; do not use VCC as “some positive supply.”

Validation contract#

validateHwConfig() returns a fixed-capacity ValidationResult containing structured diagnostics with code, path, and message. It checks IDs and uniqueness, definition references and cycles, endpoint existence, connector contacts, and the physical boundary rule. It also builds the endpoint graph and reports canonical-net contradictions when structural checks permit it.

Invalid connections, including cross-assembly device-terminal connections and self-connections, are diagnosed and are never inserted into a graph returned by buildTopologyGraph().

Incomplete knowledge is valid: an assembly or definition may omit internal details. References that are present must still resolve exactly.

Deliberate v2 boundaries#

Version 2 does not define overrides, definition inheritance, implicit pin aliases, connector geometry, cable/harness manufacturing data, PCB routing, simulation, or general electrical-rule checking. Physical location and serial metadata are optional instance metadata. A future first-class harness can be added as an assembly kind without changing the boundary rule.

The firmware reference implementation lives in src/NightMare/HardwareProfile.h and .cpp. The public operations are:

ValidationResult validateHwConfig(const Profile &config);
bool buildTopologyGraph(const Profile &config, TopologyGraph &graph,
                        ValidationResult *diagnostics = nullptr);
bool inferNets(const TopologyGraph &graph, InferredNets &nets);

NightMare/HardwareDefinitions.h supplies reusable definitions for the ESP32-C3 SuperMini rev1, MycroftY controller rev1, a DS18B20 waterproof probe, and a generic one-channel relay module. standardDefinitions(count) returns the complete catalog; the MycroftY definition composes the ESP32 definition.

Firmware publishes the source configuration canonically as retained MessagePack at <device>/hardware/msgpack. The readable <device>/hardware/json sibling is published only when NM_ENABLE_JSON_WIRE=1; HW JSON can generate it on demand regardless. Inferred nets are generated views and are never serialized.

The logical schema remains HwConfigVersion = 2; the positional wire contract starts at HardwareEncodingVersion = 1:

hardware   = [encodingVersion, hwConfigVersion, hostAssembly,
              definitions[], roots[], connections[]]
definition = [id, kind, name|null, model|null, manufacturer|null, members]
assembly   = [id, definition|null, name|null, kind, model|null,
              manufacturer|null, serialNumber|null, location|null, members]
members    = [assemblies[], devices[], connectors[], connections[]]
device     = [id, name|null, kind|null, model|null, manufacturer|null, terminals[]]
terminal   = [id, canonicalNet, name|null]
connector  = [id, name|null, kind, model|null, manufacturer|null, contacts[]]
contact    = [id, canonicalNet, name|null]
endpoint   = [assembly, kind, owner, endpoint]
connection = [a, b, wire|null]
wire       = [color|null, gauge|null, label|null, lengthMm]

Encoding version is always position 0. Positions and enum numbers are append-only; optional additions go at the end. Reordering, removing, or repurposing a position requires a new HardwareEncodingVersion.

Serialized member shapes#

The string values are fixed as follows:

assembly kind
    custom_board, market_board, module, sensor_probe, panel,
    enclosure, external, generic

connector kind
    header, screw_terminal, jst, usb, terminal,
    direct_pin, direct_wire, generic

endpoint kind
    device_terminal, connector_contact

Definitions and assemblies contain assemblies, devices, connectors, and connections arrays. The firmware always emits these arrays, including when empty. A deployed assembly can name a reusable definition and add inline members, but an inline member cannot replace a definition member with the same ID.

Device terminals and connector contacts have an id, optional name, and optional canonical_net. Endpoint references use the exact shape shown above. Definition/assembly-local connection paths are relative to their containing assembly; an empty path means that assembly. Top-level connection paths are absolute from a root.

Connection wire metadata uses optional color, gauge, label, and length_mm fields. Zero length is omitted.

A minimal reusable definition and deployment instance serialize as:

{
  "version": 2,
  "host_assembly": "controller",
  "definitions": [{
    "id": "controller-v1",
    "kind": "custom_board",
    "model": "My controller",
    "assemblies": [],
    "devices": [{
      "id": "mcu",
      "kind": "mcu",
      "terminals": [
        {"id": "GPIO10"},
        {"id": "GND", "canonical_net": "GND"}
      ]
    }],
    "connectors": [{
      "id": "j1",
      "kind": "header",
      "contacts": [{"id": "1"}, {"id": "2", "canonical_net": "GND"}]
    }],
    "connections": [{
      "a": {"assembly": "", "kind": "device_terminal", "owner": "mcu", "endpoint": "GPIO10"},
      "b": {"assembly": "", "kind": "connector_contact", "owner": "j1", "endpoint": "1"}
    }]
  }],
  "roots": [{
    "id": "controller",
    "definition": "controller-v1",
    "assemblies": [],
    "devices": [],
    "connectors": [],
    "connections": []
  }],
  "connections": []
}

Optional metadata fields are omitted rather than serialized as null.

The firmware uses bounded graph/diagnostic storage (MaxGraphAssemblies, MaxGraphEndpoints, MaxGraphEdges, and MaxDiagnostics). Each effective assembly has one graph index and one stored diagnostic/lookup path; GraphNode::assembly is that index, so endpoint nodes do not allocate duplicate path Strings. Capacity exhaustion is a validation error, never silent truncation. TopologyGraph and InferredNets are caller- owned workspaces; firmware code should give long-lived analyses static storage instead of placing both large fixed arrays on a small task stack.

Last updated · Edit this page on GitHub