Criar e editar um preset

Um preset reúne os comandos de rede de um aparelho de outro fabricante, como uma TV ou um receiver. Depois de publicado, ele fica na biblioteca de presets, e o donoA conta que criou o projeto. Só ela altera a configuração e envia ao equipamento. Quem recebe o projeto compartilhado usa e aciona, mas não altera. de qualquer projeto pode adicioná-lo ao projeto. No projeto, o preset vira um aparelho de presetUm aparelho de outro fabricante, como uma TV, que o Studio SHC aciona por um comando de rede pronto..

Quem pode criar e editar

Contas de revenda e de administrador criam presets, e só quem publicou um preset o edita. A lista completa está em Quem vê a tela Presets.

Quando a criação de presets está suspensa:

• Conta de revenda: o botão Criar preset some da tela Presets, e a tela de criação mostra Publicação suspensa e a mensagem A criação de presets está temporariamente desativada. Os presets já publicados continuam disponíveis para uso.
• Conta de administrador: o botão Criar preset continua na tela, com um contorno vermelho. A tela de criação abre e funciona, com a faixa Criação de preset suspensa para os demais usuários — visível a você por ser administrador.

Editar um preset já publicado funciona normalmente, também durante a suspensão.

Criar um preset

1. Na barra lateral, clique em Presets.
2. Clique no botão + (Criar preset), no canto da tela.
3. Preencha os dados do equipamento.
4. Escolha os campos que quem usar vai preencher.
5. Adicione os comandos.
6. Teste cada comando no aparelho.
7. Se o aparelho pede senha, token ou pareamento, configure a autorização.
8. Clique em Publicar preset.

O Studio SHC volta para a tela Presets, e o preset aparece na biblioteca para todas as contas.

Para sair sem publicar, clique em Cancelar ou na seta Voltar sem publicar. Se você mudou alguma coisa, aparece Descartar alterações?. Clique em Sim, descartar para sair e perder o que preencheu, ou em Não para continuar editando.

Dados do equipamento

No topo da tela, em Equipamento:

Campo	O que preencher
Nome do equipamento	O nome que aparece na biblioteca, por exemplo Receiver Denon AVR-X1700H. Obrigatório
O que este preset controla	Uma frase sobre o que os comandos fazem, por exemplo liga, desliga e troca a entrada da TV pela rede. Obrigatório
Fabricante	A marca do aparelho, por exemplo Denon. Obrigatório
Categoria	O tipo de aparelho, escolhido na lista, como TV, Receiver / Amplificador ou Projetor. É o filtro da biblioteca
Linha ou geração	A linha ou a geração do aparelho, por exemplo Tizen 2016+
Modelos compatíveis	Os modelos em que o preset funciona
Versões ou anos	A faixa de firmwareO programa que roda dentro do equipamento. Cada versão nova pode trazer correções e melhorias. ou de ano, por exemplo 2021 em diante

Em Você já testou este preset?, escolha Teórico ou Testado em campo. Quem for usar o preset vê essa informação na biblioteca.

Campos que quem usar vai preencher

Na seção O que quem usar vai preencher ficam os dados que mudam de um projeto para outro, como o IPO endereço de um aparelho dentro da rede da casa. Tem o formato 192.168.0.10. do aparelho. Quem adiciona o preset ao projeto preenche esses campos. O resto fica pronto nas ações do comando.

Os campos mais comuns já vêm prontos. Ligue a chave do cartão para usar o campo:

Cartão	Quando usar
Endereço IP	O aparelho tem um IP diferente em cada projeto
Porta	A porta muda de um projeto para outro
Endereço MAC	O comando usa Wake-on-LAN para acordar o aparelho
ID do aparelho	O protocolo identifica o aparelho por um número
Senha ou chave	O aparelho exige senha ou chave no comando
Token do pareamento	O aparelho entrega um token ao parear. Ninguém digita esse valor

Cada cartão ligado mostra como escrever o campo nas ações, por exemplo {{ip}}. Ao desligar um cartão, as ações que usam o campo continuam com ele escrito, e o preset só é publicado depois que você tira o campo das ações.

Criar um campo

1. Clique em Adicionar campo.
2. Em O que pedir a quem usar o preset, escreva o nome que aparece para quem adiciona o preset, por exemplo Endereço IP do receiver.
3. Em Nome do campo, escreva o nome usado nas ações, só com letras, números e _. Com o nome zona, você escreve {{zona}} nas ações.
4. Em Tipo do campo, escolha o tipo.
5. Se quiser, preencha Valor sugerido (opcional). Ele já vem preenchido para quem adiciona o preset.
6. Deixe Preenchimento obrigatório ligado se o comando não funciona sem esse valor. Desligado, se ninguém preencher, o comando vai com o campo vazio.
7. Clique em Salvar campo.

