Hubitat é um sistema orientado a eventos. Em geral, as automações no Hubitat são realizadas usando um app que atua em um dispositivo (o código por trás de um dispositivo é chamado de driver), onde o dispositivo no Hubitat geralmente corresponde a algum dispositivo do mundo real, como um switch ou termostato. Os dispositivos podem oferecer comandos que podem ser executados no dispositivo (por exemplo, para desligar um interruptor ou definir um termostato para um determinado ponto de ajuste). Os dispositivos geralmente também geram eventos, que geralmente são mudanças de estado – por exemplo, um movimento se tornando ativo ou um interruptor sendo desligado.
Relacionados aos eventos estão os atributos, que possuem um valor. Esses atributos geralmente representam o estado atual de um dispositivo e são visíveis em Estados atuais na página de detalhes do dispositivo. A alteração do valor de um atributo em um dispositivo é feita através do envio de um evento (normalmente no driver). O próprio hub - em vez de um dispositivo - também gera alguns eventos, como o nascer do sol, o pôr do sol ou quando o modo do hub muda.
Embora não seja explicitamente obrigatório, muitas vezes acontece que comandos e atributos têm um relacionamento no mundo real. Por exemplo, os comandos on() e off() em um dispositivo de comutação geralmente têm como objetivo ligar ou desligar o interruptor (ou tomada, dimmer, lâmpada, etc.), o que deve resultar em um evento que altera o valor do atributo switch. No entanto, observe que isso não é garantido. O comportamento exato depende do driver, mas normalmente você pode assumir uma abordagem "disparar e esquecer": o driver envia o comando para o dispositivo (de forma assíncrona), então o driver irá lidar com a geração de eventos em resposta se ou quando o dispositivo envia informações sobre o novo estado de volta ao hub ("se" porque o dispositivo pode estar offline, configurado incorretamente ou outro aplicativo pode ter enviado um comando "conflitante" antes que o dispositivo reporte de volta, entre outras possibilidades).
Em geral, um aplicativo pode assinar um ou mais desses eventos e, em seguida, executar ações configuradas pelo usuário em resposta. Por exemplo, um aplicativo pode escutar (assinar) um sensor de movimento específico para se tornar ativo (um evento). O aplicativo poderia então dizer a um botão para ligar (executar um comando em um dispositivo). Este é o meio pelo qual os aplicativos criam automações no Hubitat.
Alguns aplicativos são usados para ajudar a integrar dispositivos para tornar a configuração e a manutenção mais fáceis do que uma abordagem apenas de driver ou para lidar com a comunicação entre algum serviço ou dispositivo do mundo real e o(s) dispositivo(s) Hubitat. Às vezes, eles são chamados de “aplicativos de integração”. Exemplos integrados incluem o aplicativo Hue Bridge Integration e o aplicativo Sonos Integration. O foco aqui está principalmente em aplicativos típicos orientados para automação.
Para uma introdução ao desenvolvimento de aplicativos Hubitat, comece com Visão geral do desenvolvimento de aplicativos e depois vá para Construindo um aplicativo simples.
Em geral, um driver "traduz" informações de e para Zigbee, Z-Wave, Matter, uma LAN ou API de nuvem, ou qualquer que seja o protocolo do dispositivo subjacente, em atributos (eventos) e comandos "padrão" do Hubitat, para que tanto usuários quanto aplicativos pode interagir com dispositivos sem conhecer detalhes subjacentes específicos.
NOTA: Os drivers virtuais são diferentes porque geralmente simulam o comportamento real do dispositivo sem um dispositivo real subjacente. Como desenvolvedor, eles podem ser úteis como uma forma de testar aplicativos sem a necessidade de um dispositivo “real” (ou eventos reais do dispositivo). Alguns usuários também encontraram usos criativos para tais dispositivos em suas automações.
Um conceito importante para o desenvolvimento de drivers (e aplicativos) são capabilities, que especificam um conjunto de comandos e/ou atributos que um driver que implementa esse recurso deve oferecer. A maioria dos drivers implementa vários recursos, dependendo dos recursos do dispositivo e do uso pretendido.
Por exemplo, um driver que implementa capability "Switch" deve oferecer comandos on() e off(). Além disso, ele deve ter um atributo switch que reporte on ou off como o valor (geralmente esperado para representar o estado real do dispositivo), de acordo com a especificação de capacidade. Os recursos diferem no que exigem, mas geralmente correspondem aos recursos do mundo real que os dispositivos reais desse tipo geralmente oferecem. Consulte Lista de recursos do driver para obter uma lista de recursos disponíveis e os comandos e atributos que eles exigem.
Para uma introdução ao desenvolvimento de driver Hubitat, comece com: Visão geral do desenvolvimento de driver.
Os aplicativos e drivers Hubitat são escritos em Groovy e executados dentro do aplicativo Hubitat Elevation e do ambiente de execução do driver. Este ambiente é uma sandbox que fornece métodos específicos do Hubitat por conveniência (veja mais em outros guias do desenvolvedor para aplicativos, drivers e métodos comuns) e segurança.
Como parte deste modelo, existem algumas restrições. Você não pode:
println() ou sleep()No entanto, o sandbox geralmente fornece uma maneira de fazer tudo o que você precisa em um aplicativo ou driver. Por exemplo, você pode usar log.debug() e métodos semelhantes em vez de println().
Você não precisa ser um especialista em Groovy para criar aplicativos ou drivers no Hubitat, embora alguma experiência em desenvolvimento — especialmente com Groovy, Java ou linguagens semelhantes — possa ser útil. Hubitat usa Groovy versão 2.4. A documentação oficial do Groovy 2.4 pode ser encontrada em: http://docs.groovy-lang.org/docs/groovy-2.4.21/html/documentation/. Outros recursos também estão disponíveis on-line ou impressos (mas esteja ciente da versão para a qual foram escritos, pois diferentes versões do Groovy podem não oferecer alguns recursos encontrados em outras versões).
Existem também muitos exemplos de aplicativos e drivers Hubitat; consulte a documentação do desenvolvedor de aplicativos e drivers e o repositório HubitatPublic para obter mais informações). O restante da documentação do desenvolvedor também inclui exemplos e tutoriais para desenvolvimento de aplicativos e drivers.
Alguns pontos interessantes que podem ser dignos de nota para desenvolvedores familiarizados com outras linguagens:
Groovy não requer ponto-e-vírgula no final das instruções, ao contrário de Java/C/C++/etc., e os desenvolvedores Groovy normalmente os omitem.
Groovy não requer parênteses ao chamar um método que possui pelo menos um parâmetro:
log.debug "Minha mensagem de log"
A palavra-chave return é opcional; a última instrução em um método será usada como valor de retorno (se o método não for void).
"Strings bacanas" permitem o uso de ${} em torno de um valor para interpolar esse valor dentro da string (isso não funciona para strings entre aspas simples ou triplas entre aspas simples):
String nome = "João"
// Isso imprimirá "Meu nome é John" nos Logs:
log.debug "Meu nome é ${name}"
Muitos desenvolvedores (e exemplos) fazem uso do suporte do Groovy para closures. Em resumo, normalmente são blocos de código curtos e anônimos, semelhantes a métodos que podem aceitar parâmetros (por padrão, um único parâmetro implícito chamado it) e retornar um valor. Eles podem ser passados como parâmetros para métodos e são particularmente úteis com muitos métodos de coleção Groovy. Por exemplo:
def minhaLista = [1,2,3]
log.debug myList.any { it == 1 } // retorna verdadeiro
ou, por exemplo, você pode escrever em um aplicativo Hubitat:
myMotionSensors.any { it.currentValue("motion") == "ativo" }
Groovy suporta parâmetros posicionais (como Java), mas também parâmetros nomeados. Por exemplo, ao definir as preferências do aplicativo (entradas, etc.), você escreverá linhas de código como:
input name: "mySettingName", type: "text", title: "Escreva seu texto aqui"
Isso aproveita os parâmetros nomeados (e outros recursos do Groovy, como a omissão opcional de parênteses e ponto-e-vírgula) para permitir que esse código seja lido quase como o inglês. (Tecnicamente, os parâmetros nomeados são implementados como um Map usando a chave como o nome e o valor como o valor no próprio método, mas você raramente precisa se preocupar com esses detalhes, a menos que pretenda criar tais métodos sozinho. Muitos métodos construídos nos métodos Hubitat fazem uso desse recurso, e os exemplos aqui - e a maioria dos códigos reais de aplicativos e drivers que você verá - fazem uso extensivo dessas chamadas.)
Métodos bacanas e nomes de variáveis convencionalmente usam camelCase (como Java).
input), uma vez que estes se tornam variáveis para todo o aplicativo ou driver automaticamente (você aprenderá mais sobre isso nas visões gerais do aplicativo e do driver).Para começar a desenvolver aplicativos, comece com:
Ou para motoristas: