isar 1.20.2__py3-none-any.whl → 1.34.9__py3-none-any.whl

robot_interface/robot_interface.py

@@ -1,13 +1,13 @@
 from abc import ABCMeta, abstractmethod
 from queue import Queue
 from threading import Thread
-from typing import List, Sequence
+from typing import Callable, List, Optional
 
-from robot_interface.models.initialize import InitializeParams
 from robot_interface.models.inspection.inspection import Inspection
 from robot_interface.models.mission.mission import Mission
-from robot_interface.models.mission.status import MissionStatus, RobotStatus, StepStatus
-from robot_interface.models.mission.step import InspectionStep, Step
+from robot_interface.models.mission.status import MissionStatus, RobotStatus, TaskStatus
+from robot_interface.models.mission.task import InspectionTask
+from robot_interface.models.robots.media import MediaConfig
 
 
 class RobotInterface(metaclass=ABCMeta):
@@ -17,10 +17,6 @@ class RobotInterface(metaclass=ABCMeta):
     def initiate_mission(self, mission: Mission) -> None:
         """Send a mission to the robot and initiate execution of the mission
 
-        This function should be used in combination with the mission_status function
-        if the robot is designed to run full missions and not in a stepwise
-        configuration.
-
         Parameters
         ----------
         mission: Mission
@@ -31,55 +27,66 @@ class RobotInterface(metaclass=ABCMeta):
 
         Raises
         ------
+        RobotAlreadyHomeException
+            If the mission is a return home mission and the robot wish to disregard the
+            mission as it is already at home
         RobotInfeasibleMissionException
             If the mission input is infeasible and the mission fails to be scheduled in
             a way that means attempting to schedule again is not necessary
         RobotException
             Will catch all RobotExceptions not previously listed and retry scheduling of
             the mission until the number of allowed retries is exceeded
-        NotImplementedError
-            If the robot is designed for stepwise mission execution
 
         """
         raise NotImplementedError
 
-    def mission_status(self) -> MissionStatus:
-        """Gets the status of the currently active mission on the robot
+    @abstractmethod
+    def task_status(self, task_id: str) -> TaskStatus:
+        """Gets the status of the currently active task on robot.
+
+        Returns
+        -------
+        TaskStatus
+            Status of the execution of current task.
+
+        Raises
+        ------
+        RobotCommunicationTimeoutException or RobotCommunicationException
+            If the robot package is unable to communicate with the robot API the fetching
+            of task status will be attempted again until a certain number of retries
+        RobotTaskStatusException
+            If there was an error when retrieving the task status
+        RobotException
+            If the task status could not be retrieved.
+
+        """
+        raise NotImplementedError
 
-        This function should be used in combination with the initiate_mission function
-        if the robot is designed to run full missions and not in a stepwise
-        configuration.
+    @abstractmethod
+    def mission_status(self, mission_id: str) -> MissionStatus:
+        """Gets the status of the mission with ID mission_id on robot.
 
         Returns
         -------
         MissionStatus
-            Status of the executing mission on the robot.
+            Status of the execution of mission.
 
         Raises
         ------
+        RobotCommunicationTimeoutException or RobotCommunicationException
+            If the robot package is unable to communicate with the robot API the fetching
+            of mission status will be attempted again until a certain number of retries
         RobotMissionStatusException
-            If the mission status could not be collected this will lead to the mission
-            being marked as failed
+            If there was an error when retrieving the mission status
         RobotException
-            An uncaught RobotException in the robot package while retrieving the status
-            will cause the mission to be marked as failed
-        NotImplementedError
-            If the robot is designed for stepwise mission execution
+            If the mission status could not be retrieved.
 
         """
+        raise NotImplementedError
 
     @abstractmethod
-    def initiate_step(self, step: Step) -> None:
-        """Send a step to the robot and initiate the execution of the step
-
-        This function should be used in combination with the step_status function
-        if the robot is designed to run stepwise missions and not in a full mission
-        configuration.
-
-        Parameters
-        ----------
-        step : Step
-            The step that should be initiated on the robot.
+    def stop(self) -> None:
+        """Stops the execution of the current task and corresponding mission.
 
         Returns
         -------
@@ -87,45 +94,37 @@ class RobotInterface(metaclass=ABCMeta):
 
         Raises
         ------
-        RobotInfeasibleStepException
-            If the step input is infeasible and the step fails to be scheduled in
-            a way that means attempting to schedule again is not necessary
+        RobotActionException
+            If the robot fails to perform the requested action to stop mission execution
+            the action to stop will be attempted again until a certain number of retries
         RobotException
-            Will catch all RobotExceptions not previously listed and retry scheduling
-            of the step until the number of allowed retries is exceeded before the step
-            will be marked as failed and the mission cancelled
-        NotImplementedError
-            If the robot is designed for full mission execution.
+            Will catch other RobotExceptions and retry to stop the mission
 
         """
         raise NotImplementedError
 
     @abstractmethod
-    def step_status(self) -> StepStatus:
-        """Gets the status of the currently active step on robot.
-
-        This function should be used in combination with the initiate_step function
-        if the robot is designed to run stepwise missions and not in a full mission
-        configuration.
+    def pause(self) -> None:
+        """Pauses the execution of the current task and stops the movement of the robot.
 
         Returns
         -------
-        StepStatus
-            Status of the execution of current step.
+        None
 
         Raises
         ------
+        RobotActionException
+            If the robot fails to perform the requested action to pause mission execution
+            the action to pause will be attempted again until a certain number of retries
         RobotException
-            If the step status could not be retrieved.
-        NotImplementedError
-            If the robot is designed for full mission execution.
+            Will catch other RobotExceptions and retry to pause the mission
 
         """
         raise NotImplementedError
 
     @abstractmethod
-    def stop(self) -> None:
-        """Stops the execution of the current step and stops the movement of the robot.
+    def resume(self) -> None:
+        """Resumes the execution of the current task and continues the rest of the mission.
 
         Returns
         -------
@@ -134,32 +133,34 @@ class RobotInterface(metaclass=ABCMeta):
         Raises
         ------
         RobotActionException
-            If the robot fails to perform the requested action to stop mission execution
-            the action to stop will be attempted again until a certain number of retries
+            If the robot fails to perform the requested action to resume mission execution
+            the action to resume will be attempted again until a certain number of retries
         RobotException
-            Will catch other RobotExceptions and retry to stop the mission
+            Will catch other RobotExceptions and retry to resume the mission
 
         """
         raise NotImplementedError
 
     @abstractmethod
-    def get_inspections(self, step: InspectionStep) -> Sequence[Inspection]:
-        """Return the inspections connected to the given step.
+    def get_inspection(self, task: InspectionTask) -> Inspection:
+        """Return the inspection connected to the given task.
 
         Parameters
         ----------
-        step : Step
+        task : InspectionTask
 
         Returns
         -------
-        Sequence[InspectionResult]
-            List containing all the inspection results connected to the given step
+        Inspection
+            The inspection connected to the given task.
+            get_inspection has responsibility to assign the inspection_id of the task
+            to the inspection that it returns.
 
         Raises
         ------
         RobotRetrieveInspectionException
             If the robot package is unable to retrieve the inspections for the relevant
-            mission or step an error message is logged and the state machine continues
+            mission or task an error message is logged and the state machine continues
         RobotException
             Catches other RobotExceptions that lead to the same result as a
             RobotRetrieveInspectionException
@@ -168,27 +169,33 @@ class RobotInterface(metaclass=ABCMeta):
         raise NotImplementedError
 
     @abstractmethod
-    def initialize(self, params: InitializeParams) -> None:
-        """Initializes the robot. The initialization needed is robot dependent and the
-        function can be a simple return statement if no initialization is needed for the
-        robot.
+    def register_inspection_callback(
+        self, callback_function: Callable[[Inspection, Mission], None]
+    ) -> None:
+        """Register a function which should be run when inspection data is received
+        asynchronously. This function should expect to receive an Inspection from.
 
         Parameters
         ----------
-        params: InitializeParams
+        callback_function : Callable[[Inspection, Mission], None]
 
         Returns
         -------
         None
 
