Package: isar
ISARISAR - Integration and Supervisory control of Autonomous Robots - is a tool for integrating robot applications into
operator systems. Through the ISAR API you can send commands to a robot to do missions and collect results from the
missions.Getting startedSteps:InstallIntegrate a robotRun the ISAR serverRun a robot missionInstallFor local development, please fork the repository. Then, clone and install in the repository root folder:git clone https://github.com/<path_to_parent>/isar
cd isar
pip install -e .[dev]Forzshyou might have to type".[dev]"Verify that you can run the tests:pytest.The repository contains a configuration file for installing pre-commit hooks. Currently,blackand a mirror ofmypyare configured hooks. Install with:pre-commit installVerify that pre-commit runs:pre-commitpre-commit will now run the installed hooks before code is commited to git. To turn pre-commit off, run:pre-commit uninstallRobot integrationTo connect the state machine to a robot in a separate repository, it is required that the separate repository implements
therobot interface.The separate repository should also have a settings.env file in a config folder whereCAPABILITIESandROBOT_MODELare set.
A mocked robot can be found inthis repository. Install the repo, i.e:pipinstallisar-robotNB: isar-robot has not been published to PyPi for some time, and needs to be downloaded directly
from git to work.Then, ensure theISAR_ROBOT_PACKAGEvariable insettings.envis set to the name of the package you installed.isar_robotis set by default. See the section
forconfigurationfor overwriting configuration.If you have the robot repository locally, you can simply install throughpipinstall-e/path/to/robot/repo/Running ISAR with a robot simulatorA simulator based on the open source robot Turtlebot3 has been implemented for use with ISAR and may be
foundhere. Follow the installation instructions for the simulator and
installisar-turtlebotin the same manner as given in therobot integrationsection. Overwrite
the following configuration variables:ISAR_ROBOT_PACKAGE=isar_turtlebotISAR_DEFAULT_MAP=turtleworldRun ISAR serverTo run ISAR:pythonmain.pyNote, running the full system requires that an implementation of a robot has been installed. See
thissectionfor installing a mocked robot or a Turtlebot3 simulator.Running a robot missionOnce the application has been started the swagger site may be accessed athttp://localhost:3000/docsExecute the/schedule/start-missionendpoint withmission_id=1to run a mission.Inthisfolder there are predefined default missions, for example the mission
corresponding tomission_id=1. A new mission may be added by adding a new json-file with a mission description. Note,
the mission IDs must be unique.Running with docker-composeISAR may be started with an instance of theisar-robotpackage bydocker-composeup--buildProvided that the simulator fromisar-turtlebotis running ISAR may be
started with the turtlebot bydocker-compose-fdocker-compose-turtlebot.ymlup--buildConfigurationThe system consists of many configuration variables which may alter the functionality. As an example, it is possible to
change mission planners or add multiple storage handlers as described in themission plannerandstoragesections.There are two methods of specifying configuration.Override the default value by setting an environment variable.Every configuration variable is defined insettings.py, and they may all be
overwritten by specifying the variables in the environment instead. Note that the configuration variable must be
prefixed withISAR_when specified in the environment. So for theROBOT_PACKAGEconfiguration variable:exportISAR_ROBOT_PACKAGE=isar_turtlebotThis means ISAR will connect toisar_turtlebotrobot package.Adding environment variables throughsettings.env.By adding environment variables with the prefixISAR_to thesettings.envfile
the configuration variables will be overwritten by the values in this file.Running testsAfter following the steps inDevelopment, you can run the tests:pytest.To create an interface test in your robot repository, use the functioninterface_testfromrobot_interface. The
argument should be an interface object from your robot specific implementation.
Seeisar-robotfor example.Integration testsIntegration tests can be foundhereand have been created
with a simulator in mind. The integration tests will not run as part ofpytest .or as part of the CI/CD pipeline. To
run the integration tests please follow the instructions inthis sectionfor
setting up theisar-turtlebotimplementation with simulator and run the following command once the simulation has been
launched.pytesttests/integrationNote that these tests will run towards the actual simulation (you may monitor it through Gazebo and RVIZ) and it will
take a long time.DocumentationTo build the project documentation, run the following commands:cddocs
makedocsThe documentation can now be viewed atdocs/build/html/index.html.ComponentsThe system consists of two main components.State machineFastAPIState machineThe state machine handles interaction with the robots API and monitors the execution of missions. It also enables
interacting with the robot before, during and after missions.The state machine is based on thetransitionspackage for Python. An visualization of the state machine can be seen below:In general the statesStates.Off,
States.Initialize,
States.Initiate,
States.Stop,
States.Monitor,
States.Paused,indicates that the state machine is already running. For running a mission the state machine need to be in the stateStates.IdleFastAPIThe FastAPI establishes an interface to the state machine for the user. As the API and state machine are separate
threads, they communicate through python queues. FastAPI runs on an ASGI-server, specifically uvicorn. The
FastAPI-framework is split into routers where the endpoint operations are defined.Mission plannerThe mission planner that is currently in use is a local mission planner, where missions are specified in a json file. You can create your own mission planner by implementing
themission planner interfaceand adding your planner to the
selectionhere. Note that you must add your module as an option in the dictionary.StorageThe storage modules that are used is defined by theISAR_STORAGEconfiguration variable. This can be changed by
overriding the configuration through an environment variable. It accepts a json encoded list and will use each element
in the list to retrieve the corresponding handler. The current options areISAR_STORAGE = '["local", "blob", "slimm"]'Note that theblobandslimmoptions require special configuration to authenticate to these endpoints.Implement your own storage moduleYou can create your own storage module by implementing thestorage interfaceand adding your storage module to the selectionhere. Note that you must add your module as an
option in the dictionary.Task selectionThe tasks of a mission are selected based on a task selector module, defined by theTASK_SELECTORconfiguration variable. The default task selector issequential. When using the default module, tasks are executed in sequential order defined by the current input mission.Implement you own task selector moduleCustom task selector modules may be added by implementing additional versions of thetask selector interface.For every custom module, the interface functionnext_task()must be implemented. All interface implementations by default have access to the list of tasks in the current mission through the memberself.tasks, however additional variables may be supplied by adding arguments tonext_task(). To comply with the interface definition, the function should return the next task upon every call, and raise theTaskSelectorStopexception when all tasks in the current mission have been completed:classCustomTaskSelector(TaskSelectorInterface):...defnext_task(...)->Task:# Add code here...# Raise `TaskSelectorStop` when all tasks have been completed...Optionally, theinitialize()function may be extended by supplementing the parameter list or function body:classCustomTaskSelector(TaskSelectorInterface):...definitialize(self,tasks:List[Task],...)->None:super.initialize(tasks=tasks)# Add supplementary code here...A custom task selector may be made available duringmodule selectionby adding it to the series of options in the dictionary of injector modules. It can then be activated by overriding the task selector configuration variable:# Add custom task selector module to `modules.py`classCustomTaskSelectorModule(Module):@provider@singletondefprovide_task_selector(self)->TaskSelectorInterface:returnCustomTaskSelector()...# Make it available to select during injector instantiationmodules:dict[str,tuple[Module,Union[str,bool]]]={..."task_selector":({"sequential":SequentialTaskSelectorModule,"custom":CustomTaskSelectorModule}...)...}API authenticationThe API has an option to include user authentication. This can be enabled by setting the environment variableISAR_AUTHENTICATION_ENABLED = trueBy default, thelocalstorage module is used and API authentication is disabled. If using Azure Blob Storage a set of
environment variables must be available which gives access to an app registration that may use the storage account.
Enabling API authentication also requires the same environment variables. The required variables areAZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_CLIENT_SECRETMQTT communicationISAR is able to publish parts of its internal state to topics on an MQTT broker whenever they change. This is by default
turned off but may be activated by setting the environment variableISAR_MQTT_ENABLED = trueThe connection to the broker will be determined by the following configuration values insettings.pyISAR_MQTT_USERNAME
ISAR_MQTT_HOST
ISAR_MQTT_PORTThe default values of these are overwritten by the environment insettings.env.To specify broker password, add the following environment variable to a .env file in the root of the repository:ISAR_MQTT_PASSWORDIf not specified the password will default to an empty string.ContributionsEquinor welcomes all kinds of contributions, including code, bug reports, issues, feature requests, and documentation
Please initiate your contribution by creating anissueor by forking the
project and making a pull requests. Commit messages shall be written according tothis guide.