Matter Implementation Guide
============================

What is this?
-------------

The ``purpleair_api.PurpleAirMatterConverter`` module maps raw PurpleAir sensor readings to
**Matter-compatible device type structures** per the `Matter 1.5.1 Core Specification <https://csa-iot.org/developer-resource/specifications/>`_
(Connectivity Standards Alliance, 2024).

This lets you expose PurpleAir sensors through any Matter-compatible ecosystem:
Apple Home, Google Home, Amazon Alexa, Samsung SmartThings, Home Assistant, and
more — by providing data in the format those platforms understand.

Prerequisites
-------------

.. code-block:: bash

    pip install purpleair_api

You also need a PurpleAir Read API key (email ``contact@purpleair.com``).

Quick Start
-----------

.. code-block:: python

    from purpleair_api.PurpleAirReadAPI import PurpleAirReadAPI
    from purpleair_api.PurpleAirMatterConverter import PurpleAirMatterConverter

    # Fetch sensor data
    pa = PurpleAirReadAPI("YOUR_READ_API_KEY")
    raw = pa.request_sensor_data(282168)

    # Convert to Matter Air Quality Sensor
    device = PurpleAirMatterConverter.to_air_quality_sensor(raw)

    print(device["device_type"])
    # {'id': 45, 'label': 'Air Quality Sensor', 'matter_version': '1.5.1',
    #  'spec_reference': 'Matter 1.5.1 Core Spec — Air Quality Sensor Device Type ...'}

    print(device["air_quality_summary"])
    # {'epa_aqi': 68, 'epa_category': 'Moderate',
    #  'matter_air_quality_rating': 'GOOD', 'matter_air_quality_rating_value': 2}

Three Device Types
------------------

Air Quality Sensor (full)
^^^^^^^^^^^^^^^^^^^^^^^^^^

Use ``to_air_quality_sensor()`` to return all available PurpleAir measurements
as Matter clusters:

.. list-table::
    :widths: 30 40 30
    :header-rows: 1

   * - PurpleAir field
     - Matter cluster
     - Attribute
   * - ``pm2.5``
     - Air Quality (0x005D)
     - ``measuredValue`` (µg/m³ ×100)
   * - ``pm1.0``
     - Air Quality (0x005D)
     - ``pm1Density`` (µg/m³ ×100)
   * - ``pm10.0``
     - Air Quality (0x005D)
     - ``pm10Density`` (µg/m³ ×100)
   * - ``voc``
     - Air Quality (0x005D)
     - ``vocDensity`` (µg/m³ ×100)
   * - *(computed)*
     - Air Quality (0x005D)
     - ``airQuality`` enum
   * - *(computed)*
     - Air Quality (0x005D)
     - ``aqiRating`` enum
   * - ``temperature`` °F
     - Temperature (0x0402)
     - ``measuredValue`` (°C ×100)
   * - ``humidity`` %
     - Humidity (0x0405)
     - ``measuredValue`` (% ×100)
   * - ``pressure`` PSI
     - Pressure (0x0403)
     - ``measuredValue`` (kPa ×10)

Matter Device Type: **0x002D** (Air Quality Sensor)

Temperature Sensor
^^^^^^^^^^^^^^^^^^

Use ``to_temperature_sensor()`` for a minimal device exposing only temperature.

Matter Device Type: **0x0302** (Temperature Sensor)

.. code-block:: python

    tmp = PurpleAirMatterConverter.to_temperature_sensor(raw)

Environmental Sensor
^^^^^^^^^^^^^^^^^^^^

Use ``to_environmental_sensor()`` for temperature, humidity, and pressure on
one endpoint without air quality clusters.

Matter Device Type: **0x0307** (Environmental Sensor)

.. code-block:: python

    env = PurpleAirMatterConverter.to_environmental_sensor(raw)

EPA AQI Calculation
-------------------