-        Raises
-        ------
-        RobotInitializeException
-            If the robot package is unable to initialize the robot correctly the mission
-            will be cancelled
-        RobotException
-            Catches other RobotExceptions that might have occurred during initialization
-            where the result is that the mission is cancelled
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def generate_media_config(self) -> Optional[MediaConfig]:
+        """
+        Generate a JSON containing the url and token needed to establish a media stream
+        connection to a robot.
+
+        Returns
+        -------
+        MediaConfig
+            An object containing the connection information for a media stream connection
 
         """
         raise NotImplementedError
@@ -212,16 +219,14 @@ class RobotInterface(metaclass=ABCMeta):
         -------
         List[Thread]
             List containing all threads that will be started to publish telemetry.
+
         """
         raise NotImplementedError
 
     @abstractmethod
     def robot_status(self) -> RobotStatus:
         """
-        Method which returns an enum indicating if the robot package is able to reach
-        the interface which is used to communicate with the robot. This is further used
-        by ISAR to indicate whether the ISAR instance is fully functional and may be
-        used by other systems.
+        Method which returns an enum indicating the status of the robot.
 
         Returns
         -------
@@ -231,13 +236,43 @@ class RobotInterface(metaclass=ABCMeta):
         Raises
         -------
         RobotCommunicationException
-            Raised if the robot package is unable to communicate with the robot API
+            Raised if the robot package is unable to communicate with the robot API.
+            The fetching of robot status will be attempted again until success
+        RobotAPIException
+            Raised if the robot package is able to communicate with the API but an error
+            occurred while interpreting the response. The fetching of robot status will
+            be attempted again until success
+        RobotException
+            Catches other RobotExceptions that may have occurred while retrieving the
+            robot status. The fetching of robot status will be attempted again until
+            success
+
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_battery_level(self) -> float:
+        """
+        Method which returns the percent charge remaining in the robot battery.
+
+        Returns
+        -------
+        float
+            The battery percentage on the robot
+
+        Raises
+        -------
+        RobotCommunicationException
+            Raised if the robot package is unable to communicate with the robot API.
+            The fetching of robot battery level will be attempted again until success
         RobotAPIException
             Raised if the robot package is able to communicate with the API but an error
-            occurred while interpreting the response
+            occurred while interpreting the response. The fetching of robot battery level
+            will be attempted again until success
         RobotException
             Catches other RobotExceptions that may have occurred while retrieving the
-            robot status
-            At this point ISAR will attempt to request the robot status again
+            robot battery level. The fetching of robot battery level will
+            be attempted again until success
+
         """
         raise NotImplementedError

robot_interface/telemetry/mqtt_client.py

@@ -1,19 +1,38 @@
 import json
 import time
 from abc import ABCMeta, abstractmethod
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from queue import Queue
 from typing import Callable, Tuple
 
-from robot_interface.models.exceptions.robot_exceptions import RobotTelemetryException
+from paho.mqtt.packettypes import PacketTypes
+from paho.mqtt.properties import Properties
+
+from isar.config.settings import settings
+from robot_interface.models.exceptions.robot_exceptions import (
+    RobotTelemetryException,
+    RobotTelemetryNoUpdateException,
+    RobotTelemetryPoseException,
+)
 from robot_interface.telemetry.payloads import CloudHealthPayload
 from robot_interface.utilities.json_service import EnhancedJSONEncoder
 
 
+def props_expiry(seconds: int) -> Properties:
+    p = Properties(PacketTypes.PUBLISH)
+    p.MessageExpiryInterval = seconds
+    return p
+
+
 class MqttClientInterface(metaclass=ABCMeta):
     @abstractmethod
     def publish(
-        self, topic: str, payload: str, qos: int = 0, retain: bool = False
+        self,
+        topic: str,
+        payload: str,
+        qos: int = 0,
+        retain: bool = False,
+        properties: Properties = None,
     ) -> None:
         """
         Parameters
@@ -29,7 +48,6 @@ class MqttClientInterface(metaclass=ABCMeta):
 
         Returns
         -------
-
         """
         pass
 
