fprime-gds 3.4.3__py3-none-any.whl → 3.4.4a1__py3-none-any.whl

fprime_gds/common/communication/adapters/base.py

@@ -9,6 +9,8 @@ adapter for use with the comm-layer.
 @author lestarch
 """
 import abc
+from typing import Type
+from fprime_gds.plugin.definitions import gds_plugin_implementation, gds_plugin_specification
 
 
 class BaseAdapter(abc.ABC):
@@ -47,71 +49,41 @@ class BaseAdapter(abc.ABC):
         """
 
     @classmethod
-    @abc.abstractmethod
-    def get_arguments(cls):
-        """
-        Returns a set of arguments consumed by this adapter. This will be consumed by the CLI layer in order to provide
-        command line arguments to the user. Note: these should be globally unique args, e.g. --ip-address
+    @gds_plugin_specification
+    def register_communication_plugin(cls) -> Type["BaseAdapter"]:
+        """Register a communications adapter
 
-        :return: dictionary, keys of tuple of arg flags and value of list of other arguments to argparse's add_argument
-        """
+        Plugin hook for registering a plugin that supplies an adapter to the communications interface (radio, uart, i2c,
+        etc). This interface is expected to read and write bytes from a wire and will be provided to the framing system.
 
-    @classmethod
-    @abc.abstractmethod
-    def check_arguments(cls, args):
-        """
-        Code that should check arguments of this adapter. If there is a problem with this code, then a "ValueError"
-        should be raised describing the problem with these arguments.
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
 
-        :param args: arguments as dictionary
+        Returns:
+            BaseAdapter subclass
         """
+        raise NotImplementedError()
+
+
+class NoneAdapter(BaseAdapter):
+    """ None adapter used to turn off the comm script """
 
     @classmethod
-    def get_adapters(cls):
-        """
-        Get all known adapters of this base class. These must be imported into the comm-layer to be available to the
-        system, however; they only need to be imported. Once imported this function will find them and make them
-        available to the comm-layer in the standard way.
+    def get_name(cls):
+        """ Get name of the non-adapter """
+        return "none"
 
-        :return: list of all imported comm adapters.
-        """
-        adapter_map = {}
-        for adapter in cls.__subclasses__():
-            # Get two versions of names
-            adapter_name = adapter.__module__
-            adapter_short = adapter_name.split(".")[-1]
-            # Check to use long or short name
-            if adapter_short not in adapter_map:
-                adapter_name = adapter_short
-            adapter_map[adapter_name] = adapter
-        return adapter_map
-
-    @staticmethod
-    def process_arguments(clazz, args):
-        """
-        Process arguments incoming from the command line and construct a dictionary of kwargs to supply to the chosen
-        adapter at creation time. This will allow the user to choose any imported adapters at runtime.
+    def read(self, timeout=0.500):
+        """ Raise exception if this is called"""
+        raise NotImplementedError()
 
-        :param args: arguments to process
-        :return: dictionary of constructor keyword arguments
-        """
-        return {
-            value["dest"]: getattr(args, value["dest"])
-            for value in clazz.get_arguments().values()
-        }
+    def write(self, frame):
+        """ Raise exception if this is called"""
+        raise NotImplementedError()
 
     @classmethod
-    def construct_adapter(cls, adapter_name, args):
-        """
-        Constructs a new adapter, from the given adapter name and the given namespace of argument inputs. This is a
-        wrapper of "get_adapters" and "process_arguments" to help build a new, fully configured, adapter. This is a
-        factory method.
-
-        :param adapter_name: name of the adapter to build
-        :param args: namespace of arg value to help build an adapter
-        :return: newly constructed adapter
-        """
-        if adapter_name == "none":
-            return None
-        adapter = cls.get_adapters()[adapter_name]
-        return adapter(**cls.process_arguments(adapter, args))
+    @gds_plugin_implementation
+    def register_communication_plugin(cls):
+        """ Register this as a plugin """
+        return cls

fprime_gds/common/communication/adapters/ip.py

@@ -18,6 +18,8 @@ import time
 import fprime_gds.common.communication.adapters.base
 import fprime_gds.common.logger
 
+from fprime_gds.plugin.definitions import gds_plugin_implementation
+
 LOGGER = logging.getLogger("ip_adapter")
 
 
@@ -114,7 +116,7 @@ class IpAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
 
     def write(self, frame):
         """
-        Send a given framed bit of data by sending it out the serial interface. It will attempt to reconnect if there is
+        Send a given framed bit of data by sending it out the serial interface. It will attempt to reconnect if there
         was a problem previously. This function will return true on success, or false on error.
 
         :param frame: framed data packet to send out
