Integração e API

Adaptador de Integração

Como um transformador de interfaces, o adaptador de integração traduz o contrato de um dispositivo ou serviço para o modelo esperado pela plataforma. Desde o padrão Adapter formalizado no movimento de padrões de projeto dos anos 1990, implementações passaram a mapear REST, MQTT, Modbus, Zigbee e APIs proprietárias. A escolha exige definir direção, estado, erros e versionamento. O risco é esconder diferenças semânticas: converter campos não garante equivalência de comportamento.

🔀 Tipos de Comunicação

PROTOCOL

Adaptação de protocolo

Um adaptador de protocolo recebe mensagens numa tecnologia e produz mensagens noutra. Um gateway Modbus TCP–MQTT pode ler registradores de um medidor e publicar `casa/energia/potencia` em JSON. A conversão precisa definir endianness, escala, unidade, qualidade e frequência. Um registrador `0x0012` com valor 2345 pode significar 234,5 V, mas essa semântica não existe no MQTT por si só. O adaptador precisa carregar o mapa. Buffers e filas tratam ritmos diferentes. O Modbus usa polling; MQTT é orientado a publicação. O adaptador pode publicar a cada 5 s ou apenas quando muda. A decisão afeta tráfego, latência e perda de eventos. Não se deve chamar essa transformação de transparência completa: timeout, confirmação e endereçamento continuam diferentes.

MAPPING

Adaptação de modelo de dados

O componente traduz objetos e atributos sem mudar necessariamente o transporte. Uma API de fabricante pode retornar `{"power":1,"brightness":127}`; a plataforma espera uma entidade `light` com brilho de 0 a 255 e estado booleano. O adaptador converte faixa, nomes, enumerações, unidades e estruturas. Ele também precisa representar ausência, desconhecido e indisponível. Mapear `null` para zero é erro frequente. O modelo de destino pode não suportar um recurso, como efeito RGBIC por segmento. Nesse caso, o adaptador expõe subconjunto, cria entidade auxiliar ou documenta a perda. A decisão deve ser estável, porque automações passam a depender dos nomes. Mudanças exigem migração e versão.

CALL

Adaptação de chamada e ciclo de vida

Uma biblioteca síncrona pode ser encapsulada numa API assíncrona; callbacks podem virar eventos; polling pode simular notificações. Em Home Assistant, uma integração costuma manter um coordenador de atualização e entidades que leem estado em cache, evitando uma chamada por propriedade. O adaptador precisa iniciar, autenticar, descobrir, atualizar, reconectar e encerrar. Chamadas bloqueantes não devem travar o event loop. Timeouts são obrigatórios. Um dispositivo Bluetooth pode aceitar apenas uma conexão por vez, exigindo fila. A adaptação de ciclo de vida é tão importante quanto o payload. Uma função que funciona em teste único pode falhar após 24 h por vazamento de sessão ou reconexão mal tratada.

ACL

Adaptação anti-corrupção entre domínios

Em arquitetura orientada a domínio, uma anti-corruption layer impede que conceitos proprietários contaminem o modelo interno. O fabricante pode chamar uma casa de `site`, um cômodo de `zone` e uma cena de `mood`. O adaptador traduz para entidades canônicas. Isso facilita trocar fornecedor. A camada precisa preservar identificadores estáveis e metadados necessários. Ela não deve apenas renomear. Regras como “modo away desarma gravação interna” têm significado operacional. O adaptador deve representar capacidade, permissões e limitações. Quanto mais lógica acumula, mais ele se aproxima de um serviço de integração independente, que exige testes, observabilidade e versão.

✅ Vantagens Arquiteturais

⚡

Isola mudanças do fornecedor

Quando a API externa muda de `/v1/devices` para `/v2/assets`, somente o adaptador precisa conhecer a alteração; o restante da plataforma continua consumindo a interface interna. Esse isolamento reduz custo de manutenção. Só funciona se a interface interna for realmente estável. Copiar o JSON externo integralmente para dentro não cria isolamento. O adaptador deve escolher campos canônicos. Mudanças inevitáveis precisam de compatibilidade. Testes de contrato com respostas gravadas ou sandbox detectam. Um adaptador sem monitoramento pode falhar silenciosamente quando o fornecedor adiciona paginação, altera token ou muda limites. Métricas de erro, latência e última atualização são essenciais.

⚡

Permite combinar protocolos heterogêneos

Uma residência pode ter BACnet no HVAC, Modbus no medidor, Zigbee nos sensores e REST numa nuvem. Adaptadores convertem cada origem para um event bus, MQTT ou modelo comum. O benefício é criar automações transversais sem implementar quatro protocolos em cada consumidor. O custo é manter quatro adaptadores. A arquitetura deve evitar uma cadeia longa: Modbus→MQTT→Node-RED→REST→Home Assistant aumenta pontos de falha. Sempre que possível, cada origem entra uma vez no modelo central. O caminho precisa ser documentado. Latência e responsabilidade por comandos devem ser conhecidas. Duplicar uma entidade por duas rotas causa conflito.

