diff --git a/docs/en/libraries.rst b/docs/en/libraries.rst index 07f0978be68..daddca2b1d8 100644 --- a/docs/en/libraries.rst +++ b/docs/en/libraries.rst @@ -92,6 +92,17 @@ The Arduino ESP32 offers some unique APIs, described in this section: api/* +Matter APIs +----------- + +.. toctree:: + :maxdepth: 1 + :glob: + + matter/matter + matter/matter_ep + matter/ep_* + Zigbee APIs ----------- diff --git a/docs/en/matter/ep_color_light.rst b/docs/en/matter/ep_color_light.rst new file mode 100644 index 00000000000..17f9b47e817 --- /dev/null +++ b/docs/en/matter/ep_color_light.rst @@ -0,0 +1,212 @@ +################ +MatterColorLight +################ + +About +----- + +The ``MatterColorLight`` class provides a color light endpoint for Matter networks with RGB color control using the HSV color model. This endpoint implements the Matter lighting standard for full-color lighting control. + +**Features:** +* On/off control +* RGB color control with HSV color model +* State persistence support +* Callback support for state and color changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* RGB smart lights +* Color-changing lights +* Mood lighting +* Entertainment lighting control +* Smart home color automation + +API Reference +------------- + +Constructor +*********** + +MatterColorLight +^^^^^^^^^^^^^^^^ + +Creates a new Matter color light endpoint. + +.. code-block:: arduino + + MatterColorLight(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter color light endpoint with optional initial state and color. + +.. code-block:: arduino + + bool begin(bool initialState = false, espHsvColor_t colorHSV = {0, 254, 31}); + +* ``initialState`` - Initial on/off state (default: ``false`` = off) +* ``colorHSV`` - Initial HSV color (default: red 12% intensity HSV(0, 254, 31)) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter light events. + +.. code-block:: arduino + + void end(); + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the light. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +getOnOff +^^^^^^^^ + +Gets the current on/off state. + +.. code-block:: arduino + + bool getOnOff(); + +toggle +^^^^^^ + +Toggles the on/off state. + +.. code-block:: arduino + + bool toggle(); + +Color Control +************* + +setColorRGB +^^^^^^^^^^^ + +Sets the color using RGB values. + +.. code-block:: arduino + + bool setColorRGB(espRgbColor_t rgbColor); + +* ``rgbColor`` - RGB color structure with red, green, and blue values (0-255 each) + +getColorRGB +^^^^^^^^^^^ + +Gets the current color as RGB values. + +.. code-block:: arduino + + espRgbColor_t getColorRGB(); + +setColorHSV +^^^^^^^^^^^ + +Sets the color using HSV values. + +.. code-block:: arduino + + bool setColorHSV(espHsvColor_t hsvColor); + +* ``hsvColor`` - HSV color structure with hue (0-360), saturation (0-254), and value/brightness (0-254) + +getColorHSV +^^^^^^^^^^^ + +Gets the current color as HSV values. + +.. code-block:: arduino + + espHsvColor_t getColorHSV(); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback for when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState, espHsvColor_t newColor); + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback for on/off state changes. + +.. code-block:: arduino + + void onChangeOnOff(EndPointOnOffCB onChangeCB); + +onChangeColorHSV +^^^^^^^^^^^^^^^^ + +Sets a callback for color changes. + +.. code-block:: arduino + + void onChangeColorHSV(EndPointRGBColorCB onChangeCB); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the physical light state using current Matter internal state. + +.. code-block:: arduino + + void updateAccessory(); + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns current on/off state. + +.. code-block:: arduino + + operator bool(); + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns light on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Example +------- + +Color Light +*********** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterColorLight/MatterColorLight.ino + :language: arduino diff --git a/docs/en/matter/ep_color_temperature_light.rst b/docs/en/matter/ep_color_temperature_light.rst new file mode 100644 index 00000000000..2a2cfe2395e --- /dev/null +++ b/docs/en/matter/ep_color_temperature_light.rst @@ -0,0 +1,258 @@ +########################### +MatterColorTemperatureLight +########################### + +About +----- + +The ``MatterColorTemperatureLight`` class provides a color temperature light endpoint for Matter networks with brightness and color temperature control. This endpoint implements the Matter lighting standard for lights that support color temperature adjustment (warm white to cool white). + +**Features:** +* On/off control +* Brightness level control (0-255) +* Color temperature control (100-500 mireds) +* State persistence support +* Callback support for state, brightness, and temperature changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Tunable white lights +* Color temperature adjustable lights +* Smart lighting with warm/cool control +* Circadian lighting +* Smart home lighting automation + +API Reference +------------- + +Constructor +*********** + +MatterColorTemperatureLight +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter color temperature light endpoint. + +.. code-block:: arduino + + MatterColorTemperatureLight(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter color temperature light endpoint with optional initial state, brightness, and color temperature. + +.. code-block:: arduino + + bool begin(bool initialState = false, uint8_t brightness = 64, uint16_t colorTemperature = 370); + +* ``initialState`` - Initial on/off state (default: ``false`` = off) +* ``brightness`` - Initial brightness level (0-255, default: 64 = 25%) +* ``colorTemperature`` - Initial color temperature in mireds (100-500, default: 370 = Soft White) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter light events. + +.. code-block:: arduino + + void end(); + +Constants +********* + +MAX_BRIGHTNESS +^^^^^^^^^^^^^^ + +Maximum brightness value (255). + +.. code-block:: arduino + + static const uint8_t MAX_BRIGHTNESS = 255; + +MAX_COLOR_TEMPERATURE +^^^^^^^^^^^^^^^^^^^^^ + +Maximum color temperature value (500 mireds = cool white). + +.. code-block:: arduino + + static const uint16_t MAX_COLOR_TEMPERATURE = 500; + +MIN_COLOR_TEMPERATURE +^^^^^^^^^^^^^^^^^^^^^ + +Minimum color temperature value (100 mireds = warm white). + +.. code-block:: arduino + + static const uint16_t MIN_COLOR_TEMPERATURE = 100; + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the light. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +getOnOff +^^^^^^^^ + +Gets the current on/off state. + +.. code-block:: arduino + + bool getOnOff(); + +toggle +^^^^^^ + +Toggles the on/off state. + +.. code-block:: arduino + + bool toggle(); + +Brightness Control +****************** + +setBrightness +^^^^^^^^^^^^^ + +Sets the brightness level. + +.. code-block:: arduino + + bool setBrightness(uint8_t newBrightness); + +* ``newBrightness`` - Brightness level (0-255) + +getBrightness +^^^^^^^^^^^^^ + +Gets the current brightness level. + +.. code-block:: arduino + + uint8_t getBrightness(); + +Color Temperature Control +************************* + +setColorTemperature +^^^^^^^^^^^^^^^^^^^ + +Sets the color temperature. + +.. code-block:: arduino + + bool setColorTemperature(uint16_t newTemperature); + +* ``newTemperature`` - Color temperature in mireds (100-500) + +**Note:** Color temperature is measured in mireds (micro reciprocal degrees). Lower values (100-200) are warm white, higher values (400-500) are cool white. + +getColorTemperature +^^^^^^^^^^^^^^^^^^^ + +Gets the current color temperature. + +.. code-block:: arduino + + uint16_t getColorTemperature(); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback for when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState, uint8_t newBrightness, uint16_t newTemperature); + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback for on/off state changes. + +.. code-block:: arduino + + void onChangeOnOff(EndPointOnOffCB onChangeCB); + +onChangeBrightness +^^^^^^^^^^^^^^^^^^ + +Sets a callback for brightness changes. + +.. code-block:: arduino + + void onChangeBrightness(EndPointBrightnessCB onChangeCB); + +onChangeColorTemperature +^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for color temperature changes. + +.. code-block:: arduino + + void onChangeColorTemperature(EndPointTemperatureCB onChangeCB); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the physical light state using current Matter internal state. + +.. code-block:: arduino + + void updateAccessory(); + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns current on/off state. + +.. code-block:: arduino + + operator bool(); + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns light on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Example +------- + +Color Temperature Light +*********************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterTemperatureLight/MatterTemperatureLight.ino + :language: arduino diff --git a/docs/en/matter/ep_contact_sensor.rst b/docs/en/matter/ep_contact_sensor.rst new file mode 100644 index 00000000000..cdb5e131936 --- /dev/null +++ b/docs/en/matter/ep_contact_sensor.rst @@ -0,0 +1,137 @@ +################### +MatterContactSensor +################### + +About +----- + +The ``MatterContactSensor`` class provides a contact sensor endpoint for Matter networks. This endpoint implements the Matter contact sensing standard for detecting open/closed states (e.g., doors, windows). + +**Features:** +* Contact state reporting (open/closed) +* Simple boolean state +* Read-only sensor (no control functionality) +* Automatic state updates +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Door/window sensors +* Contact switches +* Security systems +* Access control +* Smart home automation triggers + +API Reference +------------- + +Constructor +*********** + +MatterContactSensor +^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter contact sensor endpoint. + +.. code-block:: arduino + + MatterContactSensor(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter contact sensor endpoint with an initial contact state. + +.. code-block:: arduino + + bool begin(bool _contactState = false); + +* ``_contactState`` - Initial contact state (``true`` = closed, ``false`` = open, default: ``false``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter contact sensor events. + +.. code-block:: arduino + + void end(); + +Contact State Control +********************* + +setContact +^^^^^^^^^^ + +Sets the contact state. + +.. code-block:: arduino + + bool setContact(bool _contactState); + +* ``_contactState`` - Contact state (``true`` = closed, ``false`` = open) + +This function will return ``true`` if successful, ``false`` otherwise. + +getContact +^^^^^^^^^^ + +Gets the current contact state. + +.. code-block:: arduino + + bool getContact(); + +This function will return ``true`` if closed, ``false`` if open. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns the current contact state. + +.. code-block:: arduino + + operator bool(); + +Example: + +.. code-block:: arduino + + if (mySensor) { + Serial.println("Contact is closed"); + } else { + Serial.println("Contact is open"); + } + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the contact state. + +.. code-block:: arduino + + void operator=(bool _contactState); + +Example: + +.. code-block:: arduino + + mySensor = true; // Set contact to closed + mySensor = false; // Set contact to open + +Example +------- + +Contact Sensor +************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterContactSensor/MatterContactSensor.ino + :language: arduino diff --git a/docs/en/matter/ep_dimmable_light.rst b/docs/en/matter/ep_dimmable_light.rst new file mode 100644 index 00000000000..7a442e4e4dc --- /dev/null +++ b/docs/en/matter/ep_dimmable_light.rst @@ -0,0 +1,236 @@ +################### +MatterDimmableLight +################### + +About +----- + +The ``MatterDimmableLight`` class provides a dimmable light endpoint for Matter networks. This endpoint implements the Matter lighting standard for lights with brightness control. + +**Features:** +* On/off control +* Brightness level control (0-255) +* State persistence support +* Callback support for state and brightness changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Dimmable smart lights +* Brightness control switches +* Smart home lighting automation +* Variable brightness lighting + +API Reference +------------- + +Constructor +*********** + +MatterDimmableLight +^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter dimmable light endpoint. + +.. code-block:: arduino + + MatterDimmableLight(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter dimmable light endpoint with optional initial state and brightness. + +.. code-block:: arduino + + bool begin(bool initialState = false, uint8_t brightness = 64); + +* ``initialState`` - Initial on/off state (``true`` = on, ``false`` = off, default: ``false``) +* ``brightness`` - Initial brightness level (0-255, default: 64 = 25%) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter light events. + +.. code-block:: arduino + + void end(); + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the light. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +* ``newState`` - New state (``true`` = on, ``false`` = off) + +This function will return ``true`` if successful, ``false`` otherwise. + +getOnOff +^^^^^^^^ + +Gets the current on/off state of the light. + +.. code-block:: arduino + + bool getOnOff(); + +This function will return ``true`` if the light is on, ``false`` if off. + +toggle +^^^^^^ + +Toggles the on/off state of the light. + +.. code-block:: arduino + + bool toggle(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Brightness Control +****************** + +setBrightness +^^^^^^^^^^^^^ + +Sets the brightness level of the light. + +.. code-block:: arduino + + bool setBrightness(uint8_t newBrightness); + +* ``newBrightness`` - New brightness level (0-255, where 0 = off, 255 = maximum brightness) + +This function will return ``true`` if successful, ``false`` otherwise. + +getBrightness +^^^^^^^^^^^^^ + +Gets the current brightness level of the light. + +.. code-block:: arduino + + uint8_t getBrightness(); + +This function will return the brightness level (0-255). + +Constants +********* + +MAX_BRIGHTNESS +^^^^^^^^^^^^^^ + +Maximum brightness value constant. + +.. code-block:: arduino + + static const uint8_t MAX_BRIGHTNESS = 255; + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns the current on/off state of the light. + +.. code-block:: arduino + + operator bool(); + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns the light on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback function to be called when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +* ``onChangeCB`` - Function to call when state changes + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState, uint8_t newBrightness); + +* ``newState`` - New on/off state +* ``newBrightness`` - New brightness level (0-255) + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback function to be called when the on/off state changes. + +.. code-block:: arduino + + void onChangeOnOff(EndPointOnOffCB onChangeCB); + +* ``onChangeCB`` - Function to call when on/off state changes + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState); + +onChangeBrightness +^^^^^^^^^^^^^^^^^^ + +Sets a callback function to be called when the brightness level changes. + +.. code-block:: arduino + + void onChangeBrightness(EndPointBrightnessCB onChangeCB); + +* ``onChangeCB`` - Function to call when brightness changes + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(uint8_t newBrightness); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the state of the light using the current Matter Light internal state. + +.. code-block:: arduino + + void updateAccessory(); + +Example +------- + +Dimmable Light +************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterDimmableLight/MatterDimmableLight.ino + :language: arduino diff --git a/docs/en/matter/ep_enhanced_color_light.rst b/docs/en/matter/ep_enhanced_color_light.rst new file mode 100644 index 00000000000..3463c1c9d02 --- /dev/null +++ b/docs/en/matter/ep_enhanced_color_light.rst @@ -0,0 +1,303 @@ +######################## +MatterEnhancedColorLight +######################## + +About +----- + +The ``MatterEnhancedColorLight`` class provides an enhanced color light endpoint for Matter networks with full RGB color control, brightness, and color temperature. This endpoint implements the Matter lighting standard for advanced color lighting with all features. + +**Features:** +* On/off control +* RGB color control with HSV color model +* Brightness level control (0-255) +* Color temperature control (100-500 mireds) +* State persistence support +* Callback support for all parameter changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Full-featured RGB smart lights +* Advanced color and temperature control +* Mood lighting with all features +* Entertainment lighting +* Circadian lighting with color temperature +* Smart home advanced lighting automation + +API Reference +------------- + +Constructor +*********** + +MatterEnhancedColorLight +^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter enhanced color light endpoint. + +.. code-block:: arduino + + MatterEnhancedColorLight(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter enhanced color light endpoint with optional initial state, color, brightness, and color temperature. + +.. code-block:: arduino + + bool begin(bool initialState = false, espHsvColor_t colorHSV = {21, 216, 25}, uint8_t newBrightness = 25, uint16_t colorTemperature = 454); + +* ``initialState`` - Initial on/off state (default: ``false`` = off) +* ``colorHSV`` - Initial HSV color (default: HSV(21, 216, 25) = warm white) +* ``newBrightness`` - Initial brightness level (0-255, default: 25 = 10%) +* ``colorTemperature`` - Initial color temperature in mireds (100-500, default: 454 = Warm White) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter light events. + +.. code-block:: arduino + + void end(); + +Constants +********* + +MAX_BRIGHTNESS +^^^^^^^^^^^^^^ + +Maximum brightness value (255). + +.. code-block:: arduino + + static const uint8_t MAX_BRIGHTNESS = 255; + +MAX_COLOR_TEMPERATURE +^^^^^^^^^^^^^^^^^^^^^ + +Maximum color temperature value (500 mireds = cool white). + +.. code-block:: arduino + + static const uint16_t MAX_COLOR_TEMPERATURE = 500; + +MIN_COLOR_TEMPERATURE +^^^^^^^^^^^^^^^^^^^^^ + +Minimum color temperature value (100 mireds = warm white). + +.. code-block:: arduino + + static const uint16_t MIN_COLOR_TEMPERATURE = 100; + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the light. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +getOnOff +^^^^^^^^ + +Gets the current on/off state. + +.. code-block:: arduino + + bool getOnOff(); + +toggle +^^^^^^ + +Toggles the on/off state. + +.. code-block:: arduino + + bool toggle(); + +Color Control +************* + +setColorRGB +^^^^^^^^^^^ + +Sets the color using RGB values. + +.. code-block:: arduino + + bool setColorRGB(espRgbColor_t rgbColor); + +getColorRGB +^^^^^^^^^^^ + +Gets the current color as RGB values. + +.. code-block:: arduino + + espRgbColor_t getColorRGB(); + +setColorHSV +^^^^^^^^^^^ + +Sets the color using HSV values. + +.. code-block:: arduino + + bool setColorHSV(espHsvColor_t hsvColor); + +getColorHSV +^^^^^^^^^^^ + +Gets the current color as HSV values. + +.. code-block:: arduino + + espHsvColor_t getColorHSV(); + +Brightness Control +****************** + +setBrightness +^^^^^^^^^^^^^ + +Sets the brightness level. + +.. code-block:: arduino + + bool setBrightness(uint8_t newBrightness); + +getBrightness +^^^^^^^^^^^^^ + +Gets the current brightness level. + +.. code-block:: arduino + + uint8_t getBrightness(); + +Color Temperature Control +************************* + +setColorTemperature +^^^^^^^^^^^^^^^^^^^^ + +Sets the color temperature. + +.. code-block:: arduino + + bool setColorTemperature(uint16_t newTemperature); + +getColorTemperature +^^^^^^^^^^^^^^^^^^^ + +Gets the current color temperature. + +.. code-block:: arduino + + uint16_t getColorTemperature(); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback for when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState, espHsvColor_t newColor, uint8_t newBrightness, uint16_t newTemperature); + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback for on/off state changes. + +.. code-block:: arduino + + void onChangeOnOff(EndPointOnOffCB onChangeCB); + +onChangeBrightness +^^^^^^^^^^^^^^^^^^ + +Sets a callback for brightness changes. + +.. code-block:: arduino + + void onChangeBrightness(EndPointBrightnessCB onChangeCB); + +onChangeColorHSV +^^^^^^^^^^^^^^^^ + +Sets a callback for color changes. + +.. code-block:: arduino + + void onChangeColorHSV(EndPointRGBColorCB onChangeCB); + +onChangeColorTemperature +^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for color temperature changes. + +.. code-block:: arduino + + void onChangeColorTemperature(EndPointTemperatureCB onChangeCB); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the physical light state using current Matter internal state. + +.. code-block:: arduino + + void updateAccessory(); + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns current on/off state. + +.. code-block:: arduino + + operator bool(); + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns light on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Example +------- + +Enhanced Color Light +******************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterEnhancedColorLight/MatterEnhancedColorLight.ino + :language: arduino diff --git a/docs/en/matter/ep_fan.rst b/docs/en/matter/ep_fan.rst new file mode 100644 index 00000000000..8abc9d2933e --- /dev/null +++ b/docs/en/matter/ep_fan.rst @@ -0,0 +1,292 @@ +######### +MatterFan +######### + +About +----- + +The ``MatterFan`` class provides a fan endpoint for Matter networks with speed and mode control. This endpoint implements the Matter fan control standard. + +**Features:** +* On/off control +* Fan speed control (0-100%) +* Fan mode control (OFF, LOW, MEDIUM, HIGH, ON, AUTO, SMART) +* Fan mode sequence configuration +* Callback support for state, speed, and mode changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Smart ceiling fans +* Exhaust fans +* Ventilation fans +* Fan speed controllers +* HVAC fan control + +API Reference +------------- + +Constructor +*********** + +MatterFan +^^^^^^^^^ + +Creates a new Matter fan endpoint. + +.. code-block:: arduino + + MatterFan(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter fan endpoint with optional initial speed, mode, and mode sequence. + +.. code-block:: arduino + + bool begin(uint8_t percent = 0, FanMode_t fanMode = FAN_MODE_OFF, FanModeSequence_t fanModeSeq = FAN_MODE_SEQ_OFF_HIGH); + +* ``percent`` - Initial speed percentage (0-100, default: 0) +* ``fanMode`` - Initial fan mode (default: ``FAN_MODE_OFF``) +* ``fanModeSeq`` - Fan mode sequence configuration (default: ``FAN_MODE_SEQ_OFF_HIGH``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter fan events. + +.. code-block:: arduino + + void end(); + +Constants +********* + +MAX_SPEED +^^^^^^^^^ + +Maximum speed value (100%). + +.. code-block:: arduino + + static const uint8_t MAX_SPEED = 100; + +MIN_SPEED +^^^^^^^^^ + +Minimum speed value (1%). + +.. code-block:: arduino + + static const uint8_t MIN_SPEED = 1; + +OFF_SPEED +^^^^^^^^^ + +Speed value when fan is off (0%). + +.. code-block:: arduino + + static const uint8_t OFF_SPEED = 0; + +Fan Modes +********* + +FanMode_t +^^^^^^^^^ + +Fan mode enumeration: + +* ``FAN_MODE_OFF`` - Fan is off +* ``FAN_MODE_LOW`` - Low speed +* ``FAN_MODE_MEDIUM`` - Medium speed +* ``FAN_MODE_HIGH`` - High speed +* ``FAN_MODE_ON`` - Fan is on +* ``FAN_MODE_AUTO`` - Auto mode +* ``FAN_MODE_SMART`` - Smart mode + +Fan Mode Sequences +****************** + +FanModeSequence_t +^^^^^^^^^^^^^^^^^ + +Fan mode sequence enumeration: + +* ``FAN_MODE_SEQ_OFF_LOW_MED_HIGH`` - OFF, LOW, MEDIUM, HIGH +* ``FAN_MODE_SEQ_OFF_LOW_HIGH`` - OFF, LOW, HIGH +* ``FAN_MODE_SEQ_OFF_LOW_MED_HIGH_AUTO`` - OFF, LOW, MEDIUM, HIGH, AUTO +* ``FAN_MODE_SEQ_OFF_LOW_HIGH_AUTO`` - OFF, LOW, HIGH, AUTO +* ``FAN_MODE_SEQ_OFF_HIGH_AUTO`` - OFF, HIGH, AUTO +* ``FAN_MODE_SEQ_OFF_HIGH`` - OFF, HIGH + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the fan. + +.. code-block:: arduino + + bool setOnOff(bool newState, bool performUpdate = true); + +* ``newState`` - New state (``true`` = on, ``false`` = off) +* ``performUpdate`` - Perform update after setting (default: ``true``) + +getOnOff +^^^^^^^^ + +Gets the current on/off state. + +.. code-block:: arduino + + bool getOnOff(); + +toggle +^^^^^^ + +Toggles the on/off state. + +.. code-block:: arduino + + bool toggle(bool performUpdate = true); + +Speed Control +************* + +setSpeedPercent +^^^^^^^^^^^^^^^ + +Sets the fan speed percentage. + +.. code-block:: arduino + + bool setSpeedPercent(uint8_t newPercent, bool performUpdate = true); + +* ``newPercent`` - Speed percentage (0-100) +* ``performUpdate`` - Perform update after setting (default: ``true``) + +getSpeedPercent +^^^^^^^^^^^^^^^ + +Gets the current speed percentage. + +.. code-block:: arduino + + uint8_t getSpeedPercent(); + +Mode Control +************ + +setMode +^^^^^^^ + +Sets the fan mode. + +.. code-block:: arduino + + bool setMode(FanMode_t newMode, bool performUpdate = true); + +* ``newMode`` - Fan mode to set +* ``performUpdate`` - Perform update after setting (default: ``true``) + +getMode +^^^^^^^ + +Gets the current fan mode. + +.. code-block:: arduino + + FanMode_t getMode(); + +getFanModeString +^^^^^^^^^^^^^^^^ + +Gets a friendly string for the fan mode. + +.. code-block:: arduino + + static const char *getFanModeString(uint8_t mode); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback for when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(FanMode_t newMode, uint8_t newPercent); + +onChangeMode +^^^^^^^^^^^^ + +Sets a callback for mode changes. + +.. code-block:: arduino + + void onChangeMode(EndPointModeCB onChangeCB); + +onChangeSpeedPercent +^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for speed changes. + +.. code-block:: arduino + + void onChangeSpeedPercent(EndPointSpeedCB onChangeCB); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the physical fan state using current Matter internal state. + +.. code-block:: arduino + + void updateAccessory(); + +Operators +********* + +uint8_t operator +^^^^^^^^^^^^^^^^ + +Returns the current speed percentage. + +.. code-block:: arduino + + operator uint8_t(); + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the speed percentage. + +.. code-block:: arduino + + void operator=(uint8_t speedPercent); + +Example +------- + +Fan Control +*********** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterFan/MatterFan.ino + :language: arduino diff --git a/docs/en/matter/ep_generic_switch.rst b/docs/en/matter/ep_generic_switch.rst new file mode 100644 index 00000000000..902133dce4e --- /dev/null +++ b/docs/en/matter/ep_generic_switch.rst @@ -0,0 +1,94 @@ +################### +MatterGenericSwitch +################### + +About +----- + +The ``MatterGenericSwitch`` class provides a generic switch endpoint for Matter networks. This endpoint works as a smart button that can send click events to the Matter controller, enabling automation triggers. + +**Features:** +* Click event reporting to Matter controller +* Simple button functionality +* Automation trigger support +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Smart buttons +* Automation triggers +* Remote controls +* Scene activation buttons +* Event generators for smart home automation + +API Reference +------------- + +Constructor +*********** + +MatterGenericSwitch +^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter generic switch endpoint. + +.. code-block:: arduino + + MatterGenericSwitch(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter generic switch endpoint. + +.. code-block:: arduino + + bool begin(); + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter switch events. + +.. code-block:: arduino + + void end(); + +Event Generation +**************** + +click +^^^^^ + +Sends a click event to the Matter controller. + +.. code-block:: arduino + + void click(); + +This function sends a click event that can be used to trigger automations in smart home apps. The event is sent immediately and the Matter controller will receive it. + +**Usage Example:** + +When a physical button is pressed and released, call this function to send the click event: + +.. code-block:: arduino + + if (buttonReleased) { + mySwitch.click(); + Serial.println("Click event sent to Matter controller"); + } + +Example +------- + +Generic Switch (Smart Button) +***************************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterSmartButton/MatterSmartButton.ino + :language: arduino diff --git a/docs/en/matter/ep_humidity_sensor.rst b/docs/en/matter/ep_humidity_sensor.rst new file mode 100644 index 00000000000..d680f157c84 --- /dev/null +++ b/docs/en/matter/ep_humidity_sensor.rst @@ -0,0 +1,136 @@ +#################### +MatterHumiditySensor +#################### + +About +----- + +The ``MatterHumiditySensor`` class provides a humidity sensor endpoint for Matter networks. This endpoint implements the Matter humidity sensing standard for read-only humidity reporting. + +**Features:** +* Humidity measurement reporting (0-100%) +* 1/100th percent precision +* Read-only sensor (no control functionality) +* Automatic humidity updates +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Room humidity monitoring +* Weather stations +* HVAC systems +* Humidity logging +* Smart home climate monitoring + +API Reference +------------- + +Constructor +*********** + +MatterHumiditySensor +^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter humidity sensor endpoint. + +.. code-block:: arduino + + MatterHumiditySensor(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter humidity sensor endpoint with an initial humidity value. + +.. code-block:: arduino + + bool begin(double humidityPercent = 0.00); + +* ``humidityPercent`` - Initial humidity percentage (0.0-100.0, default: 0.00) + +This function will return ``true`` if successful, ``false`` otherwise. + +**Note:** The implementation stores humidity with 1/100th percent precision internally. Values must be between 0.0 and 100.0. + +end +^^^ + +Stops processing Matter humidity sensor events. + +.. code-block:: arduino + + void end(); + +Humidity Control +**************** + +setHumidity +^^^^^^^^^^^ + +Sets the reported humidity percentage. + +.. code-block:: arduino + + bool setHumidity(double humidityPercent); + +* ``humidityPercent`` - Humidity percentage (0.0-100.0) + +This function will return ``true`` if successful, ``false`` otherwise. + +**Note:** Humidity is stored with 1/100th percent precision. Values outside the 0.0-100.0 range will be rejected. + +getHumidity +^^^^^^^^^^^ + +Gets the current reported humidity percentage. + +.. code-block:: arduino + + double getHumidity(); + +This function will return the humidity percentage with 1/100th percent precision. + +Operators +********* + +double operator +^^^^^^^^^^^^^^^ + +Returns the current humidity percentage. + +.. code-block:: arduino + + operator double(); + +Example: + +.. code-block:: arduino + + double humidity = mySensor; // Get current humidity + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the humidity percentage. + +.. code-block:: arduino + + void operator=(double humidityPercent); + +Example: + +.. code-block:: arduino + + mySensor = 45.5; // Set humidity to 45.5% + +Example +------- + +Humidity Sensor +*************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterHumiditySensor/MatterHumiditySensor.ino + :language: arduino diff --git a/docs/en/matter/ep_occupancy_sensor.rst b/docs/en/matter/ep_occupancy_sensor.rst new file mode 100644 index 00000000000..456cafccefe --- /dev/null +++ b/docs/en/matter/ep_occupancy_sensor.rst @@ -0,0 +1,152 @@ +##################### +MatterOccupancySensor +##################### + +About +----- + +The ``MatterOccupancySensor`` class provides an occupancy sensor endpoint for Matter networks. This endpoint implements the Matter occupancy sensing standard for detecting occupied/unoccupied states (e.g., motion sensors, PIR sensors). + +**Features:** +* Occupancy state reporting (occupied/unoccupied) +* Multiple sensor type support (PIR, Ultrasonic, Physical Contact) +* Simple boolean state +* Read-only sensor (no control functionality) +* Automatic state updates +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Motion sensors (PIR) +* Occupancy detection +* Security systems +* Smart lighting automation +* Energy management (turn off lights when unoccupied) + +API Reference +------------- + +Constructor +*********** + +MatterOccupancySensor +^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter occupancy sensor endpoint. + +.. code-block:: arduino + + MatterOccupancySensor(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter occupancy sensor endpoint with an initial occupancy state and sensor type. + +.. code-block:: arduino + + bool begin(bool _occupancyState = false, OccupancySensorType_t _occupancySensorType = OCCUPANCY_SENSOR_TYPE_PIR); + +* ``_occupancyState`` - Initial occupancy state (``true`` = occupied, ``false`` = unoccupied, default: ``false``) +* ``_occupancySensorType`` - Sensor type (default: ``OCCUPANCY_SENSOR_TYPE_PIR``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter occupancy sensor events. + +.. code-block:: arduino + + void end(); + +Sensor Types +************ + +OccupancySensorType_t +^^^^^^^^^^^^^^^^^^^^^^ + +Occupancy sensor type enumeration: + +* ``OCCUPANCY_SENSOR_TYPE_PIR`` - Passive Infrared (PIR) sensor +* ``OCCUPANCY_SENSOR_TYPE_ULTRASONIC`` - Ultrasonic sensor +* ``OCCUPANCY_SENSOR_TYPE_PIR_AND_ULTRASONIC`` - Combined PIR and Ultrasonic +* ``OCCUPANCY_SENSOR_TYPE_PHYSICAL_CONTACT`` - Physical contact sensor + +Occupancy State Control +*********************** + +setOccupancy +^^^^^^^^^^^^ + +Sets the occupancy state. + +.. code-block:: arduino + + bool setOccupancy(bool _occupancyState); + +* ``_occupancyState`` - Occupancy state (``true`` = occupied, ``false`` = unoccupied) + +This function will return ``true`` if successful, ``false`` otherwise. + +getOccupancy +^^^^^^^^^^^^ + +Gets the current occupancy state. + +.. code-block:: arduino + + bool getOccupancy(); + +This function will return ``true`` if occupied, ``false`` if unoccupied. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns the current occupancy state. + +.. code-block:: arduino + + operator bool(); + +Example: + +.. code-block:: arduino + + if (mySensor) { + Serial.println("Room is occupied"); + } else { + Serial.println("Room is unoccupied"); + } + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the occupancy state. + +.. code-block:: arduino + + void operator=(bool _occupancyState); + +Example: + +.. code-block:: arduino + + mySensor = true; // Set to occupied + mySensor = false; // Set to unoccupied + +Example +------- + +Occupancy Sensor +**************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterOccupancySensor/MatterOccupancySensor.ino + :language: arduino diff --git a/docs/en/matter/ep_on_off_light.rst b/docs/en/matter/ep_on_off_light.rst new file mode 100644 index 00000000000..8d30851ea1b --- /dev/null +++ b/docs/en/matter/ep_on_off_light.rst @@ -0,0 +1,190 @@ +################ +MatterOnOffLight +################ + +About +----- + +The ``MatterOnOffLight`` class provides a simple on/off light endpoint for Matter networks. This endpoint implements the Matter lighting standard for basic light control without dimming or color features. + +**Features:** +* Simple on/off control +* State persistence support +* Callback support for state changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Simple smart lights +* On/off switches +* Basic lighting control +* Smart home automation + +API Reference +------------- + +Constructor +*********** + +MatterOnOffLight +^^^^^^^^^^^^^^^^ + +Creates a new Matter on/off light endpoint. + +.. code-block:: arduino + + MatterOnOffLight(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter on/off light endpoint with an optional initial state. + +.. code-block:: arduino + + bool begin(bool initialState = false); + +* ``initialState`` - Initial on/off state (``true`` = on, ``false`` = off, default: ``false``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter light events. This will just stop processing Light Matter events but won't remove the endpoint. + +.. code-block:: arduino + + void end(); + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the light. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +* ``newState`` - New state (``true`` = on, ``false`` = off) + +This function will return ``true`` if successful, ``false`` otherwise. + +getOnOff +^^^^^^^^ + +Gets the current on/off state of the light. + +.. code-block:: arduino + + bool getOnOff(); + +This function will return ``true`` if the light is on, ``false`` if off. + +toggle +^^^^^^ + +Toggles the on/off state of the light. + +.. code-block:: arduino + + bool toggle(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns the current on/off state of the light. + +.. code-block:: arduino + + operator bool(); + +Example: + +.. code-block:: arduino + + if (myLight) { + Serial.println("Light is on"); + } + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns the light on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Example: + +.. code-block:: arduino + + myLight = true; // Turn light on + myLight = false; // Turn light off + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback function to be called when the light state changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +* ``onChangeCB`` - Function to call when state changes + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState); + +* ``newState`` - New on/off state (``true`` = on, ``false`` = off) + +The callback should return ``true`` if the change was handled successfully. + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback function to be called when the on/off state changes (same as ``onChange``). + +.. code-block:: arduino + + void onChangeOnOff(EndPointCB onChangeCB); + +* ``onChangeCB`` - Function to call when state changes + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the state of the light using the current Matter Light internal state. It is necessary to set a user callback function using ``onChange()`` to handle the physical light state. + +.. code-block:: arduino + + void updateAccessory(); + +This function will call the registered callback with the current state. + +Example +------- + +Basic On/Off Light +****************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterOnOffLight/MatterOnOffLight.ino + :language: arduino diff --git a/docs/en/matter/ep_on_off_plugin.rst b/docs/en/matter/ep_on_off_plugin.rst new file mode 100644 index 00000000000..dee2b040492 --- /dev/null +++ b/docs/en/matter/ep_on_off_plugin.rst @@ -0,0 +1,187 @@ +################# +MatterOnOffPlugin +################# + +About +----- + +The ``MatterOnOffPlugin`` class provides an on/off plugin unit endpoint for Matter networks. This endpoint implements the Matter on/off plugin standard for controlling power outlets, relays, and other on/off devices. + +**Features:** +* Simple on/off control +* State persistence support +* Callback support for state changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Smart power outlets +* Relay control +* Power switches +* Smart plugs +* On/off device control + +API Reference +------------- + +Constructor +*********** + +MatterOnOffPlugin +^^^^^^^^^^^^^^^^^ + +Creates a new Matter on/off plugin endpoint. + +.. code-block:: arduino + + MatterOnOffPlugin(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter on/off plugin endpoint with an optional initial state. + +.. code-block:: arduino + + bool begin(bool initialState = false); + +* ``initialState`` - Initial on/off state (``true`` = on, ``false`` = off, default: ``false``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter plugin events. + +.. code-block:: arduino + + void end(); + +On/Off Control +************** + +setOnOff +^^^^^^^^ + +Sets the on/off state of the plugin. + +.. code-block:: arduino + + bool setOnOff(bool newState); + +* ``newState`` - New state (``true`` = on, ``false`` = off) + +This function will return ``true`` if successful, ``false`` otherwise. + +getOnOff +^^^^^^^^ + +Gets the current on/off state of the plugin. + +.. code-block:: arduino + + bool getOnOff(); + +This function will return ``true`` if the plugin is on, ``false`` if off. + +toggle +^^^^^^ + +Toggles the on/off state of the plugin. + +.. code-block:: arduino + + bool toggle(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Operators +********* + +bool operator +^^^^^^^^^^^^^ + +Returns the current on/off state of the plugin. + +.. code-block:: arduino + + operator bool(); + +Example: + +.. code-block:: arduino + + if (myPlugin) { + Serial.println("Plugin is on"); + } + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Turns the plugin on or off. + +.. code-block:: arduino + + void operator=(bool state); + +Example: + +.. code-block:: arduino + + myPlugin = true; // Turn plugin on + myPlugin = false; // Turn plugin off + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback function to be called when the plugin state changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +* ``onChangeCB`` - Function to call when state changes + +The callback signature is: + +.. code-block:: arduino + + bool onChangeCallback(bool newState); + +* ``newState`` - New on/off state (``true`` = on, ``false`` = off) + +onChangeOnOff +^^^^^^^^^^^^^ + +Sets a callback function to be called when the on/off state changes (same as ``onChange``). + +.. code-block:: arduino + + void onChangeOnOff(EndPointCB onChangeCB); + +updateAccessory +^^^^^^^^^^^^^^^ + +Updates the state of the plugin using the current Matter Plugin internal state. + +.. code-block:: arduino + + void updateAccessory(); + +This function will call the registered callback with the current state. + +Example +------- + +On/Off Plugin +************* + +.. literalinclude:: ../../../libraries/Matter/examples/MatterOnOffPlugin/MatterOnOffPlugin.ino + :language: arduino diff --git a/docs/en/matter/ep_pressure_sensor.rst b/docs/en/matter/ep_pressure_sensor.rst new file mode 100644 index 00000000000..713d43c5d7e --- /dev/null +++ b/docs/en/matter/ep_pressure_sensor.rst @@ -0,0 +1,133 @@ +#################### +MatterPressureSensor +#################### + +About +----- + +The ``MatterPressureSensor`` class provides a pressure sensor endpoint for Matter networks. This endpoint implements the Matter pressure sensing standard for read-only pressure reporting. + +**Features:** +* Pressure measurement reporting in hectopascals (hPa) +* Read-only sensor (no control functionality) +* Automatic pressure updates +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Atmospheric pressure monitoring +* Weather stations +* Barometric pressure sensors +* Pressure logging +* Smart home weather monitoring + +API Reference +------------- + +Constructor +*********** + +MatterPressureSensor +^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter pressure sensor endpoint. + +.. code-block:: arduino + + MatterPressureSensor(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter pressure sensor endpoint with an initial pressure value. + +.. code-block:: arduino + + bool begin(double pressure = 0.00); + +* ``pressure`` - Initial pressure in hectopascals (hPa, default: 0.00) + +This function will return ``true`` if successful, ``false`` otherwise. + +**Note:** Typical atmospheric pressure at sea level is around 1013.25 hPa. Pressure values typically range from 950-1050 hPa. + +end +^^^ + +Stops processing Matter pressure sensor events. + +.. code-block:: arduino + + void end(); + +Pressure Control +**************** + +setPressure +^^^^^^^^^^^ + +Sets the reported pressure value. + +.. code-block:: arduino + + bool setPressure(double pressure); + +* ``pressure`` - Pressure in hectopascals (hPa) + +This function will return ``true`` if successful, ``false`` otherwise. + +getPressure +^^^^^^^^^^^ + +Gets the current reported pressure value. + +.. code-block:: arduino + + double getPressure(); + +This function will return the pressure in hectopascals (hPa). + +Operators +********* + +double operator +^^^^^^^^^^^^^^^ + +Returns the current pressure. + +.. code-block:: arduino + + operator double(); + +Example: + +.. code-block:: arduino + + double pressure = mySensor; // Get current pressure + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the pressure value. + +.. code-block:: arduino + + void operator=(double pressure); + +Example: + +.. code-block:: arduino + + mySensor = 1013.25; // Set pressure to 1013.25 hPa + +Example +------- + +Pressure Sensor +*************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterPressureSensor/MatterPressureSensor.ino + :language: arduino diff --git a/docs/en/matter/ep_temperature_sensor.rst b/docs/en/matter/ep_temperature_sensor.rst new file mode 100644 index 00000000000..0202ba54395 --- /dev/null +++ b/docs/en/matter/ep_temperature_sensor.rst @@ -0,0 +1,136 @@ +####################### +MatterTemperatureSensor +####################### + +About +----- + +The ``MatterTemperatureSensor`` class provides a temperature sensor endpoint for Matter networks. This endpoint implements the Matter temperature sensing standard for read-only temperature reporting. + +**Features:** +* Temperature measurement reporting in Celsius +* 1/100th degree Celsius precision +* Read-only sensor (no control functionality) +* Automatic temperature updates +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* Room temperature monitoring +* Weather stations +* HVAC systems +* Temperature logging +* Smart home climate monitoring + +API Reference +------------- + +Constructor +*********** + +MatterTemperatureSensor +^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Matter temperature sensor endpoint. + +.. code-block:: arduino + + MatterTemperatureSensor(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter temperature sensor endpoint with an initial temperature value. + +.. code-block:: arduino + + bool begin(double temperature = 0.00); + +* ``temperature`` - Initial temperature in Celsius (default: 0.00) + +This function will return ``true`` if successful, ``false`` otherwise. + +**Note:** The implementation stores temperature with 1/100th degree Celsius precision internally. + +end +^^^ + +Stops processing Matter temperature sensor events. + +.. code-block:: arduino + + void end(); + +Temperature Control +******************* + +setTemperature +^^^^^^^^^^^^^^ + +Sets the reported temperature value. + +.. code-block:: arduino + + bool setTemperature(double temperature); + +* ``temperature`` - Temperature in Celsius + +This function will return ``true`` if successful, ``false`` otherwise. + +**Note:** Temperature is stored with 1/100th degree Celsius precision. The valid range is typically -273.15°C (absolute zero) to 327.67°C. + +getTemperature +^^^^^^^^^^^^^^ + +Gets the current reported temperature value. + +.. code-block:: arduino + + double getTemperature(); + +This function will return the temperature in Celsius with 1/100th degree precision. + +Operators +********* + +double operator +^^^^^^^^^^^^^^^ + +Returns the current temperature. + +.. code-block:: arduino + + operator double(); + +Example: + +.. code-block:: arduino + + double temp = mySensor; // Get current temperature + +Assignment operator +^^^^^^^^^^^^^^^^^^^ + +Sets the temperature value. + +.. code-block:: arduino + + void operator=(double temperature); + +Example: + +.. code-block:: arduino + + mySensor = 25.5; // Set temperature to 25.5°C + +Example +------- + +Temperature Sensor +****************** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterTemperatureSensor/MatterTemperatureSensor.ino + :language: arduino diff --git a/docs/en/matter/ep_thermostat.rst b/docs/en/matter/ep_thermostat.rst new file mode 100644 index 00000000000..1a736383443 --- /dev/null +++ b/docs/en/matter/ep_thermostat.rst @@ -0,0 +1,310 @@ +################ +MatterThermostat +################ + +About +----- + +The ``MatterThermostat`` class provides a thermostat endpoint for Matter networks with temperature control, setpoints, and multiple operating modes. This endpoint implements the Matter thermostat standard. + +**Features:** +* Multiple operating modes (OFF, HEAT, COOL, AUTO, etc.) +* Heating and cooling setpoint control +* Local temperature reporting +* Automatic temperature regulation +* Deadband control for AUTO mode +* Callback support for mode, temperature, and setpoint changes +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Matter standard compliance + +**Use Cases:** +* HVAC systems +* Smart thermostats +* Temperature control systems +* Climate control automation +* Energy management systems + +API Reference +------------- + +Constructor +*********** + +MatterThermostat +^^^^^^^^^^^^^^^^ + +Creates a new Matter thermostat endpoint. + +.. code-block:: arduino + + MatterThermostat(); + +Initialization +************** + +begin +^^^^^ + +Initializes the Matter thermostat endpoint with control sequence and auto mode settings. + +.. code-block:: arduino + + bool begin(ControlSequenceOfOperation_t controlSequence = THERMOSTAT_SEQ_OP_COOLING, ThermostatAutoMode_t autoMode = THERMOSTAT_AUTO_MODE_DISABLED); + +* ``controlSequence`` - Control sequence of operation (default: ``THERMOSTAT_SEQ_OP_COOLING``) +* ``autoMode`` - Auto mode enabled/disabled (default: ``THERMOSTAT_AUTO_MODE_DISABLED``) + +This function will return ``true`` if successful, ``false`` otherwise. + +end +^^^ + +Stops processing Matter thermostat events. + +.. code-block:: arduino + + void end(); + +Control Sequences +***************** + +ControlSequenceOfOperation_t +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Control sequence enumeration: + +* ``THERMOSTAT_SEQ_OP_COOLING`` - Cooling only +* ``THERMOSTAT_SEQ_OP_COOLING_REHEAT`` - Cooling with reheat +* ``THERMOSTAT_SEQ_OP_HEATING`` - Heating only +* ``THERMOSTAT_SEQ_OP_HEATING_REHEAT`` - Heating with reheat +* ``THERMOSTAT_SEQ_OP_COOLING_HEATING`` - Cooling and heating +* ``THERMOSTAT_SEQ_OP_COOLING_HEATING_REHEAT`` - Cooling and heating with reheat + +Thermostat Modes +**************** + +ThermostatMode_t +^^^^^^^^^^^^^^^^ + +Thermostat mode enumeration: + +* ``THERMOSTAT_MODE_OFF`` - Off +* ``THERMOSTAT_MODE_AUTO`` - Auto mode +* ``THERMOSTAT_MODE_COOL`` - Cooling mode +* ``THERMOSTAT_MODE_HEAT`` - Heating mode +* ``THERMOSTAT_MODE_EMERGENCY_HEAT`` - Emergency heat +* ``THERMOSTAT_MODE_PRECOOLING`` - Precooling +* ``THERMOSTAT_MODE_FAN_ONLY`` - Fan only +* ``THERMOSTAT_MODE_DRY`` - Dry mode +* ``THERMOSTAT_MODE_SLEEP`` - Sleep mode + +Mode Control +************ + +setMode +^^^^^^^ + +Sets the thermostat mode. + +.. code-block:: arduino + + bool setMode(ThermostatMode_t mode); + +getMode +^^^^^^^ + +Gets the current thermostat mode. + +.. code-block:: arduino + + ThermostatMode_t getMode(); + +getThermostatModeString +^^^^^^^^^^^^^^^^^^^^^^^ + +Gets a friendly string for the thermostat mode. + +.. code-block:: arduino + + static const char *getThermostatModeString(uint8_t mode); + +Temperature Control +******************* + +setLocalTemperature +^^^^^^^^^^^^^^^^^^^ + +Sets the local temperature reading. + +.. code-block:: arduino + + bool setLocalTemperature(double temperature); + +* ``temperature`` - Temperature in Celsius + +getLocalTemperature +^^^^^^^^^^^^^^^^^^^ + +Gets the current local temperature. + +.. code-block:: arduino + + double getLocalTemperature(); + +Setpoint Control +**************** + +setCoolingHeatingSetpoints +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets both cooling and heating setpoints. + +.. code-block:: arduino + + bool setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCoolingTemperature); + +* ``_setpointHeatingTemperature`` - Heating setpoint in Celsius (or 0xffff to keep current) +* ``_setpointCoolingTemperature`` - Cooling setpoint in Celsius (or 0xffff to keep current) + +**Note:** Heating setpoint must be lower than cooling setpoint. In AUTO mode, cooling setpoint must be at least 2.5°C higher than heating setpoint (deadband). + +setHeatingSetpoint +^^^^^^^^^^^^^^^^^^ + +Sets the heating setpoint. + +.. code-block:: arduino + + bool setHeatingSetpoint(double _setpointHeatingTemperature); + +getHeatingSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the heating setpoint. + +.. code-block:: arduino + + double getHeatingSetpoint(); + +setCoolingSetpoint +^^^^^^^^^^^^^^^^^^ + +Sets the cooling setpoint. + +.. code-block:: arduino + + bool setCoolingSetpoint(double _setpointCoolingTemperature); + +getCoolingSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the cooling setpoint. + +.. code-block:: arduino + + double getCoolingSetpoint(); + +Setpoint Limits +*************** + +getMinHeatSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the minimum heating setpoint limit. + +.. code-block:: arduino + + float getMinHeatSetpoint(); + +getMaxHeatSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the maximum heating setpoint limit. + +.. code-block:: arduino + + float getMaxHeatSetpoint(); + +getMinCoolSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the minimum cooling setpoint limit. + +.. code-block:: arduino + + float getMinCoolSetpoint(); + +getMaxCoolSetpoint +^^^^^^^^^^^^^^^^^^ + +Gets the maximum cooling setpoint limit. + +.. code-block:: arduino + + float getMaxCoolSetpoint(); + +getDeadBand +^^^^^^^^^^^ + +Gets the deadband value (minimum difference between heating and cooling setpoints in AUTO mode). + +.. code-block:: arduino + + float getDeadBand(); + +Event Handling +************** + +onChange +^^^^^^^^ + +Sets a callback for when any parameter changes. + +.. code-block:: arduino + + void onChange(EndPointCB onChangeCB); + +onChangeMode +^^^^^^^^^^^^ + +Sets a callback for mode changes. + +.. code-block:: arduino + + void onChangeMode(EndPointModeCB onChangeCB); + +onChangeLocalTemperature +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for local temperature changes. + +.. code-block:: arduino + + void onChangeLocalTemperature(EndPointTemperatureCB onChangeCB); + +onChangeCoolingSetpoint +^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for cooling setpoint changes. + +.. code-block:: arduino + + void onChangeCoolingSetpoint(EndPointCoolingSetpointCB onChangeCB); + +onChangeHeatingSetpoint +^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback for heating setpoint changes. + +.. code-block:: arduino + + void onChangeHeatingSetpoint(EndPointHeatingSetpointCB onChangeCB); + +Example +------- + +Thermostat +********** + +.. literalinclude:: ../../../libraries/Matter/examples/MatterThermostat/MatterThermostat.ino + :language: arduino diff --git a/docs/en/matter/matter.rst b/docs/en/matter/matter.rst new file mode 100644 index 00000000000..7ed1afaeac6 --- /dev/null +++ b/docs/en/matter/matter.rst @@ -0,0 +1,216 @@ +###### +Matter +###### + +About +----- + +The Matter library provides support for creating Matter-compatible devices including: + +* Support for Wi-Fi and Thread connectivity +* Matter commissioning via QR code or manual pairing code +* Multiple endpoint types for various device categories +* Event monitoring and callback support +* Integration with Apple HomeKit, Amazon Alexa, and Google Home +* Smart home ecosystem compatibility + +The Matter library is built on top of `ESP Matter SDK `_ and provides a high-level Arduino-style interface for creating Matter devices. + +Matter Protocol Overview +************************ + +Matter (formerly Project CHIP - Connected Home over IP) is an open-source connectivity standard for smart home devices. It enables seamless communication between devices from different manufacturers, allowing them to work together within a single ecosystem. + +**Key Features:** + +* **Multi-Protocol Support**: Works over Wi-Fi, Thread, and Ethernet +* **Interoperability**: Devices from different manufacturers work together +* **Security**: Built-in security features including encryption and authentication +* **Local Control**: Devices can communicate locally without requiring cloud connectivity +* **Simple Setup**: Easy commissioning via QR code or pairing code + +Matter Network Topology +*********************** + +.. code-block:: text + + ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ + │ Matter Hub │◄─────►│ Wi-Fi Router │◄─────►│ ESP Border │ + │ (HomePod etc) │ │ │ │ Border Router │ + └─────────────────┘ └──────────────────┘ └─────────────────┘ + │ │ │ + │ ▼ │ + │ ┌─────────────────┐ │ + │ │ Matter Device │ │ + │ │ (via Wi-Fi) │ │ + │ └─────────────────┘ │ + │ │ + ▼ ▼ + ┌─────────────────┐ ┌─────────────────┐ + │ Matter Device │ │ Matter Device │ + │ (via Wi-Fi) │ │ (via Thread) │ + └─────────────────┘ └─────────────────┘ + + +**Network Interfaces:** + +* **Wi-Fi**: High-bandwidth connection for devices that require constant power +* **Thread**: Low-power mesh networking for battery-operated devices +* **Ethernet**: Wired connection for stationary devices + +Matter Library Structure +------------------------ + +**The library is split into three main components:** + +* ``Matter``: The main class that manages the Matter network and device commissioning +* ``MatterEndPoint``: The base class for all Matter endpoints, which provides common functionality for all endpoint types +* ``Specific endpoint classes``: The classes for all Matter endpoints, which provides the specific functionality for each endpoint type + +Matter +****** + +The ``Matter`` class is the main entry point for all Matter operations. It serves as the central manager that handles: + +* **Device Commissioning**: Managing the commissioning process via QR code or manual pairing code +* **Network Connectivity**: Checking and managing Wi-Fi and Thread connections +* **Event Handling**: Monitoring Matter events and device state changes +* **Device Management**: Decommissioning and factory reset functionality + +The ``Matter`` class is implemented as a singleton, meaning there's only one instance available globally. You access it directly as ``Matter`` without creating an instance. + +The ``Matter`` class provides the following key methods: + +* ``begin()``: Initializes the Matter stack +* ``isDeviceCommissioned()``: Checks if the device is commissioned +* ``isWi-FiConnected()``: Checks Wi-Fi connection status (if Wi-Fi is enabled) +* ``isThreadConnected()``: Checks Thread connection status (if Thread is enabled) +* ``isDeviceConnected()``: Checks overall device connectivity +* ``decommission()``: Factory resets the device +* ``getManualPairingCode()``: Gets the manual pairing code for commissioning +* ``getOnboardingQRCodeUrl()``: Gets the QR code URL for commissioning +* ``onEvent()``: Sets a callback for Matter events + +MatterEndPoint +************** + +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 +* **Attribute Access**: Methods to get and set attribute values from Matter clusters +* **Identify Cluster**: Support for device identification (visual feedback) +* **Secondary Network Interfaces**: Support for multiple network interfaces (Wi-Fi, Thread, Ethernet) +* **Attribute Change Callbacks**: Base framework for handling attribute changes from Matter controllers + +.. toctree:: + :maxdepth: 2 + + matter_ep + +Specific endpoint classes +************************* + +The library provides specialized endpoint classes for different device types. Each endpoint type includes specific clusters and functionality relevant to that device category. + +**Lighting Endpoints:** + +* ``MatterOnOffLight``: Simple on/off light control +* ``MatterDimmableLight``: Light with brightness control +* ``MatterColorTemperatureLight``: Light with color temperature control +* ``MatterColorLight``: Light with RGB color control (HSV color model) +* ``MatterEnhancedColorLight``: Enhanced color light with color temperature and brightness control + +**Sensor Endpoints:** + +* ``MatterTemperatureSensor``: Temperature sensor (read-only) +* ``MatterHumiditySensor``: Humidity sensor (read-only) +* ``MatterPressureSensor``: Pressure sensor (read-only) +* ``MatterContactSensor``: Contact sensor (open/closed state) +* ``MatterOccupancySensor``: Occupancy sensor (occupied/unoccupied state) + +**Control Endpoints:** + +* ``MatterFan``: Fan with speed and mode control +* ``MatterThermostat``: Thermostat with temperature control and setpoints +* ``MatterOnOffPlugin``: On/off plugin unit (power outlet/relay) +* ``MatterGenericSwitch``: Generic switch endpoint (smart button) + +.. toctree:: + :maxdepth: 1 + :glob: + + ep_* + +Common Problems and Issues +-------------------------- + +Troubleshooting +--------------- + +Common Issues +************* + +**Device won't commission** + * Ensure the Matter hub is in pairing mode + * Check that Wi-Fi or Thread connectivity is properly configured + * Verify the QR code or pairing code is correct + * For ESP32/ESP32-S2, ensure Wi-Fi credentials are set in the code + +**Commissioning fails** + * Try factory resetting the device by calling ``Matter.decommission()`` + * Erase flash memory: ``Arduino IDE Menu`` -> ``Tools`` -> ``Erase All Flash Before Sketch Upload: "Enabled"`` + * Or use esptool: ``esptool.py --port erase_flash`` + +**Wi-Fi connection issues** + * Verify Wi-Fi credentials (SSID and password) are correct + * Check that the device is within range of the Wi-Fi router + * Ensure the Wi-Fi network is 2.4 GHz (Matter requires 2.4 GHz Wi-Fi) + +**Thread connection issues** + * Verify Thread border router is properly configured + * Check that Thread network credentials are correct + * Ensure device supports Thread (ESP32-H2, ESP32-C6 with Thread enabled) + +**Device not responding** + * Check Serial Monitor for error messages (115200 baud) + * Verify endpoint initialization with ``begin()`` method + * Ensure ``Matter.begin()`` is called after all endpoints are initialized + +**Callbacks not firing** + * Verify callback functions are registered before commissioning + * Check that callback functions are properly defined + * Ensure endpoint is properly initialized with ``begin()`` + +Factory Reset +************* + +If you have problems with commissioning or device connectivity, you can try to factory reset the device. This will erase all the Matter network settings and act as a brand new device. + +.. code-block:: arduino + + Matter.decommission(); + +This will reset the device and it will need to be commissioned again. + +Event Monitoring +**************** + +For debugging and monitoring Matter events, you can set up an event callback: + +.. code-block:: arduino + + Matter.onEvent([](matterEvent_t event, const chip::DeviceLayer::ChipDeviceEvent *eventData) { + Serial.printf("Matter Event: 0x%04X\r\n", event); + // Handle specific events + switch(event) { + case MATTER_COMMISSIONING_COMPLETE: + Serial.println("Device commissioned!"); + break; + case MATTER_WIFI_CONNECTIVITY_CHANGE: + Serial.println("Wi-Fi connectivity changed"); + break; + // ... handle other events + } + }); + +This allows you to monitor commissioning progress, connectivity changes, and other Matter events in real-time. diff --git a/docs/en/matter/matter_ep.rst b/docs/en/matter/matter_ep.rst new file mode 100644 index 00000000000..084d22e2125 --- /dev/null +++ b/docs/en/matter/matter_ep.rst @@ -0,0 +1,200 @@ +############## +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_* diff --git a/libraries/Matter/src/MatterEndpoints/MatterThermostat.cpp b/libraries/Matter/src/MatterEndpoints/MatterThermostat.cpp index 6ee18ef0cc9..667929bd6ed 100644 --- a/libraries/Matter/src/MatterEndpoints/MatterThermostat.cpp +++ b/libraries/Matter/src/MatterEndpoints/MatterThermostat.cpp @@ -302,16 +302,16 @@ bool MatterThermostat::setRawTemperature(int16_t _rawTemperature, uint32_t attri return true; } -bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCollingTemperature) { +bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCoolingTemperature) { // at least one of the setpoints must be valid - bool settingCooling = _setpointCollingTemperature != (float)0xffff; + bool settingCooling = _setpointCoolingTemperature != (float)0xffff; bool settingHeating = _setpointHeatingTemperature != (float)0xffff; if (!settingCooling && !settingHeating) { log_e("Invalid Setpoints values. Set correctly at least one of them in Celsius."); return false; } int16_t _rawHeatValue = static_cast(_setpointHeatingTemperature * 100.0f); - int16_t _rawCoolValue = static_cast(_setpointCollingTemperature * 100.0f); + int16_t _rawCoolValue = static_cast(_setpointCoolingTemperature * 100.0f); // check limits for the setpoints if (settingHeating && (_rawHeatValue < kDefaultMinHeatSetpointLimit || _rawHeatValue > kDefaultMaxHeatSetpointLimit)) { @@ -323,7 +323,7 @@ bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTempera } if (settingCooling && (_rawCoolValue < kDefaultMinCoolSetpointLimit || _rawCoolValue > kDefaultMaxCoolSetpointLimit)) { log_e( - "Invalid Cooling Setpoint value: %.01fC - valid range %d..%d", _setpointCollingTemperature, kDefaultMinCoolSetpointLimit / 100, + "Invalid Cooling Setpoint value: %.01fC - valid range %d..%d", _setpointCoolingTemperature, kDefaultMinCoolSetpointLimit / 100, kDefaultMaxCoolSetpointLimit / 100 ); return false; @@ -337,7 +337,7 @@ bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTempera // only setting Cooling Setpoint if (settingCooling && !settingHeating && _rawCoolValue < (heatingSetpointTemperature + (kDefaultDeadBand * 10))) { log_e( - "AutoMode :: Invalid Cooling Setpoint value: %.01fC - must be higher or equal than %.01fC", _setpointCollingTemperature, getHeatingSetpoint() + deadband + "AutoMode :: Invalid Cooling Setpoint value: %.01fC - must be higher or equal than %.01fC", _setpointCoolingTemperature, getHeatingSetpoint() + deadband ); return false; } @@ -352,7 +352,7 @@ bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTempera if (settingCooling && settingHeating && (_rawCoolValue <= _rawHeatValue || _rawCoolValue - _rawHeatValue < kDefaultDeadBand * 10.0)) { log_e( "AutoMode :: Error - Heating Setpoint %.01fC must be lower than Cooling Setpoint %.01fC with a minimum difference of %0.1fC", - _setpointHeatingTemperature, _setpointCollingTemperature, deadband + _setpointHeatingTemperature, _setpointCoolingTemperature, deadband ); return false; } diff --git a/libraries/Matter/src/MatterEndpoints/MatterThermostat.h b/libraries/Matter/src/MatterEndpoints/MatterThermostat.h index 53df61d191e..e4fdefd34ad 100644 --- a/libraries/Matter/src/MatterEndpoints/MatterThermostat.h +++ b/libraries/Matter/src/MatterEndpoints/MatterThermostat.h @@ -101,19 +101,19 @@ class MatterThermostat : public MatterEndPoint { // Heating Setpoint must be lower than Cooling Setpoint // When using AUTO mode the Cooling Setpoint must be higher than Heating Setpoint by at least the 2.5C (deadband) // Thermostat Matter Server will enforce those rules and the Max/Min setpoints limits as in the Matter Specification - bool setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCollingTemperature); + bool setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCoolingTemperature); // set the heating setpoint in 1/100th of a Celsio degree bool setHeatingSetpoint(double _setpointHeatingTemperature) { - return setCoolingHeatingSetpoints((double)0xffff, _setpointHeatingTemperature); + return setCoolingHeatingSetpoints(_setpointHeatingTemperature, (double)0xffff); } // get the heating setpoint in 1/100th of a Celsio degree double getHeatingSetpoint() { return heatingSetpointTemperature / 100.0; } // set the cooling setpoint in 1/100th of a Celsio degree - bool setCoolingSetpoint(double _setpointCollingTemperature) { - return setCoolingHeatingSetpoints(_setpointCollingTemperature, (double)0xffff); + bool setCoolingSetpoint(double _setpointCoolingTemperature) { + return setCoolingHeatingSetpoints((double)0xffff, _setpointCoolingTemperature); } // get the cooling setpoint in 1/100th of a Celsio degree double getCoolingSetpoint() {