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

robot_interface/models/mission/task.py

@@ -1,96 +1,160 @@
-from dataclasses import dataclass, field
-from typing import Iterator, List, Optional
-
-from robot_interface.models.mission.status import StepStatus, TaskStatus
-from robot_interface.models.mission.step import (
-    STEPS,
-    DriveToPose,
-    InspectionStep,
-    MotionStep,
-    Step,
+from enum import Enum
+from typing import Literal, Optional, Type, Union
+
+from alitra import Pose, Position
+from pydantic import BaseModel, Field
+
+from robot_interface.models.exceptions.robot_exceptions import ErrorMessage
+from robot_interface.models.inspection.inspection import (
+    Audio,
+    CO2Measurement,
+    Image,
+    Inspection,
+    ThermalImage,
+    ThermalVideo,
+    Video,
 )
+from robot_interface.models.mission.status import TaskStatus
 from robot_interface.utilities.uuid_string_factory import uuid4_string
 
 
-@dataclass
-class Task:
-    steps: List[STEPS]
-    status: TaskStatus = field(default=TaskStatus.NotStarted, init=False)
-    tag_id: Optional[str] = field(default=None)
-    id: str = field(default_factory=uuid4_string, init=True)
-    _iterator: Iterator = None
-
-    def next_step(self) -> Step:
-        step: Step = next(self._iterator)
-        while step.status != StepStatus.NotStarted:
-            step = next(self._iterator)
-        return step
-
-    def is_finished(self) -> bool:
-        for step in self.steps:
-            if step.status is StepStatus.Failed and isinstance(step, MotionStep):
-                # One motion step has failed meaning the task as a whole should be
-                # considered as failed
-                return True
-
-            elif (step.status is StepStatus.Failed) and isinstance(
-                step, InspectionStep
-            ):
-                # It should be possible to perform several inspections per task. If
-                # one out of many inspections fail the task is considered as
-                # partially successful.
-                continue
-
-            elif step.status is StepStatus.Successful:
-                # The task is complete once all steps are completed
-                continue
-            else:
-                # Not all steps have been completed yet
-                return False
-
-        return True
-
-    def update_task_status(self) -> None:
-        for step in self.steps:
-            if step.status is StepStatus.Failed and isinstance(step, MotionStep):
-                self.status = TaskStatus.Failed
-                return
-
-            elif (step.status is StepStatus.Failed) and isinstance(
-                step, InspectionStep
-            ):
-                self.status = TaskStatus.PartiallySuccessful
-                continue
-
-            elif step.status is StepStatus.Successful:
-                continue
-
-        if self.status is not TaskStatus.PartiallySuccessful:
-            self.status = TaskStatus.Successful
-
-        elif self._all_inspection_steps_failed():
-            self.status = TaskStatus.Failed
-
-    def reset_task(self):
-        for step in self.steps:
-            if isinstance(step, DriveToPose):
-                step.status = StepStatus.NotStarted
-            elif (
-                isinstance(step, InspectionStep)
-                and step.status == StepStatus.InProgress
-            ):
-                step.status = StepStatus.NotStarted
-        self._iterator = iter(self.steps)
-
-    def _all_inspection_steps_failed(self) -> bool:
-        for step in self.steps:
-            if isinstance(step, MotionStep):
-                continue
-            elif step.status is not StepStatus.Failed:
-                return False
-
-        return True
-
-    def __post_init__(self) -> None:
-        if self._iterator is None:
-            self._iterator = iter(self.steps)
+class TaskTypes(str, Enum):
+    ReturnToHome = "return_to_home"
+    TakeImage = "take_image"
+    TakeThermalImage = "take_thermal_image"
+    TakeVideo = "take_video"
+    TakeThermalVideo = "take_thermal_video"
+    TakeCO2Measurement = "take_co2_measurement"
+    RecordAudio = "record_audio"
+
+
+class ZoomDescription(BaseModel):
+    objectWidth: float
+    objectHeight: float
+
+
+class Task(BaseModel):
+    status: TaskStatus = Field(default=TaskStatus.NotStarted)
+    error_message: Optional[ErrorMessage] = Field(default=None)
+    tag_id: Optional[str] = Field(default=None)
+    id: str = Field(default_factory=uuid4_string, frozen=True)
+
+
+class InspectionTask(Task):
+    """
+    Base class for all inspection tasks which produce results to be uploaded.
+    """
+
+    inspection_id: str = Field(default_factory=uuid4_string, frozen=True)
+    robot_pose: Pose = Field(default=None, init=True)
+    inspection_description: Optional[str] = Field(default=None)
+    zoom: Optional[ZoomDescription] = Field(default=None)
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return Inspection
+
+
+class ReturnToHome(Task):
+    """
+    Task which cases the robot to return home
+    """
+
+    type: Literal[TaskTypes.ReturnToHome] = TaskTypes.ReturnToHome
+
+
+class TakeImage(InspectionTask):
+    """
+    Task which causes the robot to take an image towards the given target.
+    """
+
+    target: Position = Field(default=None)
+    type: Literal[TaskTypes.TakeImage] = TaskTypes.TakeImage
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return Image
+
+
+class TakeThermalImage(InspectionTask):
+    """
+    Task which causes the robot to take a thermal image towards the given target.
+    """
+
+    target: Position = Field(default=None)
+    type: Literal[TaskTypes.TakeThermalImage] = TaskTypes.TakeThermalImage
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return ThermalImage
+
+
+class TakeVideo(InspectionTask):
+    """
+    Task which causes the robot to take a video towards the given target.
+
+    Duration of video is given in seconds.
+    """
+
+    target: Position = Field(default=None)
+    duration: float = Field(default=None)
+    type: Literal[TaskTypes.TakeVideo] = TaskTypes.TakeVideo
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return Video
+
+
+class TakeThermalVideo(InspectionTask):
+    """
+    Task which causes the robot to record thermal video towards the given target
+
+    Duration of video is given in seconds.
+    """
+
+    target: Position = Field(default=None)
+    duration: float = Field(default=None)
+    type: Literal[TaskTypes.TakeThermalVideo] = TaskTypes.TakeThermalVideo
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return ThermalVideo
+
+
+class RecordAudio(InspectionTask):
+    """
+    Task which causes the robot to record a video at its position, facing the target.
+
+    Duration of audio is given in seconds.
+    """
+
+    target: Position = Field(default=None)
+    duration: float = Field(default=None)
+    type: Literal[TaskTypes.RecordAudio] = TaskTypes.RecordAudio
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return Audio
+
+
+class TakeCO2Measurement(InspectionTask):
+    """
+    Task which causes the robot to take a CO2 measurement at its position.
+    """
+
+    type: Literal[TaskTypes.TakeCO2Measurement] = TaskTypes.TakeCO2Measurement
+
+    @staticmethod
+    def get_inspection_type() -> Type[Inspection]:
+        return CO2Measurement
+
+
+TASKS = Union[
+    ReturnToHome,
+    TakeImage,
+    TakeThermalImage,
+    TakeVideo,
+    TakeThermalVideo,
+    TakeCO2Measurement,
+    RecordAudio,
+]

robot_interface/models/robots/battery_state.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class BatteryState(Enum):
+    Normal = "Normal"
+    Charging = "Charging"

robot_interface/models/robots/media.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class MediaConnectionType(str, Enum):
+    LiveKit = "LiveKit"
+
+
+@dataclass
+class MediaConfig:
+    url: str
+    token: str
+    media_connection_type: MediaConnectionType

robot_interface/models/robots/robot_model.py

@@ -4,10 +4,10 @@ from enum import Enum
 # Did you write your own isar-robot package and would like to have it included here?
 # Open a pull request to the ISAR repository!
 class RobotModel(Enum):
-    TaurobInspector: str = "TaurobInspector"
-    TaurobOperator: str = "TaurobOperator"
-    ExR2: str = "ExR2"
-    Robot: str = "Robot"  # This corresponds to the mock in isar_robot
-    Turtlebot: str = "Turtlebot"
-    AnymalX: str = "AnymalX"
-    AnymalD: str = "AnymalD"
+    TaurobInspector = "TaurobInspector"
+    TaurobOperator = "TaurobOperator"
+    ExR2 = "ExR2"
+    Robot = "Robot"  # This corresponds to the mock in isar_robot
+    Turtlebot = "Turtlebot"
+    AnymalX = "AnymalX"
+    AnymalD = "AnymalD"

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,47 +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
-            If the mission is not initiated.
-        NotImplementedError
-            If the robot is designed for stepwise mission execution.
+            Will catch all RobotExceptions not previously listed and retry scheduling of
+            the mission until the number of allowed retries is exceeded
 
         """
         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.
 
-        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.
+        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
+
+    @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 there was an error when retrieving the mission status
         RobotException
             If the mission status could not be retrieved.
-        NotImplementedError
-            If the robot is designed for stepwise mission execution.
 
         """
+        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
         -------
@@ -79,40 +94,37 @@ 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
         RobotException
-            If the step is not initiated.
-        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
         -------
@@ -120,51 +132,70 @@ class RobotInterface(metaclass=ABCMeta):
 
         Raises
         ------
+        RobotActionException
+            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
-            If the robot is not stopped.
+            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 task an error message is logged and the state machine continues
         RobotException
-            If the inspection results can't be retrieved.
+            Catches other RobotExceptions that lead to the same result as a
+            RobotRetrieveInspectionException
 
         """
         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
-        ------
-        RobotException
-            If the initialization failed
+        """
+        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
@@ -195,15 +226,53 @@ class RobotInterface(metaclass=ABCMeta):
     @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
         -------
         RobotStatus
             Enum indicating if the robot may be reached by the isar-robot package.
 
+        Raises
+        -------
+        RobotCommunicationException
+            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. The fetching of robot battery level
+            will be attempted again until success
+        RobotException
+            Catches other RobotExceptions that may have occurred while retrieving the
+            robot battery level. The fetching of robot battery level will
+            be attempted again until success
+
         """
         raise NotImplementedError