KoBa-beep/ClaudeCode-Skill

Cenas Lua HC3

Responda no idioma do usuário; mantenha identificadores em inglês. Explique para iniciantes onde clicar.

Cena ou QuickApp?

Necessidade	Cena	QuickApp
Reagir a um evento (botão, porta, horário, variável) com algumas ações	✅	mais pesado
Manter estado na memória, executar permanentemente, comunicar-se com um dispositivo (HTTP, TCP, MQTT)	❌ começa do zero a cada execução	✅
Botões / rótulos na interface do usuário	❌	✅
Regra prática: QuickApps são os drivers, cenas encadeiam ações chamando métodos de QA
(fibaro.call(idQA, "setMode", "Away")). Para QuickApps, use a habilidade hc3-quickapp.

Duas partes

1. Declarações (condições / gatilhos): uma tabela Lua, não código — quando a cena inicia.
2. Ações: código Lua executado a cada início. Dica para usuários: construa a cena no modo blocos, depois "Converter para Lua": o HC3 escreve declarações exatas (nomes de propriedades, números dos dias da semana). A conversão é unidirecional.

Declarações

{
  operador = "todos",               -- "todos" (E) | "qualquer" (OU); grupos podem ser aninhados
  condições = {
    { tipo = "dispositivo", id = 201, propriedade = "valor", operador = "==", valor = true, éGatilho = true },
    { tipo = "data", propriedade = "cron", operador = "corresponder", valor = {"*", "*", "*", "*", "*", "*"}, éGatilho = false },
  }
}

• éGatilho = true: uma mudança desta condição inicia a cena (então todas as condições são avaliadas); false: apenas filtro. Pelo menos um gatilho é necessário ou a cena nunca inicia por si só.
• Operadores: ==, !=, >, >=, <, <=, qualquerValor (qualquer mudança), corresponder (datas).
• duração = 60 em uma condição de dispositivo: deve permanecer verdadeira por 60 s [V] (visível em cenas de blocos convertidas). Tipos de condição e exemplos: referências/declarações.md (dispositivo, botão de cena central, cron, nascer/pôr do sol, variável global, evento personalizado, alarme, localização, clima, inicialização do HC3).

Ações

fibaro.debug("MinhaCena", json.encode(fonteGatilho))      -- primeira linha enquanto desenvolve: veja o que a iniciou
se fonteGatilho.tipo == "dispositivo" então                    -- .id, .propriedade, .valor
senão se fonteGatilho.tipo == "data" então
senão se fonteGatilho.tipo == "usuário" então                  -- iniciada manualmente (botão Executar, aplicativo)
fim

Funções: fibaro.chamar, fibaro.obterValor, fibaro.obter (valor + timestamp), fibaro.obterVariávelGlobal / definirVariávelGlobal (strings), fibaro.obterVariávelDeCena / definirVariávelDeCena (persistem entre execuções da mesma cena), fibaro.alerta, fibaro.emitirEventoPersonalizado, fibaro.cena("executar"|"matar", {ids}), fibaro.perfil, fibaro.alarme, fibaro.definirTimeout(ms, fn), api.*, net.ClienteHTTP, json. Logs precisam de uma tag: fibaro.debug("Tag", "msg"). Notificações: mesmas regras que QuickApps (usuários vs IDs de telefone, sem push crítico) — veja a habilidade hc3-quickapp, referências/notificações.md.

Armadilhas (leia antes de responder "minha cena não funciona")

1. Sem memória entre execuções → variáveis de cena ou variáveis globais.
2. Opção "Permitir reinicialização de uma cena em execução": Sim = um novo gatilho mata a instância em execução (setTimeout pendente perdido) e começa novamente — correto para "luz apaga 5 min após o último movimento"; Não = gatilhos são ignorados enquanto ela executa (inclusive enquanto um setTimeout aguarda).
3. Modo manual ignora declarações.
4. Gatilhos disparam apenas em mudanças: mesmo valor novamente → nada.
5. Tipos de valor: interruptor verdadeiro/falso, dimerizador / persiana 0–99, número de sensor; variáveis globais são sempre strings (== "1", não == 1); em declarações escreva valor = verdadeiro sem aspas.
6. Uma cena que altera seu próprio dispositivo de gatilho pode entrar em loop: filtre com fonteGatilho.
7. Apenas propriedades de dispositivo disparam cenas; uma variável interna de QuickApp não dispara (uma variável global dispara, e atualizações de propriedade de QA como valor disparam).
8. Evite enquanto verdadeiro / fibaro.dormir longo: use gatilhos, setTimeout, ou um QuickApp.
9. A numeração dos dias da semana no cron e alguns nomes de propriedades variam: verifique uma cena de blocos convertida [V].

Entregável

Bloco de declarações + bloco de ações (separadamente, prontos para colar), as opções de cena a definir (reinicialização sim/não, modo automático, cômodo), os IDs a substituir (ID_SENSOR_PORTA…) ou IDs reais do inventário do usuário, e um procedimento de teste ("abra a porta, o console da cena mostra …"). Exemplos práticos: referências/exemplos.md.