@@ -151,6 +153,11 @@ class IpAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
             self.write(IpAdapter.KEEPALIVE_DATA)
             time.sleep(interval)
 
+    @classmethod
+    def get_name(cls):
+        """ Get the name of this adapter  """
+        return "ip"
+
     @classmethod
     def get_arguments(cls):
         """
@@ -163,13 +170,13 @@ class IpAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
                 "dest": "address",
                 "type": str,
                 "default": "0.0.0.0",
-                "help": "Address of the IP adapter server. Default: %(default)s",
+                "help": "Address of the IP adapter server.",
             },
             ("--ip-port",): {
                 "dest": "port",
                 "type": int,
                 "default": 50000,
-                "help": "Port of the IP adapter server. Default: %(default)s",
+                "help": "Port of the IP adapter server.",
             },
             ("--ip-client",): {
                 # dest is "server" since it is handled in BaseAdapter.construct_adapter and passed with the same
@@ -182,14 +189,25 @@ class IpAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
         }
 
     @classmethod
-    def check_arguments(cls, args):
+    @gds_plugin_implementation
+    def register_communication_plugin(cls):
+        """ Register this as a communication plugin """
+        return cls
+
+    @classmethod
+    def check_arguments(cls, address, port, server=True):
         """
         Code that should check arguments of this adapter. If there is a problem with this code, then a "ValueError"
         should be raised describing the problem with these arguments.
 
         :param args: arguments as dictionary
         """
-        check_port(args["address"], args["port"])
+        try:
+            if server:
+                check_port(address, port)
+        except OSError as os_error:
+            raise ValueError(f"{os_error}")
+
 
 
 class IpHandler(abc.ABC):

fprime_gds/common/communication/adapters/uart.py

@@ -15,6 +15,8 @@ from serial.tools import list_ports
 
 import fprime_gds.common.communication.adapters.base
 
+from fprime_gds.plugin.definitions import gds_plugin_implementation
+
 LOGGER = logging.getLogger("serial_adapter")
 
 
@@ -151,18 +153,29 @@ class SerialAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
                 "dest": "device",
                 "type": str,
                 "default": default,
-                "help": "UART device representing the FSW. Default: %(default)s",
+                "help": "UART device representing the FSW.",
             },
             ("--uart-baud",): {
                 "dest": "baud",
                 "type": int,
                 "default": 9600,
-                "help": "Baud rate of the serial device. Default: %(default)s",
+                "help": "Baud rate of the serial device.",
             },
         }
 
     @classmethod
-    def check_arguments(cls, args):
+    def get_name(cls):
+        """ Get name of the adapter """
+        return "uart"
+
+    @classmethod
+    @gds_plugin_implementation
+    def register_communication_plugin(cls):
+        """ Register this as a communication plugin """
+        return cls
+
+    @classmethod
+    def check_arguments(cls, device, baud):
         """
         Code that should check arguments of this adapter. If there is a problem with this code, then a "ValueError"
         should be raised describing the problem with these arguments.
@@ -170,16 +183,16 @@ class SerialAdapter(fprime_gds.common.communication.adapters.base.BaseAdapter):
         :param args: arguments as dictionary
         """
         ports = map(lambda info: info.device, list_ports.comports(include_links=True))
-        if args["device"] not in ports:
-            msg = f"Serial port '{args['device']}' not valid. Available ports: {ports}"
+        if device not in ports:
+            msg = f"Serial port '{device}' not valid. Available ports: {ports}"
             raise ValueError(
                 msg
             )
         # Note: baud rate may not *always* work. These are a superset
         try:
-            baud = int(args["baud"])
+            baud = int(baud)
         except ValueError:
-            msg = f"Serial baud rate '{args['baud']}' not integer. Use one of: {SerialAdapter.BAUDS}"
+            msg = f"Serial baud rate '{baud}' not integer. Use one of: {SerialAdapter.BAUDS}"
             raise ValueError(
                 msg
             )

fprime_gds/common/communication/checksum.py

@@ -11,7 +11,6 @@ def crc_calculation(data: bytes):
     return zlib.crc32(data) & 0xFFFFFFFF
 
 
-CHECKSUM_SELECTION = "crc32"
 CHECKSUM_MAPPING = {
     "fixed": lambda data: 0xCAFECAFE,
     "crc32": crc_calculation,
@@ -19,8 +18,7 @@ CHECKSUM_MAPPING = {
 }
 
 
-def calculate_checksum(data: bytes):
+def calculate_checksum(data: bytes, selected_checksum: str):
     """Calculates the checksum of bytes"""
-    selected_checksum = CHECKSUM_SELECTION
     hash_fn = CHECKSUM_MAPPING.get(selected_checksum, CHECKSUM_MAPPING.get("default"))
     return hash_fn(data)

fprime_gds/common/communication/framing.py

@@ -15,8 +15,10 @@ import abc
 import copy
 import struct
 import sys
+from typing import Type
 
-from .checksum import calculate_checksum
+from .checksum import calculate_checksum, CHECKSUM_MAPPING
+from fprime_gds.plugin.definitions import gds_plugin_implementation, gds_plugin_specification
 
 
 class FramerDeframer(abc.ABC):
@@ -70,6 +72,24 @@ class FramerDeframer(abc.ABC):
                 return packets, data, discarded_aggregate
             packets.append(packet)
 
+    @classmethod
+    @gds_plugin_specification
+    def register_framing_plugin(cls) -> Type["FramerDeframer"]:
+        """Register a plugin to provide framing capabilities
+
+        Plugin hook for registering a plugin that supplies a FramerDeframer implementation. Implementors of this hook must
+        return a non-abstract subclass of FramerDeframer. This class will be provided as a framing implementation option
+        that users may select via command line arguments.
+
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
+
+        Returns:
+            FramerDeframer subclass
+        """
+        raise NotImplementedError()
+
 
 class FpFramerDeframer(FramerDeframer):
     """
