NightMare Networkv1.0.0-alpha.1

Search every page of the documentation. Or start with:

Docs / Modules / Resources

Resources

Resources are NightMare's application-facing network abstraction.

A Resource says:

what capability exists
who owns it
whether it is state, an operation, or an occurrence
how another device may interact with it

The Resource layer deliberately separates application types from MQTT connection.

application                     connection
    T
    │
NetValue<T>
    │  NetCodec<T>
    ▼
encoded std::string  ───────────────> MQTT

ResourcesManager never needs to know the application's T.

Class model#

NetResource
├── NetValueResource
│   └── NetValue<T>
│       ├── ManagedSensor<T>
│       ├── RemoteSensor<T>
│       ├── ManagedState<T>
│       └── RemoteState<T>
├── NetActionResource
│   ├── ManagedAction
│   └── RemoteAction
└── NetEventResource
    └── NetEvent<T>
        ├── ManagedEvent<T>
        └── RemoteEvent<T>

The normal application API is the eight leaf types.

The three kinds say different things:

Value  = something is           (Sensor, State)
Action = please do something    (Action)
Event  = something happened     (Event)

An Event is its own kind, not a Value with a flag. NetEventResource does not derive from NetValueResource, so an Event carries no current value, availability, freshness, advertisement or hardware state.

NetValue<T> remains public for cases that do not fit the standard wrappers, but most projects should prefer the semantic wrappers because they make ownership, access, and synchronization intent obvious.

Managed vs Remote#

A Resource's role is fixed when it is constructed.

Managed
    this device implements the Resource

Remote
    another device implements the Resource

The role does not change.

A Remote Resource can be retargeted to another source, but it remains Remote.

Automatic binding#

Resources are owned by the application, not by ResourcesManager.

A Resource must therefore outlive its binding. Each Resource enlists itself when constructed; startNightMareESP() binds all enlisted Resources in declaration order before networking starts.

ManagedSensor<float> temperature("temperature");

void setup()
{
    startNightMareESP();
}

The manager stores a non-owning pointer. Explicit bindResource() remains available for Resources created after startup or for deliberate manual binding.

A project can later remove the binding:

gResourcesManager.unbindResource(&temperature);

Module ownership practice#

If a module primarily implements a Sensor, State, Action, Event, or Config, that module should normally own its declaration, stable name, handlers, and exposure. For example, TemperatureSensor.cpp/.h should normally own the hardware driver and its ManagedSensor<float> rather than making main.cpp a registry of every application capability. Cross-module orchestration still belongs above the individual modules.

When related Resources naturally belong to one subsystem, prefer names such as <group>:<value> or <group>:<subgroup>:<value>:

led_strip:state
led_strip:brightness
led_strip:colour
climate:bedroom:target_temperature

This convention is not enforced. : remains an ordinary valid name character and has no runtime or protocol meaning. The convention only gives backend and tooling a stable hint for future grouping and relationship inference; flat Resource names remain valid.

Why declare before startNightMareESP()#

The normal order is:

construct Resources
register handlers
startNightMareESP()

This has two benefits.

First, startup binds the declared Resources before MQTT starts, so normal manifest/state announcement can happen immediately.

Second, if an adopted identity still has retained state to clean up, the cleanup pass can only discover Managed Resources declared by the current firmware.

ManagedSensor#

A ManagedSensor<T> is:

local owner
READ
STRICT

Use it for state produced by this device that other devices may observe but not write.

ManagedSensor<float> roomTemperature("temperature");

void updateTemperature(float value)
{
    roomTemperature.setValue(value);
}

setValue() updates authoritative local truth.

If the Resource is bound and MQTT connection is available, NightMare publishes the state retained at:

<device>/resource/temperature/state

If connection is unavailable, the local value still changes. Reconnect re-announcement publishes the authoritative state later.

Managed advertisement policy#

Managed Values publish changes immediately when available and their signed advertisement interval is non-negative. A positive interval also reaffirms an unchanged retained value; 0 is event-driven only and a negative value suppresses publication. The default is 300000 ms.

