Guia do usuário

Instalação da aplicação, controlador, emparelhamento, chaves de convidado, automação e segurança. Versão do documento: 30-05-2026.

Conteúdo
  1. O que é o Entrixy
  2. Instalação do app
  3. Preparação do controlador
    1. Configurador de firmware
    2. Gravação pelo navegador
    3. Regravar relés Wi-Fi prontos
    4. Gravação manual com esptool
  4. Vínculo do controlador com o app
  5. Objetos
    1. Controlador BLE
    2. Número de telefone
    3. Webhook
  6. Chaves de convidado
  7. Automação
    1. Geolocalização
    2. Wi-Fi
    3. Hora
    4. BLE
    5. Combinação de regras
    6. Confirmação da ação
  8. Webhooks em detalhe
    1. Modo app
    2. Modo servidor
  9. Integrações com casa inteligente
  10. O app web para convidados
  11. Segurança
  12. Perguntas frequentes e problemas

1. O que é o Entrixy

O Entrixy é um sistema para controlar acessos à distância: cancelas, portas, portões, fechaduras. Há duas formas de o fazer:

Qualquer objeto pode ser partilhado com um convidado — um familiar, um colega, um estafeta — com limites de prazo, horário ou condições de geolocalização.

Recursos adicionais:

2. Instalação do app

O app é distribuído como arquivo APK avulso pelo site entrixy.com. Ainda não está nas lojas de aplicativos.

Em um telefone Android

  1. Abra no seu telefone entrixy.com/download/android e toque em "Baixar APK".
  2. Aguarde o download terminar. Abra o arquivo entrixy.apk.
  3. Se o sistema pedir, permita a instalação de fontes desconhecidas para o seu navegador ou gestor de ficheiros.
  4. Confirme a instalação.
  5. No primeiro arranque a aplicação pede permissões. Para que serve cada uma:
    PermissãoPara quê
    Bluetooth (busca e conexão)Encontrar o controlador por perto e enviar o comando de abertura
    GeolocalizaçãoCenários de automação por geozona. Pesquisa BLE em versões antigas do Android.
    Localização em segundo planoDisparo ao aproximar-se do objeto com a aplicação em segundo plano
    CâmeraLeitura do QR code de uma chave de convidado
    NotificaçõesAvisos de uma chamada recebida ou de uma ação à espera de confirmação
    Isentar da otimização de bateriaPara que a economia de energia não encerre o serviço em segundo plano
Uma dica para Samsung e Huawei. Abra Definições → Bateria → Aplicações que nunca adormecem (ou um item semelhante) e acrescente o Entrixy.

Depois da instalação, a aplicação pergunta em que papel a quer usar:

3. Preparação do controlador

Se já tem um controlador pronto com o firmware de fábrica do Entrixy, salte esta secção e vá diretamente para o vínculo.

Por predefinição, o controlador trabalha em modo de impulso: fecha durante um instante (0,5–2 segundos) um par de contactos do motor ou da fechadura, tal como se alguém carregasse no botão Abrir.

Para motores e fechaduras que precisam de entradas separadas de abertura/fecho ou de um estado mantido existe modo biestável: o controlador comuta a posição e memoriza-a — a aplicação mostra Aberto/Fechado em vez de apenas Disparado. O modo escolhe-se ao gerar o firmware no configurador.

Servem como controlador:

Tomadas e interruptores Wi-Fi não servem. O Athom Plug, o Shelly Plus Plug S e equipamentos semelhantes comutam a tensão de rede para uma carga e não têm saída seca NO/COM. Para acionar um motor de portão precisa de um relé com contacto seco (Shelly Plus 1) ou de um módulo feito por si.
Importante sobre os chips. O controlo BLE direto só é suportado pelos chips da família ESP32 com Bluetooth: ESP32, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2. O ESP32-S2 chip e o antigo ESP8266 não têm Bluetooth — só podem ser usados com o firmware Wi-Fi ou através de um webhook.
Quando a autonomia não é o ponto. Se o motor tiver Wi-Fi e uma tomada por perto e quiser abrir à distância, veja opção pela internet. Essa é a via alternativa: o controlador está sempre online e não depende da distância a que está o seu telemóvel.

Se montar o controlador por si próprio ou precisar de firmware para uma disposição de pinos fora do padrão, são três passos:

