fprime-gds 3.6.2a1__py3-none-any.whl → 4.0.0a2__py3-none-any.whl

fprime_gds/common/tools/README.md

@@ -0,0 +1,34 @@
+# FPrime GDS tools
+## fprime-prm-write
+### JSON file reference
+JSON files for the `fprime-prm-write` tool should take the following form:
+```json
+{
+    "componentInstanceOne": {
+        "parameterNameOne": "parameter value",
+        "parameterNameTwo": ["a", "b", "c"],
+        "parameterNameThree": {
+            "complexValue": [123, 456]
+        }
+    },
+    "componentInstanceTwo": {
+        "parameterNameFour": true
+    }
+}
+```
+The JSON should consist of a key-value map of component instance names to an inner key-value map. The inner key-value map should consist of parameter name-to-value map entries. The parameter values support complex FPrime types, such as nested structs, arrays or enum constants. Structs are instantiated with key-value maps, where the keys are the field names and the values are the field values. Arrays are just JSON arrays, and enum constants are represented as strings.
+
+### How to Initialize a ParamDB .dat File
+
+The `fprime-prm-write` tool can be used to create a `.dat` file compatible with the `PrmDb` component from a json file. To use, create a compatible JSON file as defined in the JSON File Reference above, and pass it in to the tool using the `dat` subcommand, like so:
+```
+fprime-prm-write dat <json file> --dictionary <path to compiled FPrime dict>
+```
+You should then have a `.dat` file which can be passed in to the `PrmDb`. Note, this `.dat` file will only have entries for the parameters specified in the JSON file. If you want it to instead have a value for all parameters which have a default value, you can add the `--defaults` option. Then, the generated `.dat` file will essentially reset all parameters back to default, except for those specified in the JSON file.
+
+### How to Create a .seq File From a Parameter JSON File
+Sometimes, you may want to update parameters while the FPrime application is running. This can be accomplished with a sequence of `_PRM_SET` commands, which the `fprime-prm-write` tool can automatically create for you. To use, create a compatible JSON file as defined in the JSON File Reference above, and pass it in to the tool using the `seq` subcommand, like so:
+```
+fprime-prm-write seq <json file> --dictionary <path to compiled FPrime dict>
+```
+You should then have a `.seq` file which can be compiled and executed by the `CmdSequencer`.

fprime_gds/common/tools/params.py

@@ -0,0 +1,246 @@
+# author: zimri.leisher
+# created on: Jan 27, 2025
+
+# allow us to use bracketed types
+from __future__ import annotations
+import json as js
+from pathlib import Path
+from argparse import ArgumentParser
+from typing import Any
+from fprime_gds.common.loaders.prm_json_loader import PrmJsonLoader
+from fprime_gds.common.templates.prm_template import PrmTemplate
+from fprime.common.models.serialize.type_base import BaseType
+from fprime.common.models.serialize.array_type import ArrayType
+from fprime.common.models.serialize.bool_type import BoolType
+from fprime.common.models.serialize.enum_type import EnumType
+from fprime.common.models.serialize.numerical_types import (
+    F32Type,
+    F64Type,
+    I8Type,
+    I16Type,
+    I32Type,
+    I64Type,
+    U8Type,
+    U16Type,
+    U32Type,
+    U64Type,
+)
+from fprime.common.models.serialize.serializable_type import SerializableType
+from fprime.common.models.serialize.string_type import StringType
+
+FW_PRM_ID_TYPE_SIZE = 4 # serialized size of the FwPrmIdType
+
+
+def instantiate_prm_type(prm_val_json, prm_type: type[BaseType]):
+    """given a parameter type and its value in json form, instantiate the type
+    with the value, or raise an exception if the json is not compatible"""
+    prm_instance = prm_type()
+    if isinstance(prm_instance, BoolType):
+        value = str(prm_val_json).lower().strip()
+        if value in {"true", "yes"}:
+            av = True
+        elif value in {"false", "no"}:
+            av = False
+        else:
+            raise RuntimeError("Param value is not a valid boolean")
+        prm_instance.val = av
+    elif isinstance(prm_instance, EnumType):
+        prm_instance.val = prm_val_json
+    elif isinstance(prm_instance, (F64Type, F32Type)):
+        prm_instance.val = float(prm_val_json)
+    elif isinstance(
+        prm_instance,
+        (I64Type, U64Type, I32Type, U32Type, I16Type, U16Type, I8Type, U8Type),
+    ):
+        prm_instance.val = int(prm_val_json, 0) if isinstance(prm_val_json, str) else int(prm_val_json)
+    elif isinstance(prm_instance, StringType):
+        prm_instance.val = prm_val_json
+    elif isinstance(prm_instance, (ArrayType, SerializableType)):
+        prm_instance.val = prm_val_json
+    else:
+        raise RuntimeError(
+            "Param value could not be converted to type object"
+        )
+    return prm_instance
+
+
+def parsed_json_to_dat(templates_and_values: list[tuple[PrmTemplate, Any]]) -> bytes:
+    """convert a list of (PrmTemplate, prm value json) to serialized bytes for a PrmDb"""
+    serialized = bytes()
+    for template_and_value in templates_and_values:
+        template, json_value = template_and_value
+        prm_instance = instantiate_prm_type(json_value, template.prm_type_obj)
+
+        prm_instance_bytes = prm_instance.serialize()
+
+        # see https://github.com/nasa/fprime/blob/devel/Svc/PrmDb/docs/sdd.md#32-functional-description
+        # for an explanation of the binary format of parameters in the .dat file
+
+        # delimiter
+        serialized += b"\xA5"
+
+        record_size = FW_PRM_ID_TYPE_SIZE + len(prm_instance_bytes)
+
+        # size of following data
+        serialized += record_size.to_bytes(length=4, byteorder="big")
+        # id of param
+        serialized += template.prm_id.to_bytes(length=4, byteorder="big")
+        # value of param
+        serialized += prm_instance_bytes
+    return serialized
+
+
+def parsed_json_to_seq(templates_and_values: list[tuple[PrmTemplate, dict]], include_save=False) -> list[str]:
+    """convert a list of (PrmTemplate, prm value json) to a command sequence for the CmdSequencer.
+    Returns a list of lines in the sequence."""
+    cmds = []
+    cmds.append("; Autocoded sequence file from JSON")
+    for template_and_value in templates_and_values:
+        template, json_value = template_and_value
+        set_cmd_name = template.comp_name + "." + template.prm_name.upper() + "_PRM_SET"
+        cmd = "R00:00:00 " + set_cmd_name + " " + str(json_value)
+        cmds.append(cmd)
+        if include_save:
+            save_cmd = template.comp_name + "." + template.prm_name.upper() + "_PRM_SAVE"
+            cmds.append(save_cmd)
+    return cmds
+
+
+
+def parse_json(param_value_json, name_dict: dict[str, PrmTemplate], include_implicit_defaults=False) -> list[tuple[PrmTemplate, dict]]:
+    """
+    param_value_json: the json object read from the .json file
+    name_dict: a dictionary of (fqn param name, PrmTemplate) pairs
+    include_implicit_defaults: whether or not to also include default values from the name dict
+                               if no value was specified in the json
+    @return a list of tuple of param template and the intended param value (in form of json dict)
+    """
+    # first, check the json for errors
+    for component_name in param_value_json:
+        for param_name in param_value_json[component_name]:
+            fqn_param_name = component_name + "." + param_name
+            param_temp: PrmTemplate = name_dict.get(fqn_param_name, None)
+            if not param_temp:
+                raise RuntimeError(
+                    "Unable to find param "
+                    + fqn_param_name
+                    + " in dictionary"
+                )
+
+    # okay, now iterate over the dict
+    templates_to_values = []
+    for fqn_param_name, prm_template in name_dict.items():
+
+        prm_val = None
+
+        if include_implicit_defaults:
+            # there is a default value
+            prm_val = prm_template.prm_default_val
+        
+        comp_json = param_value_json.get(prm_template.comp_name, None)
+        if comp_json:
+            # if there is an entry for the component
+            if prm_template.prm_name in comp_json:
+                # if there is an entry for this param
+                # get the value
+                prm_val = comp_json[prm_template.prm_name]
+        
+        if not prm_val:
+            # not writing a val for this prm
+            continue
+
+        templates_to_values.append((prm_template, prm_val))
+
+    return templates_to_values
+
+
+def main():
+    arg_parser = ArgumentParser()
+    subparsers = arg_parser.add_subparsers(dest="subcmd", required=True)
+
+
+    json_to_dat = subparsers.add_parser("dat", help="Compiles .json files into param DB .dat files")
+    json_to_dat.add_argument(
+        "json_file", type=Path, help="The .json file to turn into a .dat file", default=None
+    )
+    json_to_dat.add_argument(
+        "--dictionary",
+        "-d",
+        type=Path,
+        help="The dictionary file of the FSW",
+        required=True,
+    )
+    json_to_dat.add_argument("--defaults", action="store_true", help="Whether or not to implicitly include default parameter values in the output")
+    json_to_dat.add_argument("--output", "-o", type=Path, help="The output file", default=None)
+
+
+    json_to_seq = subparsers.add_parser("seq", help="Converts .json files into command sequence .seq files")
+    json_to_seq.add_argument(
+        "json_file", type=Path, help="The .json file to turn into a .seq file", default=None
+    )
+    json_to_seq.add_argument(
+        "--dictionary",
+        "-d",
+        type=Path,
+        help="The dictionary file of the FSW",
+        required=True,
+    )
+    json_to_seq.add_argument("--defaults", action="store_true", help="Whether or not to implicitly include default parameter values in the output")
+    json_to_seq.add_argument("--save", action="store_true", help="Whether or not to include the PRM_SAVE cmd in the output")
+    json_to_seq.add_argument("--output", "-o", type=Path, help="The output file", default=None)
+
+
+    args = arg_parser.parse_args()
+
+    if args.json_file is None or not args.json_file.exists():
+        print("Unable to find", args.json_file)
+        exit(1)
+
+    if args.json_file.is_dir():
+        print("json-file is a dir", args.json_file)
+        exit(1)
+
+    if not args.dictionary.exists():
+        print("Unable to find", args.dictionary)
+        exit(1)
+
+    output_format = args.subcmd
+
+    # just compile the one file in place
+    if args.output is None:
+        output_path = args.json_file.with_suffix("." + output_format)
+    else:
+        output_path = args.output
+    
+    convert_json(args.json_file, args.dictionary, output_path, output_format, args.defaults, args.save)
+
+
+def convert_json(json_file: Path, dictionary: Path, output: Path, output_format: str, implicit_defaults=False, include_save_cmd=False):
+
+    print("Converting", json_file, "to", output, "(format: ." + output_format + ")")
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    json = js.loads(json_file.read_text())
+
+    dict_parser = PrmJsonLoader(str(dictionary.resolve()))
+    id_dict, name_dict, versions = dict_parser.construct_dicts(
+        str(dictionary.resolve())
+    )
+
+    templates_to_values = parse_json(json, name_dict, implicit_defaults)
+
+    if output_format == "dat":
+        serialized_values = parsed_json_to_dat(templates_to_values)
+
+        print("Done, writing to", output.resolve())
+        output.write_bytes(serialized_values)
+    elif output_format == "seq":
+        sequence_cmds = parsed_json_to_seq(templates_to_values, include_save_cmd)
+        print("Done, writing to", output.resolve())
+        output.write_text("\n".join(sequence_cmds))
+    else:
+        raise RuntimeError("Invalid output format " + str(output_format))
+
+
+if __name__ == "__main__":
+    main()

