Skip to content
ThingFace

The confirmation levels

When the page sends a message to the board, the cloud keeps nothing on the way: delivery is at most once, in order, within one connection. What the page can know depends on how it sends. There are three levels, from the cheapest to the only one that says "done". The Olá example has one button for each.

Call in the page (/_devui/v1.js)Resolves whenWhat the page knows
dev.send(m)the cloud's relay accepted the message (ACK of level 1)only that the cloud received it; the board may not even be online
dev.send(m, {ack: 'device'})the board's SDK received it and the on_msg callback returned (ACK of level 2)the board received it; the app has not applied it yet
dev.request(m)the app applied it and answered with devui_replywhatever the answer says: only this level is "done"

How to choose

  • send with no confirmation is for what can be lost without harm: a setting the next message repeats, a continuous movement of a control. It is the lightest for the board.
  • send with ack: 'device' says the message reached the firmware. The SDK sends the ACK when the callback returns, not when the app carries out the request: an app that queues and applies later (the right way, since the callback runs in the SDK's task and must not block) can still fail to apply it.
  • request is for what needs an answer: turning a relay on, saving a setting, any command whose result the page shows. The app answers with devui_reply (on Arduino, DevUI.reply) after applying it, with what happened, refusals included ("value out of range").

What an error means

  • TIMEOUT does not prove nothing was done. The request may have been applied and the answer lost in a drop. That is why the page shows the board's state, not the echo of what it sent: after a drop, the state the board sends when the session reopens says what holds.
  • Expired (4408): a message waited more than 10 s in the relay's queue, or the device read it more than 10 s old. The lib treats it as not carried out, even if a level 1 ACK already came: a command carried out late is worse than a lost one. This drop by the SDK holds only before the on_msg callback: once the callback got the message and the app queued it, nobody checks its age any more. Whoever applies it later drops the old request on its own (see below).
  • DEVUI_ERR_STALE_REQUEST means the request's connection ended (the board went offline or reconnected after it came): devui_reply sends nothing, and the page already got OFFLINE for it. It has nothing to do with the request's age: a request 30 s old on a connection that is still up is answered as usual.
  • OFFLINE: the board was not connected; nothing reached it. On the board, devui_send returns ESP_ERR_INVALID_STATE while it is offline, and the app need not treat that as an error.

A request that waited in the app's queue

The callback runs in the SDK's task and must not block, so the app copies the message to a queue of its own and applies it later. While it waits there, the page may give up (the TIMEOUT of dev.request, 10 s by default), and applying the command after that is carrying it out late. The SDK does not check that wait; the app does:

  1. In the callback, keep the time it came with the copy (esp_timer_get_time() on the ESP-IDF, millis() on Arduino), and the request's connection too (msg->conn).
  2. When taking it from the queue, drop what is past the limit without applying it and without answering (the page already gave up). Use the page's deadline, 10 s, or a shorter one.
  3. Also drop a request of a connection that ended (the connection kept differs from the current one, or a DEVUI_EV_OFFLINE came after it): the page already got OFFLINE, and its devui_reply would give DEVUI_ERR_STALE_REQUEST.

The Olá example does all three (MSG_MAX_AGE_MS in main/main.c).

Repeating is the app's decision

Nothing is kept across reconnections, and neither the SDK nor the lib repeats messages by itself. When repeating makes sense, the app repeats, in a way that repeating does no harm: sending the absolute state ("brightness 70") instead of the increment ("+10"). The absolute state is also what keeps every open tab right after a drop: each tab that comes back gets the whole state (DEVUI_STATE).

Readers

A session with the reader role gets what the board sends, but the relay drops what it tries to send to the board, unless the product allows it (READER_DATA). The rule is the cloud's: the firmware need not check the role for it, and it gets each session's role in the SESSION_OPEN if it wants to show something else to whoever only reads.

The whole rule is in the protocol's specification, devui.1.