Optional Services
Timezone
Overview
Provides device-wide timezone management exposed as a service named Time with parameters TZ (IANA timezone) and TZ-POSIX (POSIX TZ string). Both parameters are readable and writable.
Service and Parameters
Service name:
TimeParameters (under
params : Time):TZ(type string): IANA timezone name, e.g.,America/New_YorkTZ-POSIX(type string): POSIX timezone string, e.g.,EST5EDT,M3.2.0,M11.1.0Timestamp(type int64): epoch time in seconds. The value is 0 until the first write. Present only whenCONFIG_ESP_RMAKER_NEO_TIME_CURRENT_TIME_PARAMis enabled. Use it on nodes that cannot reach a time server, for example nodes under local control only.
All parameters have properties: read, write.
Behavior
Incoming parameter updates (from cloud)
When
TZis written:Node applies the timezone using the IANA name.
On success, node updates local state and derives the corresponding POSIX value, updating
TZ-POSIXas well.On failure, no state change is reported for either parameter.
When
TZ-POSIXis written:Node applies the timezone using the provided POSIX string.
On success, node updates local state for
TZ-POSIX.The IANA
TZwill not change since it cannot be derived from the POSIX string; onlyTZ-POSIXis guaranteed to update.
When
Timestampis written:Node sets its local clock from the epoch value, and reports back its clock reading after the write.
The reported value can differ from the value written, because the write is a coarse time source bounded by delivery latency.
The reported
Timestampis the node’s clock reading at the last write. It does not advance, so do not display it as the current time.When the clock owner already set the clock, the node ignores the write and reports its own clock. A late or replayed write then cannot step a synced clock.
CONFIG_ESP_RMAKER_NEO_TIME_CLOCK_OWNERselects the clock owner:SDK(default): use this when the SDK runs SNTP (enable_time_syncis true), or when the node has no time source. The node applies writes until the SDK SNTP client gets a time. If the app started SNTP before the SDK, the node applies writes only while the clock is not valid.EXTERNAL: use this when the app, not the SDK, gets the time. For example, the app runs its own SNTP client or reads a GPS or RTC chip, or the OS runs NTP. The SDK cannot see when that source syncs, so the node applies writes only while the clock is not valid.On POSIX and the ESP-IDF linux target, the SDK runs no SNTP, so with
SDKevery write tries to set the host clock. PickEXTERNALwhen the host runs NTP.
After the node applies a write, SNTP steps the clock again on its next sync.
Whenever possible, it is preferred to update TZ instead of TZ-POSIX.
Local updates (from device)
When the device changes timezone locally (e.g., via internal API):
Node emits a timezone change event that updates the corresponding parameter(s) in the service state, ensuring shadows reflect the change.
State reporting
After successful changes (from cloud or local), node publishes updated parameters in the named shadow under
params : { "Time": { ... } }.Indexed shadow is not used for timezone parameters unless explicitly marked
indexedin node configuration (default: not indexed).
Examples
Write only
TZfrom cloud
// Incoming params request
{
"Time": {
"TZ": "America/New_York"
}
}
// Expected named shadow reported
{
"Time": {
"TZ": "America/New_York",
"TZ-POSIX": "EST5EDT,M3.2.0,M11.1.0"
}
}
Write only
TZ-POSIXfrom cloud
// Incoming params request
{
"Time": {
"TZ-POSIX": "CAT-2"
}
}
// Expected named shadow reported
{
"Time": {
"TZ-POSIX": "CAT-2"
}
}
Local update to IANA timezone
// Local API updates TZ to America/New_York
// Expected named shadow reported
{
"Time": {
"TZ": "America/New_York",
"TZ-POSIX": "EST5EDT,M3.2.0,M11.1.0"
}
}
Error Handling
If applying a timezone fails, the node should not update
TZorTZ-POSIXin reported state for that request.If setting the clock fails, the node does not update
Timestampin reported state for that request. A value at or before the build-time reference, or a value above 4294967295 (UINT32_MAX, the year 2106), is rejected. The upper limit also rejects a value in milliseconds sent by mistake. See Time Synchronization.When
TZis accepted and applied but the POSIX string cannot be derived from it,TZis still updated in reported state andTZ-POSIXis left unchanged.
System
Overview
Provides device-wide system control operations exposed as a service named System with parameters for reboot, network reset, and factory reset. All parameters are boolean values that trigger actions when set to true.
Service and Parameters
Service name:
SystemParameters (under
params : System):Reboot(type boolean): Triggers device reboot when set totrueNetwork-Reset(type boolean): Triggers network reset when set totrueFactory-Reset(type boolean): Triggers factory reset when set totrue
All parameters have properties: read, write.
Behavior
Incoming parameter updates (from cloud)
When
Rebootis set totrue:Node initiates a reboot sequence after the configured delay
When
Network-Resetis set totrue:Node resets network configuration and may reboot after the configured delays
When
Factory-Resetis set totrue:Node performs a factory reset, clearing all configuration and may reboot after the configured delays
State reporting
After successful parameter writes, the node reports the parameter value back in the named shadow under
params : { "System": { ... } }Indexed shadow is not used for system parameters unless explicitly marked
indexedin node configuration (default: not indexed)
Factory reset participants
A factory reset clears the data the SDK owns: the RainMaker Neo NVS namespaces, the stored per-device parameter values and the network credentials. A component that derives another protocol’s data model from the RainMaker Neo one holds persistent state the SDK knows nothing about — pairings, credentials, access control entries. Left behind, that state outlives the reset: the node comes back up factory-new to the cloud while the other protocol’s controllers still hold valid credentials for it.
Such a component registers a factory reset participant with esp_rmaker_system_ctrl_factory_reset_participant_register(), supplying a wipe callback that erases its own state. esp_rmaker_system_ctrl_factory_reset() runs every registered participant after clearing the SDK’s own data, in registration order, and reboots afterwards. A failing wipe is logged and does not stop the remaining participants. Registration is not thread-safe: register and unregister from one task while no reset can run, before esp_rmaker_start() or after esp_rmaker_stop().
A participant whose reset primitive restarts the system rather than returning — because the external stack owns its own restart — sets reboots_on_wipe. It is wiped last, after every other participant, because an earlier restart would strand their wipes. At most one participant may claim this; a second registration is rejected.
A reset originating in the external model itself takes the other direction: the model has already committed to wiping its own state, so it calls esp_rmaker_system_ctrl_factory_reset_from_participant(), passing its own wipe as self. That clears the SDK’s side and wipes every other participant, so a single reset still reaches all of them whichever side started it. Passing a negative reset_reboot_s leaves the restart to the caller, for a stack that reboots itself.
The entry point runs synchronously on the calling thread, participant wipes included, so the caller must have the stack for them. A factory reset requested while another is running, or after its reboot has been scheduled, runs nothing and returns ESP_RMAKER_INVALID_STATE — whether a participant’s own wipe triggers it in turn or another task asks for one at the same time. Participants do not need their own re-entry guards: one that gets this from inside its own wipe can ignore it, since the running reset already includes that wipe. A run that does not reboot, because reset_reboot_s is negative or the reboot could not be scheduled, leaves the node resettable again.
A delayed reset (reset_s above 0, or a System service reset with reset_seconds above 0) runs on a dedicated task created on the first such request. Its stack is CONFIG_ESP_RMAKER_NEO_SYSTEM_CTRL_RESET_TASK_STACK_SIZE (default 3072, the FreeRTOS timer task stack these resets used to run on); raise it when a participant’s wipe needs more, for example when it runs another protocol stack’s own factory reset.
Configuration
The system service is enabled with a configuration struct whose flags field selects which params the service exposes. A param that is not selected is not created at all, so it does not appear in the node configuration:
SYSTEM_SERV_FLAG_REBOOT: Exposes theRebootparamSYSTEM_SERV_FLAG_NETWORK_RESET: Exposes theNetwork-ResetparamSYSTEM_SERV_FLAG_FACTORY_RESET: Exposes theFactory-ResetparamSYSTEM_SERV_FLAGS_ALL: All three
At least one flag is required. The rest of the configuration sets the timing and the platform hook:
reboot_seconds: delay before the reboot triggered byRebootreset_seconds: delay before a network/factory reset takes effectreset_reboot_seconds: delay before the reboot that follows a reset; a negative value means “do not reboot”network_reset_fn: callback that clears the platform’s network credentials. Required (non-NULL) whenever theNETWORK_RESETorFACTORY_RESETflag is set
Examples
Trigger reboot from cloud
{
"System": {
"Reboot": true
}
}
Trigger network reset from cloud
{
"System": {
"Network-Reset": true
}
}
Trigger factory reset from cloud
{
"System": {
"Factory-Reset": true
}
}
Error Handling
If a system operation fails to initiate, the parameter write should be rejected and no state change reported.
Local Control
Overview
Lets a client control the node over the local network, with no cloud round trip. This section covers the service the node reports to the cloud; the on-the-wire protocol a client speaks is specified separately in Local Control Endpoint Protocol, which is the authority on endpoints, framing and discovery.
Service name:
Local ControlTransport: HTTP (protocomm)
Service and Parameters
Parameter |
Type |
Access |
Description |
|---|---|---|---|
|
int |
read-only |
protocomm security version in use: |
|
string |
read-only |
Proof of Possession for the session |
|
string |
read-only |
SRP6a username; present only with security version |
POP is reported for both security versions. Whether a PoP is actually required comes
from the no_pop capability on the version endpoint, not from this parameter — a
security-1-without-PoP node reports an empty string here.
Security 0 is not supported.
Behavior
The service is added to the node when local control starts, and removed when it is disabled. Enabled before the start task starts the local endpoints, it starts from the start task once the node ID and the network are available (see Initialization); enabled after that step, it starts at once.
Challenge-response for on-network user-node association shares the same protocomm instance and session; it is an independently enable-able endpoint set, not a separate service. See the endpoint protocol spec for the four enabled/disabled combinations.
The HTTP port defaults to
CONFIG_ESP_RMAKER_NEO_LOCAL_CTRL_HTTP_PORT.The PoP is generated once and persisted, unless the application sets its own with
esp_rmaker_local_ctrl_set_pop()before enabling the service — which is how a device reuses the PoP printed on it (see the guides on factory provisioning).
Custom Endpoints
An application can add its own endpoints to the Local Control protocomm instance with
esp_rmaker_local_ctrl_add_endpoint(), and remove them with esp_rmaker_local_ctrl_remove_endpoint().
Add the endpoints from the
RMAKER_EVENT_LOCAL_CTRL_STARTEDhandler. When the service is not running, add returnsESP_RMAKER_INVALID_STATE.The node holds up to 4 custom endpoints. Protocomm rejects a duplicate name, which includes the standard endpoint names.
Disabling the service removes all custom endpoints, also when challenge-response keeps the HTTP server running.
A custom endpoint uses the same session security as
get_params. With security 1 andCONFIG_ESP_RMAKER_NEO_LOCAL_CTRL_SEC1_POP=n, any client on the LAN can call it.The handler runs on the HTTP server task, with a stack of
CONFIG_ESP_RMAKER_NEO_LOCAL_CTRL_STACK_SIZEbytes.Remove does not wait for a handler that runs at that time. Keep
priv_datavalid until the service stops.Add and remove have no lock. Do not call them at the same time as each other, or as the service enable or disable.