MatterEndPoint

############## MatterEndPoint ##############

About

The MatterEndPoint class is the base class for all Matter endpoints. It provides common functionality for all endpoint types.

• Endpoint Management: Each endpoint has a unique endpoint ID for identification within the Matter network
• Attribute Access: Methods to get and set attribute values from Matter clusters
• Identify Cluster: Support for device identification (visual feedback like LED blinking)
• Secondary Network Interfaces: Support for multiple network interfaces (Wi-Fi, Thread, Ethernet)
• Attribute Change Callbacks: Base framework for handling attribute changes from Matter controllers

All Matter endpoint classes inherit from MatterEndPoint, providing a consistent interface and common functionality across all device types.

MatterEndPoint APIs

Endpoint Management

getEndPointId ^^^^^^^^^^^^^

Gets the current Matter Accessory endpoint ID.

.. code-block:: arduino

uint16_t getEndPointId();

This function will return the endpoint number (typically 1-254).

setEndPointId ^^^^^^^^^^^^^

Sets the current Matter Accessory endpoint ID.

.. code-block:: arduino

void setEndPointId(uint16_t ep);

• ep - Endpoint number to set

Secondary Network Interface

createSecondaryNetworkInterface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Creates a secondary network interface endpoint. This can be used for devices that support multiple network interfaces, such as Ethernet, Thread and Wi-Fi.

.. code-block:: arduino

bool createSecondaryNetworkInterface();

This function will return true if successful, false otherwise.

getSecondaryNetworkEndPointId ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the secondary network interface endpoint ID.

.. code-block:: arduino

uint16_t getSecondaryNetworkEndPointId();

This function will return the secondary network endpoint ID, or 0 if not created.

Attribute Management

getAttribute ^^^^^^^^^^^^

Gets a pointer to an attribute from its cluster ID and attribute ID.

.. code-block:: arduino

esp_matter::attribute_t *getAttribute(uint32_t cluster_id, uint32_t attribute_id);

• cluster_id - Cluster ID (e.g., OnOff::Attributes::OnOff::Id)
• attribute_id - Attribute ID (e.g., OnOff::Attributes::OnOff::Id)

This function will return a pointer to the attribute, or NULL if not found.

getAttributeVal ^^^^^^^^^^^^^^^

Gets the value of an attribute from its cluster ID and attribute ID.

.. code-block:: arduino

bool getAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal);

• cluster_id - Cluster ID
• attribute_id - Attribute ID
• attrVal - Pointer to store the attribute value

This function will return true if successful, false otherwise.

setAttributeVal ^^^^^^^^^^^^^^^

Sets the value of an attribute from its cluster ID and attribute ID.

.. code-block:: arduino

bool setAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal);

• cluster_id - Cluster ID
• attribute_id - Attribute ID
• attrVal - Pointer to the attribute value to set

This function will return true if successful, false otherwise.

updateAttributeVal ^^^^^^^^^^^^^^^^^^

Updates the value of an attribute from its cluster ID. This is typically used for read-only attributes that are updated by the device itself (e.g., sensor readings).

.. code-block:: arduino

bool updateAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal);

• cluster_id - Cluster ID
• attribute_id - Attribute ID
• attrVal - Pointer to the attribute value to update

This function will return true if successful, false otherwise.

Identify Cluster

onIdentify ^^^^^^^^^^

Sets a callback function for the Identify cluster. This callback is invoked when clients interact with the Identify Cluster of a specific endpoint.

.. code-block:: arduino

void onIdentify(EndPointIdentifyCB onEndPointIdentifyCB);

• onEndPointIdentifyCB - Function pointer to the callback function. The callback receives a boolean parameter indicating if identify is enabled.

The callback signature is:

.. code-block:: arduino

bool identifyCallback(bool identifyIsEnabled);

When identifyIsEnabled is true, the device should provide visual feedback (e.g., blink an LED). When false, the device should stop the identification feedback.

Example usage:

.. code-block:: arduino

myEndpoint.onIdentify([](bool identifyIsEnabled) {
    if (identifyIsEnabled) {
        // Start blinking LED
        digitalWrite(LED_PIN, HIGH);
    } else {
        // Stop blinking LED
        digitalWrite(LED_PIN, LOW);
    }
    return true;
});

Attribute Change Callback

attributeChangeCB ^^^^^^^^^^^^^^^^^

This function is called by the Matter internal event processor when an attribute changes. It can be overridden by the application if necessary.

.. code-block:: arduino

virtual bool attributeChangeCB(uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val);

• endpoint_id - Endpoint ID where the attribute changed
• cluster_id - Cluster ID of the changed attribute
• attribute_id - Attribute ID that changed
• val - Pointer to the new attribute value

This function should return true if the change was handled successfully, false otherwise.

All endpoint classes implement this function to handle attribute changes specific to their device type. You typically don't need to override this unless you need custom behavior.

Supported Endpoints

The Matter library provides specialized endpoint classes that inherit from MatterEndPoint. Each endpoint type includes specific clusters and functionality relevant to that device category.

.. toctree:: :maxdepth: 1 :glob:

ep_*