Skip to content

INSTALLATION.md

Latest commit

 

History

History
125 lines (96 loc) · 7.54 KB

INSTALLATION.md

File metadata and controls

125 lines (96 loc) · 7.54 KB

INSTALAÇÃO

Configurando o Home Assistant

  • Ative a API do Home Assistant para seu usuário e obtenha um token de acesso de longa duração.

Criando a Skill Alexa

  1. Crie uma Skill na Alexa Developer Console seguindo os passos abaixo:
    • Name your Skill: Escolha um nome de sua preferência (Ex: Home Assistant Assist)
    • Choose a primary locale: Portuguese (BR)
    • Choose a type of experience: Other
    • Choose a model: Custom
    • Hosting services: Alexa hosted (Python)
    • Hosting region: US East (N. Virginia) é o padrão, mas é necessário utilizar a mesma região onde criou a conta na AWS e configurou o IAM Instruções aqui
    • Templates: Clique em Import skill
    • Insert the address: https://github.com/fabianosan/HomeAssistantAssist.git e clique Import
  2. Vá na aba Code
  3. Insira suas informações no arquivo de configuração conforme instruções abaixo:
    • Abra o arquivo config.cfg no diretório raiz do projeto (/Skill Code/lambda/).
    • Insira as seguintes informações: 
      home_assistant_url=https://SUA-URL-EXTERNA-DO-HOME-ASSISTANT
home_assistant_token=SEU-TOKEN-DO-HOME-ASSISTANT
home_assistant_agent_id=SEU-AGENT-ID
home_assistant_language=pt-BR
home_assistant_room_recognition=False
home_assistant_dashboard=ID-SEU-DASHBOARD
home_assistant_kioskmode=False
    • home_assistant_url: URL externa do seu Home Assistant (caminho raiz).
    • home_assistant_token: Token de acesso de longa duração do seu Home Assistant.
    • (opcional) home_assistant_agent_id: ID do agente de conversação configurado no seu Home Assistant, se não configurado, será utilizado o Assist (Padrão).
    • (opcional) home_assistant_language: Idioma para chamar a API de conversação do Home Assistant. Se não configurado, será utilizado o padrão do agente definido.
    • (opcional) home_assistant_room_recognition: Ative o modo de identificação de área do dispositivo com True. Atenção, só funciona com IA, se utilizar o Assist padrão, desative essa opção, pois nenhum comando irá funcionar.
    • (opcional) home_assistant_dashboard: Caminho do dashboard para exibir na echoshow, ex.: mushroom, se não configurado, irá carregar o "lovelace"
    • (opcional) home_assistant_kioskmode: Ative o modo quisque com True. Atenção, só ative essa opção se tiver o componente instalado.
  4. Se desejar, altere as respostas padrão da skill no arquivo /locale/pt-BR.lang ou outro idioma suportado).
  5. Salve as alterações.
  6. Clique em Deploy.

Obtendo o home_assistant_agent_id do Assist ou da IA generativa (se estiver utilizando uma):

  • Com seu Home Assistant aberto, navegue até a Ferramentas de Desenvolvedor, vá na aba Ações e siga os passos abaixo:
  1. Busque por conversation.process no campo de ações e selecione:

Ação: Conversação: Processo

  1. Ative o campo Agente e selecione o agente de conversação desejado na lista:

Ação: Agente

  1. Alterne para o MODO YAML e copie o ID que está no campo agent_id:

Ação: Agente ID

Obtendo o home_assistant_token (Token de longa duração):

  • Com seu Home Assistant aberto, navegue até o seu perfil de usuário, no canto inferior esquerdo, clique e depois vá na aba Segurança na parte superior:

    1. No final da página, clique no botão CRIAR TOKEN:
    2. Digite o nome que achar adeuqado, ex.: Skill Home Assistant Assist e clique em em OK:

    Criar token

    1. Copie o token:

    Token criado

    1. Coloque o token gerado no arquivo de configuração.

Configurando o Invocation Name

  • O nome de invocação padrão configurado no código é "casa inteligente".
  • Para alterar o nome de invocação:
    1. Vá para a aba Build.
    2. Clique em Invocations e depois em Skill Invocation Name.
    3. Insira o novo nome de invocação desejado e salve as alterações (teste se essa palavra de ativação pode ser usada na aba de Test).
    4. Dê rebuild do modelo clicando Build skill se alterar.

Publicando a Skill

  1. Após fazer o deploy do código na aba Code, volte para aba Build e clique em Build skill.

  2. Depois vá no aplicativo Alexa em seu celular e vá em: Mais > Skills e jogos > deslize a tela até o fim e clique em Suas Skills > Desenv., clique na skill que você acabou de criar e ative

    Desenv. skills Ativar para uso

  3. Volte no console da Alexa Developer Console e teste a Skill na aba Test para garantir que a palavra de ativação e a skill estão funcionando corretamente.

Ativando o reconhecimento de cômodo (só funciona com IA)

  • Nesse modo, a skill envia o device id (do dispositivo echo que está executando a skill) na chamada da API de conversação do Home Assistant, então com uma instrução de comando para a IA e um rótulo associado no dispositivo, a IA consegue identificador os dispositivo da mesma área onde está localizado sua Alexa, para ativar, siga os passos abaixo:

    Atenção !

    Esse modo deixa os comandos mais lentos e e exige configurações mais complexas:

    1. Altere a configuração home_assistant_room_recognition para True e faça um novo deploy e um novo Build Model da skill;
    2. Ative o log de debug da API de conversação adicionando a seguinte configuração no configuration.yaml do Home Assistant:
    • Insira a seguinte informação: 
      logger:
  logs:
    homeassistant.components.conversation: debug
    1. Reinicie o Home Assistant e inicie a skill pelo dispositivo echo desejado, depois de ativado, o log mostrará a instrução recebida pela skill conforme o exemplo abaixo:
    2024-10-10 11:04:56.798 DEBUG (MainThread) [homeassistant.components.conversation.agent_manager] Processing in pt-BR: ligue a luz da sala. device_id: amzn1.ask.device.AMAXXXXXX

    Você também pode obter o device_id no log "device: " pela Alexa Developer Console em Cloud Watch se souber como fazê-lo. 4. Pegue todo o identificador que estiver após o device_id, ex.: amzn1.ask.device.AMAXXXXXX e adicione um novo rótulo no dispositivo echo pela Integração Alexa Media Player:

    Rótulo no dispositivo echo com o device ID recebido da skill

    1. Atualize o prompt de comando da IA de sua preferência com a instrução abaixo: 
      Se solicitado uma ação em um dispositivo e sua área não for fornecida, capture o identificador contido após o "device_id:" no comando, obtenha o rótulo com mesmo identificador e associe a área desse rótulo ao dispositivo para saber área o dispositivo pertence.

Boa sorte!

Agora você pode usar sua skill Alexa para integrar e interagir com o Home Assistant via Assist por voz ou abrir a tela do seu dashboard preferido na Echoshow. Se gostou, lembre-se de mandar um Obrigado para os desenvolvedores.

Agradecimentos

Ao [rodrigoscoelho](https://github.com/rodrigoscoelho), quem iniciou o desenvolvimento desta skill.