⚡

Simplifica testes por interfaces substituíveis

Uma interface interna permite usar adaptador falso em teste. Em vez de ligar uma bomba real, a automação recebe um `PumpAdapter` simulado que reproduz estados e falhas. Isso melhora cobertura de cenários como timeout, sobrecorrente e perda de rede. O contrato precisa incluir erros e eventos, não apenas caso feliz. Testes de unidade validam mapeamento. Testes de integração usam o dispositivo real ou emulador. Testes de contrato comparam versões da API. Um mock excessivamente simples pode mascarar incompatibilidade. Dados de produção devem ser anonimizados antes de virar fixture. O adaptador favorece testabilidade quando seus limites são explícitos.

⚡

Reduz acoplamento entre lógica e biblioteca

Bibliotecas de fabricantes mudam classes, métodos e autenticação. O adaptador oferece métodos próprios, como `set_target_temperature(22.0)`, e traduz para o SDK atual. A lógica da casa não importa diretamente a biblioteca. Isso facilita trocar implementação, usar chamada local em vez de nuvem ou suportar dois modelos. A camada acrescenta código e precisa justificar. Para uma integração de 50 linhas sem perspectiva de mudança, uma abstração complexa pode ser excesso. O critério é volatilidade, número de consumidores e criticidade. A analogia de transformador é útil: ele adapta níveis, mas também introduz perdas e custo.

⚡

Documenta as perdas de interoperabilidade

Um bom adaptador declara capacidades. Se a câmera suporta PTZ, mas a plataforma só expõe stream, a limitação aparece. Se Matter representa ligar e brilho, mas não uma cena dinâmica proprietária, o adaptador não inventa paridade. Flags, feature bits e diagnósticos permitem que a interface mostre. Isso evita automações que tentam comando inexistente. A documentação deve listar leitura, escrita, frequência, unidades, autenticação e comportamento offline. A consequência prática é escolher dispositivos com base no que realmente será integrado, não apenas no logotipo de compatibilidade.

Exemplo de Código

class TapoLightAdapter:
    def __init__(self, client): self._client = client
    async def set_brightness(self, value_0_255: int):
        pct = round(max(0, min(255, value_0_255)) * 100 / 255)
        await asyncio.wait_for(self._client.set_brightness(pct), timeout=5)
    async def state(self):
        raw = await self._client.get_state()
        return {'on': bool(raw['device_on']), 'brightness': round(raw['brightness'] * 255 / 100)}

Home AssistantIntegrações Python funcionam como adaptadores entre APIs, dispositivos e o modelo de entidades. O manifesto declara domínio, dependências, discovery e requisitos. Config entries gerenciam instâncias; entidades representam luz, sensor, clima e outras classes. A documentação de desenvolvimento recomenda setup assíncrono e bibliotecas separadas quando apropriado. O adaptador precisa usar coordenadores para polling compartilhado, tratar indisponibilidade e expor diagnósticos. Uma integração local pode substituir uma cloud sem alterar automações se os entity IDs e capacidades forem migrados cuidadosamente.

Node-REDNodes de entrada, processamento e saída adaptam MQTT, HTTP, Modbus, BACnet e APIs. Um flow pode converter payload, escala e tópico. Function nodes em JavaScript oferecem flexibilidade, mas lógica extensa vira difícil de testar. Subflows e nodes customizados são preferíveis para comportamento reutilizável. O adaptador precisa tratar reconexão, timeout e status do node. Deploy parcial reduz impacto. Credenciais ficam no credential store. Node-RED é adequado a composição visual; não elimina a necessidade de contrato de dados.

Apache CamelFramework de integração baseado em Enterprise Integration Patterns, com componentes para HTTP, MQTT, AMQP, Kafka, arquivos e centenas de sistemas. Routes conectam endpoints e aplicam transformação, filtro, split, aggregate e error handling. É indicado quando muitas integrações corporativas precisam de políticas consistentes. Em casa individual, costuma ser pesado. Em edifícios e plataformas multi-tenant, pode organizar. O desenvolvedor precisa gerir runtime Java, dependências, observabilidade e atualizações. A diversidade de componentes não garante compatibilidade semântica.

Matter Bridge e gateways multiprotocoloUma bridge Matter adapta dispositivos Zigbee, Z-Wave ou proprietários para tipos de dispositivo Matter. Philips Hue Bridge, Aqara Hub e outras pontes expõem subconjuntos conforme certificação e firmware. A bridge traduz atributos, comandos, eventos e segurança. Recursos proprietários podem não atravessar. Multi-Admin compartilha a representação Matter, não o protocolo original. O adaptador é implementado no firmware do gateway e sua qualidade determina estabilidade. O usuário precisa validar classe e recurso, não apenas “suporta Matter”.