Operating System Download
=========================

Command the data logger to download an Operating System via HTTP GET from a URL.
There are two delivery modes supported.

- `Flat`_ A minimal format containing only a direct file URL.

- `Rich`_ A structured format with optional: versioning, file chunking, and checksums.

**Topic Structure:** ``<baseTopic>/cc/<deviceID>/OS``

Flat
----

A minimal format containing only a direct file URL.

.. admonition:: Properties

    - ``"url":`` {*string*} web address to a specific server to retrieve OS file.
    - ``"tranID":`` *(optional)*

**Flat Example Command**

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

.. code-block:: json

    {
        "url":"https://DataThings.com/Operating_Systems/CR6.14.2.0.obj"
    }

Rich
----

A structured format with optional: versioning, file chunking, and checksums.
This method of Operating System Download is used by Campbell Cloud.

.. admonition:: Properties

    - ``"cmd":`` {*string*} *(optional)*  Specifies the ``"OS"`` command. This is not required if `'OS'` is provided in the topic.

    - ``"version":`` {*string*} *(optional)* The device is updated only when its current OS version differs from the specified version (exact match).

    - ``"minVersion":`` {*string*} *(optional)* A dotted-decimal version (e.g. ``"1.5.3"``). The update is skipped when this version is **less than or equal to** the device's current version, so the update only proceeds when it moves the device forward. Trailing components default to zero (``"1.5"`` is treated as ``"1.5.0"``). Applies to both the flat and chunked forms.

    - ``"pre_url":`` {*string*} *(optional)* The beginning segment of the complete URL - ``<pre_url><url><post_url>``.

    - ``"url":`` {*string*} *(required)* The complete URL if `pre_url` and `post_url` are not used, or the middle segment of the composed URL ``<pre_url><url><post_url>``.

    - ``"post_url":`` {*string*} *(optional)* The end segment of the composed URL ``<pre_url><url><post_url>``.

    - ``"size":`` {*string*} *(optional)* Specifies the expected size (in bytes) of each file. Size checks are performed after transfer to ensure each file was received completely.

    - ``"chksum32":`` {*string*} *(optional)* A list of 32-bit checksums for each file. Used to verify data integrity and ensure that each file was received without corruption.

**Rich Example Command**

This example sends the Operating System in chunked files

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

.. code-block:: json

    {
        "cmd": "OS",
        "version": "1.5.3",
        "pre_url": "https://DataThings.com/Operating_Systems/",
        "url": [    "Aspen.Beta.1.5.3_0",
                    "Aspen.Beta.1.5.3_1",
                    "Aspen.Beta.1.5.3_2",
                    "Aspen.Beta.1.5.3_3",
                    "Aspen.Beta.1.5.3_4",
                    "Aspen.Beta.1.5.3_5"
                ],
        "post_url": ".obc",
        "size": [90000, 90000, 90000, 90000, 46305],
        "chksum32": [1943087122, 698388942, 1264426681, 1520571022, 4097410382]
    }

**Progress**

Progress of the OS download will be published on the state topic.

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

- Download Started

.. code-block:: json

    {
        "clientId": "ABCD-EFGH-1234",
        "state": "online",
        "fileTransfer": "OS file download"
    }

- Flashing OS:

.. important::

    Data logger will go offline and apply the update

.. code-block:: json

    {
        "clientId": "ABCD-EFGH-1234",
        "state": "online",
        "fileTransfer": "Flashing OS"
    }

    {
        "clientId": "ABCD-EFGH-1234",
        "state": "offline",
        "reason": "OS update"
    }

- Process Complete

.. code-block:: json

    {
        "clientId": "ABCD-EFGH-1234",
        "state": "online"
    }

.. note::

    The OS command does not respond back to the ``cr`` topic.