@@ -97,10 +117,11 @@ class FpFramerDeframer(FramerDeframer):
     HEADER_FORMAT = None
     START_TOKEN = None
 
-    def __init__(self):
+    def __init__(self, checksum_type):
         """Sets constants on construction."""
         # Setup the constants as soon as possible.
         FpFramerDeframer.set_constants()
+        self.checksum = checksum_type
 
     @classmethod
     def set_constants(cls):
@@ -134,7 +155,7 @@ class FpFramerDeframer(FramerDeframer):
             FpFramerDeframer.HEADER_FORMAT, FpFramerDeframer.START_TOKEN, len(data)
         )
         framed += data
-        framed += struct.pack(">I", calculate_checksum(framed))
+        framed += struct.pack(">I", calculate_checksum(framed, self.checksum))
         return framed
 
     def deframe(self, data, no_copy=False):
@@ -176,7 +197,8 @@ class FpFramerDeframer(FramerDeframer):
                 )
                 # If the checksum is valid, return the packet. Otherwise continue to rotate
                 if check == calculate_checksum(
-                    data[: data_size + FpFramerDeframer.HEADER_SIZE]
+                    data[: data_size + FpFramerDeframer.HEADER_SIZE],
+                    self.checksum
                 ):
                     data = data[total_size:]
                     return deframed, data, discarded
@@ -192,6 +214,33 @@ class FpFramerDeframer(FramerDeframer):
             return None, data, discarded
         return None, data, discarded
 
+    @classmethod
+    def get_name(cls):
+        """ Get the name of this plugin """
+        return "fprime"
+
+    @classmethod
+    def get_arguments(cls):
+        """ Get arguments for the framer/deframer """
+        return {("--comm-checksum-type",): {
+            "dest": "checksum_type",
+            "action": "store",
+            "type": str,
+            "help": "Setup the checksum algorithm. [default: %(default)s]",
+            "choices": [
+                item
+                for item in CHECKSUM_MAPPING.keys()
+                if item != "default"
+            ],
+            "default": "crc32",
+        }}
+
+    @classmethod
+    @gds_plugin_implementation
+    def register_framing_plugin(cls):
+        """ Register a bad plugin """
+        return cls
+
 
 class TcpServerFramerDeframer(FramerDeframer):
     """

fprime_gds/common/zmq_transport.py

@@ -9,6 +9,7 @@ replace the ThreadedTcpServer for several reasons as described below.
 
 @author lestarch
 """
+
 import logging
 import struct
 from typing import Tuple
@@ -24,6 +25,7 @@ from fprime_gds.common.transport import (
 
 LOGGER = logging.getLogger("transport")
 
+
 class ZmqWrapper(object):
     """Handler for ZMQ functions for use in other objects"""
 
@@ -50,7 +52,9 @@ class ZmqWrapper(object):
             sub_topic: subscription topic used to filter incoming messages
             pub_topic: publication topic supplied for remote subscription filters
         """
-        assert len(transport_url) == 2, f"Must supply a pair of URLs for ZeroMQ not '{transport_url}'"
+        assert (
+            len(transport_url) == 2
+        ), f"Must supply a pair of URLs for ZeroMQ not '{transport_url}'"
         self.pub_topic = pub_topic
         self.sub_topic = sub_topic
         self.transport_url = transport_url
@@ -78,8 +82,12 @@ class ZmqWrapper(object):
         The connection is made using self.transport_url, and as such, this must be configured before running. This is
         intended to be called on the sending thread.
         """
-        assert self.transport_url is not None and len(self.transport_url) == 2, "Must configure before connecting"
-        assert self.zmq_socket_outgoing is None, "Cannot connect outgoing multiple times"
+        assert (
+            self.transport_url is not None and len(self.transport_url) == 2
+        ), "Must configure before connecting"
+        assert (
+            self.zmq_socket_outgoing is None
+        ), "Cannot connect outgoing multiple times"
         assert self.pub_topic is not None, "Must configure sockets before connecting"
         self.zmq_socket_outgoing = self.context.socket(zmq.PUB)
         self.zmq_socket_outgoing.setsockopt(zmq.SNDHWM, 0)
@@ -93,7 +101,7 @@ class ZmqWrapper(object):
             self.zmq_socket_outgoing.connect(self.transport_url[0])
 
     def connect_incoming(self):
-        """ Sets up a ZeroMQ connection for incoming data
+        """Sets up a ZeroMQ connection for incoming data
 
         ZeroMQ allows multiple connections to a single endpoint. This only affects incoming connections as sockets must
         be created on their owning threads. This will connect the ZeroMQ topology and if self.server is set, will bind
@@ -102,8 +110,12 @@ class ZmqWrapper(object):
         The connection is made using self.transport_url, and as such, this must be configured before running. This is
         intended to be called on the receiving thread.
         """
-        assert self.transport_url is not None and len(self.transport_url) == 2, "Must configure before connecting"
-        assert self.zmq_socket_incoming is None, "Cannot connect incoming multiple times"
+        assert (
+            self.transport_url is not None and len(self.transport_url) == 2
+        ), "Must configure before connecting"
+        assert (
+            self.zmq_socket_incoming is None
+        ), "Cannot connect incoming multiple times"
         assert self.sub_topic is not None, "Must configure sockets before connecting"
         self.zmq_socket_incoming = self.context.socket(zmq.SUB)
         self.zmq_socket_incoming.setsockopt(zmq.RCVHWM, 0)
@@ -125,7 +137,7 @@ class ZmqWrapper(object):
         self.zmq_socket_incoming.close()
 
     def terminate(self):
-        """ Terminate the ZeroMQ context"""
+        """Terminate the ZeroMQ context"""
         self.context.term()
 
     def recv(self, timeout=None):
@@ -162,11 +174,14 @@ class ZmqClient(ThreadedTransportClient):
         self.zmq = ZmqWrapper()
 
     def connect(
-        self, transport_url: Tuple[str], sub_routing: RoutingTag, pub_routing: RoutingTag
+        self,
+        transport_url: Tuple[str],
+        sub_routing: RoutingTag,
+        pub_routing: RoutingTag,
     ):
         """Connects to the ZeroMQ network"""
         self.zmq.configure(transport_url, sub_routing.value, pub_routing.value)
-        self.zmq.connect_outgoing() # Outgoing socket, for clients, exists on the current thread
+        self.zmq.connect_outgoing()  # Outgoing socket, for clients, exists on the current thread
         super().connect(transport_url, sub_routing, pub_routing)
 
     def disconnect(self):
@@ -176,16 +191,18 @@ class ZmqClient(ThreadedTransportClient):
 
     def send(self, data):
         """Send data via ZeroMQ"""
-        if data[:4] == b'ZZZZ':
+        if data[:4] == b"ZZZZ":
             data = data[4:]
-        self.zmq.send(data)  # Must strip out ZZZZ as that is a ThreadedTcpServer only property
+        self.zmq.send(
+            data
+        )  # Must strip out ZZZZ as that is a ThreadedTcpServer only property
 
     def recv(self, timeout=None):
         """Receives data from ZeroMQ"""
         return self.zmq.recv(timeout)
 
     def recv_thread(self):
-        """ Overrides the recv_thread method
+        """Overrides the recv_thread method
 
         Overrides the recv_thread method of the superclass such that the ZeroMQ socket may be created/destroyed
         before/after the main recv loop.
@@ -203,11 +220,11 @@ class ZmqGround(GroundHandler):
     to the display and processing layer(s). This effectively acts as the "FSW" side of that interface as it
     frames/deframes packets heading to that layer.
 
-    Since there is likely only one communications client to the FSW users should call make_server() after construction
+    Since there is likely only one communications client to the FSW users should instantiate with server=True
     to ensure that it binds to resources for the network. This is not forced in case of multiple FSW connections.
     """
 
-    def __init__(self, transport_url):
+    def __init__(self, transport_url, server=True):
         """Initialize this interface with the transport_url needed to connect
 
         Args:
@@ -217,6 +234,8 @@ class ZmqGround(GroundHandler):
         self.zmq = ZmqWrapper()
         self.transport_url = transport_url
         self.timeout = 10
+        if server:
+            self.zmq.make_server()
 
     def open(self):
         """Open this ground interface. Delegates to the connect method
@@ -242,10 +261,6 @@ class ZmqGround(GroundHandler):
         self.zmq.disconnect_outgoing()
         self.zmq.terminate()
 
-    def make_server(self):
-        """Makes it into a server"""
-        self.zmq.make_server()
-
     def receive_all(self):
         """Receive all available packets
 

fprime_gds/executables/apps.py

@@ -0,0 +1,150 @@
+""" 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,
+however; this comes with complexity of setting up a new thread/process/isolation to ensure that the plugin does not
+threaten the fprime-gds core functionality and processes.
+
+The second method is to inherit from `GdsApp` implementing the `get_process_invocation` function to return the necessary
+command line that will be spun into its own process.
+
+@author lestarch
+"""
+import subprocess
+from abc import ABC, abstractmethod
+from typing import List, Type
+
+from fprime_gds.plugin.definitions import gds_plugin_specification
+
+
+class GdsBaseFunction(ABC):
+    """ 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.
+
+    Developers who intend to run in an isolated subprocess are strongly encouraged to use `GdsApp` (see below).
+    Developers who need flexibility may use GdsFunction.
+    """
+
+    @abstractmethod
+    def run(self):
+        """ Run the start-up function
+
+        Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
+
+        """
+        raise NotImplementedError()
+
+
+class GdsFunction(GdsBaseFunction, ABC):
+    """ 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
+    instability in that case of poorly designed functions.
+
+    Developers who intend to run in an isolated subprocess are strongly encouraged to use `GdsApp` (see below).
+
+    Plugin developers are required to implement a single function `run`, which must take care of setting up and running
+    the start-up function. Developers **must** handle the isolation of this functionality including spinning off a new
+    thread, subprocess, etc. Additionally, the developer must define the `register_gds_function_plugin` class method
+    annotated with the @gds_plugin_implementation annotation.
+
+    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.
+    """
+
+    @classmethod
+    @gds_plugin_specification
+    def register_gds_function_plugin(cls) -> Type["GdsFunction"]:
+        """Register gds start-up functionality
+
+        Plugin hook for registering a plugin that supplies start-up functionality. This functionality will run on start-up
+        of the GDS network.
+
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
+
+        Returns:
+            GDSFunction subclass
+        """
+        raise NotImplementedError()
+
+
+class GdsApp(GdsBaseFunction):
+    """ 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.
+
+    Plugin developers are required to implement the `get_process_invocation` function that returns a list of arguments
+    needed to invoke the process via python's `subprocess`. Additionally, the developer must define the
+    `register_gds_function_plugin` class method annotated with the @gds_plugin_implementation annotation.
+
+    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
+
+        Command line arguments are passed in to match those returned from the `get_arguments` functions.
+
+        Args:
+            arguments: arguments from the command line
+        """
+        self.process = None
+        self.arguments = arguments
+
+    def run(self):
+        """ 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.
+        """
+        invocation_arguments = self.get_process_invocation()
+        self.process = subprocess.Popen(invocation_arguments)
+
+    def wait(self, timeout=None):
+        """ 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
+        allowed for the killed process to exit.
+
+        Return:
+            return code of the underlying process
+        """
+        try:
+            _, _ = self.process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            self.process.kill()
+            _, _ = self.process.wait(timeout=timeout)
+        return self.process.returncode
+
+    @abstractmethod
+    def get_process_invocation(self) -> List[str]:
+        """ Run the start-up function
+
+        Run the start-up function unconstrained by the limitations of running in a dedicated subprocess.
+
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    @gds_plugin_specification
+    def register_gds_app_plugin(cls) -> Type["GdsApp"]:
+        """Register a gds start-up application
+
+        Plugin hook for registering a plugin that supplies start-up functionality. This functionality will run on start-up
+        of the GDS network isolated into a dedicated process.
+
+        Note: users should return the class, not an instance of the class. Needed arguments for instantiation are
+        determined from class methods, solicited via the command line, and provided at construction time to the chosen
+        instantiation.
+
+        Returns:
+            GdsApp subclass
+        """
+        raise NotImplementedError()