The advertisement policy is persistent under the stable local Resource name in /resourcesettings.json. It is owned by ResourcesManager, not ConfigManager, and is restored before networking starts. Advertisement is a manager/protocol concern and is intentionally absent from the Resource object's public API. Use the Resource command ADVERTISE <signed-ms> to inspect or change it.

The period is the maximum intended advertisement interval under normal framework servicing, not a hard real-time guarantee. A successful change or refresh publication resets its timer. Policy changes persist before their runtime commit; failed manifest publication is marked dirty and retried with rate limiting by ResourcesManager::tick().

Setting a negative interval withdraws retained /state and suppresses future state publications. Returning to a non-negative interval immediately publishes the current authoritative value when available. Neither setting controls hardware polling, power, acquisition, computation, or a local control loop.

Availability is runtime state. setAvailable(false) keeps the Resource bound and in the manifest, withdraws retained state, and still permits local setValue() calls to update last-known data. Returning to available publishes the current value immediately when advertisement is non-negative.

Optional hardware policy#

A Managed Value can describe application-owned hardware without asking NightMare to poll it:

temperature.setHardwarePolicy({
    .pollMs = 1000,
    .flags = REPORT_HW_CONNECTION | CONFIGURABLE_POLL | CAN_DISABLE,
    .note = "Address: 0x48"
});

The application performs acquisition and consults hardwarePollMs() and hardwareEnabled(). It may report runtime connectivity with setHardwareConnected() when REPORT_HW_CONNECTION was declared. Notes are informational and limited to 64 encoded UTF-8 bytes. Reported connection state defaults to true until the application reports otherwise. ResourcesManager may persist only a remotely configured poll_ms override; flags, notes, connection state, and firmware defaults are never persisted.

RemoteSensor#

A RemoteSensor<T> observes a read-only Value owned by another device.

RemoteSensor<float> outdoorTemperature("outdoor_temperature");

RemoteSensor uses:

role:        REMOTE
access:      READ
sync:        STRICT

getValue() therefore reflects the owner's authoritative state directly.

Receiving updates#

Install onUpdate when application code needs to react to an effective Value change:

void temperatureChanged(NetValue<float> &resource, const float &value)
{
    Serial.println(value);
}

RemoteSensor<float> outdoorTemperature("outdoor_temperature");

void setup()
{
    outdoorTemperature.onUpdate = temperatureChanged;
    outdoorTemperature.setSource("weather-node", "temperature");
    startNightMareESP();
}

onUpdate is not a packet-received callback.

It fires only when the effective value returned by getValue() changes.

Repeated owner packets with the same Value do not fire it.

ManagedState#

A ManagedState<T> is a writable Value owned by this device.

ManagedState<bool> power("power");

It publishes retained state exactly like a ManagedSensor, but also subscribes to:

<device>/resource/power/set

Remote requests are decoded before application code sees them.

The application decides whether to accept the request:

bool onPowerWrite(ManagedState<bool> &state, const bool &requested)
{
    if (!setHardwarePower(requested))
        return false;

    return true;
}

ManagedState<bool> power("power");

void setup()
{
    power.onWrite = onPowerWrite;
    startNightMareESP();
}

Returning true means the requested Value becomes authoritative state.

Returning false leaves state unchanged.

The application handler should therefore return true only when the request is accepted as the new device truth.

Local writes to ManagedState#

The owner can also change the state directly:

power.setValue(true);

This does not call onWrite.

onWrite is the ingress policy for remote /set requests. setValue() expresses local owner intent directly.

RemoteState#

A RemoteState<T> represents a writable Value implemented by another device.

RemoteState<bool> bedroomPower("bedroom_power");

Calling:

bedroomPower.setValue(true);

publishes:

bedroom-ac/resource/power/set

The call returns true only if the request was accepted for connection.

It does not mean the remote device accepted the requested state.

Optimistic RemoteState behavior#

RemoteState uses OPTIMISTIC synchronization by default.

After a successful local write:

bedroomPower.setValue(true);

the locally visible getValue() becomes true immediately for the optimistic window.

The owner's last reported state remains available separately:

bedroomPower.authoritativeValue();

The default optimistic window is:

5000 ms

and can be changed per Resource:

bedroomPower.optimisticWindowMs = 2000;

Owner state remains authoritative.

The optimistic window only prevents a delayed old owner packet from making the application briefly flicker back immediately after a local request.

Effective vs authoritative Value#

For any NetValue<T>:

resource.getValue();

returns the effective application-facing Value.

resource.authoritativeValue();

returns the owner's last reported Value.

For Managed Values and STRICT Remote Values those are normally the same.

For an optimistic RemoteState they can temporarily differ.

Freshness#

Remote Value freshness is:

ResourceFreshness::UNKNOWN
ResourceFreshness::FRESH
ResourceFreshness::STALE

Useful helpers/state include:

resource.available()
resource.freshness()
resource.isStale()
resource.lastUpdateMs()

State begins UNKNOWN.

A valid owner /state update makes it FRESH.

An empty owner /state tombstone makes the Resource unavailable without using STALE as a synonym for withdrawal.

While available, a Remote Value becomes STALE after approximately twice a positive advertisement interval learned from the owner's compact manifest. Interval 0 is event-driven only and disables time-based aging. A negative interval says only that the owner does not advertise this Value; it does not change Resource or hardware availability. A new valid owner state restores availability and FRESH. The last decoded Value remains readable as last-known data while unavailable or stale.

Retargeting the Resource clears state learned from the old source completely.

Remote Resource identity and source#

RemoteSensor, RemoteState, RemoteAction, and RemoteEvent have a stable local name and a separately configurable remote source.

Example:

RemoteSensor<float> selectedTemperature("selected_temperature");

void setup()
{
    startNightMareESP();
}

Later:

selectedTemperature.setSource("weather-node", "temperature");

A source-less Remote Resource is registered but has no network address or ingress subscription. The local name never changes when the source changes.

This is useful when the source comes from configuration or later discovery.

Retargeting#

Remote wrappers (RemoteSensor, RemoteState, RemoteAction, RemoteEvent) expose:

setSource(deviceName, resourceName);
clearSource();

Retargeting:

  • unsubscribes the previous source,
  • clears Value state learned from the old source (a RemoteEvent resets lastUpdateMs()),
  • updates manifest subscriptions,
  • subscribes to the new source if valid,
  • saves the binding in /remoteresources.json,
  • republishes the retained consume manifest.

The Resource remains Remote.

If the requested source is invalid, points at the current device, or duplicates another locally bound Resource address, the manager refuses it and keeps the previous source.

At startNightMareESP(), persisted bindings are restored after application Resources have been automatically bound and before networking starts. Unknown local names and malformed source entries are removed from the file. An offline remote device is not a reason to remove a binding.

Bindings are stored by stable local name:

{
  "outdoor_temperature": "weather-node/temperature",
  "bedroom_power": "bedroom-ac/power"
}

Declaring dependencies#

A Managed Value can declare that it is another Value:

ManagedSensor<bool> door("door");
ManagedSensor<bool> acDoor("ac_door");

acDoor.dependsOn(door);

This means ac_door and door are the same logical value, and door is authoritative. When door changes, ResourcesManager copies the value into ac_door and publishes ac_door's state. There is no project synchronization code:

// Not needed, and not the intent:
door.onUpdate = [](auto &, bool value) { acDoor.setValue(value); };

The relationship is declared once and the framework maintains it.

What propagation does#

An authoritative update to the source is mirrored into every Managed Value that declared it:

source receives an authoritative update
    -> publish the source as usual
    -> copy its encoded value into each dependent
    -> mark each dependent authoritative and fresh
    -> publish each dependent's state

The sources of an authoritative update are a local setValue(), an accepted /set from another device, and /state arriving for a Remote Value.

Mirroring uses the internal owner path, not the write path. A dependent is a ManagedSensor<T>, which has no onWrite to begin with, and the distinction is the reason: a mirrored update is the source changing underneath the dependent, never a request to change it. onWrite means "someone is asking to change this", which is a different event and the one write-through will have to carry when ManagedState<T> is allowed to depend on something.