3.1 Configurador de firmware

Abra entrixy.com/esp/ble/ — é um formulário com os parâmetros do firmware. (O hub entrixy.com/controller/ permite escolher primeiro entre a opção BLE e a de internet — aqui seguimos a via BLE.)

O que preencher (o formulário está dividido em seções):

  1. 1. Escolha a sua placa. Toque no cartão da sua placa (ESP32 DevKit, ESP32-S3 DevKit, ESP32-C3 SuperMini, um relé Shelly Plus 1 já pronto, um módulo nu, etc.) — o modelo, os pinos e a polaridade preenchem-se sozinhos. Depois pode ajustá-los à mão.
  2. 2. Placa. O modelo do chip ESP32 — determina que pinos estão disponíveis. O botão «Detetar o chip ligado» reconhece a placa por USB no Chrome ou no Edge.
  3. 3. Tipo de fechadura. Trinco — um único pulso de abertura. Biestável — duas posições (abrir e fechar em pinos distintos); o estado é guardado e vê-se na aplicação.
  4. 4. Pinos e polaridade. Pino do relé de abertura — o GPIO ao qual está ligada a entrada de comando do módulo de relé; os seus contactos NO/COM vão para os bornes Open do motor. Nível durante o pulso e nível em repouso (HIGH/LOW): na maioria dos módulos comerciais e no Shelly o impulso é LOW e o repouso HIGH; nos comutadores de transístor diretos é ao contrário. Duração do pulso — normalmente 500–2000 ms. Abaixo: o pino do botão de emparelhamento (habitualmente o botão BOOT integrado, GPIO0; uma pressão longa apaga o emparelhamento) e os LED opcionais (indique −1 se não tiver nenhum).
  5. 5. Alimentação e economia de bateria. Parâmetros do ciclo BLE: período do ciclo de anúncio (com que frequência o controlador acorda — um valor menor dá resposta mais rápida, um maior poupa energia), duração da janela de anúncio, tempo de retenção da conexão, janela de vínculo e sono entre ciclos (10–20 s — duas pilhas AA duram meses; 0 significa sem suspensão, para alimentação por USB).
  6. 6. Relógio externo (opcional). Um módulo RTC (DS3231, DS1307, PCF8563) e os pinos I2C — só são precisos se entregar aos convidados chaves com prazo. Sem ele pode saltar esta secção.

Com o formulário preenchido, clique em "Gerar o programa".

3.2 Gravação pelo navegador

O jeito mais simples — sem instalar programas extras.

Requisitos:
  • Chrome, Edge, Opera ou Brave em computador, versão 89 ou mais recente. O Firefox, o Safari e os navegadores móveis não suportam WebSerial e não funcionarão.
  • Um cabo USB para ligar o controlador ao computador.
  • Um controlador USB-COM. Na maioria das placas instala-se sozinho. Se a sua usa um chip CH340 ou CP210x e não aparece nenhuma porta, instale o controlador do fabricante.
  1. Conecte o controlador ao computador por USB.
  2. Na página do configurador, clique em "Enviar ao controlador".
  3. O navegador mostra um seletor de dispositivos USB. Escolha o seu controlador na lista.
  4. Na página aparece um registro do processo:
    • Leitura dos dados do chip (tipo, endereço MAC).
    • Download do firmware a partir do servidor.
    • A gravação começa. A barra vai de 0 a 100%.
    • Reinício do controlador.
  5. No fim, o controlador reinicia sozinho e arranca com o novo firmware.
Não desligue o USB durante a gravação. Se o processo for interrompido, o controlador fica em modo bootloader e tem de ser gravado outra vez.

Se algo der errado:

SintomaSolução
"WebSerial não é compatível"Abra a página no Chrome ou Edge de computador
O controlador não aparece no seletor de portasInstale o driver USB-COM (CH340, CP210x)
"Failed to connect" após longa esperaMantenha premido o botão BOOT (ou IO0) da placa, carregue em RESET, largue o RESET e depois o BOOT — assim coloca o controlador em modo bootloader à mão
«Port is already open»Feche o IDE do Arduino, o PuTTY, o MicroPython e tudo o resto que esteja a ocupar a porta

3.3 Regravar relés Wi-Fi prontos

