Skip to main content

Local Control

Local control lets a client on the same network talk to a node directly over HTTP, without a round trip to the cloud. It is what keeps a light responsive when the internet connection is slow, and controllable when it is down altogether.

This page is the product view. For the firmware side — the enable call, the security versions, and the Kconfig — see Local control.

What it does, and what it does not​

Local control covers reading and writing parameters on a node you already own. A client finds the node on the local network, opens an authenticated session, and gets and sets the same parameters it would through the cloud.

It is not an offline mode for the whole product. These still require the cloud:

  • Adding a new user, or associating a node with one
  • Groups, group control, schedules, and automations
  • Time series history, OTA, and notifications
  • Voice assistants

A node that has never been provisioned and associated cannot be driven locally either — local control is a faster path to a node you already have, not a way to skip setup.

How a client finds the node​

The node advertises a single mDNS service, _esp_rmaker_ctrl._tcp, and the client connects directly. Its cap TXT record lists what the node currently offers:

  • local_ctrl — local control itself, reading and writing parameters
  • ch_resp — on-network challenge-response, which proves a node's identity on the network without granting parameter access

So a client can tell, before connecting, whether a node is available for control, for association, or both. The SDK ships a reference client, tools/local_ctrl_cli/local_ctrl_cli.py, which does exactly that: it discovers a node by its Node ID, reads its capabilities, and opens an interactive prompt offering the matching commands.

Security​

The session is authenticated before any parameter is readable. Two security versions exist, chosen in firmware:

  • Security 1 — a proof of possession, the PoP, shared out of band.
  • Security 2 — SRP6a, where the PoP acts as the password. The username is fixed to wifiprov so device and client always agree.

There is no unauthenticated option: Security 0 is not supported.

The PoP is generated on the device and persisted in NVS, so it survives a reboot and stays stable for a given device. Getting it to the user — printed on the device, on the box, or carried in a QR code — is a product decision.

What the firmware must do​

Local control is off by default. Firmware enables it with one call between node init and node start, optionally setting the PoP first, and selects the security version through Kconfig. On-network challenge-response has its own enable call but rides on the same service and the same authenticated session — the two can be enabled in any combination.

What the operator must do​

Nothing. Local control is entirely a device and client concern — there is no deployment setting for it, and no cloud specification, because no cloud component takes part.

Limits and caveats​

  • Client and node must be on the same network. There is no relaying and no NAT traversal.
  • Parameter access only; everything in the list above still needs the cloud.
  • Each session costs the node memory and a socket, so the practical number of simultaneous local clients is small.
  • The HTTP port is configurable in firmware, so a client should take it from the mDNS advertisement rather than hardcoding it.
Phone app support is unconfirmed

Whether the ESP RainMaker Home app performs local control against a Neo node — and when it would prefer the local path over the cloud — is not currently documented. What is verified here is the firmware capability and the reference CLI client. If your product depends on app-side local control, confirm the behaviour with your Espressif contact first.