O campo aparece em Outros campos, com o lápis Editar campo e a lixeira Remover campo. Ao trocar o nome de um campo, o Studio SHC troca o nome também nas ações que o usam.

Alguns tipos pedem mais dados:

Tipo	O que mais preencher
Porta, Número inteiro, Número decimal	Mínimo e Máximo, se houver faixa
Lista de opções	Em Opções, clique em Adicionar opção e preencha Aparece na lista (o que a pessoa escolhe) e Vai no comando (o que é enviado)
Liga / desliga	Quando ligado e Quando desligado: o que vai no comando em cada estado, por exemplo On e Off
Texto com formato próprio (regex)	Formato aceito, por exemplo ^[0-9]+$ para só números, e Aviso quando estiver errado
Senha	Nada. O valor aparece escondido na tela
Vem do pareamento	Nada. Quem adiciona o preset não vê esse campo: o valor vem do aparelho, por um comando que usa Guardar da resposta

Se faltar algo, a janela avisa embaixo do campo, por exemplo Dê um nome ao campo., Use apenas letras, números e underline. ou Já existe um campo com esse nome.

Comandos

Cada comando é uma ação do aparelho: ligar, desligar, trocar de entrada. No projeto, cada comando vira uma saídaO ponto do equipamento que liga, desliga ou ajusta uma carga, como uma lâmpada ou um motor de persiana. do aparelho de preset.

1. Em Comandos, clique em Adicionar comando.
2. Na janela Comando do equipamento, preencha Nome do comando, por exemplo HDMI 1.
3. Preencha O que ele faz, por exemplo acorda a TV e liga.
4. Em Ações, em ordem, monte a primeira ação (veja abaixo).
5. Para acrescentar outra ação, clique em Adicionar ação.
6. Clique em Salvar comando.

O botão Salvar comando só funciona com o nome e O que ele faz preenchidos. O comando aparece na lista com as ações e o que ele envia. Na linha do comando ficam os ícones Testar comando na rede, Editar comando e Remover comando.

Cada comando tem de 1 a 5 ações, enviadas na ordem. Uma TV que precisa acordar antes de ligar, por exemplo, tem duas ações: Wake-on-LAN e, depois, o comando. Dois comandos do mesmo preset não podem ter o mesmo nome.

Em Campos deste preset, a janela mostra os campos que você pode usar nas ações, como {{ip}}. O valor entra quando alguém adiciona o preset ao projeto.

Tipos de ação

No topo de cada ação, escolha o tipo:

Tipo	O que faz
TCP e UDP	Envia um texto ou bytes para um IP e uma porta
Wake-on-LAN	Acorda o aparelho pela rede, pelo endereço MAC
HTTP e HTTPS	Envia um pedido a um endereço web do aparelho (veja Ação HTTP ou HTTPS)
Espera	Espera alguns segundos antes da próxima ação, até 30 segundos
WS e WSS	Conversa com o aparelho por WebSocket (veja Ação WebSocket)

Logo abaixo, a ação diz onde ela funciona:

• Roda pelo Studio SHC e no botão do equipamento.: TCP, UDP, Wake-on-LAN e Espera.
• Roda só pelo Studio SHC (Testar, Saídas, Visual e Cenas do App). Não pode ir para o botão de um equipamento.: HTTP, HTTPS, WS e WSS.

Um comando com uma ação que roda só pelo Studio SHC ganha a marca Só pelo Studio SHC. Ele funciona em Saídas, na tela Visual e nas Cenas do AppUm cartão com várias ações que o Studio SHC e o app do morador acionam com um toque, sem botão na parede. Fica salva no projeto, não no equipamento, e não precisa de Atualizar tudo., e não aparece na lista do que um botão faz.

Endereço IP e Porta são de cada ação, e cada ação pode usar uma porta diferente. Escreva um valor fixo, como 8080, ou um campo, como {{ip}}. Uma ação nova já vem com o IP, a porta e o Endereço MAC da ação anterior.

As ações TCP, HTTP e WebSocket têm também Tempo para conectar. Vazio, vale o tempo de Autorização e respostas.

As ações HTTP e WebSocket têm também Tempo de espera: quanto tempo o Studio SHC espera a resposta do aparelho. Vazio, vale o Tempo de espera padrão de Autorização e respostas, ou 4 segundos.

Ação TCP ou UDP