Os relés Wi-Fi comerciais com contacto seco (Shelly Plus 1, Shelly Plus 1PM) vêm com o firmware do fabricante. Para ter controlo BLE direto, sem nuvem e sem depender do Wi-Fi, esse firmware tem de ser substituído pelo do Entrixy.

Estes equipamentos são feitos para automatismos de portão e cancela: têm um par de bornes secos NO/COM que se ligam diretamente aos bornes Open do seu motor. A caixa é compacta, o relé é certificado e, ao contrário de um módulo caseiro, dispensa caixa de derivação.

O que você vai precisar:

Segurança. Desligue o equipamento da corrente antes de o abrir. Nunca ligue um adaptador USB-série a um equipamento sob tensão de rede — a diferença de potencial de massa destrói a porta USB do seu computador.

Passos:

  1. Abra o configurador entrixy.com/esp/ble/. Escolha na secção «Relés Wi-Fi comerciais para regravar» a predefinição com o nome do seu relé.
  2. As definições de pinos preenchem-se sozinhas. Vêm de bases de dados abertas de pinouts (templates.blakadder.com, devices.esphome.io) e estão testadas nas revisões mais comuns.
  3. Na página do configurador, na secção «Aceder ao UART em relés Wi-Fi comerciais», encontre o seu modelo e siga as instruções de ligação.
  4. Ligue o adaptador USB-série: TX ao RX do equipamento, RX ao TX do equipamento, GND ao GND. Alimente o equipamento pelos 3,3 V do adaptador, ou pela sua própria fonte com a rede desligada.
  5. Coloque o ESP em modo bootloader (na maioria dos equipamentos, ligue o GPIO0 ao GND ao alimentar).
  6. Clique em "Gerar o programa" e aguarde terminar.
  7. Carregue-o com «Enviar para o controlador» ou com o esptool no seu computador.
  8. Desligue todos os fios e feche a caixa. Devolva ao equipamento a sua alimentação de rede habitual.
  9. O relé aparece por BLE como um dispositivo à espera de emparelhamento. Emparelhe-o conforme descrito na secção 4. Vínculo do controlador.
  10. Ligue os bornes NO/COM do lado da rede do equipamento em paralelo com o botão Abrir do seu motor (ver a tabela de bornes típicos na secção do configurador «Ligar o relé ao motor»).

Se o seu modelo não estiver entre os presets:

  1. Procure em templates.blakadder.com — uma base aberta de modelos Tasmota.
  2. O modelo indica os GPIOs dos principais elementos: Relay1 = pino do relé, Button1 = pino do botão, Led1 = LED de status.
  3. Certifique-se de que o equipamento tem bornes de saída NO/COM (contacto seco) — sem eles não consegue acionar um motor de portão, apenas comutar corrente para uma carga.
  4. Introduza à mão no formulário do configurador os valores de GPIO que descobriu.

3.4 Gravação manual com esptool

Se o WebSerial não funcionar (num computador antigo ou num telemóvel, por exemplo), descarregue o ficheiro de firmware e use o utilitário esptool.

  1. Na página do configurador carregue em «Descarregar ficheiro» e guarde o .bin.
  2. Instale o esptool com Python: 
    pip install esptool
  3. Conecte o controlador ao computador.
  4. Execute o comando de gravação: 
    esptool.py --chip auto --port /dev/ttyUSB0 \
  write_flash 0x0 entrixy-ble-XXXX.bin
    No Windows, em vez de /dev/ttyUSB0 use a porta COM (por exemplo COM3). Use o seu próprio nome de arquivo. O endereço 0x0 está correto — o nosso ficheiro já contém o bootloader, a tabela de partições e a aplicação numa única imagem combinada.
  5. Quando terminar, desligue o controlador e volte a ligá-lo para arrancar o novo firmware.

4. Vínculo do controlador com o app

