File Operations

File operations are one‑shot devwork actions that create, read, update, delete, and move files on the device’s USB file system. All local paths may include a directory prefix (e.g., /cfg/config.json).

Important: The devwork envelope must wrap actions in an "actions" array:

{
  "devwork": {
    "actions": [
      { "a": "fcre", "p": { "file": "/config.json", "content": { "key": "value" } } }
    ]
  }
}

Action	Description
fdld	Download a file from a URL
fcre	Create a file with optional content
fapp	Append content to a file
fmv	Move / rename a file
fdel	Delete a file or directory
fmkd	Create a directory
ffmt	Format the entire USB filesystem
fget	Retrieve a file or directory listing

---

fdld

Downloads a file from a URL and saves it to the local filesystem. A temporary file in /tmp is used during the download; on success it is renamed to the target path.

Configuration variables

• a (Required, string): Must be fdld.
• p (Required, object):

Parameter	Type	Required	Description
url	string	yes	HTTP/HTTPS URL to fetch
file	string	yes	Local path to save to (parent directories must exist)

Response: The device sends an uplink message on completion.

Field	Type	Description
file	string	Local file path
res	number	0 = OK, 1 = timeout, 2 = internal error, 3 = server error
httpres	number	HTTP status code (if available)
httplen	number	Content length from the HTTP server

{
  "devwork": {
    "actions": [
      {
        "a": "fdld",
        "p": {
          "url": "https://example.com/config.json",
          "file": "/cfg/config.json"
        }
      }
    ]
  }
}

---

fcre

Creates a file with optional content. Any existing file at that path is discarded before writing.

Configuration variables

• a (Required, string): Must be fcre.
• p (Required, object):

Parameter	Type	Required	Description
file	string	yes	Local path to create
content	string or object	no	Initial file content

{
  "devwork": {
    "actions": [
      { "a": "fcre", "p": { "file": "/notes.txt", "content": "hello" } }
    ]
  }
}

---

fapp

Appends content to an existing file.

Configuration variables

• a (Required, string): Must be fapp.
• p (Required, object):

Parameter	Type	Required	Description
file	string	yes	Local path to append to
content	string	yes	Data to append

{
  "devwork": {
    "actions": [
      { "a": "fapp", "p": { "file": "/notes.txt", "content": " world" } }
    ]
  }
}

---

fmv

Moves or renames a file. The source and destination may be in different directories.

Configuration variables

• a (Required, string): Must be fmv.
• p (Required, object):

Parameter	Type	Required	Description
src	string	yes	Current file path
dst	string	yes	New file path

{
  "devwork": {
    "actions": [
      { "a": "fmv", "p": { "src": "/tmp/temp.json", "dst": "/cfg/live.json" } }
    ]
  }
}

---

fdel

Deletes a file or directory.

Configuration variables

• a (Required, string): Must be fdel.
• p (Required, object):

Parameter	Type	Required	Description
path	string	yes	Local file or directory to delete

{
  "devwork": {
    "actions": [
      { "a": "fdel", "p": { "path": "/notes.txt" } }
    ]
  }
}

---

fmkd

Creates a new directory.

Configuration variables

• a (Required, string): Must be fmkd.
• p (Required, object):

Parameter	Type	Required	Description
path	string	yes	Directory path to create

{
  "devwork": {
    "actions": [
      { "a": "fmkd", "p": { "path": "/cfg" } }
    ]
  }
}

---

ffmt

Formats the entire USB filesystem. This wipes all files and directories.

Configuration variables

• a (Required, string): Must be ffmt.
• p (Required, object):

Parameter	Type	Required	Description
conf	string	yes	Must be "YES" (confirmation string)

{
  "devwork": {
    "actions": [
      { "a": "ffmt", "p": { "conf": "YES" } }
    ]
  }
}

---

fget

Retrieves a file’s contents or a directory listing. The device responds with an uplink message.

Configuration variables

• a (Required, string): Must be fget.
• p (Required, object):

Parameter	Type	Required	Description
path	string	yes	Local file or directory path
asc	boolean	no	Strip non‑ASCII bytes from file content
hex	boolean	no	Send file content as a hex string

Response: The device sends an uplink message: { "devwork": { "fs": { "fget": { "isFile": true|false, "path": "<path>", "content": <file content or directory JSON> } } } }

Files larger than ~1 KB may be truncated in the JSON response.

{
  "devwork": {
    "actions": [
      { "a": "fget", "p": { "path": "/cfg/config.json" } }
    ]
  }
}

Related

• Device Work — all devwork actions
• Device Actions — reboot, debug, alloc
• MQTT Overview — message envelope and topic structure