> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Matter

> Conecte dispositivos Matter ao Portal por meio de um Matter Server

# Matter

A integração Matter conecta o Portal a um **Matter Server** já existente na sua rede (como o `python-matter-server`, mantido pela Nabu Casa). O Portal não se torna um Matter Controller — ele atua como cliente, consumindo os dispositivos comissionados no servidor Matter.

Essa arquitetura te da Matter de verdade reusando o stack que o ecossistema open-source já mantem. O Portal foca em automações, dashboards e integrações; o Matter Server cuida da fabric, BLE, mDNS e IPv6.

## Pre-requisitos

* Um **Matter Server** rodando na rede local (recomendado: [python-matter-server](https://github.com/home-assistant-libs/python-matter-server))
* Home edge do Portal na mesma rede do Matter Server
* Para comissionar dispositivos novos: BLE + IPv6 funcionando no host do Matter Server
* Para dispositivos Matter-over-Thread: um Thread Border Router na rede (Apple TV, Nest Hub, OpenThread BR)

## Configurar

<Steps>
  <Step title="Suba um Matter Server">
    Exemplo com Docker:

    ```yaml theme={null}
    matter-server:
      image: ghcr.io/home-assistant-libs/python-matter-server:stable
      network_mode: host
      volumes:
        - matter-data:/data
      command: --storage-path /data
    ```

    O servidor escuta em `ws://<host>:5580/ws` por padrão.
  </Step>

  <Step title="Adicione a integração no Portal">
    Va em **Configurações → Integrações → Adicionar → Matter**.
  </Step>

  <Step title="Informe o endereco do Matter Server">
    Preencha:

    * **Endereco** — IP ou hostname (ex.: `192.168.1.10`)
    * **Porta** — `5580` por padrão
    * **Path WebSocket** — `/ws` por padrão

    O Portal faz um probe na URL e cria a config\_entry quando a conexão funciona.
  </Step>

  <Step title="Comissione dispositivos">
    Use o app do Matter Server (ou o `python-matter-server` CLI) para comissionar novos dispositivos via QR code. Eles aparecem automaticamente no Portal — uma entry abriga todos os nodes do mesmo servidor.
  </Step>
</Steps>

## Clusters Suportados

| Cluster Matter                | Entidade Portal             | Funcionalidades                  |
| ----------------------------- | --------------------------- | -------------------------------- |
| `OnOff`                       | `switch` ou `light`         | Ligar/desligar                   |
| `LevelControl`                | `light` (brightness)        | Brilho 0–254                     |
| `ColorControl`                | `light` (color)             | Hue/saturacao, color temperature |
| `DoorLock`                    | `lock`                      | Trancar/destrancar               |
| `WindowCovering`              | `cover`                     | Abrir/fechar/posição             |
| `Thermostat`                  | `climate`                   | Modo, temperatura, setpoints     |
| `FanControl`                  | `fan`                       | Liga/desliga, velocidade         |
| `OccupancySensing`            | `binary_sensor` (occupancy) | Detecção de presença             |
| `BooleanState`                | `binary_sensor` (contact)   | Sensor de contato                |
| `TemperatureMeasurement`      | `sensor`                    | Temperatura                      |
| `RelativeHumidityMeasurement` | `sensor`                    | Umidade                          |
| `IlluminanceMeasurement`      | `sensor`                    | Iluminancia                      |

## Arquitetura

```
[Dispositivo Matter] ─── Matter ──▶ [Matter Server] ◀── WebSocket ── [Portal home edge]
                                                                            │
                                                                            ▼
                                                                       [Portal core]
```

* O **Matter Server** mantem a fabric, comissiona dispositivos e expoe tudo via WebSocket.
* O **home edge** do Portal mantem uma conexão WebSocket persistente com o Matter Server.
* Atualizações de estado chegam via eventos `attribute_updated` e são publicadas como `state_update` no Portal.
* Comandos do Portal (ex.: `light.turn_on`) viram chamadas `device_command` para o Matter Server.

<Info>
  O Portal não implementa o stack Matter diretamente. Isso significa que você não precisa lidar com BLE, IPv6 ou mDNS no home edge — toda essa complexidade fica no Matter Server.
</Info>

## Limitacoes Conhecidas

* **Comissionar dispositivos** ainda e feito via app/CLI do Matter Server. Suporte nativo no painel do Portal (com QR scanner) está planejado.
* **Multi-admin** (compartilhar um dispositivo Matter com outras fabrics como Apple Home ou Google Home) requer usar `open_commissioning_window` via API — sem UI dedicada por enquanto.
* **Matter Bridges** são suportadas (todos os endpoints da bridge viram dispositivos Portal), mas a hierarquia de bridge não e refletida na UI.