onUpdate does fire on a dependent whose effective value changed.

When the source loses its value#

Mirroring runs both ways. If the source stops having a value, the dependent stops claiming one:

source withdrawn
    -> dependent becomes unavailable
    -> dependent's retained /state is tombstoned

The last decoded value stays readable through getValue(). What is withdrawn is the assertion that it is current, which also means a reconnect will not re-announce it.

This happens when the source's retained state is tombstoned, when a Remote source is retargeted or cleared with setSource()/clearSource(), and when the source is unbound.

It matters because the dependent's /state is retained. Without withdrawal, a consumer reading ac_door/state directly would see a stale value that looks entirely valid.

Rules#

dependsOn() exists on ManagedSensor<T> only. It is absent from RemoteSensor, RemoteState, ManagedAction and RemoteAction: a Remote Value already mirrors its source, and an Action has no value to mirror.

ManagedState<T> is excluded on purpose. A mirror is read-only by construction, but a ManagedState accepts /set, so a write to a dependent would have to be forwarded to whoever is authoritative and come back as an ordinary mirrored update:

SET dependent
    -> forward the request to the authoritative source
    -> source changes
    -> the normal mirror comes back

Write-through is not designed yet, so until it is, nothing writable can declare a dependency and then advertise a value it has no way to change.

A Value has at most one dependency, and the last call wins:

a.dependsOn(b);
a.dependsOn(c);

// final relationship:
a -> c

A declaration is rejected, with a warning, when the Value depends on itself or the two wire types differ. Wire types are compared, not C++ types, so int8_t and uint32_t are both integer and a mismatch between them is not caught.

Propagation is one level. A dependent is not treated as a source in turn, so a chain a -> b -> c stops at b. Chain resolution is a future protocol feature.

Semantic identity is your claim#

dependsOn() asserts semantic identity, not merely causal dependency. You are responsible for declaring it only between Resources that represent the same logical value. NightMare and backend tooling may detect structural and type inconsistencies but cannot guarantee semantic equivalence.

roomOccupied.dependsOn(doorOpen);   // compiles, propagates, and is nonsense

Both are bool, so nothing in the firmware can object.

For a Value influenced by several inputs through controller logic, do not use dependsOn(). Write the logic and call setValue(); multi-input dependency declarations are not part of this model.

Dependencies are firmware declarations: never persisted, not runtime configurable. Declaring them before startNightMareESP() avoids republishing the manifest once per call.

ManagedAction#

Use ManagedAction when this device exposes an operation rather than persistent state.

Without argument metadata:

ManagedAction rebootPeripheral("reboot_peripheral");

With a schema:

static const ActionArgMetadata TimerArgs[] = {
    {"seconds", NetValueType::INTEGER, true},
    {"mode", NetValueType::STRING, false},
};

ManagedAction setTimer("set_timer", TimerArgs);

The schema must outlive the Action, so static/global arrays are the normal source.

Install a handler:

ActionResult onSetTimer(ManagedAction &action, const std::string &payload)
{
    // Parse the canonical payload as required by the application.
    return {true, "timer accepted"};
}

void setup()
{
    setTimer.onInvoke = onSetTimer;
    startNightMareESP();
}

The Action is described in the manifest and subscribes to:

<device>/resource/set_timer/invoke

ActionResult#

Managed Action execution returns:

struct ActionResult
{
    bool success;
    std::string result;
};

Ordinary raw MQTT /invoke does not have a response topic, so the remote sender does not receive this result automatically.

The result is still useful for local/correlated execution paths. ResourcesManager::executeAction() preserves it directly, and the > Resource-command adapter can surface a ManagedAction result through the normal command/MQTTP response path.

RemoteAction#

A RemoteAction invokes an Action owned by another device.

Normal form:

RemoteAction setTimer(
    "bedroom_timer");

setTimer.setSource("bedroom-ac", "set_timer");

Invoke it:

setTimer.invoke(R"({"seconds":300})");

