Skip to content
ThingFace

Three pieces, one path.

The board connects outward, the cloud stores the page and links each browser to the right board, and your page talks to the firmware through messages.

BoardC SDK · key generated on the chip
ThingFacestores the page · relays bytes
Browseryour page, isolated from the others

On the board: the SDK

A C library that runs on ESP-IDF, Arduino, and PlatformIO. It opens an outbound TLS connection to gw.thingface.com, proves the board's identity with a key generated on the chip itself, and keeps the connection up: if the Wi-Fi drops or the router changes, it reconnects automatically. The board never accepts incoming connections, so there is no port to open and none to attack.

In the cloud: store and relay

The page (HTML, CSS, JavaScript, and images) is published to the product from the command line and applies to all of its boards: the firmware does not need to carry it, and no board changes the product's interface. If you prefer each board to serve what it carries, set the product's interface to on the device, and the board uploads its own page, up to 512 KB. The cloud stores the page and serves it at an address dedicated to that board, isolated from the others. When someone opens the page with a login, the cloud links that browser to the board and relays messages in both directions, without reading any of them.

In the browser: your page

The page talks to the board through a JavaScript library with two functions:

import { connect } from '/_devui/v1.js';
const board = await connect();
board.on('message', (m) => show(m));
board.send({ led: true });

And, on the board:

static void on_msg(const devui_msg_t *m, void *ctx) {
    /* m->data, m->len: what the page sent */
}
devui_on_message(on_msg, NULL);
devui_send(DEVUI_ALL, state, len, DEVUI_STATE); /* to every open page */
Complete example

An ESP-IDF project with three files: the page, the firmware and the CMake that embeds the page in the firmware (the interface on the device; with the interface in the cloud, CMake embeds nothing and the page goes out with devui publish). The Wi-Fi comes from the SDK's shared example (examples/comum).

web/index.html: the page

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Light</title>
<p>Light: <strong id="estado">…</strong></p>
<button id="botao" disabled>Turn on</button>
<script type="module">
  import { connect } from '/_devui/v1.js';

  const board = await connect();
  const label = document.getElementById('estado');
  const button = document.getElementById('botao');
  let on = false;

  // the state always comes from the board: when the page opens and at each change
  board.on('message', (m) => {
    on = m.led;
    label.textContent = on ? 'on' : 'off';
    button.textContent = on ? 'Turn off' : 'Turn on';
  });

  // the button only works with the board connected
  const connection = (s) => { button.disabled = s !== 'online'; };
  board.on('state', connection);
  connection(board.state);

  button.onclick = () => board.send({ led: !on });
</script>

main/main.c: the board

#include <stdbool.h>
#include <string.h>

#include "devui.h"
#include "devui_bundle.h"
#include "driver/gpio.h"
#include "esp_app_desc.h"
#include "esp_log.h"
#include "exemplo_wifi.h"
#include "nvs_flash.h"

#define LED GPIO_NUM_2

static const char *TAG = "light";
static bool on;

/* the board's whole state, to one page (its session) or to all of them (DEVUI_ALL) */
static void send_state(uint16_t session)
{
    const char *state = on ? "{\"led\":true}" : "{\"led\":false}";
    devui_send(session, state, strlen(state), DEVUI_TEXT | DEVUI_STATE);
}

/* the page sent {"led":true} or {"led":false} */
static void on_msg(const devui_msg_t *m, void *ctx)
{
    on = m->len == 12 && memcmp(m->data, "{\"led\":true}", 12) == 0;
    gpio_set_level(LED, on);
    send_state(DEVUI_ALL);
}

static void on_event(const devui_event_t *ev, void *ctx)
{
    if (ev->type == DEVUI_EV_SESSION_OPEN) {
        send_state(ev->session); /* whoever just opened the page sees the LED as it is */
    } else if (ev->type == DEVUI_EV_PAIR_CODE) {
        ESP_LOGI(TAG, "open to pair: %s", ev->pair_url);
    }
}

void app_main(void)
{
    ESP_ERROR_CHECK(nvs_flash_init());
    gpio_reset_pin(LED);
    gpio_set_direction(LED, GPIO_MODE_OUTPUT);
    exemplo_wifi_start(); /* before devui_start: the board's key is born with the radio on */

    devui_config_t cfg = DEVUI_CONFIG_DEFAULT();
    cfg.bundle = devui_bundle, cfg.bundle_size = devui_bundle_size;       /* the page, embedded by CMake */
    cfg.manifest = devui_manifest, cfg.manifest_size = devui_manifest_size;
    cfg.fw_version = esp_app_get_description()->version;
    devui_on_message(on_msg, NULL);
    devui_on_event(on_event, NULL);
    ESP_ERROR_CHECK(devui_start(&cfg));

    /* no owner yet: ask for the pairing code (the link comes in the DEVUI_EV_PAIR_CODE event) */
    esp_err_t r = devui_pair_begin();
    if (r != ESP_OK && r != DEVUI_ERR_HAS_OWNER) {
        ESP_LOGW(TAG, "pairing: %s", esp_err_to_name(r));
    }
}

main/CMakeLists.txt

idf_component_register(SRCS "main.c"
                       PRIV_REQUIRES devui comum driver esp_app_format nvs_flash)
# embeds the web/ folder in the firmware (interface on the device): the board uploads the page to the cloud when it connects
devui_add_bundle(${COMPONENT_LIB} "${CMAKE_CURRENT_LIST_DIR}/../web" --product luz --version 0.1.0)

What if the board is off?

The page still opens and says the board is offline. If you turn on last state, the board marks a message as state (up to 4 KB) and the cloud delivers it to whoever opens the page later: the page loads already showing the latest values.

What the cloud does not do

  • It is not a VPN: nobody gains access to the board's network.
  • It is not an HTTP tunnel: the old page's fetch calls and forms do not reach the board; the page replaces those calls with send and on, or uses the ESPUI or ESP-DASH adapter.
  • It does not keep history, draw charts, or trigger alerts on values: for that, the cloud would have to read your messages, and it does not.