Depois da gravação, o controlador fica à espera de emparelhamento. Nesse modo emite durante 90 segundos o sinal «à espera de um proprietário». Se ninguém emparelhar nesse prazo, passa ao modo normal sem proprietário.

  1. Abra o app no papel de proprietário.
  2. Vá em Configurações → "Adicionar objeto" → tipo "BLE".
  3. O app começa a procurar controladores em modo de vínculo.
  4. Se o controlador já estiver em modo de emparelhamento (acabado de gravar, ou com o botão de emparelhamento premido há pouco), aparece na lista. Selecione-o.
  5. Se não aparecer, carregue no botão de emparelhamento do controlador. O LED começa a piscar depressa e a lista na aplicação atualiza-se.
  6. A aplicação faz uma troca de chaves ECDH. Demora uns segundos. A partir daí o controlador é seu — mais ninguém se pode emparelhar com ele enquanto não o repuser.
  7. Dê um nome ao objeto («Cancela do pátio», «Portão lateral», «Fechadura da arrecadação»). Pode escolher um ícone ou carregar uma foto.
Limpar o vínculo. Para entregar o controlador a outro proprietário ou emparelhá-lo de novo, mantenha o botão de emparelhamento premido mais de 5 segundos. O controlador volta ao estado de fábrica e entra outra vez em modo de emparelhamento durante 90 segundos.

5. Objetos

Um objeto é aquilo que quer controlar. Um mesmo utilizador pode ter vários objetos de tipos diferentes: a cancela do pátio (um controlador BLE), o número do operador (um telefone), um relé na casa inteligente (um webhook).

5.1 Controlador BLE

Adiciona-se pela secção «Emparelhamento do controlador» acima. No ecrã principal aparece como um cartão com indicador de estado:

Um toque no cartão abre o objeto diretamente, se as suas definições de segurança o permitirem.

5.2 Número de telefone

Para portões e cancelas que abrem com uma chamada.

  1. Configurações → "Adicionar objeto" → tipo "Chamada".
  2. Introduza o número do operador ou o do controlador da cancela.
  3. Defina «Desligar após N segundos» se quiser uma chamada de abertura curta (5–10 segundos) e sem conversa.
  4. Escolha como será tratado:
    • Chamada direta — o app disca o número sozinho.
    • Notificação — os convidados recebem a pergunta «abrir?», confirma você mesmo e a chamada sai do seu telemóvel.

5.3 Webhook

Para integração com tudo o que aceite comandos HTTP: uma casa inteligente, um relé na sua rede Wi-Fi, a API de um portão, IFTTT.

  1. Configurações → "Adicionar objeto" → tipo "URL".
  2. Informe a URL do serviço de destino.
  3. Escolha o método HTTP: GET, POST, PUT.
  4. Acrescente cabeçalhos se forem exigidos (Authorization, X-API-Key).
  5. Informe o corpo da requisição para POST ou PUT.
  6. Escolha o modo: app ou servidor (detalhes na seção 8. Webhooks).

6. Chaves de convidado

A chave de convidado é um convite para outra pessoa aceder aos seus objetos. O convidado usa a mesma aplicação Entrixy, apenas no papel de convidado.

Criação de uma chave

  1. Na tela principal: Convidados → Criar chave.
  2. Escreva o nome do destinatário («Estafeta», «Ana»). Esse nome vê-o você no registo; o convidado vê outro.
  3. Assinale os objetos a que dá acesso. Serve qualquer subconjunto dos seus objetos.
  4. Configure a automação de cada objeto que partilha (geozona, horário, zona BLE). Pode fixar as definições para que o convidado não as altere, ou propor valores predefinidos que o convidado possa afrouxar ou apertar.
  5. Salve. A chave aparece na lista de convidados.

Entrega da chave

O cartão da chave oferece várias formas de a fazer chegar ao destinatário:

Gerenciar convidados

Na secção Convidados estão as chaves que emitiu. Para cada uma delas pode:

O registro de eventos do convidado

Cada abertura feita por um convidado fica no registo do proprietário com a marca «Convidado: nome». Funciona mesmo que o convidado tenha usado BLE diretamente sem rede — o evento é guardado no telemóvel do convidado e enviado assim que este se liga ao servidor.

7. Automação

Qualquer objeto pode ser configurado para disparar automaticamente segundo condições. Abra-o pelo menu do objeto → Automação.

7.1 Geolocalização

Abre quando você se aproxima de um ponto no mapa.

  1. Coloque o ponto no mapa (carregue em «Usar a atual» se estiver junto ao objeto).
  2. Defina o raio — a distância à qual dispara (habitualmente 20–50 metros para pátios, 100–200 para grandes estacionamentos).
  3. Salve.