@@ -39,9 +57,20 @@ class MqttPublisher(MqttClientInterface):
         self.mqtt_queue: Queue = mqtt_queue
 
     def publish(
-        self, topic: str, payload: str, qos: int = 0, retain: bool = False
+        self,
+        topic: str,
+        payload: str,
+        qos: int = 0,
+        retain: bool = False,
+        properties: Properties = None,
     ) -> None:
-        queue_message: Tuple[str, str, int, bool] = (topic, payload, qos, retain)
+        queue_message: Tuple[str, str, int, bool, Properties] = (
+            topic,
+            payload,
+            qos,
+            retain,
+            properties,
+        )
         self.mqtt_queue.put(queue_message)
 
 
@@ -54,6 +83,7 @@ class MqttTelemetryPublisher(MqttClientInterface):
         interval: float,
         qos: int = 0,
         retain: bool = False,
+        properties: Properties = None,
     ) -> None:
         self.mqtt_queue: Queue = mqtt_queue
         self.telemetry_method: Callable = telemetry_method
@@ -61,9 +91,13 @@ class MqttTelemetryPublisher(MqttClientInterface):
         self.interval: float = interval
         self.qos: int = qos
         self.retain: bool = retain
+        self.properties: Properties = properties
 
     def run(self, isar_id: str, robot_name: str) -> None:
-        self.cloud_healt_topic: str = f"isar/{isar_id}/cloud_health"
+        self.cloud_health_topic: str = f"isar/{isar_id}/cloud_health"
+        self.battery_topic: str = f"isar/{isar_id}/battery"
+        self.pose_topic: str = f"isar/{isar_id}/pose"
+        self.pressure_topic: str = f"isar/{isar_id}/pressure"
         topic: str
         payload: str
 
@@ -71,19 +105,47 @@ class MqttTelemetryPublisher(MqttClientInterface):
             try:
                 payload = self.telemetry_method(isar_id=isar_id, robot_name=robot_name)
                 topic = self.topic
+            except (RobotTelemetryPoseException, RobotTelemetryNoUpdateException):
+                time.sleep(self.interval)
+                continue
             except RobotTelemetryException:
                 payload = json.dumps(
-                    CloudHealthPayload(isar_id, robot_name, datetime.now(UTC)),
+                    CloudHealthPayload(isar_id, robot_name, datetime.now(timezone.utc)),
                     cls=EnhancedJSONEncoder,
                 )
-                topic = self.cloud_healt_topic
+                topic = self.cloud_health_topic
+
+            publish_properties = self.properties
 
-            self.publish(topic=topic, payload=payload, qos=self.qos, retain=self.retain)
+            if topic in (
+                self.battery_topic,
+                self.pose_topic,
+                self.pressure_topic,
+            ):
+                publish_properties = props_expiry(settings.MQTT_TELEMETRY_EXPIRY)
 
+            self.publish(
+                topic=topic,
+                payload=payload,
+                qos=self.qos,
+                retain=self.retain,
+                properties=publish_properties,
+            )
             time.sleep(self.interval)
 
     def publish(
-        self, topic: str, payload: str, qos: int = 0, retain: bool = False
+        self,
+        topic: str,
+        payload: str,
+        qos: int = 0,
+        retain: bool = False,
+        properties: Properties = None,
     ) -> None:
-        queue_message: Tuple[str, str, int, bool] = (topic, payload, qos, retain)
+        queue_message: Tuple[str, str, int, bool, Properties] = (
+            topic,
+            payload,
+            qos,
+            retain,
+            properties,
+        )
         self.mqtt_queue.put(queue_message)

robot_interface/telemetry/payloads.py

@@ -1,11 +1,15 @@
 from dataclasses import dataclass
 from datetime import datetime
-from typing import List
+from typing import List, Optional
 
 from alitra import Pose
-from transitions import State
 
-from robot_interface.models.mission.status import RobotStatus
+from isar.models.status import IsarStatus
+from isar.storage.storage_interface import BlobStoragePath
+from robot_interface.models.exceptions.robot_exceptions import ErrorReason
+from robot_interface.models.mission.status import MissionStatus, TaskStatus
+from robot_interface.models.mission.task import TaskTypes
+from robot_interface.models.robots.battery_state import BatteryState
 
 
 @dataclass
