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.
Naming related declarations#
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.