Como funciona o disparo:

7.2 Wi-Fi

Abre quando o seu telemóvel se liga a uma rede Wi-Fi específica. Útil para «quando estou em casa, abre o portão à chegada».

  1. Ative a regra de Wi-Fi.
  2. Adicione uma rede. O app lista as disponíveis por perto.
  3. Pode acrescentar várias redes (casa e trabalho, por exemplo). Por predefinição, qualquer correspondência dispara.

7.3 Hora

Um limite por hora do dia e dia da semana. Use-o para restringir um convidado («acesso apenas em horário de trabalho») ou como condição na sua própria automação.

7.4 BLE

Dispara consoante a potência do sinal BLE do controlador. Bom para fechaduras e cancelas onde o GPS é impreciso — dentro de edifícios ou num estacionamento subterrâneo.

7.5 Combinação de regras

Pode ativar várias regras ao mesmo tempo e escolher como se combinam:

7.6 Confirmação da ação

Você pode exigir uma confirmação extra antes de cada abertura:

Estas definições podem ser gravadas na chave de um convidado — exigir um PIN ao convidado, por exemplo, mas não a si.

8. Webhooks em detalhe

Um objeto webhook funciona num de dois modos. A escolha depende de quem deve fazer o pedido HTTP: o seu telemóvel ou o nosso servidor.

8.1 Modo app

O pedido HTTP é enviado pela aplicação no seu telemóvel. Ao disparar — você toca, ou um convidado pede através do servidor — o servidor avisa o seu telemóvel, e este faz o pedido ao endereço de destino.

Quando escolher:

Limitação: o seu telemóvel tem de estar online nesse momento. Se estiver desligado ou sem internet, o webhook não será enviado.

8.2 Modo servidor

O nosso servidor envia ele próprio o pedido HTTP, a partir do seu próprio endereço IP. O seu telemóvel não é preciso nesse momento.

O corpo da requisição é JSON com assinatura HMAC:

{
  "action": "open",
  "object_id": 42,
  "timestamp": 1717075200,
  "nonce": "8f2a1c4b5e6d7f80",
  "signature": "a3b4c5d6e7f8..."
}

A assinatura é calculada assim: monte a string timestamp.nonce.action.object_id e calcule HMAC-SHA256(essa string, webhook_secret), depois compare com a signatureque você recebeu. Rejeite a requisição se |now − timestamp| tem mais de 300 segundos. O formato completo e um vetor de teste estão em entrixy.com/webhook.

Quando escolher:

Segurança: ao criar o webhook você define um webhook_secret. Os convidados nunca recebem esse segredo, mesmo tendo acesso ao objeto. O servidor assina os pedidos com ele em seu nome.

Tempo-limite: se o serviço de destino não responder em 15 segundos, o servidor fecha a ligação e devolve um estado de erro.

9. Integrações com a casa inteligente

O diretório /integrations/ do site contém configurações prontas para as plataformas mais populares. Cada uma tem o seu próprio README com esquema de ligações.

PlataformaO que fazer
Home AssistantCopie configuration.yaml do diretório. No Entrixy crie um webhook em modo servidor com o URL https://your-ha/api/webhook/entrixy.
ShellyNo Entrixy crie um webhook em modo aplicação com o URL http://shelly-ip/relay/0?turn=on. Uma simples chamada GET: o telemóvel faz o pedido dentro da sua rede doméstica.
TasmotaIgual ao Shelly. URL: http://tasmota-ip/cm?cmnd=Power%20Toggle.
ESPHomeFirmware alternativo para o ESP32 se preferir o ecossistema ESPHome ao nosso protocolo BLE. No diretório há uma configuração YAML de exemplo.
OpenHABSemelhante ao Home Assistant. Aceita pedidos HTTP através da API de regras.
curlUm script de teste. Aceita o nosso JSON, verifica a assinatura HMAC e imprime o resultado. Use-o para depurar.
FlaskUm esqueleto em Python para o seu próprio serviço. Aceita o nosso JSON e valida a assinatura.

10. A aplicação web para convidados

Se um convidado não quiser instalar a aplicação Android, ou tiver um iPhone, existe uma versão web em entrixy.com/app/.

A aplicação web suporta:

A aplicação web não suporta:

Para que tudo funcione sem limites, é melhor que o convidado instale a aplicação Android.

11. Segurança

A ligação com o controlador

O primeiro emparelhamento usa ECDH X25519. Ambas as partes calculam o segredo partilhado ao mesmo tempo — o segredo em si nunca passa pelo ar.

Cada comando de abertura (FIRE) é assinado com HMAC-SHA256 usando o segredo partilhado e um nonce de uso único que o controlador emite previamente. Escutar o ar não permite repetir o comando — esse nonce já foi gasto.

Acesso de convidado

O convidado não recebe o segredo partilhado, mas um token de duração limitada (24 horas por predefinição), assinado pelo proprietário. O controlador verifica a assinatura do proprietário e a validade — mesmo um token de convidado que tenha fugido deixa de funcionar depois de expirar.

O token é renovado automaticamente através do servidor enquanto o emparelhamento do proprietário se mantiver. Assim que o proprietário revoga a chave, a renovação seguinte falha e o convidado perde o acesso.

A ligação entre a aplicação e o servidor

Todas as ligações usam TLS (HTTPS e WSS). Os dados de utilizador — números de telefone, nomes de objetos e de convidados — ficam no servidor cifrados de ponta a ponta, pelo que nem o dono do servidor os consegue ler sem a sua chave.

A criptografia está descrita em detalhe no documento Arquitetura E2EE.

Webhooks em modo servidor

Os pedidos são assinados com HMAC-SHA256. O segredo que define no servidor nunca é entregue a clientes nem a convidados. Quem intercetar um pedido não o consegue repetir, porque a marca temporal expira ao fim de 300 segundos — uma regra que o serviço de destino aplica.

12. Perguntas frequentes e resolução de problemas

O controlador BLE não aparece

  1. Verifique se o controlador tem alimentação. O LED deve estar a piscar.
  2. Verifique se o Bluetooth do telemóvel está ligado.
  3. Se a poupança de bateria estiver ativa, desligue-a para o Entrixy.
  4. Aproxime-se do controlador, a um ou dois metros — no limite do alcance o sinal pode cair.
  5. Se o controlador estiver em sono profundo (deep_sleep_wake_s > 0), não está no ar todo o tempo — só durante a sua janela de vigília. Espere 10 a 30 segundos.

Dispara várias vezes seguidas

O mais provável é que esteja mesmo no limite da zona de disparo e o sinal esteja a oscilar por interferências. O que fazer:

Um convidado diz que o cartão está cinzento e não abre

Verifique o estado da chave dele na sua secção Convidados. Motivos possíveis:

A aplicação fechou-se sozinha

O Android mata os serviços em segundo plano com agressividade para poupar bateria. Para o evitar:

O webhook não chega ao Home Assistant

  1. Verifique o URL nas definições do webhook. Tem de estar completo — com o esquema https:// e a porta, se não for a padrão.
  2. Verifique se o Home Assistant é acessível de fora (em modo servidor) ou a partir da sua rede doméstica (em modo aplicação).
  3. Veja os registos do Home Assistant no momento do disparo — deve haver uma entrada do pedido recebido.
  4. Verifique a firewall do seu router, caso esteja a bloquear ligações de entrada.

As notificações de chamada não funcionam na Huawei

As notificações push assentam no Google FCM, que na Huawei não está disponível sem os Serviços Google. Como alternativa, mantenha a aplicação aberta em vez de minimizada, ou use o emparelhamento BLE e as geozonas em vez das notificações.

Como atualizar a aplicação

Abra entrixy.com/download/android no telemóvel e instale a versão mais recente por cima da atual. Os seus dados são mantidos.

Quando uma atualização é obrigatória — uma correção crítica de segurança — a aplicação mostra uma caixa de diálogo bloqueante no arranque.

Como apagar a sua conta e todos os dados

Abra a aplicação → Definições → Apagar conta. Tudo o que está no servidor é eliminado no prazo de 30 dias, o período padrão indicado na política de privacidade.

Para uma eliminação imediata, envie um pedido para o endereço de apoio indicado na Política de Privacidade.

Documento atualizado a 30-05-2026. Se algo não estiver claro ou o seu cenário não estiver coberto, escreva para hello@entrixy.com.