Merge pull request #16 from MrClock8163/feature/settings

MrClock8163 · web-flow · commit da6a36e82540 · 2025-07-30T09:56:06.000+02:00
Settings download and upload commands
diff --git a/docs/commands/settings/download.rst b/docs/commands/settings/download.rst
@@ -0,0 +1,36 @@
+Downloading
+===========
+
+The settings are saved by iterating over a set collection of parameter names.
+Any particular instrument might not respond to the query of any of the
+parameters (e.g. a total station will not respond to queries regarding the
+digital level settings). These settings are marked empty, and later cleaned up
+before the config file is saved to disk.
+
+It is possible to save the default values for the parameters, that the
+instrument did not respond to. In this case, the config file might need to be
+manually cleaned of the irrelevant or unwanted settings.
+
+Examples
+--------
+
+.. code-block:: shell
+    :caption: Saving only applicable GeoCom settings
+
+    iman download settings COM1 geocom tps_settings.json
+
+.. code-block:: shell
+    :caption: Saving to YAML format in a file without extension
+
+    iman download settings -f yaml COM1 geocom tps_settings
+
+.. code-block:: shell
+    :caption: Saving all settings including defaults of not applicable ones
+
+    iman download settings --defaults COM1 geocom tps_settings.json
+
+Usage
+-----
+
+.. click:: instrumentman.settings:cli_download
+    :prog: iman download settings
diff --git a/docs/commands/settings/index.rst b/docs/commands/settings/index.rst
@@ -0,0 +1,15 @@
+:icon: material/cog
+
+Settings
+========
+
+For different measurements, different instrument settings might be required.
+The settings commands can be used to save the settings to the config file,
+and later load them back as necessary.
+
+.. toctree::
+    :maxdepth: 1
+
+    download
+    validate
+    upload
diff --git a/docs/commands/settings/upload.rst b/docs/commands/settings/upload.rst
@@ -0,0 +1,61 @@
+Uploading
+=========
+
+Once a config file is created (either manually, or saved from the instrument),
+the parameters can be uploaded back to the instrument. The config file must
+have a valid structure, or the upload will be refused.
+
+The config file can either be in JSON, YAML or TOML format, but regardless,
+the structure must follow the required schema.
+
+.. note::
+ 
+    Configs can be validated before upload with the validation command.
+
+Examples
+--------
+
+.. code-block:: json
+    :caption: Total station ATR and target setting
+
+    {
+        "protocol": "geocom",
+        "settings": [
+            {
+                "subsystem": "aut",
+                "options": {
+                    "atr": true
+                }
+            },
+            {
+                "subsystem": "bap",
+                "options": {
+                    "target_type": "REFLECTOR",
+                    "prizm_type": "MINI"
+                }
+            }
+        ]
+    }
+
+
+.. code-block:: json
+    :caption: DNA normal staff direction with meter units
+
+    {
+        "protocol": "gsidna",
+        "settings": [
+            {
+                "subsystem": "settings",
+                "options": {
+                    "distance_unit": "METER",
+                    "staff_mode": false
+                }
+            }
+        ]
+    }
+
+Usage
+-----
+
+.. click:: instrumentman.settings:cli_upload
+    :prog: iman upload settings
diff --git a/docs/commands/settings/validate.rst b/docs/commands/settings/validate.rst
@@ -0,0 +1,13 @@
+Validation
+==========
+
+An instrument settings file must have a valid structure, or the upload will be
+refused. The schema file is available in the
+`GitHub repository <https://github.com/MrClock8163/Instrumentman/blob/main/src/instrumentman/settings/schema_settings.json>`_.
+
+Usage
+-----
+
+.. click:: instrumentman.settings:cli_validate
+    :prog: iman validate settings
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -44,6 +44,7 @@ Content
     commands/protocoltest/index
     commands/files/index
     commands/jobs/index
+    commands/settings/index
 
 Indices
 
diff --git a/docs/latexindex.rst b/docs/latexindex.rst
@@ -29,3 +29,4 @@ Applications
     commands/protocoltest/index
     commands/files/index
     commands/jobs/index
