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.

:guilabel:`Subscribe` ``<baseTopic>/cc/<deviceID>/fileControl``

Checksum
--------

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

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "checksum": "a2a186d5"
    }

.. admonition:: 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.

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Basic response:**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Verbose Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "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"
            }
        }
    }

.. admonition:: 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.

.. admonition:: 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**

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

.. code-block:: json

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

**Response Example**

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

.. code-block:: json

    {
        "success": "HTTP get succeeded"
    }

.. admonition:: Error Response

    -  ``{"error": "HTTP get failed"}``

Upload
------

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

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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


**Response Example**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "success": "File Upload Succeeded"
    }

.. admonition:: 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.

.. admonition:: Properties

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

**Example Command**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response Example**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "success": "File deleted"
    }

.. admonition:: Error Responses

    - ``{"error": "File does not exist: <file name>"}``

    - ``{"error": "File delete failed"}``

Stop program
------------

File control action to stop the currently running program.

.. admonition:: 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**

.. code-block:: json

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

**Progress**

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

:guilabel:`Publish` ``cs/v2/state/ABCD-EFGH-1234``

.. code-block:: json

    {
        "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.

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "success": "Program stopped"
    }

Run program
-----------

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

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish`
``cs/v2/cr/ABCD-EFGH-1234/fileControl/tran_1234``

::

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


:guilabel:`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"``.

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "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.

.. admonition:: 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**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

Success:

.. code-block:: json

    {
        "success": "File moved"
    }

On failure:

.. code-block:: json

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

Copy file
---------

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

.. admonition:: Properties

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

**Example Command**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

Success:

.. code-block:: json

    {
        "success": "File copied"
    }

On failure:

.. code-block:: json

    {
        "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.

.. admonition:: Properties

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

**Example Command**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

**Response**

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

Success:

.. code-block:: json

    {
        "success": "Drive formatted"
    }

On failure one of:

.. code-block:: json

    {
        "error": "Drive not specified"
    }

.. code-block:: json

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

.. code-block:: json

    {
        "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.

.. admonition:: Properties

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

**Example Command**

:guilabel:`Subscribe` ``cs/v2/cc/ABCD-EFGH-1234/fileControl``

.. code-block:: json

    {
        "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:

:guilabel:`Publish` ``cs/v2/cr/ABCD-EFGH-1234/fileControl``

.. code-block:: json

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

.. code-block:: json

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