Skip to content

Commit

Permalink
Update readme with references to isar-turtlebot
Browse files Browse the repository at this point in the history
  • Loading branch information
@aeshub
aeshub committed Dec 16, 2021
1 parent b875506 commit ef64fb5
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 45 deletions.
118 changes: 75 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
[![License](https://img.shields.io/badge/License-EPL_2.0-blue.svg)](https://opensource.org/licenses/EPL-2.0)

ISAR - Integration and Supervisory control of Autonomous Robots - is a tool for integrating robot applications into
Equinor systems. Through the ISAR API you can send command to a robot to do missions and collect results from the
operator systems. Through the ISAR API you can send commands to a robot to do missions and collect results from the
missions.

## Components

The system consists of two threads running in parallel.
The system consists of two main components.

1. State machine
1. FastAPI
Expand Down Expand Up @@ -40,18 +40,53 @@ FastAPI-framework is split into routers where the endpoint operations are define

## Installation

ISAR may be installed through pip as

```bash
$ pip install isar
pip install isar
```

To run ISAR:
However, to run ISAR you are required to clone this repository and run:

```bash
$ python main.py
python main.py
```

Note, running the full system requires that an implementation of a robot has been installed. See
this [section](#robot-integration) for installing a mocked robot.
this [section](#robot-integration) for installing a mocked robot or a Turtlebot3 simulator.

## Robot integration

To connect the state machine to a robot in a separate repository, it is required that the separate repository implements
the [robot interface](https://github.com/equinor/isar/blob/main/src/robot_interface/robot_interface.py). A mocked robot
can be found in [this repository](https://github.com/equinor/isar-robot). Install the repo, i.e:

```bash
pip install git+https://@github.com/equinor/isar-robot.git@main
```

Then, ensure the `robot_package` variable
in [default.ini](https://github.com/equinor/isar/blob/62312ac6844c06f93d98dce8db05d8172f22bca0/src/isar/config/default.ini#L4)
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

```bash
pip install -e /path/to/robot/repo/
```

### Running ISAR with a robot simulator

A simulator based on the open source robot Turtlebot3 has been implemented for use with ISAR and may be
found [here](https://github.com/equinor/isar-turtlebot). Follow the installation instructions for the simulator and
install `isar-turtlebot` in the same manner as given in the [robot integration](#robot-integration) section. Set the
following configuration variables
in [default.ini](https://github.com/equinor/isar/blob/62312ac6844c06f93d98dce8db05d8172f22bca0/src/isar/config/default.ini#L4):

```bash
robot_package = isar_turtlebot
default_map = turtleworld
```

## Running a robot mission

Expand All @@ -61,7 +96,7 @@ Once the application has been started the swagger site may be accessed at
http://localhost:3000/docs
```

Execute the `/schedule/start-mission` with `mission_id=1` to run a mission.
Execute the `/schedule/start-mission` endpoint with `mission_id=1` to run a mission.

In [this](./src/isar/config/predefined_missions) 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,
Expand All @@ -72,39 +107,17 @@ 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]
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:

```bash
$ pytest -n 10 .
```

## Robot integration

To connect the state machine to a robot in a separate repository, it is required that the separate repository implements
the [robot interface](https://github.com/equinor/isar/blob/main/src/robot_interface/robot_interface.py). Install the
repo, i.e:

```bash
$ pip install git+https://@github.com/equinor/isar-robot.git@main
```

Then, set an environment variable to the name of the package you installed:

```
$ export ROBOT_PACKAGE=isar_robot
```

If you have the robot repository locally, you can simply install through

```bash
$ pip install -e /path/to/robot/repo/
pytest .
```

## Mission planner
Expand Down Expand Up @@ -138,20 +151,22 @@ storage = blob
### Implement your own storage module

You can create your own storage module by implementing the [storage interface](./src/isar/storage/storage_interface.py)
and adding your storage module to the selection in the [here](./src/isar/modules.py). Note that you must add your module
as an option in the dictionary.

and adding your storage module to the selection [here](./src/isar/modules.py). Note that you must add your module as an
option in the dictionary.

## API authentication
The API has an option to inlcude user authentication. This can be set in the [default configuration](./src/isar/config/default.ini).

The API has an option to include user authentication. This can be set in
the [default configuration](./src/isar/config/default.ini).

```
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
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
Expand All @@ -164,18 +179,35 @@ AZURE_CLIENT_SECRET
After following the steps in [Development](#dev), you can run the tests:

```bash
$ pytest -n 10 .
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](https://github.com/equinor/isar-robot/blob/main/tests/interfaces/test_robotinterface.py) for example.

### Integration tests

Integration tests can be found [here](https://github.com/equinor/isar/tree/main/tests/integration) 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](#running-isar-with-a-robot-simulator) for
setting up the `isar-turtlebot` implementation with simulator and run the following command once the simulation has been
launched.

```bash
pytest tests/integration
```

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](https://github.com/equinor/isar-robot/blob/main/tests/interfaces/test_robotinterface.py) for example.
Note that these tests will run towards the actual simulation (you may monitor it through Gazebo and RVIZ) and it will
take a long time.

## Documentation

To build the project documentation, run the following commands:

```bash
$ cd docs
$ make docs
cd docs
make docs
```

The documentation can now be viewed at `docs/build/html/index.html`.
Expand All @@ -184,4 +216,4 @@ The 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](https://github.com/equinor/isar/issues) on
github or by forking the project on github and making a pull requests.
GitHub or by forking the project on GitHub and making a pull requests.
6 changes: 4 additions & 2 deletions tests/integration/turtlebot/test_successful_mission.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
UtilitiesModule,
)
from isar.services.readers.base_reader import BaseReader
from isar.state_machine.states_enum import States
from robot_interface.models.geometry.frame import Frame
from robot_interface.models.geometry.position import Position
from robot_interface.models.mission import DriveToPose
Expand Down Expand Up @@ -77,7 +78,8 @@ def run_before_and_after_tests():
yield

print("Removing temporary results folder for testing")
shutil.rmtree(results_folder)
if results_folder.exists():
shutil.rmtree(results_folder)
print("Cleanup finished")


Expand All @@ -100,7 +102,7 @@ def test_successful_mission(
mission: Mission = deepcopy(state_machine_thread.state_machine.current_mission)

start_time: datetime = datetime.utcnow()
while state_machine_thread.state_machine.current_state != "idle":
while state_machine_thread.state_machine.current_state != States.Idle:
if (datetime.utcnow() - start_time) > integration_test_timeout:
raise TimeoutError
time.sleep(5)
Expand Down

0 comments on commit ef64fb5

Please sign in to comment.