1. Escolha Escrever em texto ou Escrever em hexadecimal.
2. Em O que enviar, escreva o comando. Em texto, por exemplo PWON ou Z{{zona}}PWON. Em hexadecimal, dois dígitos por byte, por exemplo AA 11 00 01.
3. Em Final do comando, escolha o que vai no fim: Nenhum, CR (\r), LF (\n), CRLF (\r\n) ou Personalizado. Muitos aparelhos só respondem com o final certo.

Em texto, use \r, \n, \t e \xNN para códigos invisíveis. Em Resultado, a ação mostra o que vai ser enviado e os bytes, com os valores de exemplo dos campos.

Ação Wake-on-LAN

Em Endereço MAC, escreva o MAC do aparelho no formato AA:BB:CC:DD:EE:FF, ou o campo {{mac}}.

Ação HTTP ou HTTPS

• Método: GET, POST, PUT ou DELETE. Uma ação nova começa em GET. Se uma ação GET tiver Corpo, aparece o aviso Esta ação é GET e tem corpo. O normal, com corpo, é POST. Clique em Usar POST para trocar o método. O aviso não impede publicar.
• Cabeçalhos: clique em Adicionar cabeçalho e preencha Nome e Valor. O valor aceita {{campo}}. Os atalhos Content-Type: JSON e Accept: JSON põem esses cabeçalhos com application/json; clique de novo no atalho para tirá-lo.
• HTTPS: escolha HTTPS no tipo da ação. O Studio SHC aceita o certificado do próprio aparelho, só para o IP e a porta da ação. Na ação com AWS Signature, o certificado precisa ser válido (veja Autorizar um serviço AWS).

Formato do conteúdo

Numa ação HTTP, Formato do conteúdo diz como o Studio SHC monta o Corpo:

Formato	Como o corpo sai
Automático	Como você escreveu. Com o cabeçalho Content-Type em JSON, o valor de cada {{campo}} entra já preparado para JSON
Texto	Como você escreveu, com o cabeçalho Content-Type: text/plain
JSON	Em JSON, com o cabeçalho Content-Type: application/json. Se o corpo não for um JSON válido, o comando não é enviado e aparece o corpo não é um JSON válido.
Formulário	Escreva um par nome=valor por linha, ou vários na mesma linha separados por &. O Studio SHC prepara cada valor, mesmo que o valor de um campo tenha espaço, & ou acento

Se você escrever o cabeçalho Content-Type no comando, vale o seu.

Ação WebSocket

Escolha WS ou WSS no tipo da ação. Na WSS, o Studio SHC aceita o certificado do próprio aparelho, só para o IP e a porta da ação.

Campo	O que preencher
Caminho	O caminho do WebSocket no aparelho, por exemplo /ws
Esperar a mensagem do aparelho (opcional)	Um trecho da mensagem que o aparelho manda ao conectar. O Studio SHC só envia depois de receber uma mensagem com esse trecho. Vazio, envia assim que conectar
Mensagem a enviar (opcional)	O que enviar, com {{campo}} onde o valor muda. Vazio, a ação só conecta, como no pareamento

Guardar da resposta

Use quando o aparelho entrega um token ao parear. Nas ações HTTP, HTTPS, WS e WSS, a parte Guardar da resposta guarda um valor da resposta num campo do tipo Vem do pareamento, como o Token do pareamento.

1. Ligue o cartão Token do pareamento, ou crie um campo do tipo Vem do pareamento.
2. Na ação do comando que pareia, em Guardar no campo, escolha o campo.
3. Em Onde está na resposta, escreva o caminho do valor, com os nomes separados por ponto, por exemplo resposta.token.

O valor fica salvo no aparelho de preset, e os outros comandos usam o campo normalmente, como {{token}}. Um campo Vem do pareamento que nenhum comando guarda impede a publicação.

Ajustar o envio de um comando

Na janela Comando do equipamento, abra Ajustes de envio pelo app na ação correspondente.

Ação e campo	Como funciona
TCP — Prazo total TCP	Limita a operação inteira: conexão, envio e espera de resposta. Deixe vazio para não limitar o tempo total; máximo de 60 segundos
TCP — Janela de resposta TCP	Tempo para receber a resposta. Zero envia sem esperar. Vazio usa a janela padrão de 2 segundos; máximo de 60 segundos
Wake-on-LAN — Destino do WoL	Endereço IPv4 de destino. O padrão é 255.255.255.255; pode ser um campo do preset, como {{broadcast}}
Wake-on-LAN — Porta do WoL	Porta de 1 a 65535. O padrão é 9; as portas 5202 e 5203 pertencem aos equipamentos e ficam reservadas
WebSocket — Eventos de erro do WebSocket	Um trecho por linha. Ao receber um desses trechos, o app encerra a conversa com falha. Até 20 trechos de 300 caracteres
WebSocket — Aguardar resposta após enviar	O app envia a mensagem e aguarda a próxima resposta. A captura, as regras de resposta e a leitura de estado usam essa resposta. Exige uma Mensagem a enviar

