System service

The system service lets a user reboot, network-reset, or factory-reset the node from the phone app. It is how a device gets un-stuck without physical access — which matters for anything installed in a ceiling.

Enabling it

esp_rmaker_system_serv_config_t system_serv_config = {
    .flags                = SYSTEM_SERV_FLAGS_ALL,
    .reboot_seconds       = 2,
    .reset_seconds        = 2,
    .reset_reboot_seconds = 2,
    .network_reset_fn     = app_network_reset_credentials,
};
esp_rmaker_system_service_enable(&system_serv_config);

This creates a service named System with one boolean parameter per enabled flag. Writing true triggers the action; the SDK resets the parameter to false afterwards.

Field	Meaning
flags	OR of SYSTEM_SERV_FLAG_REBOOT, SYSTEM_SERV_FLAG_NETWORK_RESET, SYSTEM_SERV_FLAG_FACTORY_RESET. At least one is required. SYSTEM_SERV_FLAGS_ALL selects all three.
reboot_seconds	Delay before a Reboot action takes effect
reset_seconds	Delay before a network or factory reset takes effect
reset_reboot_seconds	Delay before rebooting after a reset. Negative means don't reboot.
network_reset_fn	Your function that clears network credentials. Required if either reset flag is set.

Disable the service again with esp_rmaker_system_service_disable().

Parameters exposed

Parameter	Flag	Type
Reboot	SYSTEM_SERV_FLAG_REBOOT	esp.param.reboot
Network-Reset	SYSTEM_SERV_FLAG_NETWORK_RESET	esp.param.network-reset
Factory-Reset	SYSTEM_SERV_FLAG_FACTORY_RESET	esp.param.factory-reset

The network reset function

The SDK does not know how your network stack stores credentials, so you supply the function that clears them. The examples pass app_network_reset_credentials from the app_network component.

If you omit it while a reset flag is set, esp_rmaker_system_service_enable() fails. The reset-network and reset-to-factory console commands will also fail, since they route through the same path.

You can register it separately with esp_rmaker_system_ctrl_register_network_reset_fn() if you enable the service before your network layer is ready.

Why the delays exist

Each action fires after a configurable delay, and the SDK posts an event when the countdown starts. That window is your chance to shut down cleanly:

Event	Data
RMAKER_EVENT_REBOOT	Seconds until reboot
RMAKER_EVENT_NETWORK_RESET	—
RMAKER_EVENT_FACTORY_RESET	—

case RMAKER_EVENT_FACTORY_RESET:
    app_driver_park_motor();       /* leave the hardware in a safe state */
    app_driver_persist_counters(); /* flush anything you care about */
    break;

A couple of seconds is usually enough. Set the delay long enough for your slowest cleanup — but remember the user is watching a spinner in the app.

What each reset actually clears

This is the part people get wrong.

Action	RainMaker Neo data (node config, persisted params)	Network credentials	Factory partition
Reboot	kept	kept	kept
Data reset (esp_rmaker_system_ctrl_data_reset())	erased	kept	kept
Network-Reset	kept	erased	kept
Factory-Reset	erased	erased	kept

A factory reset does not erase the factory partition

The fctry partition holds the node's permanent identity — node ID, client certificate and key, MQTT host. It is written once in manufacturing and every reset leaves it alone, deliberately. A factory-reset node is a blank but still-registered device that can be re-provisioned by a new user. To change the identity you must reflash the factory image. See Factory NVS.

Calling the actions directly

The underlying system-control API is public, so you can trigger the same actions from a button, a timer, or your own logic:

esp_rmaker_system_ctrl_reboot(2);                          /* reboot in 2 s */
esp_rmaker_system_ctrl_data_reset(2, 2);                   /* clear Neo data, then reboot */
esp_rmaker_system_ctrl_network_reset(2, 2, NULL);          /* NULL → use the registered fn */
esp_rmaker_system_ctrl_factory_reset(2, 2, NULL);

Pass a negative reset_reboot_s to skip the reboot. The app_button component's long-hold resets and the console reset commands are both built on these.

Which reset for which problem

Situation	Use
Device is wedged, state looks fine	Reboot
User moved house / changed router	Network reset
User is selling or returning the device	Factory reset
Data model changed after a firmware update and stale params are confusing things	Data reset

Expose all three in the app if you can. Restricting to reboot only means every field problem becomes a support call.

Related

• Firmware specifications → Optional Services → System — payloads and error handling
• Serial console → Resets
• Troubleshooting — button-triggered resets
• Factory NVS