PurpleAir does not natively provide AQI values. The module computes EPA AQI
from PM2.5 using the official piecewise-linear formula:

.. code-block:: python

    from purpleair_api.PurpleAirMatterConverter import EpaAqiCalculator

    pm25 = 25.0  # µg/m³
    aqi = EpaAqiCalculator.pm25_to_aqi(pm25)
    category = EpaAqiCalculator.aqi_to_epa_category(aqi)

    print(f"AQI: {aqi} ({category})")
    # AQI: 78 (Moderate)

AQI to Matter Rating Mapping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. list-table::
    :widths: 30 40 30
    :header-rows: 1

   * - AQI Range
     - EPA Category
     - Matter ``airQuality``
   * - 0–50
     - Good
     - Excellent (1)
   * - 51–100
     - Moderate
     - Good (2)
   * - 101–150
     - Unhealthy for Sensitive Groups
     - Fair (3)
   * - 151–200
     - Unhealthy
     - Poor (4)
   * - 201–300
     - Very Unhealthy
     - Very Poor (5)
   * - 301–500
     - Hazardous
     - Extremely Poor (6)

Matter Scaled-Integer Convention
--------------------------------

Matter protocol stores numbers as scaled integers to avoid floating-point
complexity. This module encodes values as:

.. list-table::
    :widths: 40 60
    :header-rows: 1

   * - Type
     - Formula
   * - Temperature
     - ``round(°C × 100)``
   * - Humidity
     - ``round(% × 100)``
   * - Pressure
     - ``round(kPa × 10)``
   * - PM / VOC density
     - ``round(µg/m³ × 100)``

Raw floating-point values are preserved in ``clusters[*]._raw_*`` fields for
debugging and display.

Using with Home Assistant + Matter
----------------------------------

1. Run ``python-matter-server`` or use the Home Assistant Matter Server add-on.
2. Expose the Matter structures through a bridge integration.
3. Home Assistant will discover the PurpleAir sensor as a Matter device.

Example bridge snippet (conceptual):

.. code-block:: python

    from purpleair_api.PurpleAirReadAPI import PurpleAirReadAPI
    from purpleair_api.PurpleAirMatterConverter import PurpleAirMatterConverter
    import matter_server  # python-matter-server

    pa = PurpleAirReadAPI("KEY")
    device = PurpleAirMatterConverter.to_air_quality_sensor(
        pa.request_sensor_data(282168)
    )

    # Feed device to your Matter bridge's device registration
    matter_bridge.add_device(device)

Matter Specification References
-------------------------------

.. list-table::
    :widths: 40 60
    :header-rows: 1

   * - Resource
     - URL
   * - Matter 1.5.1 Core Spec
     - https://csa-iot.org/developer-resource/specifications/
   * - Air Quality Measurement Cluster (0x005D)
     - https://github.com/project-chip/matter
   * - Temperature Measurement Cluster (0x0402)
     - https://github.com/project-chip/matter
   * - Humidity Measurement Cluster (0x0405)
     - https://github.com/project-chip/matter
   * - Pressure Measurement Cluster (0x0403)
     - https://github.com/project-chip/matter
   * - EPA AQI Formula
     - https://www.airnow.gov/sites/default/files/2022-05/AQI-Basics-Calculation.pdf
   * - python-matter-server
     - https://github.com/home-assistant-libs/python-matter-server
   * - matter.js (reference implementation)
     - https://github.com/project-chip/matter.js

Design Notes
------------

- **No new dependencies** — only ``requests`` is required, keeping the package lightweight.
- **Stateless** — ``PurpleAirMatterConverter`` methods are pure functions; all conversion is
  deterministic and testable without network access.
- **API-compatible response format** — handles both bare ``{"sensor": {...}}`` and
  flat sensor dictionaries from the PurpleAir API.
- **Tested** — see ``tests/test_purpleair_matter_converter.py`` for coverage including EPA AQI
  boundary conditions and unit conversion accuracy.