Os tempos são preenchidos em segundos e aceitam decimais, como 2,5. O tempo para abrir a conexão é outro campo, Tempo para conectar, na própria ação. O Tempo de espera do WebSocket inclui conexão, espera do evento, envio e resposta.

Com Aguardar resposta após enviar desligado, a captura e as regras usam a mensagem que o aparelho manda ao aceitar a conexão.

Ao personalizar prazo ou janela do TCP, ou destino ou porta do Wake-on-LAN, o comando ganha a marca Só pelo Studio SHC e sai da lista do que um botão faz. Comandos HTTP e WebSocket também têm essa marca.

Criar um comando de leitura

Um comando de leitura pergunta o estado do aparelho e diz quais informações da resposta mostrar em Estado do aparelho, na tela do aparelho de preset.

1. Na janela Comando do equipamento, monte o comando que pergunta o estado ao aparelho. A última ação, sem contar as esperas, precisa ser HTTP ou WebSocket com Aguardar resposta após enviar ligado: é a resposta dela que o Studio SHC lê.
2. Ligue Comando de leitura, no fim da janela.
3. Em Nome, escreva como a informação aparece na tela, por exemplo Volume.
4. Em Caminho na resposta, escreva onde o valor está na resposta do aparelho, com os nomes separados por ponto, por exemplo result.volume.
5. Para mostrar outra informação, clique em Adicionar informação e repita os passos 3 e 4.
6. Clique em Salvar comando.

Use Testar comando na rede para conferir: o resultado mostra Lido: com cada informação e o valor que o aparelho respondeu.

Cada preset tem no máximo um comando de leitura. Ele não pode também parear: nenhuma ação dele pode ter Guardar da resposta. O Studio SHC não guarda o que leu; para usar um valor da resposta em outro comando, use um campo Vem do pareamento com Guardar da resposta.

O comando de leitura não vira saída e não vai para botão.

Testar um comando antes de publicar

Para conferir um comando antes de publicar o preset, teste-o na rede ainda na tela de criar ou editar o preset. O teste usa o comando como está no editor, com as mudanças que você ainda não publicou.

1. Na lista de comandos, clique no ícone Testar comando na rede do comando.
2. Na janela que abre, preencha os dados que o comando pede, como o IP do aparelho. Os campos já vêm com o valor padrão do preset, quando ele tem um.
3. Clique em Enviar teste.

O resultado aparece na mesma janela, por exemplo Enviado. Confira se o aparelho reagiu., ou em vermelho, com o motivo, quando o comando não sai. Se um campo estiver errado, o teste não sai e o erro aparece embaixo do campo. Para sair, clique em Fechar.

Os dados preenchidos servem só para o teste e não são salvos. Se o comando não pede nenhum campo, a janela avisa e o teste envia o comando como está.

O token do pareamento é a exceção: ao testar o comando de pareamento, aparece Pareado. O token vale para os testes deste preset até fechar o app. O token fica guardado até você fechar o Studio SHC, para você testar os outros comandos do preset sem copiá-lo.

Num preset com OAuth 2.0 ou JWT Bearer, o teste no editor não faz o login sozinho. Teste primeiro o comando de login e depois os outros comandos.

Numa ação TCP ou UDP escrita em texto, cada caractere precisa caber num byte, de 0 a 255. Um caractere fora disso, como um emoji, dá a mensagem O comando tem caractere fora da tabela de 8 bits. Use o modo hexadecimal para bytes acima de 255. Se o caractere vem do valor de um campo, a mensagem diz qual: O valor de “Nome do campo” tem caractere fora da tabela de 8 bits. Para enviar esses bytes, escolha Escrever em hexadecimal na ação.

Autorização e respostas

A seção Autorização e respostas diz como o aparelho autoriza os comandos, o que cada resposta dele significa e quanto tempo esperar. Preencha só se o aparelho pede senha, chave, token, login ou pareamento, ou se você quer que o Studio SHC entenda as respostas dele.

Sem configuração, a seção mostra o cartão Sem autorização e sem regras de resposta:

• os comandos saem como estão escritos nas ações, sem token, chave nem login;
• o comando falha quando não consegue ser enviado ou quando o aparelho responde a uma ação HTTP com um status de erro, fora da faixa de 200 a 299. Fora isso, a resposta do aparelho não é interpretada;
• os campos Vem do pareamento continuam sendo preenchidos pelos comandos que usam Guardar da resposta.

No cartão, a linha Espera até 4 segundos para conectar. diz quanto o app espera para conectar ao aparelho, nas ações sem tempo próprio. Para trocar, clique em Alterar e preencha Tempo para conectar, até 30 segundos. Vazio, volta ao padrão de 4 segundos.

Para configurar, clique em Configurar. A configuração começa vazia, só com o Tempo para conectar que você escolheu no cartão, e tem três partes:

• Tempo de espera padrão e Tempo para conectar: valem para as ações sem tempo próprio. Vazios, 4 segundos. A espera vai até 60 segundos, e a conexão até 30.
• Autorizações: clique em Adicionar autorização para cada forma de autorizar que o aparelho usa.
• Regras de resposta: clique em Adicionar regra para dizer o que uma resposta do aparelho significa (veja Regras de resposta).

Para apagar todas as autorizações e regras de resposta, clique em Descartar configuração e confirme em Descartar configuração. Os comandos passam a sair sem autorização e sem regras de resposta, e as ações voltam para Automática (veja Qual autorização cada ação usa).

Adicionar uma autorização

1. Clique em Adicionar autorização.
2. Em Nome, escreva um nome para a autorização, por exemplo IP Control.
3. Em Tipo, escolha o tipo. Escolher um tipo preenche os campos com valores típicos.
4. Em Campos com o segredo, marque o campo do preset que guarda o segredo. Na AWS Signature, essa parte não aparece: os campos são outros (veja Autorizar um serviço AWS).
5. Preencha Comando de pareamento, Ao recusar e Tentativas, se o aparelho pareia ou pode recusar.

Tipo	Quando usar
Bearer Token, API Key, Basic Auth	O aparelho pede um token, uma chave ou usuário e senha em todo comando (veja Senha, chave ou token que o Studio SHC põe no comando)
OAuth 2.0, JWT Bearer	O serviço pede login e entrega um token que vence (veja Autorizar uma conta ou fazer login no aparelho)
AWS Signature	Um serviço da AWS (veja Autorizar um serviço AWS)
Pareamento no aparelho	O aparelho pede autorização na própria tela e entrega um token (veja Pareamento no aparelho)
No Auth	O aparelho não pede autorização

Campo	O que faz
Comando de pareamento	O comando que pareia ou faz o login. O que guarda um destes campos usa o comando que tem Guardar da resposta num dos campos marcados
Ao recusar	O que o Studio SHC faz quando o aparelho recusa a autorização (veja Mensagens escritas por quem criou o preset)
Tentativas	Quantos pareamentos novos seguidos o Studio SHC pede a cada envio de um comando, de 0 a 5. Com 0, só avisa
Aviso de demora	Numa ação WebSocket com o token, depois desse tempo sem resposta, o Studio SHC avisa que o aparelho está pedindo autorização na tela. Com 0, não avisa
Obrigatório	Ligado, os comandos só funcionam com esta autorização feita

Qual autorização cada ação usa

Cada ação HTTP ou WebSocket tem, na janela do comando, o campo Autorização. Ele começa em Automática: o Studio SHC usa a autorização que tem este comando como Comando de pareamento ou, se não houver, a dos campos que a ação usa. Se nada disso decidir, ele usa a primeira autorização da lista.

Escolha a autorização em cada ação quando o preset tiver duas ou mais e alguma delas for colocada no comando pelo Studio SHC: AWS Signature, ou Bearer Token, API Key, Basic Auth, OAuth 2.0 e JWT Bearer com envio no cabeçalho, na URL ou no corpo JSON. Se uma dessas ações ficar em Automática sem nada que decida, o preset não é publicado, e aparece a mensagem Ligar, ação 1: escolha qual autorização ela usa.

Para tirar uma autorização, clique no ícone Remover autorização, no cartão dela. Se alguma regra de resposta ou ação usa essa autorização, a janela Remover “nome da autorização”? diz o que muda. Clique em Remover autorização para confirmar. As regras que valiam só para ela passam a valer para qualquer autorização, e as ações que a usavam voltam para Automática.

Pareamento no aparelho

Use quando o aparelho, como certas TVs, pede autorização na própria tela e entrega um token.

