pntos-api 2.1.0.post0.dev0__py3-none-any.whl

pntos/api/plugins/logging.py

@@ -0,0 +1,68 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from .common import CommonPlugin, LoggingLevel
+from .controller import ControllerPlugin
+from .fusion import FusionPlugin
+from .fusion_strategy import FusionStrategyPlugin
+from .inertial import InertialPlugin
+from .initialization import InitializationPlugin
+from .orchestration import OrchestrationPlugin
+from .platform_integration import PlatformIntegrationPlugin
+from .preprocessor import PreprocessorPlugin
+from .registry import RegistryPlugin
+from .state_modeling import StateModelingPlugin
+from .transport import TransportPlugin
+from .ui import UiPlugin
+from .utility import UtilityPlugin
+
+PluginType = (
+    type[ControllerPlugin]
+    | type[FusionPlugin]
+    | type[FusionStrategyPlugin]
+    | type[InertialPlugin]
+    | type[InitializationPlugin]
+    | type['LoggingPlugin']
+    | type[OrchestrationPlugin]
+    | type[PlatformIntegrationPlugin]
+    | type[PreprocessorPlugin]
+    | type[RegistryPlugin]
+    | type[StateModelingPlugin]
+    | type[TransportPlugin]
+    | type[UiPlugin]
+    | type[UtilityPlugin]
+)
+"""
+An union of all the types of plugins.
+
+Can be used by the logging plugin to print which plugin the message originated from.
+"""
+
+
+class LoggingPlugin(CommonPlugin, ABC):
+    """
+    Logging plugin.
+
+    A plugin for logging out data to an arbitrary sink (e.g. console, file,
+    network, etc.).
+    """
+
+    @abstractmethod
+    def log(
+        self,
+        source_plugin_type: PluginType,
+        source_plugin_identifier: str,
+        level: LoggingLevel,
+        message: str,
+    ) -> None:
+        """
+        Log a string to the logging plugin's sink.
+
+        Args:
+            source_plugin_type (PluginType): Information on the plugin that sent the logout.
+            source_plugin_identifier (str): Information on the plugin that sent the logout.
+            level (LoggingLevel): The event severity.
+            message (str): The string contents to be logged.
+        """
+        pass

pntos/api/plugins/orchestration.py

