ISAR - 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.
The system consists of two main components.
- State machine
- FastAPI
The 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 the transitions package for Python. The main states are:
- Idle: The robot is in an idle state and ready to perform new missions.
- Send: The state machine has received a mission and is sending the mission to the robot.
- Monitor: The robot has received a mission from the state machine, and the state machine is monitoring the current mission.
- Collect: The state collects data during a mission.
- Cancel: The state machine has received a request to abort, or an event has occurred which requires the mission to be canceled. The cancel state also functions as a wrap-up state when a mission is finished, prior to the state machine returning to idle.
The 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.
ISAR may be installed through pip as
pip install isarHowever, to run ISAR you are required to clone this repository and run:
python main.pyNote, running the full system requires that an implementation of a robot has been installed. See this section for installing a mocked robot or a Turtlebot3 simulator.
To connect the state machine to a robot in a separate repository, it is required that the separate repository implements the robot interface. A mocked robot can be found in this repository. Install the repo, i.e:
pip install git+https://@github.com/equinor/isar-robot.git@mainThen, ensure the robot_package variable
in default.ini
is set to the name of the package you installed. isar_robot is set by default.
If you have the robot repository locally, you can simply install through
pip install -e /path/to/robot/repo/A simulator based on the open source robot Turtlebot3 has been implemented for use with ISAR and may be
found here. Follow the installation instructions for the simulator and
install isar-turtlebot in the same manner as given in the robot integration section. Set the
following configuration variables
in default.ini:
robot_package = isar_turtlebot
default_map = turtleworldOnce the application has been started the swagger site may be accessed at
http://localhost:3000/docs
Execute the /schedule/start-mission endpoint with mission_id=1 to run a mission.
In this folder there are predefined default missions, for example the mission
corresponding to mission_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.
For local development, please fork the repository. Then, clone and install in the repository root folder:
git clone https://github.com/equinor/isar
cd isar
pip install -e .[dev]
For zsh you might have to type ".[dev]"
Verify that you can run the tests:
pytest .The mission planner that is currently in use is defined by the mission_planner configuration variable. This can be set
in the default configuration. The available options are
mission_planner = local
mission_planner = echo
By default, the local planner is used.
You can create your own mission planner by implementing the mission planner interface and adding your planner to the selection here. Note that you must add your module as an option in the dictionary.
The storage module that is currently in use is defined by the storage configuration variable. This can be set in
the default configuration. The available options are
storage = local
storage = blob
You can create your own storage module by implementing the storage interface and adding your storage module to the selection here. Note that you must add your module as an option in the dictionary.
The API has an option to include user authentication. This can be set in the default configuration.
authentication_enabled = false
authentication_enabled = true
By default, the local storage 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 are
AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_CLIENT_SECRET
After following the steps in Development, you can run the tests:
pytest .To create an interface test in your robot repository, use the function interface_test from robot_interface. The
argument should be an interface object from your robot specific implementation.
See isar-robot for example.
Integration tests can be found here and have been created
with a simulator in mind. The integration tests will not run as part of pytest . or as part of the CI/CD pipeline. To
run the integration tests please follow the instructions in this section for
setting up the isar-turtlebot implementation with simulator and run the following command once the simulation has been
launched.
pytest tests/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.
To build the project documentation, run the following commands:
cd docs
make docsThe documentation can now be viewed at docs/build/html/index.html.
We welcome all kinds of contributions, including code, bug reports, issues, feature requests, and documentation. The preferred way of submitting a contribution is to either make an issue on GitHub or by forking the project on GitHub and making a pull requests.