search

ale-jr / rinnai_br_homeassistant

Integração entre módulo wifi dos aquecedores rinnai com o home assistant
MIT License
19 stars 3 forks source link

readme

Integração Módulo Wifi Rinnai com Home Assistant (Não oficial)

Addon para integrar no Home Assistant os aquecedores de água a gás da Rinnai Brasil que suportam o módulo ROU003.

Considerações

Instalação

Pré requisitos

  1. Por ser um addon e não uma integração em si (quem sabe isso não vira uma integração no futuro 😅), é necessário que a integração MQTT esteja configurada na sua instância para que as entidades relacionadas ao aquecedor sejam criadas
  2. Configurar o módulo no App oficial da Rinnai, dica: Eu só consegui configurar o módulo no App com um celular mais antigo (Androind 10) então se vocês estiver enfrentando problemas em versões mais novas do Android/iOS talvez dê para configurar com um dispotivo mais antigo (dá para usar a feature de convite para usar o seu celular mais atual depois de configurar)
  3. Descobrir o IP do módulo na sua rede, essa parte é mais chatinha e como o módulo não utiliza mDNS nem define um nome de host é mais dificil de achar, uma das formas mais fáceis é ver no seu roteador ou utilizar um app chamado Net Analyzer para descobrir quais são os ips na sua rede e ir tentando para cada endereço acessar a url http://ip/bus até ver ver uma tela cheia de números. Com o Net Analyzer é só tentar os endereços que tenham o fabricante Espressif Inc. (Sim, cobram 300 reais por um esp8266, mas até ai você pagou muito mais pelo software do que pelo hardware 😅😅😅😅)
  4. Adicione e instale este repositório como um repositório de addons do home assistant:
    • Em http://homeassistant.local:8123/hassio/store, clique no menu superior direito e depois clique em "repositórios"
    • Cole a url deste projeto https://github.com/ale-jr/rinnai_br_homeassistant, clique em adicionar e feche o modal
    • Clique botão no botão superior esquerdo e depois em "Verifique se há atualizações"
    • Pesquise por "Aquecedor Rinnai" e clique no card que aparecer, se não aparecer nenhum, tente reiniciar a instância do home assistant
    • Instale o addon
  5. Configure as variáveis Na tela do addon clique em "Ajustes" e preencha os campos
    • device_model: Modelo do seu aquecedor, exemplo: reue27 (por hora esse campo só vai servir para definir o nome do dispositivo no home assistant, porém pode ser que seja usado no futuro para descobrir o dispositivo na rede)
    • device_serial_number: Número de série do seu aquecedor (esse campo só vai ser usado para definir o serial number do dispositivo no home assistant)
    • device_host: O endereço de IP do módulo
    • device_poll_interval: De quanto em quanto tempo (em segundos) o addon deve atualizar o estado do aquecedor, se você continuar usando o aplicativo da rinnai é aconselhável deixar a partir de 30 segundos, menos que isso e o app oficial pode começar a ficar lento ou parar de funcionar as vezes
    • mqtt_host: ip do seu broker mqtt, se você usa o addon de broker do HA o host deve ser o mesmo IP do home assistant (no futuro eu quero pegar essas configs via HA ao invés de variáveis)
    • mqtt_user: usuário mqtt do seu broker mqtt
    • mqtt_password: senha do usuário do seu borker mqtt
    • ha_ip: endereço ip da sua instância do home assistant (não pode ser localhost) pois esse endereço deve ser o mesmo que o módulo ira reconhecer como origem da requisição, isso é importante para definir a prioridade na hora de definir a temperatura (explico mais sobre isso abaixo)
  6. Inicie o addon e aguarde as entidades serem criadas. Na página de dispositivos, o aquecedor vai aparecer como um dispositivo no card do MQTT, já contendo todas as entidades (por enquanto temos as entidades: status, temperatura definida, temperatura de entrada e saida, porém mais serão adicionadas no futuro)
  7. Agora é só adicionar as entidades no seu painel e/ou fazer automações :D

Contribuindo com o projeto

Iniciar o projeto localmente em modo de desenvolvimento

Para facilitar o desenvolvimento de novas features é possível rodar o projeto localmente de forma independente do home assistant. Para isso basta seguir estes passos:

  1. Clone este repo
  2. Entre em modulo_aquecedor_rinnai_brasil
  3. npm install para instalar as depedências necessárias
  4. Crie uma cópia do arquivo options-mock-example.json com o nome options-mock.json e defina todos os campos seguindo o padrão de configuração descrito na seção de instalação do addon, você deve utilizar o mesmo broker mqtt que o HA utiliza para que o dispositivo e as entidades sejam criadas na instância do HA. É aconselhável definir o serial number como "debug" ou algo do tipo para não "sujar" o dispotivo que você pretende usar no dia a dia
  5. npm run dev para subir o projeto em modo de desenvolvimento com recarregamento automático caso algum arquivo seja alterado