fprime_gds/common/utils/config_manager.py

@@ -114,7 +114,7 @@ class ConfigManager(configparser.ConfigParser):
             return U16Type()
         if type_str == "U32":
             return U32Type()
-        if type_str == "u64":
+        if type_str == "U64":
             return U64Type()
         if type_str == "I8":
             return I8Type()
@@ -153,11 +153,11 @@ class ConfigManager(configparser.ConfigParser):
 
         self.__prop["types"] = {
             "msg_len": "U32",
-            "msg_desc": "U32",
-            "ch_id": "U32",
-            "event_id": "U32",
-            "op_code": "U32",
-            "pkt_id": "U16",
+            "FwPacketDescriptorType": "U32",
+            "FwChanIdType": "U32",
+            "FwEventIdType": "U32",
+            "FwOpcodeType": "U32",
+            "FwTlmPacketizeIdType": "U16",
             "key_val": "U16",
         }
         self._set_section_defaults("types")

fprime_gds/executables/apps.py

@@ -1,4 +1,4 @@
-""" fprime_gds.executables.apps: an implementation of start-up apps in fprime
+"""fprime_gds.executables.apps: an implementation of start-up apps in fprime
 
 There are twp ways to approach start=up applications in fprime. First, is to implement a run method via a subclass of
 `GdsFunction`. This gives the implementor the ability to run anything within the run function that python offers,