@@ -30,6 +34,7 @@ class TelemetryPosePayload(TelemetryPayload):
 @dataclass
 class TelemetryBatteryPayload(TelemetryPayload):
     battery_level: float
+    battery_state: Optional[BatteryState] = None
 
 
 @dataclass
@@ -43,22 +48,16 @@ class TelemetryPressurePayload(TelemetryPayload):
 
 
 @dataclass
-class VideoStream:
+class DocumentInfo:
     name: str
     url: str
-    type: str
 
 
 @dataclass
-class RobotStatusPayload:
+class IsarStatusPayload:
     isar_id: str
     robot_name: str
-    robot_status: RobotStatus
-    previous_robot_status: RobotStatus
-    current_isar_state: State
-    current_mission_id: str
-    current_task_id: str
-    current_step_id: str
+    status: IsarStatus
     timestamp: datetime
 
 
@@ -69,7 +68,7 @@ class RobotInfoPayload:
     robot_model: str
     robot_serial_number: str
     robot_asset: str
-    video_streams: List[VideoStream]
+    documentation: List[DocumentInfo]
     host: str
     port: int
     capabilities: List[str]
@@ -81,3 +80,82 @@ class RobotHeartbeatPayload:
     isar_id: str
     robot_name: str
     timestamp: datetime
+
+
+@dataclass
+class MissionPayload:
+    isar_id: str
+    robot_name: str
+    mission_id: Optional[str]
+    status: Optional[MissionStatus]
+    error_reason: Optional[ErrorReason]
+    error_description: Optional[str]
+    timestamp: datetime
+
+
+@dataclass
+class MissionAbortedPayload:
+    isar_id: str
+    robot_name: str
+    mission_id: str
+    can_be_continued: bool
+    timestamp: datetime
+    reason: Optional[str]
+
+
+@dataclass
+class TaskPayload:
+    isar_id: str
+    robot_name: str
+    mission_id: Optional[str]
+    task_id: Optional[str]
+    status: Optional[TaskStatus]
+    task_type: Optional[TaskTypes]
+    error_reason: Optional[ErrorReason]
+    error_description: Optional[str]
+    timestamp: datetime
+
+
+@dataclass
+class InspectionResultPayload:
+    isar_id: str
+    robot_name: str
+    inspection_id: str
+    blob_storage_data_path: BlobStoragePath
+    blob_storage_metadata_path: BlobStoragePath
+    installation_code: str
+    tag_id: Optional[str]
+    inspection_type: Optional[str]
+    inspection_description: Optional[str]
+    timestamp: datetime
+
+
+@dataclass
+class InspectionValuePayload:
+    isar_id: str
+    robot_name: str
+    inspection_id: str
+    installation_code: str
+    tag_id: Optional[str]
+    inspection_type: Optional[str]
+    inspection_description: Optional[str]
+    value: float
+    unit: str
+    x: float
+    y: float
+    z: float
+    timestamp: datetime
+
+
+@dataclass
+class StartUpMessagePayload:
+    isar_id: str
+    timestamp: datetime
+
+
+@dataclass
+class InterventionNeededPayload:
+    isar_id: str
+    robot_name: str
+    reason: str
+    timestamp: datetime

robot_interface/utilities/json_service.py

@@ -7,6 +7,7 @@ from uuid import UUID
 
 import numpy as np
 from alitra import Orientation
+from pydantic import BaseModel
 
 
 class EnhancedJSONEncoder(json.JSONEncoder):
@@ -15,8 +16,13 @@ class EnhancedJSONEncoder(json.JSONEncoder):
     """
 
     def default(self, o):
+        if isinstance(o, BaseModel):
+            dump = getattr(o, "model_dump", None)
+            if callable(dump):
+                return dump()
+            return o.__dict__
         if is_dataclass(o):
-            return asdict(o)
+            return asdict(o)  # type: ignore
         if isinstance(o, UUID):
             return str(o)
         if isinstance(o, Orientation):