1. Em O que quem usar vai preencher, ligue o cartão Token do pareamento.
2. Crie o comando que pede o pareamento. Na ação dele, em Guardar da resposta, escolha Token do pareamento e preencha Onde está na resposta.
3. Nos outros comandos, escreva {{token}} onde o aparelho espera o token.
4. Em Autorização e respostas, adicione uma autorização do tipo Pareamento no aparelho.
5. Em Comando de pareamento, escolha o comando do passo 2.

O tipo Pareamento no aparelho já vem com Pedir pareamento em Ao recusar, 1 em Tentativas e 2 segundos em Aviso de demora. Quem adiciona o preset ao projeto pareia o aparelho logo depois de adicionar.

Senha, chave ou token que o Studio SHC põe no comando

Alguns aparelhos pedem uma senha, uma chave ou um token em todo comando. Com uma autorização destes tipos, o Studio SHC coloca o valor sozinho em cada comando HTTP ou WebSocket do aparelho.

Tipo	O que vai no comando
Bearer Token	O token, com Bearer na frente
API Key	A chave, como está
Basic Auth	O usuário e a senha juntos, no formato que o aparelho pede, com Basic na frente

Em Campos com o segredo, marque o campo do preset que guarda o valor. No Basic Auth, marque dois campos: o usuário e a senha. O campo do tipo Senha vira a senha.

Em Envio: onde vai, escolha onde o valor entra:

• Cabeçalho: no cabeçalho com o nome de Nome. Vazio, o nome é Authorization. O texto de Prefixo entra antes do valor; vazio, entra Bearer no Bearer Token e Basic no Basic Auth.
• Parâmetro na URL: no fim do endereço, com o nome de Nome. O Prefixo, se preenchido, também entra.
• Corpo JSON: no conteúdo do comando, com o nome de Nome. O conteúdo precisa estar em JSON, entre { e }.
• {{campo}} no texto do comando: o Studio SHC não coloca nada; você escreve o campo no comando, onde ele deve ir.

O valor não vai no comando de pareamento nem no comando que já usa o campo no texto. Se o comando já tiver um cabeçalho ou um campo com o mesmo nome, vale o do comando.

Com mais de uma autorização no preset, escolha em cada ação qual ela usa (veja Qual autorização cada ação usa).

O Studio SHC esconde o valor nos logs do app e nas mensagens da tela.

Autorizar uma conta ou fazer login no aparelho

Use OAuth 2.0 ou JWT Bearer quando o aparelho ou o serviço pede login e entrega um token que vence. Em Campos com o segredo, marque um campo só: o do token de acesso. O token de acesso e o token de renovação são campos declarados no preset inteiro, do tipo Senha ou Vem do pareamento, e não podem ser o mesmo campo. Nunca coloque esses valores nos endereços ou no identificador público do cliente.

Em Como fazer login, escolha um destes caminhos:

Caminho	O que configurar	Como autorizar
Comando do preset	O Comando de pareamento faz o login. A captura informa onde a resposta traz o token. O Comando de renovação pode usar o Campo do refresh	O Studio SHC executa os comandos do preset
Navegador (OAuth 2.0)	Endereço de autorização, Endereço de token, Identificador do cliente e Permissões (escopos), fornecidos pelo serviço	O dono do projeto clica em Parear, entra na conta no navegador e autoriza o acesso

No fluxo pelo navegador, cadastre no serviço o Endereço de retorno nesta plataforma mostrado no editor. Android, iOS e macOS usam xcene-preset-oauth:/callback. O Windows usa http://localhost:8763/callback. O serviço precisa aceitar autorização por código com PKCE, sem segredo de cliente. O Endereço de autorização e o Endereço de token começam com https:// e não levam parâmetros.

A captura pode ler o JSON da resposta, um Cabeçalho da resposta, o Texto da resposta (expressão) ou uma Mensagem do WebSocket. Para texto, use um prefixo literal, uma classe de caracteres entre parênteses e um sufixo literal, por exemplo token=(\w+). Expressões mais complexas não são aceitas nesse campo. No JSON, um caminho como resultado.token entra até o campo que guarda o valor.

O Caminho do refresh na resposta tem como padrão refresh_token. O Caminho da validade em segundos tem como padrão expires_in. Se o serviço não informar a validade, preencha Validade (minutos). No JWT Bearer sem validade na resposta, o app usa a validade escrita dentro do próprio token para decidir quando renovar. Isso não confere a assinatura do token.