PRs e issues

Encontrou algum problema? Tem alguma sugestão de melhorias? Bastar criar uma issue no projeto explicando o que aconteceu, o addon possui alguns logs, sinta se livre para anexar estes logs na hora de abrir a issue. Quer colocar a mão na massa, faça um fork desse repo, code a feature/bugfix e abra um PR apontando para o branch main (por enquanto 😅, se isso crescer a gente pensa em organizar melhor)

API

Documentação dos endpoints baseado nas requests que o aplicativo oficial faz

Conceitos

Prioridade para definir temperatura

Não sei ao certo o porquê dessa feature, mas quando o aquecedor está em funcionamento os comandos de aumentar/diminuir a temperatura só funcionam para o ip do dispositivo que possui "prioridade". Além disso, quando algum ip está como prioritário, nenhum outro dispositivo conseuge definir a temperatura e no app oficial o ícone do cadeado vai ficar vermelho.

Comportamento no addon

Toda vez antes de mudar a temperatura é verificado se existe alguma dispositivo com prioridade, se existir a temperatura não será alterada. Se não houver, antes de iniciar os comandos para alterar a temperatura o addon vai definir a prioridade para o IP da instância e logo após o término dos comandos o addon vai definir a prioridade para null

Temperatura não "linear"

Existem alguns "gaps" na hora de definir a temperatura, dos 35 até os 46 graus a temperatura pode ser definida com a precisão de um grau, após os 46 é possivel definir apenas a temperatura para 48, 50, 55 e 60 graus. a temperatura é definida chamando dois endpoints, um para aumentar a temperatura e outro para diminuir, ambos emulam o botão físico

Comportamento no addon

Quando uma temperatura fora desse gap for definida a temperatura será ajustada para a menor temperatura possível dentro das opções, exemplo, ao definir 58 graus na entidade do home assistant, a temperatura no aquecedor será definida em 55 e o estado será atualizado para 55

Ao invés de arredondar, eu escolhi essa abordagem para evitar que uma temperatura mais alta seja defina

Informações básicas (tela de controle)

Request:

GET /tela_

Response: 

41,0,0,18,1374,0,null:pri,20,1098019,Sep 16 2022,15,0,0,0

Descrição das propriedades separadas por vírgula

Parametros do aquecedor (tela modo de depuração)

Request:

GET /bus

Response: (Alguns itens foram substituidos por letras por serem dados sensíveis)

41,0,0,0,18,1380,10000,0,0,0,1260,2309,0,240,170,4000,192.168.15.11,null:pri,8,XXXXXXXX,XXXX,0,Sep 16 2022,15,Exception,xx:xx:xx:xx:xx:xx,0,0,4,0,0,0,0,100,100,0,0,-50,[0],2

Descrição das propriedades separadas por vírgula

Controle de temperatura

Request: Aumenta temperatura em um "step"

/inc

Response: Retorna o mesmo valor do endpoint /tela_

41,0,0,18,1380,0,null:pri,13,5327,Sep 16 2022,15,0,0,0

Request: Diminui temperatura em um "step"

/dec

Response: Retorna o mesmo valor do endpoint /tela_

41,0,0,16,1380,0,null:pri,13,5327,Sep 16 2022,15,0,0,0

Ligar/Desligar aquecedor

Request: Alterna entre ligar e desligar

/lig

Response:Retorna o mesmo valor do endpoint /tela_

11,0,0,18,1380,0,null:pri,12,5437,Sep 16 2022,15,0,0,0

Consumo semanal

Request: 

/consumo

Response:

97:20,382,9457,145:17,577,15477

Descrição das propriedades separadas por vírgula

Histórico

Request: 

/historico

Response:

17:30,9,65,1327,1669228461;1:57,9,5,69,1669227406;13:04,13,43,1130,1669206601;21:07,13,82,2244,1669106217;20:41,8,89,1922,1668984818;21:06,12,83,2168,1668972831;1:00,20,9,394,1668873479;17:27,12,64,1706,1668801820;18:21,9,61,1282,1668762456;2:16,8,5,119,1668761297;

Histórico de uso separado entre ; para cada uso e entre , para cada parâmetro de uso. Registros sâo ordenados dos mais atuais para os mais antigos Parametros por registro

Endpoints a serem documentados:

Melhorias