@@ -10,15 +10,27 @@ command line that will be spun into its own process.
 
 @author lestarch
 """
+
 import subprocess
+import sys
 from abc import ABC, abstractmethod
-from typing import List, Type
+from argparse import Namespace
+from typing import final, List, Dict, Tuple, Type
 
-from fprime_gds.plugin.definitions import gds_plugin_specification
+from fprime_gds.plugin.definitions import gds_plugin_specification, gds_plugin
+from fprime_gds.plugin.system import Plugins
+from fprime_gds.executables.cli import (
+    CompositeParser,
+    ParserBase,
+    BareArgumentParser,
+    StandardPipelineParser,
+    PluginArgumentParser,
+)
+from fprime_gds.common.pipeline.standard import StandardPipeline
 
 
 class GdsBaseFunction(ABC):
-    """ Base functionality for pluggable GDS start-up functions
+    """Base functionality for pluggable GDS start-up functions
 
     GDS start-up functionality is pluggable. This class acts as a base for pluggable functionality supplies helpers to
     the various start-up plugins.
@@ -29,7 +41,7 @@ class GdsBaseFunction(ABC):
 
     @abstractmethod
     def run(self):
-        """ Run the start-up function
+        """Run the start-up function
 
         Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
 
@@ -38,7 +50,7 @@ class GdsBaseFunction(ABC):
 
 
 class GdsFunction(GdsBaseFunction, ABC):
-    """ Functionality for pluggable GDS start-up functions
+    """Functionality for pluggable GDS start-up functions
 
     GDS start-up functionality is pluggable. This class acts as a wide-open implementation of functionality via a single
     `run` callback. Developers have complete control of the start-up functionality. However, this comes at the cost of
@@ -74,7 +86,7 @@ class GdsFunction(GdsBaseFunction, ABC):
 
 
 class GdsApp(GdsBaseFunction):
-    """ GDS start-up process functionality
+    """GDS start-up process functionality
 
     A pluggable base class used to start a new process as part of the GDS command line invocation. This allows
     developers to add process-isolated functionality to the GDS network.
@@ -86,8 +98,9 @@ class GdsApp(GdsBaseFunction):
     Standard plug-in functions (get_name, get_arguments) are available should the implementer desire these features.
     Arguments will be supplied to the class's `__init__` function.
     """
+
     def __init__(self, **arguments):
-        """ Construct the communication applications around the arguments
+        """Construct the communication applications around the arguments
 
         Command line arguments are passed in to match those returned from the `get_arguments` functions.
 
@@ -98,7 +111,7 @@ class GdsApp(GdsBaseFunction):
         self.arguments = arguments
 
     def run(self):
-        """ Run the application as an isolated process
+        """Run the application as an isolated process
 
         GdsFunction objects require an implementation of the `run` command. This implementation will take the arguments
         provided from `get_process_invocation` function and supplies them as an invocation of the isolated subprocess.
@@ -107,7 +120,7 @@ class GdsApp(GdsBaseFunction):
         self.process = subprocess.Popen(invocation_arguments)
 
     def wait(self, timeout=None):
-        """ Wait for the app to complete then return the return code
+        """Wait for the app to complete then return the return code
 
         Waits (blocking) for the process to complete. Then returns the return code of the underlying process. If timeout
         is non-None then the process will be killed after waiting for the timeout and another wait of timeout will be
@@ -125,7 +138,7 @@ class GdsApp(GdsBaseFunction):
 
     @abstractmethod
     def get_process_invocation(self) -> List[str]:
-        """ Run the start-up function
+        """Run the start-up function
 
         Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
 