@@ -0,0 +1,253 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from aspn23 import AspnBase, TypeTimestamp
+
+from pntos.api import CommonPlugin, Message
+
+
+class MessageStreamConfig(ABC):
+    """
+    Message stream configuration.
+
+    This class configures the buffering, delay, and sorting characteristics of
+    messages that are streamed into the :class:`pntos.api.OrchestrationPlugin`. The pntOS system
+    will deliver messages to the orchestration plugin as it receives them.
+    However, there is a fundamental tradeoff between latency and those messages
+    being in-order. In particular, to guarantee that messages are sorted by
+    timestamp, it is necessary to build a buffer and delay delivery, such that
+    a sorting function may be applied. This structure allows the plugin to
+    choose which messages are buffered and which are not.
+    """
+
+    @abstractmethod
+    def sequenced_stream_add(
+        self, message_type: type[AspnBase], source_identifier: str | None = None
+    ) -> None:
+        """
+        Request messages are streamed in sorted timestamp ordering.
+
+        Request messages of the given ``message_type`` and optional ``source_identifier`` are
+        streamed in sorted timestamp ordering.
+
+        Args:
+            message_type (type[AspnBase])
+            source_identifier (str | None, optional)
+        """
+        pass
+
+    @abstractmethod
+    def sequenced_stream_remove(
+        self, message_type: type[AspnBase], source_identifier: str | None = None
+    ) -> None:
+        """
+        Request messages are no longer streamed in sorted timestamp ordering.
+
+        Request messages of the given ``message_type`` and optional ``source_identifier`` are no
+        longer streamed in sorted timestamp ordering. This will remove a type that was previously
+        added in a call to :meth:`sequenced_stream_add`, or remove individual messages from the
+        entire list of messages that was added with a previous call to :meth:`sequenced_stream_all`.
+
+        Args:
+            message_type (type[AspnBase])
+            source_identifier (str | None, optional)
+        """
+        pass
+
+    @abstractmethod
+    def sequenced_stream_all(self, enable: bool) -> None:
+        """
+        Request all messages are streamed in sorted timestamp ordering.
+
+        Note that the ability to do this reliably will depend on the length of the buffer used by
+        the :class:`pntos.api.Mediator`.
+
+        Args:
+            enable (bool)
+        """
+        pass
+
+    @abstractmethod
+    def immediate_stream_add(
+        self, message_type: type[AspnBase], source_identifier: str | None = None
+    ) -> None:
+        """
+        Request messages are streamed immediately.
+
+        Request messages of the given ``message_type`` and optional ``source_identifier`` are
+        streamed immediately without delay, buffering, or sorting.
+
+        Args:
+            message_type (type[AspnBase])
+            source_identifier (str | None, optional)
+        """
+        pass
+
+    @abstractmethod
+    def immediate_stream_remove(
+        self, message_type: type[AspnBase], source_identifier: str | None = None
+    ) -> None:
+        """
+        Request messages are no longer streamed immediately.
+
+        Request messages of the given ``message_type`` and optional ``source_identifier`` are no
+        longer streamed immediately. This will remove a type that was previously added in a call to
+        :meth:`immediate_stream_add`, or remove individual messages from the entire list of messages
+        that was added with a previous call to :meth:`immediate_stream_all`.
+
+        Args:
+            message_type (type[AspnBase])
+            source_identifier (str | None, optional)
+        """
+        pass
+
+    @abstractmethod
+    def immediate_stream_all(self, enable: bool) -> None:
+        """
+        Request all messages are streamed immediately without delay, buffering, or sorting.
+
+        Args:
+            enable (bool)
+        """
+        pass
+
+
+class OrchestrationPlugin(CommonPlugin, ABC):
+    """
+    Orchestration plugin.
+
+    The pntOS orchestration plugin is responsible for orchestrating one or more fusion engines,
+    state model providers and other plugins in order to perform sensor fusion. The orchestration
+    plugin is sent (sorted, buffered) ASPN messages from the :class:`pntos.api.ControllerPlugin`, and is
+    responsible for computing a solution for the system, as well as estimating any other quantities
+    of interest.
+
+    In order to achieve this task, the orchestration plugin may be passed a set of other plugins
+    during the call to :meth:`~OrchestrationPlugin.init_orchestration_plugin`. If so, the
+    orchestration plugin then, as the name suggests, configures and orchestrates these plugins to
+    work together to perform sensor fusion.
+
+    Example:
+        For example, the orchestration plugin may set up a fusion engine it received in the call to
+        :meth:`~OrchestrationPlugin.init_orchestration_plugin`, then add state blocks or measurement
+        processors to that fusion engine from a :class:`pntos.api.StateModelingPlugin` it also received, and
+        process inertial data from an :class:`pntos.api.InertialPlugin` it received. The
+        :meth:`~OrchestrationPlugin.request_solutions` function will be called by the system when
+        pntOS needs to know the current filtering solutions. Other quantities which need to be
+        estimated by the orchestration engine can be returned to the system by registry updates.
+    """
+
+    @abstractmethod
+    def init_orchestration_plugin(
+        self, plugins: list[CommonPlugin] | None, stream_config: MessageStreamConfig
+    ) -> None:
+        """
+        Initial data structures needed by the orchestration plugin.
+
+        This function will be called by the system after the :meth:`pntos.api.CommonPlugin.init_plugin` but before
+        any other call to an :class:`pntos.api.OrchestrationPlugin` function.
+
+        Args:
+            plugins (list[CommonPlugin] | None): A set of plugins which should be used by the orchestration
+                plugin. For example, the plugins list may include a :class:`pntos.api.StandardFusionEngine`,
+                which the orchestration plugin can use to perform fusion of sensor data received.
+                The list may also include a :class:`pntos.api.StateModelingPlugin`, which the orchestration
+                plugin can use to extract the algorithms needed for parsing sensor data into the
+                data model a fusion engine needs. If the orchestration plugin does not require any
+                plugins, ``None`` may be passed.
+            stream_config (MessageStreamConfig): A set of configuration options that the
+                orchestration plugin can use to indicate to the :class:`pntos.api.ControllerPlugin` how it
+                would prefer delivery of messages. When the orchestration plugin receives the
+                ``stream_config`` struct, it should call the functions on it to set up how messages
+                will be delivered to it. If it does not, the order of messages' arrival will be
+                unspecified and at the discretion of the :class:`pntos.api.ControllerPlugin`.
+        """
+        pass
+
+    @abstractmethod
+    def process_pntos_message(self, message: Message, sequenced: bool) -> None:
+        """
+        Deliver a new message from an external to pntOS source into the orchestration plugin.
+
+        The plugin should utilize this sensor data contained in message by passing it into a fusion
+        engine.
+
+        Args:
+            message (Message): The :class:`pntos.api.Message` to be delivered to the
+                :class:`pntos.api.OrchestrationPlugin` from the :class:`pntos.api.ControllerPlugin`. From here the
+                :class:`pntos.api.OrchestrationPlugin` may use it directly or route it to other plugins (like
+                the :class:`pntos.api.FusionPlugin`, :class:`pntos.api.InertialPlugin`, or
+                :class:`pntos.api.InitializationPlugin`).
+            sequenced (bool): ``False`` if ``message`` was the last received :class:`pntos.api.Message`
+                or ``True`` if it was delayed by buffering. See :class:`pntos.api.MessageStreamConfig` for
+                more details.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def filter_description_list(self) -> list[str]:
+        """
+        Get a list of strings describing the filters available in this :class:`pntos.api.OrchestrationPlugin`.
+
+        One of these description strings may be used when calling :meth:`request_solutions`. For
+        consistency, these strings should adhere to the following conventions:
+
+        - Strings should be upper case and have words and acronyms separated by underscores
+          (``UPPER_SNAKE_CASE``).
+        - Strings should contain the substring ``BEST`` when they represent the primary solution.
+        - Strings should contain the substring ``DEAD_RECKONING`` when they represent a solution
+          suitable for estimating relative motion or rotation over a period of time. This solution
+          may drift more than ``BEST`` solutions, as the goal is to allow a user to get an estimate
+          of the relative motion between different times. In the calculation of this solution, some
+          sensor measurement might be excluded. For example, a system with an IMU might provide a
+          ``DEAD_RECKONING`` solution which is the solution from its free-running inertial
+          mechanization, with resets disabled during the time intervals between ``solution_times``
+          (but resets applied before all of the ``solution_times``).
+        - This substring should contain the string-equivalent to the corresponding ASPN message
+          class name, converted to UPPER_SNAKE_CASE, followed by the string ``_ESTIMATE``. This
+          allows the user to perform substring matching without a risk of getting a false positive
+          match from a type whose string would be a subset of another type.
+
+        Example:
+            For example, if the primary solution is an ASPN PVA then the string
+            ``MY_BEST_ASPN_MEASUREMENT_POSITION_VELOCITY_ATTITUDE_ESTIMATE`` would fulfill the
+            convention.
+
+        These conventions allow the user to identify their desired type of solution using substring
+        matching.
+
+        Returns:
+            list[str]: A list of strings describing the filters available in this
+            :class:`pntos.api.OrchestrationPlugin`.
+        """
+        pass
+
+    @abstractmethod
+    def request_solutions(
+        self,
+        solution_times: list[TypeTimestamp],
+        filter_description: str | None = None,
+    ) -> list[Message | None] | None:
+        """
+        Request filtering solutions at the times specified in the array ``solution_times``.
+
+        Args:
+            solution_times (list[TypeTimestamp]): The solution times.
+            filter_description (str | None, optional): An :class:`pntos.api.OrchestrationPlugin` may run
+                multiple filters. To select which filter(s) to request solutions from, enter a valid
+                filter description string in ``filter_description``. Valid filter description
+                strings can be obtained by calling :attr:`filter_description_list`. Passing in
+                ``None`` will provide a result specific to a particular :class:`pntos.api.OrchestrationPlugin`
+                implementation. When ``filter_description`` is ``None``, the implementation should
+                endeavor to return its best solution.
+
+        Returns:
+            list[Message | None] | None: An array of messages containing the filter solutions for the requested
+            ``solution_times``. The number of solutions should equal the number of times in
+            ``solution_times``, although some entries may be ``None`` if they are unavailable at the
+            corresponding time in ``solution_times``. The returned :class:`pntos.api.Message` list may be
+            ``None`` if ``filter_description`` is invalid.
+        """
+        pass

pntos/api/plugins/platform_integration.py

@@ -0,0 +1,81 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from pntos.api import CommonPlugin
+
+
+class PlatformIntegrationPlugin(CommonPlugin, ABC):
+    """
+    Platform integration plugin.
+
+    A plugin for command, control, solution output, and other behavior of the
+    system which is specific to a particular platform. Works closely with the
+    :class:`pntos.api.ControllerPlugin` to fully define the overall behavior of the system.
+
+    Caution:
+        **Unstable**: This feature is unstable and is not yet considered part of the stable pntOS
+        API. Usage of this feature is highly discouraged in non-experimental code, and its
+        definition may change at any time.
+    """
+
+    @abstractmethod
+    def take_control(
+        self,
+        plugins: list[CommonPlugin],
+        plugin_resources_locations: list[str | None] | None = None,
+        initial_config: str | None = None,
+    ) -> None:
+        """
+        Takes over secondary control from the :class:`pntos.api.ControllerPlugin`.
+
+        When pntOS first boots, it passes control over to the :class:`pntos.api.ControllerPlugin`. After the
+        :class:`pntos.api.ControllerPlugin` has initialized the plugins it wants to run, it calls this
+        plugin's :meth:`take_control` to allow for platform specific control behavior to run. The
+        :class:`pntos.api.PlatformIntegrationPlugin` (PIP) is not responsible for calling the
+        :meth:`pntos.api.CommonPlugin.init_plugin` call on any of the plugins passed in its plugins list, and
+        thus the list of plugins that is passed to the PIP should be pruned to only those plugins
+        the :class:`pntos.api.ControllerPlugin` initialized. The PIP is consequently not responsible for the
+        :class:`pntos.api.Mediator` construction or message routing - those responsibilities fall on the
+        :class:`pntos.api.ControllerPlugin`. Instead, the PIP is responsible for doing any additional logic
+        that may be platform specific.
+
+        Example:
+            For example, the PIP may decide to output solutions at a particular rate, or to have the
+            :class:`pntos.api.TransportPlugin` passed in its plugins list start/stop listening in response to
+            moding commands, or inform the :class:`pntos.api.OrchestrationPlugin` that it should not use a
+            particular sensor at runtime (via a registry convention).
+
+        In general, the goal of the PIP is to implement the platform-specific needs, whereas the
+        :class:`pntos.api.ControllerPlugin` is designed to be the generic portion of the code. The
+        :class:`pntos.api.ControllerPlugin` should be designed to be generic and re-useable, but work
+        hand-in-hand with the PIP to fully define the control behavior of the system.
+
+        :class:`pntos.api.ControllerPlugin` responsibilities:
+          - Defining concurrency model.
+          - Initializing plugins (and constructing/passing in :class:`pntos.api.Mediator`).
+          - Routing data from transport plugin to orchestration/initialization/inertial plugins.
+          - Routing requests for registry data to registry plugins.
+
+        :class:`pntos.api.PlatformIntegrationPlugin` responsibilities:
+          - Platform specific outputs.
+          - Responding to moding commands from platform.
+          - Routing situational awareness information to other pntOS plugins (via registry
+            convention).
+
+        The parameters to :meth:`pntos.api.PlatformIntegrationPlugin.take_control` should be identical to
+        those passed to the :meth:`pntos.api.ControllerPlugin.take_control`, with the exception of the
+        ``plugins`` list being a subset of the ``plugins`` passed to the :class:`pntos.api.ControllerPlugin`.
+        Which plugins are passed to the PIP is implementation specific and decided by the
+        :class:`pntos.api.ControllerPlugin`.
+
+        Args:
+            plugins (list[CommonPlugin]): A subset of the ``plugins`` passed to the
+                :class:`pntos.api.ControllerPlugin`. Which plugins are passed to the PIP is implementation
+                specific and decided by the :class:`pntos.api.ControllerPlugin`.
+            plugin_resources_locations (list[str  |  None] | None, optional): Should be identical to
+                what was passed to :meth:`pntos.api.ControllerPlugin.take_control`.
+            initial_config (str | None, optional): Should be identical to what was passed to
+                :meth:`pntos.api.ControllerPlugin.take_control`.
+        """
+        pass

pntos/api/plugins/preprocessor.py

@@ -0,0 +1,88 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from pntos.api import CommonPlugin, Message
+
+
+class Preprocessor(ABC):
+    """
+    A preprocessor.
+
+    Caution:
+        **Unstable**: This feature is unstable and is not yet considered part of the stable pntOS
+        API. Usage of this feature is highly discouraged in non-experimental code, and its
+        definition may change at any time.
+    """
+
+    @abstractmethod
+    def process_pntos_message(self, message: Message) -> list[Message] | None:
+        """
+        Process a message.
+
+        Args:
+            message (Message): A message to be processed.
+
+        Returns:
+            list[Message] | None: A list of :class:`pntos.api.Message` s. Usually this will be a single message, a
+            modified version of ``message``. It could be ``None`` if ``message`` is rejected or
+            dropped. The preprocessor could also accumulate several messages, returning ``None`` for
+            each one then returning an array with multiple processed messages.
+        """
+        pass
+
+
+class PreprocessorPlugin(CommonPlugin, ABC):
+    """
+    An implementation of a preprocessor plugin.
+
+    This plugin generates :class:`pntos.api.Preprocessor` instances which may be used to process incoming
+    messages before being distributed to other plugins.
+
+    Caution:
+         **Unstable**: This feature is unstable and is not yet considered part of the stable pntOS
+         API. Usage of this feature is highly discouraged in non-experimental code, and its
+         definition may change at any time.
+
+    Attributes:
+        preprocessor_identifiers (list[str]): A list of identifying strings for each kind of
+            :class:`pntos.api.Preprocessor` that this :class:`pntos.api.PreprocessorPlugin` can create instances of. The
+            ``preprocessor_index`` parameter of :meth:`new_preprocessor` is an index into this
+            array.
+    """
+
+    preprocessor_identifiers: list[str]
+    """Strings describing the preprocessors the provider can create.
+    """
+
+    @abstractmethod
+    def new_preprocessor(
+        self, preprocessor_index: int, config_group: str | None = None
+    ) -> Preprocessor | None:
+        """
+        Get a newly created :class:`pntos.api.Preprocessor`.
+
+        Args:
+            preprocessor_index (int): Since the :class:`pntos.api.PreprocessorPlugin` can create a different
+                preprocessor for each element in ``preprocessor_identifiers``, the
+                ``preprocessor_index`` parameter is used to select which kind of preprocessor to
+                create a new instance of. The :attr:`pntos.api.PreprocessorPlugin.preprocessor_identifiers`
+                field contains identifying strings for the kinds of preprocessors.
+
+        Example:
+                    For example, if the plugin can create 45 different preprocessors, the identifier
+                    of the last preprocessor that can be created is found in
+                    ``preprocessor_identifiers[44]``. An instance of this preprocessor can be
+                    created by calling ``new_preprocessor(44, ...)``. Note that ``0 <=
+                    preprocessor_index < length of preprocessor_identifiers``.
+            config_group (str | None, optional): Indicates which (if any) parameter group in the
+                registry may be used to obtain additional configuration values to generate the new
+                preprocessor. If the preprocessor requires no outside configuration,
+                ``config_group`` may be ``None``.
+
+        Returns:
+            Preprocessor: A newly created :class:`pntos.api.Preprocessor`. Returns ``None`` if
+            ``preprocessor_index`` is greater than or equal to the length of
+            :attr:`pntos.api.PreprocessorPlugin.preprocessor_identifiers` or if ``config_group`` is invalid.
+        """
+        pass

pntos/api/plugins/registry.py

@@ -0,0 +1,46 @@
+"""Python API of pntOS."""
+
+from abc import ABC, abstractmethod
+
+from pntos.api import CommonPlugin, Registry
+
+
+class RegistryPlugin(CommonPlugin, ABC):
+    """
+    Registry plugin.
+
+    A plugin for a global key-value registry. See the `pntOS Registry` page in
+    the `Internals` section for more information on the goal of this plugin.
+    """
+
+    @abstractmethod
+    def new_registry(self, initial_config: str | None = None) -> Registry:
+        """
+        Create a new registry based on the initial values stored in ``initial_config``.
+
+        Args:
+            initial_config (str | None, optional): The initial values the new registry should be
+                based on. The format of ``initial_config`` is implementation
+                specific, and plugins are free to support any or no format. Possible formats may
+                include:
+
+                - ``None``, in which case the plugin is free to choose initial values. Choices may
+                  include hard-coded in the plugin or none at all.
+                - A ``str``.  Examples of possible values the parameter could hold:
+
+                    1. The entire config.
+                    2. A local file path on systems which support them.
+                    3. A string adhering to the URI scheme.
+
+        Returns:
+            Registry: The newly created registry.
+
+        Note:
+            The returned :class:`pntos.api.Registry` should be capable of producing :class:`pntos.api.KeyValueStore`
+            structs that are able to be used concurrently. Thus if the user uses the return value of
+            this method to start two batches, one on group "foo" and the other on group "bar", then
+            concurrent access to both of the resulting :class:`pntos.api.KeyValueStore` structs for "foo" and
+            "bar" should be supported (i.e. no shared mutable state between them that is not
+            synchronized).
+        """
+        pass