+    commands/settings/index
diff --git a/pyproject.toml b/pyproject.toml
@@ -17,6 +17,8 @@ dependencies = [
     "rapidfuzz",
     "jsonschema",
     "jmespath",
+    "toml",
+    "PyYAML",
     "click-extra"
 ]
 classifiers = [
@@ -62,6 +64,8 @@ linting = [
     "types-pyserial",
     "types-jsonschema",
     "types-jmespath",
+    "types-toml",
+    "types-PyYAML",
     "mypy",
     "flake8"
 ]
diff --git a/src/instrumentman/__init__.py b/src/instrumentman/__init__.py
@@ -13,6 +13,7 @@
 from . import inclination
 from . import filetransfer
 from . import jobs
+from . import settings
 
 
 @extra_group("iman", params=None)  # type: ignore[misc]
@@ -63,6 +64,11 @@ def cli_download() -> None:
     """Download data from the instrument."""
 
 
+@cli.group("upload")  # type: ignore[misc]
+def cli_upload() -> None:
+    """Upload data to the instrument."""
+
+
 cli.add_command(morse.cli)
 cli.add_command(terminal.cli)
 cli_measure.add_command(setmeasurement.cli_measure)
@@ -75,7 +81,10 @@ def cli_download() -> None:
 cli_merge.add_command(setmeasurement.cli_merge)
 cli_merge.add_command(inclination.cli_merge)
 cli_validate.add_command(setmeasurement.cli_validate)
+cli_validate.add_command(settings.cli_validate)
 cli_import.add_command(setup.cli_import)
 cli_list.add_command(filetransfer.cli_list)
 cli_list.add_command(jobs.cli_list)
 cli_download.add_command(filetransfer.cli_download)
+cli_download.add_command(settings.cli_download)
+cli_upload.add_command(settings.cli_upload)
diff --git a/src/instrumentman/schema_targets.json b/src/instrumentman/schema_targets.json
@@ -1,5 +1,5 @@
 {
-    "title": "GeoComPy set measurement targets schema",
+    "title": "Instrumentman set measurement targets schema",
     "description": "Target point records for set measurements",
     "tpye": "object",
     "additionalProperties": false,
diff --git a/src/instrumentman/setmeasurement/schema_session.json b/src/instrumentman/setmeasurement/schema_session.json
@@ -1,5 +1,5 @@
 {
-    "title": "GeoComPy set measurement session schema",
+    "title": "Instrumentman set measurement session schema",
     "description": "Data recorded during a set measurement session",
     "type": "object",
     "additionalProperties": false,
diff --git a/src/instrumentman/settings/__init__.py b/src/instrumentman/settings/__init__.py
@@ -0,0 +1,103 @@
+from typing import Any
+
+from click_extra import (
+    extra_command,
+    argument,
+    option,
+    file_path,
+    Choice
+)
+
+from ..utils import (
+    com_port_argument,
+    com_option_group
+)
+
+
+@extra_command(
+    "settings",
+    params=None,
+    context_settings={"auto_envvar_prefix": None}
+)  # type: ignore[misc]
+@com_port_argument()
+@argument(
+    "protocol",
+    help="communication protocol",
+    type=Choice(["geocom", "gsidna"], case_sensitive=False)
+)
+@argument(
+    "file",
+    help="file to save settings to",
+    type=file_path(readable=False)
+)
+@com_option_group()
+@option(
+    "-f",
+    "--format",
+    help="settings file format",
+    type=Choice(["auto", "json", "yaml", "toml"], case_sensitive=False),
+    default="auto"
+)
+@option(
+    "--defaults",
+    help=(
+        "add defaults for settings that could not be saved "
+        "(e.g. not applicable to the current instrument)"
+    ),
+    is_flag=True
+)
+def cli_download(**kwargs: Any) -> None:
+    """Save instrument settings to file."""
+    from .save import main
+
+    main(**kwargs)
+
+
+@extra_command(
+    "settings",
+    params=None,
+    context_settings={"auto_envvar_prefix": None}
+)  # type: ignore[misc]
+@com_port_argument()
+@argument(
+    "settings",
+    help="file containing instrument settings",
+    type=file_path(exists=True, readable=True)
+)
+@com_option_group()
+@option(
+    "-f",
+    "--format",
+    help="settings file format",
+    type=Choice(["auto", "json", "yaml", "toml"], case_sensitive=False),
+    default="auto"
+)
+def cli_upload(**kwargs: Any) -> None:
+    """Load instrument settings from file."""
+    from .load import main
+
+    main(**kwargs)
+
+
+@extra_command(
+    "settings",
+    params=None,
+    context_settings={"auto_envvar_prefix": None}
+)  # type: ignore[misc]
+@argument(
+    "file",
+    help="settings file to validate",
+    type=file_path(exists=True, readable=True)
+)
+@option(
+    "-f",
+    "--format",
+    help="settings file format",
+    type=Choice(["auto", "json", "yaml", "toml"], case_sensitive=False),
+    default="auto"
+)
+def cli_validate(**kwargs: Any) -> None:
+    """Validate instrument settings config."""
+    from .validate import main
+
+    main(**kwargs)
diff --git a/src/instrumentman/settings/io.py b/src/instrumentman/settings/io.py
@@ -0,0 +1,67 @@
+from typing import Any, cast, TypedDict
+from pathlib import Path
+
+import json
+import yaml
+import toml
+
+from ..utils import echo_red
+
+
+class SubsystemSettingsDict(TypedDict):
+    subsystem: str
+    options: dict[str, Any]
+
+
+class SettingsDict(TypedDict):
+    protocol: str
+    settings: list[SubsystemSettingsDict]
+
+
+def read_settings(
+    file: Path,
+    format: str = "auto"
+) -> SettingsDict:
+    if format == "auto":
+        format = file.suffix[1:].lower() if file.suffix else ""
+
+    match format:
+        case "json":
+            with file.open("rt", encoding="utf8") as settings:
+                data = cast(SettingsDict, json.load(settings))
+        case "yaml" | "yml":
+            with file.open("rt", encoding="utf8") as settings:
+                data = cast(SettingsDict, yaml.load(settings, yaml.Loader))
+        case "toml":
+            # The TOML package doesn't support heterogenous arrays, even tho it
+            # was added to the language spec in 2019. Therefore the standard
+            # lib tomllib/tomli has to be used for parsing.
+            import tomllib as toml
+            with file.open("rb") as settings:
+                data = cast(SettingsDict, toml.load(settings))
+        case _:
+            echo_red(f"Unknown file format: {format}")
+            exit(1)
+
+    return data
+
+
+def write_settings(
+    data: SettingsDict,
+    file: Path,
+    format: str = "auto"
+) -> None:
+    if format == "auto":
+        format = file.suffix[1:].lower() if file.suffix else ""
+
+    with file.open("wt", encoding="utf8") as settings:
+        match format:
+            case "json":
+                json.dump(data, settings, indent=4)
+            case "yaml" | "yml":
+                yaml.dump(data, settings, yaml.Dumper)
+            case "toml":
+                toml.dump(data, settings)
+            case _:
+                echo_red(f"Unknown file format: {format}")
+                exit(1)
diff --git a/src/instrumentman/settings/load.py b/src/instrumentman/settings/load.py
diff --git a/src/instrumentman/settings/save.py b/src/instrumentman/settings/save.py
diff --git a/src/instrumentman/settings/schema_settings.json b/src/instrumentman/settings/schema_settings.json
diff --git a/src/instrumentman/settings/validate.py b/src/instrumentman/settings/validate.py

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "title": "GeoComPy set measurement targets schema",`
	`2`	`+ "title": "Instrumentman set measurement targets schema",`
`3`	`3`	`"description": "Target point records for set measurements",`
`4`	`4`	`"tpye": "object",`
`5`	`5`	`"additionalProperties": false,`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "title": "GeoComPy set measurement session schema",`
	`2`	`+ "title": "Instrumentman set measurement session schema",`
`3`	`3`	`"description": "Data recorded during a set measurement session",`
`4`	`4`	`"type": "object",`
`5`	`5`	`"additionalProperties": false,`