Aplicativos no Hubitat Elevation são os meios pelos quais os usuários configuram automações. O Hubitat vem com vários aplicativos integrados (por exemplo, iluminação ambiente, controlador de botão, notificações e muito mais), mas também é possível escrever aplicativos de usuário, também conhecidos como aplicativos personalizados. Escrever aplicativos de usuário é o foco deste documento.
Para criar ou modificar um aplicativo de usuário, navegue até Código do Apps na interface web do Hubitat (expanda a seção Ferramentas do desenvolvedor se você não vir isso na barra lateral). Selecione Novo aplicativo para criar um novo aplicativo ou selecione um aplicativo existente na lista para modificá-lo. Quando terminar, selecione Salvar para confirmar suas alterações. Observe que apenas o código válido será salvo; quaisquer erros aparecerão em uma barra amarela na parte superior do editor.
Para obter uma visão geral do ambiente de desenvolvimento Hubitat em geral, consulte Visão geral do desenvolvedor caso ainda não o tenha lido.
O código abaixo é um aplicativo Hubitat totalmente completo, embora não faça muito além de exibir "Olá, Hubitat!". Ainda assim, demonstra todos os componentes necessários para um aplicativo básico. Tente adicioná-lo ao Apps Code e instalá-lo em Apps > Adicionar aplicativo de usuário para ver como funciona.
definição(
nome: "Meu primeiro aplicativo",
namespace: "MeuNamespace",
autor: "Meu nome",
description: "Um aplicativo de exemplo simples",
categoria: "Conveniência",
iconUrl: "",
iconX2Url: ""
)
preferências {
page(nome: "mainPage", título: "Minha página", instalação: verdadeiro, desinstalação: verdadeiro) {
seção {
parágrafo "Olá, Hubitat!"
}
}
}
// Chamado quando o aplicativo é instalado pela primeira vez
def instalado() {
// por enquanto, basta escrever a entrada em "Logs" quando isso acontecer:
log.trace "instalado ()"
}
// Chamado quando o usuário pressiona o botão "Concluído" no aplicativo
def atualizado() {
log.trace "atualizado ()"
}
// Chamado quando o aplicativo é desinstalado
def desinstalado() {
log.trace "desinstalado ()"
// A maioria dos aplicativos não precisaria fazer nada aqui
}
Explicações adicionais sobre esses componentes são fornecidas abaixo.
A definição() em um aplicativo contém dados sobre o aplicativo, incluindo o nome e a descrição (mostrados na página Adicionar usuário do aplicativo). Parâmetros necessários:
name: o nome do aplicativo que será exibido na caixa de diálogo Adicionar aplicativo de usuário, na página Status do aplicativo e em outros locaisnamespace: um identificador exclusivo para o desenvolvedor (o nome do aplicativo mais as combinações de namespace devem ser exclusivos), normalmente um nome de usuário normalmente usado por esse desenvolvedor (geralmente seu nome de usuário do GitHub)autor: Uma string que identifica o desenvolvedor, às vezes um nome real ou nome da empresa (ao contrário do nome e do namespace, é usado apenas para fins de exibição)descrição: uma breve descrição da finalidade do aplicativo (mostrada abaixo do nome do aplicativo na página Adicionar usuário do aplicativo)categoria: atualmente não usadoiconUrl: atualmente não utilizado; deve ser definido como string vaziaiconX2Url: atualmente não utilizado; deve ser definido como string vaziaPara saber mais, consulte Definição de aplicativo.
O bloco preferences define a interface do usuário do aplicativo. O bloco preferences deve consistir em um ou mais blocos page. Cada página consiste em um ou mais blocos de seção. A maior parte da interface do usuário — a capacidade de selecionar dispositivos, digitar ou selecionar outras opções, exibir parágrafos, etc. — é feita dentro de uma seção.
Todos os parâmetros page são opcionais:
nome: exibido no topo da páginanextPage: para aplicativos de múltiplas páginas, deve ser definido como o nome da página para navegar quando o usuário seleciona o botão Próximouninstall: se true, mostrará o botão Remover (nome do aplicativo) na parte inferior desta página (deve ser definido como false apenas para aplicativos de várias páginas e true em pelo menos uma página )install: se true, mostrará o botão na parte inferior da página para instalar o aplicativo se ainda não estiver instalado (por exemplo, o usuário acabou de adicionar um novo aplicativo)As páginas devem conter uma ou mais seções (que por sua vez contêm entradas, parágrafos, etc., conforme abaixo). Mais comumente, uma seção é definida como:
seção("Título da minha seção") {
// entradas, etc. aqui
}
Para obter uma descrição completa das preferências do aplicativo, páginas, seções, entradas e recursos relacionados, consulte: Preferências do aplicativo.
O método input() permite exibir vários tipos de entradas (seletores de dispositivos, strings ou entradas numéricas, etc.). O formato geral é:
input (nome da string: elementName, tipo de string: elementType, título da string: elementTitle, /* ... opções adicionais */ )
Groovy permite omitir os parênteses, e os rótulos name e type podem ser omitidos, permitindo chamadas mais simples como esta:
input "meuNome", "meuTipo", título: "Minha entrada"
O valor que os usuários fornecem para todos os campos input é salvo em um Map integrado em cada instância do aplicativo chamado settings com a chave sendo o name da input. Esses valores podem ser acessados da mesma forma que os valores de qualquer mapa, por exemplo, settings.myName ou settings["myName"].
As entradas também podem ser acessadas no aplicativo usando simplesmente o nome (como se fosse um campo/variável), por exemplo, meuNome.
Há também um nome de configuração fornecido pelo hub que é preenchido em certos casos e deve ser evitado ao nomear suas próprias entradas:
hubitatQueryString: representação JSON de nomes/valores de parâmetros fornecidos na URL quando a página do aplicativo é carregada (ou seja, após ? uma URL), se houver (nenhum por padrão)Para obter mais informações sobre entradas de aplicativos e outros métodos de preferências, consulte: Preferências de aplicativos.
Os aplicativos nem sempre estão “em execução”. Um aplicativo será ativado em resposta a determinados eventos, incluindo:
subscribe() (isso executará o método de retorno de chamada especificado pelo desenvolvedor) – esse é o motivo mais comum pelo qual um aplicativo típico criado para executar uma automação seria ativadorunIn() ou métodos semelhantes (isso executará o método de retorno de chamada especificado pelo desenvolvedor)preferências)installed(), updated() ou uninstalled())mappings, descritos em outro lugar)Para armazenar dados entre execuções, os aplicativos têm um objeto state integrado disponível. Este objeto se comporta como um Map e permite armazenar os tipos de dados mais comuns (strings, números, listas ou mapas de tais objetos, etc. - qualquer coisa que possa ser serializada de/para JSON). Cada instância instalada de um aplicativo possui seu próprio objeto state.
Um objeto semelhante chamado atomicState também está disponível. Eles funcionam de forma semelhante, exceto que state grava os dados pouco antes de o aplicativo entrar em suspensão novamente, enquanto atomicState confirma as alterações assim que elas são feitas. Sugerimos começar com state e mudar para atomicState somente se houver preocupações com execução simultânea e dados de estado relacionados a isso. O uso de state é mais eficiente. Outra alternativa mais eficiente para atomicState é usar a especificação singleThreaded: true em definition, evitando mais de um wake sobreposto do aplicativo.
O objeto atomicState também fornece um método de conveniência:
atomicState.updateMapValue(Object stateKey, Object key, Object value): obtém um Map de atomicState, atualiza um valor dentro desse mapa e o grava de voltaOs objetos
stateeatomicStatereferem-se aos mesmos dados e podem ser misturados no mesmo aplicativo se necessário, mas a maioria dos desenvolvedores escolhe um ou outro com base nos requisitos do aplicativo.
Exemplo: state.foo = "bar"
Um aplicativo deve conter pelo menos os métodos callbak exigidos pelo hub:
installed(): chamado uma vez quando o aplicativo é instalado pela primeira vezupdated(): chamado quando o usuário seleciona o botão Concluído no aplicativouninstalled(): chamado quando o aplicativo é desinstalado. A maioria dos aplicativos não precisará fazer nada aqui (por exemplo, assinaturas, etc. são removidas automaticamente), mas se o seu aplicativo se integrar a um sistema externo que deve ser notificado, isso pode ser uma opção.O restante do aplicativo pode conter métodos definidos pelo usuário (conforme necessário para ajudar a organizar seu código), evento de assinatura ou manipuladores de trabalho agendados (se necessário) ou outros métodos que possam ser necessários para seu aplicativo específico.
Conforme sugerido na demonstração, os aplicativos (e drivers) têm um objeto log integrado que pode ser usado para gravar entradas em Logs. Os métodos disponíveis são:
log.infolog.debuglog.tracelog.warnlog.errorEles marcarão a entrada de log em Logs com o "nível" especificado, por exemplo, uma caixa branca de "informações" ao lado da entrada de log, uma caixa azul de "depuração" ou uma caixa vermelha de "erro". Os logs de informações e depuração são o tipo mais comumente usado em aplicativos e drivers. Muitos desenvolvedores consideram o registro útil como uma ferramenta para depuração ou outras soluções de problemas ao desenvolver um aplicativo (e podem usar muito mais durante o desenvolvimento inicial do que seria encontrado em um aplicativo mais estável).
Exemplo: log.debug "O valor de state.foo é ${state.foo}"
Para começar a criar um aplicativo simples – que realmente responda aos eventos do dispositivo e envie comandos para os dispositivos – continue com:
Também pode ser útil observar aplicativos de exemplo, muitos dos quais podem ser encontrados no repositório HubitatPublic GitHub: [https://github.com/hubitat/HubitatPublic/tree/master/example-apps](https://github .com/hubitat/HubitatPublic/tree/master/example-apps).
A documentação restante do desenvolvedor fornece mais informações sobre quais métodos estão disponíveis para código de aplicativo (e driver) e quais métodos e propriedades estão disponíveis em objetos ou utilitários fornecidos pelo Hubitat. Para aplicativos, o seguinte pode ser particularmente útil: