File Control¶

The fileControl Topic has several available actions. The JSON payload must include the ‘action’ key indicating which file function to perform. Each file control action has a unique JSON object payload.

Subscribe <baseTopic>/cc/<deviceID>/fileControl

Checksum¶

Perform a checksum of the specified file. This is useful for avoiding redundant downloads or verifying file integrity.

Properties

"action": "checksum"
"path": File Name including the drive [“cpu:HashItOut.crb”].
"algo": Specified Checksum Algorithm
- "CRC32" (32-bits) standard crc32 algorithm
- "CSI_SIG" (16-bits) CSI signature algorithm [used in Pakbus and program signature]
- "MD5" (16-bytes) MD5 sum
- "SHA256" (32-bytes) SHA256 sum
- "SHA512" (64-bytes) SHA512 sum

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "checksum",
    "path": "cpu:HashItOut.crb",
    "algo": "CRC32"
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "checksum": "a2a186d5"
}

Error Responses

{"error": "Unsupported checksum algorithm: <algorithm>"}
{"error": "File does not exist: <file name>"}
{"error": "Checksum failed, error: <>"}

List Files¶

List files on a specified data logger drive.

Properties

"action": "list" File control action to perform [list].
"path": {string}: Data logger drive [CPU].
"verbose": {Boolean} (optional) List files and their details (date/size/etc…)

Basic Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action" : "list",
    "path": "CPU"
}

Basic response:

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "drive" : "CPU",
    "clientID" : "ABCD-EFGH-1234",
    "fileList" : [
        "datalogger_program.crb",
        "cal_file.txt",
        "include_file.crb",
    ]
}

Note

In cases of extremely long file lists (greater than 2400 bytes), the list may be truncated.

Verbose Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action" : "list",
    "path": "CPU",
    "verbose": true
}

Verbose Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "fileList": {
        "datalogger_program.crb": {
            "size": 10598,
            "date": "2025-07-15T16:43:24"
        },
        "cal_file.txt": {
            "size": 246,
            "date": "2025-07-15T16:43:24"
        },
        "include_file.crb": {
            "size": 4584,
            "date": "2025-07-15T16:43:24"
        }
    }
}

Error Responses

{"error": "Directory '<drive>' does not exist"}

Download¶

This command instructs the data logger to download a file using an HTTP(S) GET request from a specified URL.

Unlike the CRBasic program download command, which is specifically intended for downloading and installing data logger programs, this command is more general-purpose. This could be used to download include files, calibration data, or other resource files.

Properties

"action": "download"
"url": {string} Full address path and file name of the file to be retrieved from the server.
"path": {string} Destination path on the data logger. Must include both the drive and file name. The file name can be new or match the one on the server [“cpu:dethstar_plans.txt”]
"tranID": (optional)

Command Example

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl/d828ee49-7b1d-4d17-9c41-ab60206cda1e

{
    "action" : "download",
    "url": "https://DataThings.com/Documents/cpu:dethstar_plans.txt",
    "path" : "cpu:dethstar_plans.txt",
    "tranID": "d828ee49-7b1d-4d17-9c41-ab60206cda1e"
}

Response Example

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl/d828ee49-7b1d-4d17-9c41-ab60206cda1e

{
    "success": "HTTP get succeeded"
}

Error Response

{"error": "HTTP get failed"}

Upload¶

Instruct the data logger to upload a file from a specific drive(path) to the specified URL.

Properties

"action": "upload"
"url": {string} The full destination path, including a file name. This file name may be new or existing.
"path": {string} File name to upload. Must specify both the drive and file name [“cpu:dethstar_plans.txt”].
"tranID": (optional) : Any

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action" : "upload",
    "url": "https://DataThings.com/Documents/cpu:dethstar_plans.txt",
    "path" : "cpu:dethstar_plans.txt"
}

Response Example

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "success": "File Upload Succeeded"
}

Error Response

{"error": "File upload failed"}
{"error": "File does not exist"}

Delete¶

Instruct the data logger to delete a file.

Important

If the file being deleted is the currently running program, the data logger will continue running the program in memory. Only the copy of the file stored on the logger’s drive (e.g., CPU: or CRD:) will be removed.

Properties

"action": {string}: “delete”
"path": {string}: Path to file to delete [“CPU:myFile.dld”].
"tranID": (optional) : Any

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "delete",
    "path": "CPU:myFile.dld"
}

Response Example

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "success": "File deleted"
}

Error Responses

{"error": "File does not exist: <file name>"}
{"error": "File delete failed"}

Stop program¶

File control action to stop the currently running program.

