Uma das grandes dores de cabeça na configuração do Home Assistant são os erros provocados pelo código YAML utilizado nos ficheiros de configuração. Embora o HA caminhe para que toda a configuração seja feita através da UI, veja-se o caso da Integrações por exemplo, o caminho ainda será longo e em algumas situações será sempre preciso usar o YAML.
O YAML (uma sigla que significa YAML Ain’t Markup Language) não é propriamente uma linguagem de programação mas sim uma sintaxe para a criação de ficheiros de configuração.
Este tutorial reflecte apenas a implementação do YAML utilizada no HA pois existem pequenas diferenças de implementação entre diversos sistemas.
Pré-requisitos
A utilização de um bom editor de código é fundamental pois um editor que permita a visualização de símbolos (espaços, tabulações, parágrafos, etc) irá facilitar bastante a escrita de código.
Nesse sentido, aconselho a utilização do Notepad++ ou o VScode caso trabalhem com os ficheiros em modo local. No Notepad++ a visualização dos símbolos tem de ser activada (view > Show Symbol > Show White Space and TAB) mas no VScode a visualização dos símbolos vem já activa por defeito.
Se quiserem uma integração directa com a interface do HA, o VScode existe como addon para Hassio embora apenas para a arquitectura amd64.
O VScode quando integrado com o HA permite ter várias funções extra, como por exemplo o autocomplete do nome das entidade, pesquisa e inserção de ícones com um clique, acesso à linha de comandos do Hassio, etc.
Um outro pré-requisito muitas vezes ignorado é a codificação do ficheiro, a qual deverá ser sempre UTF-8. Por este motivo devem ter sempre atenção quando copiarem ficheiros de outros sistemas para inserir na configuração do HA ou quando criarem novos ficheiros, em especial no Notepad++.
Os exemplos mostrados neste tutorial são escritos no VScode utilizando o código de um cartão de Lovelace.
YAML
Identações
A estrutura do YAML é determinada pela sua indentação, sendo a indentação definida pelo numero de espaços no inicio da cada linha e podem ser zero, dois ou múltiplos de dois.
indentação = espaço x 2
Os caracteres de tabulação não devem NUNCA ser utilizados para criar indentações e o HA irá gerar um erro na validação do código caso sejam utilizados.
A estrutura de cada bloco é constituída por níveis, sendo que o nível anterior é considerado parent e o inferior children. No exemplo seguinte cards: é parent de color: 'rgb(82,148,226)'. Do mesmo modo, style: tem como children color: white mas é ele próprio children de cards:.
O caracter - indica o inicio de uma listagem de variaveis ou atributos que se encontram ao mesmo nível, e que deve ser considerado na contagem de espaços na indentação. Embora o HA não considere como um erro, visualmente fica mais simples de ler o código e descobrir eventuais problemas.
Abaixo podem ver a indentação a funcionar na criação de um cartão que incorpora dois outros cartões na vertical. No nível 1 temos o cartão principal e que é parent dos dois cartões verticais no nivel 2. Em YAML os níveis iguais em termos de indentação chamam-se siblings.
Linhas Vazias
Quando necessitarem de deixar linhas vazias entre blocos de código, o que por vezes ajuda na criação do código, devem deixar a linha em branco sem caracteres ou quanto muito com espaços iguais a dois ou múltiplos de dois. A utilização de tabulações provoca erros na validação.
Comentários
Em YAML os comentários são indicados pelo caracter #. Se o comentário estiver entre dois blocos de código deve ser escrito sem espaços à esquerda, se for escrito após uma linha de código deve sempre ser precedido de um espaço ou de uma ou mais tabulações para que os comentários fiquem alinhados.
Se necessitarem de criar comentários em linhas seguidas, seja por o comentário ser muito comprido ou serem dois comentários diferentes, todas as linhas deverão ser iniciadas pelo caracter #
Conclusão
Embora inicialmente seja difícil de utilizar o YAML não é um bicho-de-sete-cabeças. Ao fim de algum tempo e com um bom editor de texto rapidamente escreverão código sem erros. E nunca se esqueçam do seguinte:
-
Depois de editar código devem SEMPRE validar a configuração antes de fazer reboot,
-
As mensagem de erro na validação e os erros no log ajudam muito no despiste de erros.
Este tutorial é baseado na informação constante na página oficial do YAML e diz respeito apenas à formatação do código.