O app renova o token sozinho quando ele falta, quando vence em menos de 15 segundos ou quando o serviço o recusa. Para isso, escolha Refazer login em Ao recusar, escolha de 1 a 5 em Tentativas e crie uma regra de resposta que reconheça a recusa do serviço, como o status 401. Em Renovação, Não renova faz o app pular o token de renovação e ir direto ao login: pelo Comando do preset, o app refaz o login sozinho; pelo Navegador (OAuth 2.0), o dono do projeto precisa entrar na conta de novo. Depois de renovar, o app repete só a ação recusada. As ações anteriores do comando não são enviadas de novo. Se nenhuma tentativa der certo, o dono do projeto entra na conta de novo pela tela do aparelho (veja Entrar na conta do serviço).

Autorizar um serviço AWS

Na autorização, em Tipo, escolha AWS Signature. Esse tipo funciona nas ações HTTP/HTTPS. A conta do serviço fornece as credenciais; quem instala o aparelho preenche os valores nos campos protegidos do preset.

Campo	O que preencher
Endpoint AWS	Endereço HTTPS do serviço, como https://example.amazonaws.com. Use só o endereço e a porta, se houver; o caminho e os parâmetros ficam na ação
Região AWS	Região informada pelo serviço, em letras minúsculas, por exemplo us-east-1
Serviço AWS	Nome usado pelo serviço na assinatura, em letras minúsculas, por exemplo execute-api ou s3
Campo da chave de acesso	Campo protegido que recebe a identificação da chave
Campo da chave secreta	Campo protegido que recebe o segredo da chave
Campo do token de sessão (opcional)	Campo protegido para a credencial temporária (STS). Escolha Sem token de sessão para uma credencial sem esse token. Se você escolher um campo aqui, o comando só sai com esse campo preenchido na instalação

Declare esses campos como Senha ou Vem do pareamento. Escolha campos diferentes para cada credencial. Use Vem do pareamento quando um comando do preset fornece o valor. Os valores pertencem à instalação; o preset guarda a escolha dos campos.

Na ação HTTP/HTTPS, escolha a autorização AWS em Autorização. O Endpoint AWS define o destino: a ação AWS não mostra Endereço IP nem Porta. O caminho, o método, os cabeçalhos e o formato do corpo da ação entram na assinatura. Deixe o relógio do dispositivo correto: a assinatura usa a data e a hora do envio. Não escreva na ação os cabeçalhos Authorization, X-Amz-Date, X-Amz-Security-Token, X-Amz-Content-Sha256 nem Content-Length: o app gera esses cabeçalhos, e o comando com eles não é enviado.

O serviço precisa apresentar certificado HTTPS válido. O app não segue redirecionamentos: um redirecionamento conta como falha. O app oculta as credenciais e a assinatura nas mensagens e nos logs. Quando uma credencial temporária expirar, troque os valores em Editar, na tela do aparelho.

Mensagens escritas por quem criou o preset

O Studio SHC tem mensagens próprias para o pareamento. Você pode trocar algumas delas por mensagens próprias do aparelho, em Textos para quem usa, no cartão da autorização:

Texto	Onde aparece
Pedir aceite na tela do aparelho	Na janela Parear “nome do aparelho”, no lugar de Aceite o pedido na tela do aparelho…, e na janela que aparece quando o aparelho pede autorização num comando, no lugar de O aparelho está pedindo autorização. Aceite o pedido na tela dele.
Autorização recusada	Quando o aparelho recusa o token: no resultado do comando e no topo da janela Parear “nome do aparelho”
Pedido negado na tela	Quando alguém nega o pedido na tela do aparelho
Ninguém respondeu na tela	Quando ninguém aceita o pedido a tempo
Ainda não pareado	Quando o comando precisa de pareamento e o aparelho ainda não foi pareado

Se um texto ficar vazio, aparece a mensagem do Studio SHC. Cada texto tem até 300 caracteres, contando os espaços, e até 4 linhas.

Em Ao recusar, escolha o que acontece quando o aparelho recusa a autorização:

• Pedir pareamento: abre a janela Parear “nome do aparelho” na hora, para aceitar o pedido na tela do aparelho, até o número de Tentativas.
• Só avisar: mostra a mensagem e não abre a janela. Para parear de novo, clique em Desparear e depois em Parear.
• Refazer login: nos tipos OAuth 2.0 e JWT Bearer, o Studio SHC renova o token ou refaz o login sozinho e reenvia a ação recusada, até o número de Tentativas (veja Autorizar uma conta ou fazer login no aparelho). Nos outros tipos, só avisa.