A true return means the request was accepted for MQTT publication.

It does not mean the remote handler returned success.

A RemoteAction does not need to duplicate the remote schema.

The normal lightweight declaration carries no local schema at all.

Optional expected Action schema#

A caller may declare the subset of arguments it knows and expects:

static const ActionArgMetadata KnownTimerArgs[] = {
    {"seconds", NetValueType::INTEGER, true},
};

RemoteAction setTimer(
    "bedroom_timer",
    KnownTimerArgs);

setTimer.setSource("bedroom-ac", "set_timer");

This is the caller's expectation, not a claim that it mirrors the complete remote contract.

Manifest comparison can warn about disagreements.

Action payload assertion#

By default:

NM_ENABLE_ACTION_PAYLOAD_ASSERTION 0

Action schema is still published, but generic payload validation is disabled.

When enabled, NightMare validates known Action arguments against a JSON object.

Unknown fields are allowed and optional declared fields may be absent.

This keeps schema checking tolerant rather than turning manifests into a rigid version lock.

Events#

Use an Event when something happened and a listener cares about the occurrence, not about a state that persists afterwards.

Sensor / State Action Event
Says something is please do something something happened
Wire retained /state transient /invoke transient /event
Late subscriber sees current value nothing nothing
Same payload twice one change, notified once two invocations two occurrences
Has a current value yes no no
Freshness / availability yes no no

Good Events:

button pressed
IR code received
acoustic beep emitted

Door open or closed is not an Event: it is state, and a consumer that connects later needs to know which one it currently is. Use a Sensor or State.

ManagedEvent#

ManagedEvent<uint32_t> beep("acoustic:beep");

void setup()
{
    startNightMareESP();
}

void onButton()
{
    beep.fire(880); // frequency in Hz
}

fire() publishes <device>/resource/acoustic:beep/event, transient and never retained. It returns true when the transport accepted the publication, and false when unbound, when the payload encodes to nothing or more than 2048 bytes, or when the connection refused it. true does not mean anybody received or handled it.

Firing equal payloads twice is two occurrences:

beep.fire(880);
beep.fire(880); // published again; nothing is compared with the previous call

A ManagedEvent has no getValue(), no setValue(), no hasValue(), no availability, no freshness, no advertisement period, no hardware policy and no dependsOn(). Besides fire() its public members are onEvent and lastUpdateMs().

Local listener

onEvent is the same-device counterpart of a RemoteEvent's handler: the code that owns the event can react to its own occurrences through the same callback shape, instead of calling a function next to every fire().

ManagedEvent<uint32_t> beep("acoustic:beep");

static void onLocalBeep(ManagedEvent<uint32_t> &event, const uint32_t &hertz)
{
    // runs inside fire(), on the caller's task
}

void setup()
{
    beep.onEvent = onLocalBeep;
}

void loop()
{
    beep.fire(880); // publishes to the network and calls onLocalBeep(880)
}

fire() attempts the publication and then calls onEvent, once per valid occurrence, for equal payloads too. It runs whether or not the transport took the message, and also while the event is unbound, because the occurrence happened on this device; fire()'s return value still reports only the publication. A payload that cannot be encoded is not an occurrence, so onEvent is not called for it. The handler runs synchronously inside fire(), so it must be short and must not call fire() on the same event.

RemoteEvent#

RemoteEvent<uint32_t> remoteBeep("beep");

static void onBeep(RemoteEvent<uint32_t> &event, const uint32_t &hertz)
{
    // one call per occurrence, with the already-decoded payload
}

void setup()
{
    remoteBeep.onEvent = onBeep;
    remoteBeep.setSource("Watson", "acoustic:beep");
    startNightMareESP();
}

onEvent runs once for every valid live occurrence, including consecutive identical payloads. There is nothing to read afterwards: the previous payload is not kept, and an occurrence that arrives while no source is configured, or before the subscription exists, is simply not seen. A payload that fails to decode is dropped without calling onEvent.

setSource() and clearSource() use the same persistence as RemoteSensor and RemoteState (/remoteresources.json, keyed by the stable local name). Retarget it like any other Remote Resource:

