#####################
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)
* HoldTime attribute for configuring how long the sensor holds the "occupied" state
* HoldTimeLimits (min, max, default) for validation and controller guidance
* HoldTime change callback for real-time updates from Matter controllers
* 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.

HoldTime Control
****************

setHoldTime
^^^^^^^^^^^

Sets the HoldTime value (in seconds). The HoldTime determines how long the sensor maintains the "occupied" state after the last detection.

.. code-block:: arduino

    bool setHoldTime(uint16_t _holdTime_seconds);

* ``_holdTime_seconds`` - HoldTime value in seconds

**Important:** This function must be called after ``Matter.begin()`` has been called, as it requires the Matter event loop to be running.

This function will return ``true`` if successful, ``false`` otherwise.

getHoldTime
^^^^^^^^^^^

Gets the current HoldTime value (in seconds).

.. code-block:: arduino

    uint16_t getHoldTime();

This function will return the current HoldTime value in seconds.

setHoldTimeLimits
^^^^^^^^^^^^^^^^^

Sets the HoldTime limits (minimum, maximum, and default values). These limits define the valid range for HoldTime values and provide metadata for Matter controllers.

.. code-block:: arduino

    bool setHoldTimeLimits(uint16_t _holdTimeMin_seconds, uint16_t _holdTimeMax_seconds, uint16_t _holdTimeDefault_seconds);

* ``_holdTimeMin_seconds`` - Minimum HoldTime value in seconds
* ``_holdTimeMax_seconds`` - Maximum HoldTime value in seconds
* ``_holdTimeDefault_seconds`` - Default/recommended HoldTime value in seconds (informational metadata for controllers)

**Important:**
* This function must be called after ``Matter.begin()`` has been called, as it requires the Matter event loop to be running.
* The ``holdTimeDefault_seconds`` parameter is informational metadata for Matter controllers (recommended default value). It does NOT automatically set the HoldTime attribute - use ``setHoldTime()`` to set the actual value.
* If the current HoldTime value is outside the new limits, it will be automatically adjusted to the nearest limit (minimum or maximum).

This function will return ``true`` if successful, ``false`` otherwise.

onHoldTimeChange
^^^^^^^^^^^^^^^^

Sets a callback function that will be called when the HoldTime value is changed by a Matter Controller.

.. code-block:: arduino

    void onHoldTimeChange(HoldTimeChangeCB onHoldTimeChangeCB);

* ``onHoldTimeChangeCB`` - Callback function of type ``HoldTimeChangeCB``

The callback function signature is:

.. code-block:: arduino

    using HoldTimeChangeCB = std::function<bool(uint16_t holdTime_seconds)>;

The callback receives the new HoldTime value and can return ``true`` to accept the change or ``false`` to reject it.

Example:

.. code-block:: arduino

    OccupancySensor.onHoldTimeChange([](uint16_t holdTime_seconds) -> bool {
        Serial.printf("HoldTime changed to %u seconds\n", holdTime_seconds);
        return true;  // Accept the change
    });

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
-------

Basic Occupancy Sensor
**********************

.. literalinclude:: ../../../libraries/Matter/examples/MatterOccupancySensor/MatterOccupancySensor.ino
    :language: arduino

Occupancy Sensor with HoldTime
*******************************

For an example that demonstrates HoldTime functionality, see:

.. literalinclude:: ../../../libraries/Matter/examples/MatterOccupancyWithHoldTime/MatterOccupancyWithHoldTime.ino
    :language: arduino

This example shows:
* How to configure HoldTimeLimits after ``Matter.begin()``
* How to set and persist HoldTime values
* How to use the ``onHoldTimeChange()`` callback
* How to implement HoldTime expiration logic in sensor simulation