Properties

"action": "stop"
"runOnPowerUp": (optional) {boolean} set the run on power up flag
- true (default) Program set to run on power up
- false Program not set to run on power up

Example Command

{
    "action" : "stop",
    "runOnPowerUp": true
}

Progress

Progress of the command will be published on the state topic.

Publish cs/v2/state/ABCD-EFGH-1234

{
    "clientId": "7GY3-DZYK-KBWF",
    "state": "offline",
    "reason": "Stopping program"
}

Response

In addition to the state topic messages, the data logger will publish a final result of the process on the cr topic.

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "success": "Program stopped"
}

Run program¶

Instruct the data logger to run a program already on the device.

Properties

"action": "run"
"path": {string} Path to file to be run [“CPU:myProgram.dld”]
"runOnPowerUp": {boolean} The program is set to run on power up (defaults to True - program is set as power up program).
"deleteDataTables": {boolean} The current data tables are deleted (defaults to false - datatables will be left alone if possible).

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "run",
    "path": "CPU:myProgram.dld",
    "runOnPowerUp": true,
    "deleteDataTables": true
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl/tran_1234

{
    "clientID": "ABCD-EFGH-1234",
    "state": "offline",
    "reason": "Running program, deleting tables"
}

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl/6fff584c-79eb-406a-a932-401758299521

Success:

{
    "success": "Program running, deleted tables"
}

Create file¶

Create (or overwrite) a file on the data logger from inline data supplied in "source". Text files are written verbatim; binary files are supplied base64-encoded together with "encoding": "base64".

Properties

"action": "create"
"path": {string} Destination file. May instead be given as "fileName" with an optional "drive" (defaults to CPU).
"source": {string} The file contents to write. For "encoding": "base64" this is the base64-encoded binary; otherwise it is written verbatim as text.
"encoding": (optional) {string} "base64" to decode "source" from base64 and write the resulting raw bytes — use this to create binary files. Omit (or "none") to write "source" verbatim.
"chksum32": (optional) {string} CRC-32 of the intended contents (the decoded bytes when base64 is used), as decimal or 0x-prefixed hex. If the file already exists and its CRC-32 matches, it is left untouched and creation is skipped.

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "create",
    "path": "CPU:blob.bin",
    "encoding": "base64",
    "source": "SGVsbG8sIHdvcmxkIQ=="
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "success": "File created"
}

Move file¶

Move a file to a new drive/name. Renaming a file is a move whose destination is on the same drive.

Properties

"action": "move"
"source": {string} Existing file to move [“CRD:file.txt”].
"destination": {string} New path/name for the file [“USR:file.txt”].

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "move",
    "source": "CRD:file.txt",
    "destination": "USR:file.txt"
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

Success:

{
    "success": "File moved"
}

On failure:

{
    "error": "Source or destination file does not exist"
}

Copy file¶

Copy a file to another drive/name, leaving the original in place.

Properties

"action": "copy"
"source": {string} Existing file to copy [“CRD:file.txt”].
"destination": {string} Destination path/name [“USR:file.txt”].

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "copy",
    "source": "CRD:file.txt",
    "destination": "USR:file.txt"
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

Success:

{
    "success": "File copied"
}

On failure:

{
    "error": "Source or destination file does not exist"
}

Format drive¶

Format (erase) a data logger drive.

Warning

Formatting a drive permanently erases every file on it.

Properties

"action": "format"
"drive": {string} Drive to format [“USR”]. The drive name may be given with or without the trailing colon.

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "format",
    "drive": "USR"
}

Response

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

Success:

{
    "success": "Drive formatted"
}

On failure one of:

{
    "error": "Drive not specified"
}

{
    "error": "Drive does not exist: <drive>"
}

{
    "error": "Open files, unable to format drive: <drive>"
}

Load OS from drive¶

Install an operating system (.obj) that is already stored on a data logger drive (for example one previously written with a create/download action). On success the data logger installs the OS and reboots to run it.

Properties

"action": "load"
"path": {string} Path to the OS file already on the logger [“CPU:CR350.1.8.0.obj”].

Example Command

Subscribe cs/v2/cc/ABCD-EFGH-1234/fileControl

{
    "action": "load",
    "path": "CPU:CR350.1.8.0.obj"
}

Response

On success the data logger reboots to install and run the new OS (the reboot ends the current session, so no success message is published beforehand). On failure it publishes one of:

Publish cs/v2/cr/ABCD-EFGH-1234/fileControl

{
    "error": "Unable to load OS file: <path>"
}

{
    "error": "OS File Check Failed"
}