Skip to main content
Documentation Hub

Local Control Service

about

ESP RainMaker offers a facility to control devices over local control, as demonstrated in the usage guide. Originally, the local network communication was established using plain text HTTP. However, enhancements have been made by implementing security measures using ESP-IDF's protocomm_security1. This offers Proof of Possession (PoP) based access control and encrypted communication.

Use Case​

ESP RainMaker was primarily built to offer remote connectivity to ESP devices. However, when both the phone and the device are connected to the same Wi-Fi network, controlling the device locally is much faster, more reliable, and cost-effective, as there is no need to communicate with the cloud or rely on internet connectivity.

Specifications​

Once local control is enabled with security level 1, the following service gets added to the node configuration:

JSON Payload (Click to view)
{
    "name": "Local Control",
    "params": [{
            "data_type": "string",
            "name": "POP",
            "properties": [
                "read"
            ],
            "type": "esp.param.local_control_pop"
        },
        {
            "data_type": "int",
            "name": "Type",
            "properties": [
                "read"
            ],
            "type": "esp.param.local_control_type"
        }
    ],
    "type": "esp.service.local_control"
}

The value of PoP (Proof of Possession) and control type are available in node parameters as below:

JSON Payload (Click to view)
{
    "Local Control": {
        "POP": "a8d8e5ce",
        "Type": 1
    }
}

Local Control Service Workflow​

  1. When a node gets associated with a user, the client side like a phone application can check if the node supports secure local control by searching for the local control service in the node configuration.

  2. If this service is available, the client will obtain the PoP from the node paramters.

  3. In cases where the node is detected on the local network through mDNS, this PoP is used to establish a secure sesssion with the node and then communicate with it using ESP-IDF's local control feature.

Question: Is this PoP the same as the one used for provisioning?

No, it is not the same.

For this context, it is generated by the node itself. This approach is taken because the provisioning PoP is programmed during manufacturing and stays the same throughout the lifetime of the node. However, it gets used only when the node is being set up, thus minimizing the risk associated with the code leaking. But, if the same code gets used for local control and gets leaked, anyone on the same network can access it, even if the node is reset and re-provisioned. Of course, in most cases, the clients on the same Wi-Fi network could be trusted clients, but this situation still poses a potential risk.

Question: What is the benefits of having PoP generated randomly and reported via node parameters?
  1. Since the PoP is generated and stored in NVS, it can be changed by performing a factory reset. The service can also be extended to allow users to periodically change the PoP if required.
  2. PoP is available to all users with whom the node is shared.

Given that local control not only provides a swifter experience but is now also secure, it is advisable to enable it as the default setting in your projects. However, note that secure local control can currently work only with ESP-IDF release/v4.2 (later than release v4.2.2), release/v4.3 (release v4.3.2 onwards), and all the other newer release branches.

Usage Guide​

Firmware​

The Local Control service needs to be enabled only on the firmware side. For instructions on how to do this, click here.

On this page