Pular para o conteúdo
ThingFace

Os níveis de confirmação

Quando a página manda uma mensagem à placa, a nuvem não guarda nada no caminho: a entrega é no máximo uma vez, na ordem, dentro de uma conexão. O que a página pode saber depende de como ela manda. São três níveis, do mais barato ao único que diz "feito". O exemplo Olá tem um botão para cada um.

Chamada na página (/_devui/v1.js)Resolve quandoO que a página sabe
dev.send(m)o relay da nuvem aceitou a mensagem (ACK de nível 1)só que a nuvem recebeu; a placa pode nem estar online
dev.send(m, {ack: 'device'})o SDK da placa recebeu e o callback on_msg retornou (ACK de nível 2)a placa recebeu; o app ainda não aplicou
dev.request(m)o app aplicou e respondeu com devui_replyo que a resposta disser: só este nível é "feito"

Como escolher

  • send sem confirmação serve para o que pode se perder sem dano: um ajuste que a próxima mensagem repete, um movimento contínuo de um controle. É o mais leve para a placa.
  • send com ack: 'device' diz que a mensagem chegou ao firmware. O SDK manda o ACK quando o callback retorna, não quando o app executa o pedido: um app que enfileira e aplica depois (o jeito certo, porque o callback roda na task do SDK e não pode bloquear) ainda pode falhar ao aplicar.
  • request é para o que precisa de resposta: ligar um relé, gravar uma configuração, qualquer comando cujo resultado a página mostra. O app responde com devui_reply (no Arduino, DevUI.reply) depois de aplicar, com o que aconteceu, inclusive a recusa ("valor fora da faixa").

O que um erro quer dizer

  • TIMEOUT não prova que nada foi feito. O pedido pode ter sido aplicado e a resposta ter se perdido numa queda. Por isso a página mostra o estado da placa, e não o eco do que mandou: depois de uma queda, o estado que a placa manda ao reabrir a sessão diz o que vale.
  • Expirado (4408): uma mensagem esperou mais de 10 s na fila do relay, ou o dispositivo a leu com mais de 10 s. A lib a trata como não executada, mesmo que um ACK de nível 1 já tenha chegado: um comando executado atrasado é pior que um comando perdido. Esse descarte do SDK vale só antes do callback on_msg: a mensagem que o callback recebeu e o app enfileirou não tem mais a idade conferida por ninguém. Quem aplica depois descarta o pedido velho por conta própria (veja abaixo).
  • DEVUI_ERR_STALE_REQUEST quer dizer que a conexão do pedido acabou (a placa ficou offline ou reconectou depois que ele chegou): o devui_reply não envia nada, e a página já recebeu OFFLINE por ele. Não tem a ver com a idade do pedido: um pedido de 30 s numa conexão que continua de pé é respondido normalmente.
  • OFFLINE: a placa não estava conectada; nada chegou a ela. Do lado da placa, devui_send devolve ESP_ERR_INVALID_STATE com ela offline, e o app não precisa tratar isso como erro.

Pedido que esperou na fila do app

O callback roda na task do SDK e não pode bloquear, então o app copia a mensagem para uma fila sua e aplica depois. Enquanto ela espera ali, a página pode desistir (TIMEOUT de dev.request, 10 s por padrão), e aplicar o comando depois disso é executá-lo atrasado. O SDK não confere essa espera; o app confere:

  1. No callback, guarde a hora da chegada junto com a cópia (esp_timer_get_time() no ESP-IDF, millis() no Arduino), e também a conexão do pedido (msg->conn).
  2. Ao tirar da fila, descarte o que passou do limite sem aplicar e sem responder (a página já desistiu). Use o mesmo prazo da página, 10 s, ou um menor.
  3. Descarte também o pedido de uma conexão que acabou (a conexão guardada difere da atual, ou houve um DEVUI_EV_OFFLINE depois dele): a página já recebeu OFFLINE, e o devui_reply dele daria DEVUI_ERR_STALE_REQUEST.

O exemplo Olá faz os três (MSG_MAX_AGE_MS em main/main.c).

Repetir é decisão do app

Nada é guardado entre reconexões, e o SDK e a lib não repetem mensagens sozinhos. Quando repetir faz sentido, quem repete é o app, de um jeito que repetir não faça mal: mandar o estado absoluto ("brilho 70") em vez do incremento ("+10"). O estado absoluto também é o que deixa todas as abas abertas certas depois de uma queda: cada aba que volta recebe o estado inteiro (DEVUI_STATE).

Leitores

Uma sessão com o papel de leitor recebe o que a placa manda, mas o relay descarta o que ela tenta mandar à placa, a não ser que o produto permita (READER_DATA). A regra é da nuvem: o firmware não precisa conferir o papel para isso, e recebe o papel de cada sessão no SESSION_OPEN se quiser mostrar outra coisa a quem só lê.

A regra inteira está na especificação do protocolo, devui.1.