@@ -148,3 +161,163 @@ class GdsApp(GdsBaseFunction):
             GdsApp subclass
         """
         raise NotImplementedError()
+
+
+class GdsStandardApp(GdsApp):
+    """Standard GDS application that is built upon the StandardPipeline
+
+    Use this class to help build a GdsApp plugin that has a known invocation and starts up the standard pipeline to
+    enable standard GDS processes.
+
+    Developers should implement a concrete subclass with the `start(pipeline)` function to run the application with the
+    supplied pipeline. The subclass must supply **kwargs parent class constructor and extend a GdsApp plugin:
+
+    ```
+    @gds_plugin(GdsApp)
+    class MyStandardApp(GdsStandardApp):
+        def __init__(self, **kwargs):
+            super().__init__(**kwargs)
+        ...
+    ```
+
+    If the plugin requires more arguments beyond the standard pipeline arguments, supply those additional arguments via
+    the `get_additional_arguments` method.
+    """
+
+    def __init__(self, **kwargs):
+        """Take all arguments and store them"""
+        super().__init__(**kwargs)
+
+    @classmethod
+    def get_additional_arguments(cls) -> Dict[Tuple, Dict[str, str]]:
+        """Function to provide additional command line arguments beyond the standard pipeline
+
+        Override this function to provide additional arguments. The form of the arguments are the same as returned by
+        standard plugins: a dictionary of tuple flags to argparse kwargs inputs.
+
+        Return:
+            dictionary of flag tuple to argparse kwargs
+        """
+        return {}
+
+    @classmethod
+    def init(cls):
+        """Allows standard application plugins to initialize before argument parsing is performed"""
+        pass
+
+    @final
+    @classmethod
+    def get_arguments(cls):
+        """Get the arguments for this plugin
+
+        This will return the combined arguments needed for the standard pipeline, and those returned from
+        `get_additional_arguments()`.
+        """
+        return {
+            **cls.get_additional_arguments(),
+            **StandardPipelineParser().get_arguments(),
+        }
+
+    @classmethod
+    def get_cli_parser(cls):
+        """Helper to get a parser for this applications' additional arguments"""
+        return BareArgumentParser(
+            cls.get_additional_arguments(), getattr(cls, "check_arguments", None)
+        )
+
+    @abstractmethod
+    def start(self, pipeline: StandardPipeline):
+        """Start function to contain behavior based in standard pipeline"""
+        raise NotImplementedError()
+
+    def get_process_invocation(self):
+        """Return the process invocation for this class' main
+
+        The process invocation of this application is to run cls.main and supply it a reproduced version of the
+        arguments needed for the given parsers.  When main is loaded, it will dispatch to the sub-classing plugin's
+        start method. The subclassing plugin will already have had the arguments supplied via the PluginParser's
+        construction of plugin objects.
+        """
+        cls = self.__class__.__name__
+        module = self.__class__.__module__
+
+        namespace = Namespace(**self.arguments)
+        args = CompositeParser(
+            [self.get_cli_parser(), StandardPipelineParser]
+        ).reproduce_cli_args(namespace)
+        return [sys.executable, "-c", f"import {module}\n{module}.{cls}.main()"] + args
+
+    @classmethod
+    def main(cls):
+        """Main function used as a generic entrypoint for GdsStandardApp derived GdsApp plugins"""
+        try:
+            cls.init()
+            try:
+                Plugins.system(
+                    []
+                )  # Disable plugin system unless specified through init
+            # In the case where `init` sets up the plugin system, we want to pass the assertion
+            # triggered by the code above that turns it off in the not-setup case. 
+            except AssertionError:
+                pass
+            parsed_arguments, _ = ParserBase.parse_args(
+                [cls.get_cli_parser(), StandardPipelineParser, PluginArgumentParser],
+                f"{cls.get_name()}: a standard app plugin",
+            )
+            pipeline = StandardPipeline()
+            # Turn off history and filing
+            pipeline.histories.implementation = None
+            pipeline.filing = None
+            pipeline = StandardPipelineParser.pipeline_factory(
+                parsed_arguments, pipeline
+            )
+            application = cls(
+                **cls.get_cli_parser().extract_arguments(parsed_arguments)
+            )
+            application.start(pipeline)
+            sys.exit(0)
+        except Exception as e:
+            print(f"[ERROR] Error launching {cls.__name__}: {e}", file=sys.stderr)
+            raise
+            sys.exit(148)
+
+
+@gds_plugin(GdsApp)
+class CustomDataHandlers(GdsStandardApp):
+    """Run an app that registers all custom data handlers
+
+    A GdsApp plugin, built using the GdsStandardApp helper, that uses the provided standard pipeline to register each
+    custom DataHandler plugin as a consumer of the appropriate type.
+    """
+
+    def __init__(self, **kwargs):
+        """Required __init__ implementation"""
+        super().__init__(**kwargs)
+
+    @classmethod
+    def init(cls):
+        """Set up the system to use only data_handler plugins"""
+        Plugins.system(["data_handler"])
+
+    def start(self, pipeline: StandardPipeline):
+        """Iterates over each data handler, registering to the producing decoder"""
+        DESCRIPTOR_TO_FUNCTION = {
+            "FW_PACKET_TELEM": pipeline.coders.register_channel_consumer,
+            "FW_PACKET_LOG": pipeline.coders.register_event_consumer,
+            "FW_PACKET_FILE": pipeline.coders.register_file_consumer,
+            "FW_PACKET_PACKETIZED_TLM": pipeline.coders.register_packet_consumer,
+        }
+
+        data_handlers = Plugins.system().get_feature_classes("data_handler")
+        for data_handler_class in data_handlers:
+            data_handler = data_handler_class()
+            descriptors = data_handler.get_handled_descriptors()
+            for descriptor in descriptors:
+                DESCRIPTOR_TO_FUNCTION.get(descriptor, lambda discard: discard)(
+                    data_handler
+                )
+
+    @classmethod
+    def get_name(cls):
+        """Return the name of this application"""
+        return "custom-data-handlers-app"