Serial console

The SDK ships a UART-backed REPL for inspecting and driving a node during development. It is the fastest way to answer "what node ID is this board?" or "does my write callback actually work?" without involving the cloud or a phone.

It works identically on both platforms: on ESP-IDF it is backed by the IDF esp_console component, on POSIX by a stdin REPL shim.

Enabling it

One call, as early as possible in your startup path:

esp_rmaker_console_init();

That sets up the REPL and registers both the common RainMaker commands and the RainMaker Neo built-ins. Call it before anything that can fail — if node init blows up, you still get a prompt.

The call is always linkable. With CONFIG_RMNG_CONSOLE_ENABLED=n it logs a warning and returns ESP_RMAKER_OK without starting anything, so you never need to #ifdef around it.

If your application already runs its own console, call esp_rmaker_register_commands() instead to add only the RainMaker Neo commands to your existing REPL. That symbol only exists when CONFIG_RMNG_CONSOLE_ENABLED=y.

Connect with idf.py -p <port> monitor on ESP-IDF, or just type into the process's stdin on POSIX.

Commands

Node identity

Command	What it prints
get-node-id	The node ID — also the AWS IoT Thing name and the MQTT client ID
node-info	Node name, type, firmware version, and model

get-node-id is the one you will use most: it is the value you search for in the Admin Dashboard and pass to local_ctrl_cli.

Resets

Three levels, in increasing severity:

Command	Erases	Keeps
reset-data	RainMaker Neo data namespaces — node config, local config, persisted parameters	Network credentials
reset-network	Network credentials (Wi-Fi)	RainMaker Neo data
reset-to-factory	Both	Nothing (but see below)
clear-claim-data	The factory credentials namespace — node ID, certificate, private key	RainMaker Neo data, network credentials

Each reboots the node after a short delay so the console response flushes first.

caution

reset-to-factory does not erase the factory partition

Despite the name, a factory reset clears runtime state only. The fctry partition — node ID, certificates, MQTT host — is untouched, by design: those are the node's permanent identity.

clear-claim-data is the exception: it erases exactly that namespace and reboots. A claiming-enabled node then claims again from scratch; a node with pre-flashed credentials needs them re-flashed. See Re-claiming a node.

reset-network and reset-to-factory need a network-reset function. The examples pass app_network_reset_credentials via the system service config; if none is registered, these commands fail with a message saying so. See System service.

Parameters

Available when CONFIG_RMNG_CONSOLE_PARAM_CMDS_ENABLED=y (the default).

Command	Effect
set-param <device_id> <param_id> <value>	Writes the value through the normal state-change path, so your write callbacks run — exactly as if the cloud had sent it. The request source is ESP_RMAKER_REQ_SRC_FIRMWARE.
update-param <device_id> <param_id> <value>	Sets the value without invoking callbacks. Use it to simulate a sensor reading or a state change your hardware detected.
get-param <device_id> <param_id>	Prints the current value held by the SDK core.

> set-param Light Power true
Successfully set Light.Power to true with callback

> get-param Light Brightness
50

The value is parsed according to the parameter's existing type. Booleans accept true or 1; objects and arrays are embedded as raw JSON, so quote them for the shell.

set-param is the single most useful debugging command in the SDK: it exercises your entire write path — parsing, callback, hardware, report — with no cloud, no app, and no network.

System

Command	Effect
reboot	Immediate reboot
up-time	Uptime in milliseconds
local-time	Current local time, honouring the timezone set via the timezone service

local-time is the quickest check that time sync and the timezone service are actually working — a node with no time will not fire schedules.

Configuration

Option	Default	Notes
CONFIG_RMNG_CONSOLE_ENABLED	y	Disable if your application provides its own console.
CONFIG_RMNG_CONSOLE_PARAM_CMDS_ENABLED	y	The three parameter commands. Only available with the default data model.

Not available with remote control on UART0

CONFIG_RMNG_CONSOLE_ENABLED cannot be set when CONFIG_RMNG_HOST_CTRL=y and the ESP-IDF console uses the default UART: remote control multiplexes the same UART0 stream, so a REPL there would clash. Move the console to USB Serial/JTAG or a second UART to run both.

Production builds

Leave the console off in shipping firmware, or at minimum drop the parameter commands. reset-to-factory and set-param over an exposed UART are a real attack surface, and the REPL costs flash and RAM. See Pre-production checklist.

Related

• Callbacks and events — what set-param triggers
• Troubleshooting
• Tools reference