Skip to main content

​
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)
  • 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

1

Suba um Matter Server

Exemplo com Docker:
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.
2

Adicione a integração no Portal

Va em Configurações → Integrações → Adicionar → Matter.
3

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

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.

​
Clusters Suportados

Cluster MatterEntidade PortalFuncionalidades
OnOffswitch ou lightLigar/desligar
LevelControllight (brightness)Brilho 0–254
ColorControllight (color)Hue/saturacao, color temperature
DoorLocklockTrancar/destrancar
WindowCoveringcoverAbrir/fechar/posição
ThermostatclimateModo, temperatura, setpoints
FanControlfanLiga/desliga, velocidade
OccupancySensingbinary_sensor (occupancy)Detecção de presença
BooleanStatebinary_sensor (contact)Sensor de contato
TemperatureMeasurementsensorTemperatura
RelativeHumidityMeasurementsensorUmidade
IlluminanceMeasurementsensorIluminancia

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

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