ESP Local Control (**esp_local_ctrl**) component in ESP-IDF provides capability to control an ESP device over HTTPS or Bluetooth® Low Energy. It provides access to application defined **properties** that are available for reading/writing via a set of configurable handlers.
1.``PROTOCOM_SEC2``: specifies that SRP6a based key exchange and end to end encryption based on AES-GCM is used. This is the most preffered option as it adds a robust security with Augmented PAKE protocol i.e., SRP6a.
2.``PROTOCOM_SEC1``: specifies that Curve25519 based key exchange and end to end encryption based on AES-CTR is used.
3.``PROTOCOM_SEC0``: specifies that data will be exchanged as a plain text (no security).
4.``PROTOCOM_SEC_CUSTOM``: you can define your own security requirement. Please note that you will also have to provide ``custom_handle`` of type ``protocomm_security_t *`` in this context.
The respective security schemes need to be enabled through the project configuration menu. Please refer to the Enabling protocom security version section in :doc:`Protocol Communication </api-reference/provisioning/protocomm>` for more details.
Now that we know how to start the **esp_local_ctrl** service, let us add a property to it. Each property must have a unique ``name`` (string), a ``type`` (e.g., enum), ``flags`` (bit fields) and ``size``.
The ``size`` is to be kept 0, if we want our property value to be of variable length (e.g., if its a string or bytestream). For fixed length property value data-types, like int, float, etc., setting the ``size`` field to the right value, helps **esp_local_ctrl** to perform internal checks on arguments received with write requests.
The interpretation of ``type`` and ``flags`` fields is totally upto the application, hence they may be used as enumerations, bitfields, or even simple integers. One way is to use ``type`` values to classify properties, while ``flags`` to specify characteristics of a property.
Here is an example property which is to function as a timestamp. It is assumed that the application defines ``TYPE_TIMESTAMP`` and ``READONLY``, which are used for setting the ``type`` and ``flags`` fields here.
Also notice that there is a ctx field, which is set to point to some custom ``func_get_time()``. This can be used inside the property get/set handlers to retrieve timestamp.
/* Use static variable for saving the value. This is essential because the value has to be valid even after this function returns. Alternative is to use dynamic allocation and set the free_fn field */
The client side implementation will have establish a protocomm session with the device first, over the supported mode of transport, and then send and receive protobuf messages understood by the **esp_local_ctrl** service. The service will translate these messages into requests and then call the appropriate handlers (set/get). Then, the generated response for each handler is again packed into a protobuf message and transmitted back to the client.
1.``get_prop_count`` : This should simply return the total number of properties supported by the service
2.``get_prop_values`` : This accepts an array of indices and should return the information (name, type, flags) and values of the properties corresponding to those indices
3.``set_prop_values`` : This accepts an array of indices and an array of new values, which are used for setting the values of the properties corresponding to the indices
Note that indices may or may not be the same for a property, across multiple sessions. Therefore, the client must only use the names of the properties to uniquely identify them. So, every time a new session is established, the client should first call ``get_prop_count`` and then ``get_prop_values``, hence form an index to name mapping for all properties. Now when calling ``set_prop_values`` for a set of properties, it must first convert the names to indexes, using the created mapping. As emphasized earlier, the client must refresh the index to name mapping every time a new session is established with the same device.
