File

File

A button that asks your device for a file and saves it to your downloads. The name you type is what the device is asked for, so one element can fetch a config dump and another the last log page.

Live preview · sample data

The button spins for the whole round trip. It clears when the file arrives, when the device says it has no such file, or when the timeout runs out.

Settings

FieldWhat it does
File / commandSent to the device as the requested file name
Button textWording on the button
Icon, Icon locationA custom icon; leave it empty for the default file icon
StyleContained, outlined or text
Timeout (s)How long to wait for the device before giving up
ColorThe button’s colour
Admin onlyHide it from everyone who isn’t an admin of the device — see Sharing a device

Sending a file from the device

The request arrives in fileRequested. You are handed the header the file will be sent with, and you fill the buffer with the bytes:

.fileRequested = [](JsonDoc header, std::vector<uint8_t> &buf) {
    String asked = header["filename"] | "";    // the element's "File / command"
 
    if (asked == "cfg") {
        String cfg = buildConfig();
        buf.assign(cfg.begin(), cfg.end());
        header["filename"]    = "config.txt";  // what the browser saves it as
        header["contentType"] = "text/plain";
        return;
    }
    // Anything else: leave the buffer alone and the dashboard reports "not found".
},

Setting header["filename"] renames the download, and header["contentType"] tells the browser what kind of file it is. Leave the rest of the header alone — the library fills in the size and the request id it matches your file back to the click with.

Read a header field with | "" rather than .as<String>(): a field the server had nothing to put in arrives as JSON null, and .as<String>() turns that into the text "null".

Who asked for it

header["user"] says who pressed the button — the same idx and role as commands:

.fileRequested = [](JsonDoc header, std::vector<uint8_t> &buf) {
    int    idx  = header["user"]["idx"] | 0;    // 0 if unknown
    String role = header["user"]["role"] | "";
 
    if (role != "admin") return;   // only the device's admins get this file
    // ...
},

A header with no user means sensordata.space could not say who it was; treat it as unknown rather than trusted.

Files sent to the device

The other direction lives on the device’s Update tab (see Device settings): choose a file and it goes straight down to the device, where it arrives in fileReceived:

.fileReceived = [](JsonDoc header, const std::vector<uint8_t> &buf) {
    String name = header["filename"] | "";
    int    idx  = header["user"]["idx"] | 0;    // who sent it
    // buf holds the bytes.
},

It carries the same user, so a device can accept a config upload from its admins and ignore everyone else.

Limits

  • 4 kB per file, both directions. A bigger one is refused and the dashboard says so.
  • A file travels as one message on the connection the dashboard already has open. There is no second connection, and nothing is stored on the device unless your firmware stores it.
  • A file your device sends is kept in the server’s memory for a few minutes and dropped as soon as it is downloaded, so one request is good for one download. Only accounts with access to that device can download it.
  • The header and the buffer are yours only until the callback returns. Copy anything you want to keep.

Firmware versions

File transfer needs SocketClient 1.10.0 or newer, which moved it onto the websocket. The header — and with it user and contentType — needs 1.11.0. On 1.10.x both callbacks take the file name on its own instead, as fileRequested(String &filename, std::vector<uint8_t> &buf).