A opção Obrigatório vem desligada. Ligada, um comando que usa um campo dessa autorização só é enviado depois que o campo tem valor, ou seja, depois do pareamento. Sem ele, aparece a mensagem de Ainda não pareado. Clique em Parear, no topo da tela do aparelho. Cada autorização vale para os próprios comandos: na TV Samsung, por exemplo, o IP Control e o WebSocket são pareados separados. Um comando que não usa autorização nenhuma, por exemplo um que só acorda o aparelho pela rede, é enviado sempre.

Regras de resposta

Uma regra de resposta diz o que uma resposta do aparelho significa. As regras são lidas de cima para baixo: a primeira que reconhecer a resposta decide. Sem nenhuma regra, vale o que está em Autorização e respostas.

1. Clique em Adicionar regra.
2. Em Quando, escolha o que conferir na resposta: Status HTTP, Valor no JSON, Texto contém, Expressão regular, Evento do WebSocket, Erro JSON-RPC ou Cabeçalho HTTP.
3. Preencha o que a condição pede, por exemplo 401, 403 em Status HTTP.
4. Em Vale para, escolha HTTP e WebSocket, Só HTTP ou Só WebSocket.
5. Em Autorização, escolha a autorização da regra, ou Qualquer uma.
6. Em Significa, escolha Token recusado, Pedido negado, Sem resposta na tela, Falha ou Sucesso.

Ligue Só quando o pedido leva o token para a regra valer só nos comandos que levam o token. Em Mensagem para a tela (opcional), escreva o que aparece para quem usa. Vazia, aparece o texto da autorização ou a mensagem do Studio SHC. Use Avaliar antes e Avaliar depois para mudar a ordem das regras.

Conferir o corpo também em respostas de erro HTTP fica ao lado dos tempos. Ligado, as regras que leem o texto da resposta valem também quando o aparelho responde com erro, como 401 ou 500. Desligado, nessas respostas só contam as regras de status e de cabeçalho.

Publicar o preset

Clique em Publicar preset, no fim da tela.

O botão fica desligado enquanto falta o mínimo, e a tela diz o que falta, por exemplo Falta o nome do equipamento, o que este preset controla e ao menos um comando para publicar. Num preset aberto para edição, o botão fica desligado até você mudar alguma coisa, com Nenhuma alteração para publicar.

Ao clicar, o Studio SHC confere o preset inteiro. Se algo impede a publicação, o preset não é publicado, e aparece a caixa Falta resolver 1 ponto ou Faltam resolver 2 pontos, com a lista do que corrigir. Se Nome do equipamento, O que este preset controla ou Fabricante estiverem vazios, o campo fica marcado em vermelho com Obrigatório.

Mensagem	O que fazer
Informe o fabricante.	Preencha Fabricante
Ligar: já existe outro comando com esse nome.	Dê outro nome a um dos comandos
Ligar, ação 1: o campo {{ip}} não foi declarado.	Ligue o cartão do campo ou crie o campo em O que quem usar vai preencher
Ligar, ação 1: o comando está vazio.	Preencha O que enviar na ação
“Token do pareamento” vem do pareamento, mas nenhum comando guarda a resposta do aparelho nele.	Escolha o campo em Guardar da resposta, num comando
Não foi possível publicar agora. Confira a conexão com a internet e tente de novo; o que você preencheu continua aqui.	Confira a internet e clique em Publicar preset de novo
A biblioteca recusou a publicação: você não tem permissão para alterar este preset.	A conta não pode publicar ou editar este preset. Veja Quem pode criar e editar

Nas mensagens, Ligar é o nome do comando, e ação 1 é a posição da ação dentro dele.

Editar e publicar uma versão nova

1. Na tela Presets, abra o preset que você publicou.
2. No topo do detalhe, clique no ícone Editar preset (o lápis).
3. Faça as mudanças na tela Editar preset.
4. Clique em Publicar preset.
5. Na janela O que mudou nesta versão?, escreva em Descrição da versão 2 o que mudou, por exemplo corrigido o comando de trocar entrada no firmware 2024.
6. Clique em Publicar versão 2.

O número é o da versão nova: o preset na versão 2 publica a versão 3, e assim por diante.

Cada publicação sobe a versão do preset em 1. A descrição é obrigatória e tem até 300 caracteres. Se ela ficar vazia, ao clicar em Publicar versão 2 aparece Descreva o que mudou nesta versão. Para voltar ao editor sem publicar, clique em Cancelar na janela: nada é publicado e o que você mudou continua na tela.

Quem já adicionou o preset a um projeto decide se atualiza o aparelho para a versão nova (veja Atualizar o aparelho para a versão nova do preset).

Para excluir um preset que você publicou, veja Excluir um preset.