remoteBeep.setSource("Moriarty", "acoustic:beep");

This unsubscribes the old /event, subscribes to the new one, persists the mapping, republishes the consume manifest and resets lastUpdateMs() to 0. The Resource remains Remote.

lastUpdateMs()#

lastUpdateMs() is a local millis() timestamp:

ManagedEvent   latest occurrence the transport accepted
RemoteEvent    latest valid live occurrence received

It is 0 before the first occurrence and, for a RemoteEvent, again after the source changes. It is diagnostic only: do not use it as freshness (an Event that has not fired is not stale), and it is not an epoch time.

Reconnect and replay#

Events are never replayed. A reconnect republishes a ManagedEvent's manifest entry and fires nothing, and rebuilds a RemoteEvent's /event subscription without calling onEvent. A consumer that was offline simply missed the occurrences that happened meanwhile; if that is not acceptable, the information is state, not an Event.

Payloads#

Events use the library's NetCodec<T>, exactly as Values do, so bool, integer, floating-point, std::string, TimeType and ColourType payloads are supported and an unsupported T fails to compile. Applications do not define their own codecs (see Applications do not define Value types); to carry several fields, fire a JSON object in a ManagedEvent<std::string>. Unlike a Value, an Event is never decoded from or published as an empty payload.

When not to use an Event#

  • The consumer needs the current state when it connects: use a Sensor or State.
  • The payload changes the state of the receiver and must be acknowledged: use an Action, and a correlated path when the result matters.
  • You need every occurrence reliably (no loss, ordering, exactly once): an Event is best effort with no acknowledgement, replay or sequence numbers.

Value codecs#

Built-in NetCodec<T> support currently covers:

bool
integral types
floating-point types
std::string
TimeType
ColourType

Manifest wire types are:

boolean
integer
float
string
struct
time
colour

TimeType canonically encodes local time of day as HH:MM:SS. ColourType canonically encodes its packed 0xRRGGBBAA value as unsigned decimal text. These are ordinary typed Values and use the same state, write, freshness, and manifest paths as every other NetValue<T>.

Applications do not define Value types#

NetCodec<T> specializations belong to the library. An application must not add its own (template <> struct NetCodec<MyType>), even though the code compiles. A Value type is part of the common wire protocol: every device and every consumer (including MessagePack manifests and backend tooling) has to agree on its encoding and its NetValueType number, so a type declared in one project would have to be declared everywhere, and a mismatch silently corrupts payloads.

Unsupported C++ Value types therefore fail to compile, and that is the intended answer. To carry a structured reading, publish a generic struct: a JSON object in a ManagedSensor<std::string>. It travels as a string, the library neither validates nor interprets its fields, and the consumer is responsible for decoding it. Document the fields next to the Resource declaration, and add fields rather than changing existing ones so older consumers keep working.

Empty payload rule#

Values and Actions deliberately differ.

For a Value:

empty payload = retained deletion / unavailable state

Therefore an empty std::string cannot be a valid Resource std::string value.

For an Action:

empty payload = valid invocation payload

A zero-argument Action can therefore be invoked with:

action.invoke();

Resource command bridge#

When Console + Resources are enabled, a command beginning with > is routed to ResourcesManager::executeCommand() before the generic command parser.

The character immediately after > is part of the grammar.

ResourceManager operations#

No space after > selects an operation owned by the manager itself:

>list
>manifest [publish] [json|msgpack]
>drop <name|owner/name>
>raw <topic> [payload]

>list returns a text table of the currently bound Resources with the columns KIND (value, event or action), NAME, TYPE (the value type of a Value or the payload type of an Event, - for an Action), OWNER (self for a Resource this device owns, otherwise the owning device, - when a Remote Resource has no owner configured) and VALUE:

KIND    NAME           TYPE    OWNER   VALUE
value   temperature    float   self    21.5
action  reboot_ctrl    -       self    -
event   acoustic:beep  string  self    managed last_update_ms=182345
event   beep           string  Watson  remote source=Watson/acoustic:beep last_update_ms=0

A Value shows its effective current value (or <unavailable>), an Action -. An Event has no value to show, so its cell describes it instead: its role, for a Remote Event its source (source=- while unconfigured), and last_update_ms.

>manifest json returns the named-key manifest. A MessagePack selection republishes <device>/manifest/msgpack and responds Republished.; raw binary is not returned through the text command channel. publish makes publication explicit. With no format it publishes canonical MessagePack and, only when enabled, the optional JSON sibling. Bare >manifest selects MessagePack and republishes only that manifest.

>drop unbinds the addressed Resource.

>raw feeds the supplied topic and opaque payload through the same Resource ingress path used for MQTT messages:

>raw bedroom-ac/resource/power/set true

This is an ingress/testing/control facility. It is not the normal short-name Resource syntax.

Resource operations by name#

A space after > selects a bound Resource by unique short name:

> temperature
> temperature get
> power set true
> identify
> identify invoke {"mode":"blink"}

A bare Value performs get.

A bare Action performs invoke with an empty payload.

A bare Event returns its runtime metadata only, never a payload:

> acoustic:beep
EVENT acoustic:beep last_update_ms=182345

The explicit verbs are:

get
set
invoke
source

The implementation also accepts action as an alias for invoke, but invoke is the canonical spelling.

source is valid only for Remote Resources. It reads, changes, or clears the persisted source:

> outdoor_temperature source
> outdoor_temperature source weather-node/temperature
> outdoor_temperature source clear
> outdoor_temperature source {"owner":"weather-node","resource":"temperature"}

Local Resource names are unique within the registry, so the stable local name always identifies exactly one Resource.

get is valid only for Values and accepts no payload. It returns the effective current value, so an optimistic RemoteState can return its active optimistic value.

set is valid only for Values and requires a payload.

For a ManagedState, set uses the same decode + onWrite acceptance path as MQTT /set ingress.

For a RemoteState, set uses the normal typed setValue() path, including optimistic behavior, and success means the request was accepted for connection.

invoke is valid only for Actions. Everything after the verb is one opaque Resource payload.

An Event accepts none of get, set, invoke, advertise or poll, and there is no fire verb: firing is application code (fire()), not an operator command. A Remote Event accepts source exactly like any other Remote Resource.

For a ManagedAction, command execution returns its local ActionResult.

For a RemoteAction, success means only that the normal MQTT /invoke publication was accepted.

Limits#

Normal Value/Action/Event payloads remain limited to:

2048 bytes

The overall Resource-command expression limit is larger:

NetResourceMaxCommandLength
    = NetResourceMaxManifestLength + 256
    = 16640 bytes

That larger envelope allows >raw to carry Resource ingress such as a manifest-sized payload.

The leading > is a command/control adapter; it does not change the Resource MQTT protocol.

Manager participation#

ResourcesManager owns:

bindResource(...)
unbindResource(...)
announceAll()
subscribeAll()
setManifestHandler(...)

Applications normally rely on automatic binding during startup. Explicit binding, unbinding, and manifest-handler methods remain available when needed.

Remote Resources are published automatically at <device>/manifest/consume/msgpack. Each declaration appears once in remotes[]; bound: true derives a dependency edge. This document is separate from the Managed Resource provider manifest and requires no duplicate project declaration.

The ResourcePublisher / ResourceSubscriber adapter is injected by NmConnection; the manager has no MQTT or broker-profile dependency.

Manifest handler#

Discovery/tooling code can observe valid manifests:

void manifestReceived(const std::string &deviceName, const std::string &manifest)
{
    // inspect/update application discovery state
}

gResourcesManager.setManifestHandler(manifestReceived);

The callback also receives an empty std::string for a valid retained manifest withdrawal.

Malformed manifests are not delivered to the handler.

Limits#

Current Resource limits are:

bound Resources:          100
Resource-name length:     64 characters
Value/Action/Event payload: 2048 bytes
manifest payload limit:   16384 bytes
dependencies per Sensor:  1

For wire details, see Resource protocol.

Last updated · Edit this page on GitHub