Settings
========

Set Settings
------------

There are multiple ways to configure settings on a data logger.
These methods have evolved from early implementations to the current system, and we strive to maintain backward compatibility.
However, it is recommended to use current configuration over the alternate method whenever possible.

SetSettings
~~~~~~~~~~~

Set a single or multiple settings in a data logger using one payload.

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

.. admonition:: Properties

    - ``"settings": {}`` {*object*} A dictionary of one or more setting name/value or setting ID/value pairs to apply.
        - If the key is a **setting name** (e.g., `"PakBusAddress"`), the **value must be a string**, even if the setting represents a number or boolean.
        - If the key is a **setting ID** (e.g., `"3"`), the **value must be the appropriate native type** expected for that setting (e.g., number, boolean, string).

    Example entries:
        - ``"PakBusAddress": "314"`` Uses the name `"PakBusAddress"`, so value must be string.
        - ``"3": 314`` Uses the ID `3` (which maps to `"PakBusAddress"`), so the value is a number.

**Example Command**

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

.. code-block:: json

    {
        "settings": {
            "StationName": "Sir Logs-a-Lot",
            "3": "314",
            "USRDriveSize": "10240"
        }
    }

Progress may be published on the state topic.

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

- Applying a setting that requires a reboot

.. code-block:: json

    {
        "clientId": "7GY3-DZYK-KBWF",
        "state": "offline",
        "reason": "Applying settings"
    }

    {
        "clientId": "7GY3-DZYK-KBWF",
        "state": "online"
    }

**Response**

The data logger will publish a final result of the process on the ``cr`` topic.

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

.. code-block:: json

    {
        "success": "Settings applied, rebooted"
    }

Set Setting <Alternate>
~~~~~~~~~~~~~~~~~~~~~~~

Instructs the data logger to change a single setting.
Each change is sent as its own payload object.
Changes are staged and will not take effect until a payload includes "apply": true, which applies all staged changes immediately.

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

.. admonition:: Properties

    - ``"action": "set"`` Indicates the operation is a setting change.
    - ``"name":`` {*string*, required} The name of the setting to modify (e.g., `"PakBusAddress"`).
      - The value must be provided as a string, even if the setting represents a number or boolean.
    - ``"value":`` {*string*, required}: The new value for the setting. Must be a string.
    - ``"apply":`` {*boolean*, optional}:
      - If ``true``, the setting change is immediately applied.
      - If omitted or ``false``, the change is staged but not yet applied.

    Example entries:
        - ``{"action": "set", "name": "PakBusAddress", "value": "10"}`` Stages a change to `"PakBusAddress"`.
        - ``{"action": "set", "name": "StationName", "value": "Sir Logs-a-Lot"}`` Stages a change to `"StationName"`.
        - ``{"action": "set", "name": "USRDriveSize", "value": "10240", "apply": true}`` Changes `"USRDriveSize"` and applies immediately.

    Setting Arrays:
        - Some settings are defined as arrays and require an explicit numeric index.
        - Symbolic or descriptive names (for example, interface labels) are **not** valid indices.

        - Array settings are referenced using the form ``<SettingName>(<index>)``.

        Example:
            - ``Baudrate`` is an array-valued setting.
            - ``Baudrate(9)`` is valid and maps to the ``ComC1`` port on the CR1000X.
            - ``Baudrate(ComC1)`` is **not valid** because ``ComC1`` is not a numeric index.

**Example Command** [Single Setting]:

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

.. code-block:: json

    {
        "action": "set",
        "name": "PakBusAddress",
        "value": "3",
        "apply": true
    }

**Response** [Single Setting]:

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

.. code-block:: json

    {
        "success":"Settings applied, no reboot required"
    }


**Example Command** [Multiple Setting]:

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

.. code-block:: json

    {
        "action": "set",
        "name": "PakBusAddress",
        "value": "3"
    }

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

.. code-block:: json

    {
        "success":"Settings set successfully"
    }

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

.. code-block:: json

    {
        "action": "set",
        "name": "StationName",
        "value": "Sir Logs-a-Lot Sr"
    }

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

.. code-block:: json

    {
        "success":"Settings set successfully"
    }

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

.. code-block:: json

    {
        "action": "set",
        "name": "USRDriveSize",
        "value": "10240",
        "apply": true
    }

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

.. code-block:: json

    {
        "success":"Settings applied, rebooted"
    }

Get Settings
------------

There are multiple ways to read/get settings on a data logger.
These methods have evolved from early implementations to the current system, and we strive to maintain backward compatibility.

GetSettings <Beta>
~~~~~~~~~~~~~~~~~~

**This Feature is still in Development and is subject to change.**
Request a single setting or a specified list of settings. Settings can be selected by name or by ID.

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

.. admonition:: Properties

    - ``"names": []`` [*array*] An array of one or more setting names.
        - **Setting Names** (e.g., `"PakBusAddress"`) must be strings.
        - If names are used setting IDs are not allowed.
    - ``"ids": []`` [*array*] An array of one or more setting IDs.
        - **Setting IDs** must be an integers.
        - The response to the Settings IDs will be as an array some ID's are an array of settings. 
    
    Example entries:
        - ``{"names": ["StationName", "PakBusAddress"]}``
        - ``{"ids": [2,3]``


**Example Command: By Names**

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

.. code-block:: json

    {
        "names": ["StationName", "PakBusAddress"]
    }

**Response**

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

.. code-block:: json

    {
        "StationName":"RedShirt_Lab",
        "PakBusAddress":"1"
    }

**Example Command: By IDs**

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

.. code-block:: json

    {
        "ids": [2, 3]
    }

**Response**

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

.. code-block:: json

    {
        "2":["RedShirt_Lab"],
        "3":[1]
    }


Get Single Setting <Alternate>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. admonition:: Properties

    - ``"action": "get"``
    - One of:
        - ``"name":`` {*string*} Setting name to publish
        - ``"id":`` {*number*} Setting id (from Device Configuration Utility) to publish

    Setting Arrays:
        - Some settings are defined as arrays and require an explicit numeric index.
        - Symbolic or descriptive names (for example, interface labels) are **not** valid indices.

        - Array settings are referenced using the form ``<SettingName>(<index>)``.

        Example:
            - ``Baudrate`` is an array-valued setting.
            - ``Baudrate(9)`` is valid and maps to the ``ComC1`` port on the CR1000X.
            - ``Baudrate(ComC1)`` is **not valid** because ``ComC1`` is not a numeric index.

**Example Command: By Setting Name**

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

.. code-block:: json

    {
        "action": "get",
        "name": "PakBusAddress"
    }

**Response**

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

.. code-block:: json

    {
        "setting": "PakBusAddress",
        "value": "3"
    }

**Example Command: By Setting ID**

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


.. code-block:: json

    {
        "action": "get",
        "id": 3
    }

**Response**

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

.. code-block:: json

    {
        "id": 3,
        "value": "3"
    }

.. note:: Setting IDs must be sent as integers


Get all settings
~~~~~~~~~~~~~~~~

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

.. admonition:: Properties

    - ``"action": "get"``
    - ``"name": null`` or ``[]`` empty list object

.. warning::

    This will be a large payload (~7KB). All data logger settings will be in a single payload.
    If the data logger does not output to the ``cr`` topic try increasing the ``Max TLS Server Connection settings``.

**Example Command**

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

.. code-block:: json

    {
        "action": "get",
        "name": null
    }

**Response**

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

.. code-block::

    {
        "StationName": "12345",
        "Security": "0",
        "PakBusAddress": "1"
        ...
        ...
    }