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.
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
| Field | What it does |
|---|---|
| File / command | Sent to the device as the requested file name |
| Button text | Wording on the button |
| Icon, Icon location | A custom icon; leave it empty for the default file icon |
| Style | Contained, outlined or text |
| Timeout (s) | How long to wait for the device before giving up |
| Color | The button’s colour |
| Admin only | Hide 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).