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

robot_interface/models/mission/task.py

@@ -1,127 +1,160 @@
-from dataclasses import dataclass, field
-from typing import Iterator, List, Optional
+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.mission.status import StepStatus, TaskStatus
-from robot_interface.models.mission.step import (
-    STEPS,
-    DriveToPose,
-    InspectionStep,
-    MotionStep,
-    Step,
+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)
-    error_message: Optional[ErrorMessage] = field(default=None, 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:
-        some_not_started: bool = False
-        for step in self.steps:
-            if step.status is StepStatus.Failed and isinstance(step, MotionStep):
-                self.error_message = ErrorMessage(
-                    error_reason=None,
-                    error_description=f"Inspection "
-                    f"{'of ' + self.tag_id if self.tag_id else ''}failed because the "
-                    f"robot could not navigate to the desired location",
-                )
-                self.status = TaskStatus.Failed
-                return
-
-            elif (step.status is StepStatus.Failed) and isinstance(
-                step, InspectionStep
-            ):
-                self.error_message = ErrorMessage(
-                    error_reason=None,
-                    error_description=f"Inspection "
-                    f"{'of ' + self.tag_id if self.tag_id else ''}was partially "
-                    f"successful because one or more inspection steps failed",
-                )
-                self.status = TaskStatus.PartiallySuccessful
-                continue
-
-            elif step.status is StepStatus.Successful:
-                continue
-
-            elif (step.status is StepStatus.NotStarted) and isinstance(
-                step, InspectionStep
-            ):
-                some_not_started = True
-
-        if self.status is not TaskStatus.PartiallySuccessful:
-            if some_not_started:
-                self.status = TaskStatus.InProgress  # TODO: handle all not_started
-            else:
-                self.status = TaskStatus.Successful
-
-        elif self._all_inspection_steps_failed():
-            self.error_message = ErrorMessage(
-                error_reason=None,
-                error_description=f"Inspection "
-                f"{'of ' + self.tag_id if self.tag_id else ''}failed as all inspection "
-                f"steps failed",
-            )
-            self.status = TaskStatus.Failed
-
-    def reset_task(self):
-        self.error_message = None
-        for step in self.steps:
-            step.error_message = None
-            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,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