equinor / isar-robot

isar-robot

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 missions.

Running the full ISAR system requires an installation of a robot which satisfies the required interface. isar-robot is a default implementation of such a robot.

Installation

For installation of isar-robot to use with ISAR, please follow the robot integration installation guide.

Run isar-robot

After installing isar-robot, it can be used through ISAR.

Development

For local development, create a fork of the repository and clone the fork to your machine:

git clone https://github.com/<your-username>/isar-robot
cd isar-robot

It is recommended to create a virtual environment, see a guide for this here: https://docs.python.org/3/library/venv.html.

Then install the requirements and the package:

pip install -r requirements.txt -e .[dev]

Configurable variables

Specific mission and step behaviours can be configured as enviorment variables. These are optional and do not have to be set. These allow for always failing specific mission types, failing specific step types, setting custom step durations, and setting custom mission durations. The following list shows all configurable environment variables. In this case "normal" means non-localization or return to home tasks.

The variable names and types are as follows:

STEP_DURATION_IN_SECONDS: float
MISSION_DURATION_IN_SECONDS: float
SHOULD_FAIL_NORMAL_STEP: bool
SHOULD_FAIL_NORMAL_MISSION: bool
SHOULD_FAIL_LOCALIZATION_STEP: bool
SHOULD_FAIL_LOCALIZATION_MISSION: bool
SHOULD_FAIL_RETURN_TO_HOME_STEP: bool 
SHOULD_FAIL_RETURN_TO_HOME_MISSION: bool

Every configuration variable is defined in settings.py, and they may all be overwritten by specifying the variables in your ".env" file in ISAR. Note that the configuration variable must be prefixed with ROBOT_ when specified in the ISAR environment file.

Dependencies

The dependencies used for this package are listed in pyproject.toml and pinned in requirements.txt. This ensures our builds are predictable and deterministic. This project uses pip-compile (from pip-tools) for this:

pip-compile --output-file=requirements.txt pyproject.toml

To update the requirements to the latest versions, run the same command with the --upgrade flag:

pip-compile --output-file=requirements.txt pyproject.toml --upgrade

Contributing

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 request.

isar-robot's Issues

Add test to verify implementation of ISAR interface

Is your feature request related to a problem? Please describe.
The implementation of the interface in ISAR is subject to change as the interface itself changes. A test which checks if the interface is satisfied should be implemented.

Describe the solution you'd like
A test which verifies that all functions required by the interface are implemented and that the return types are correct.

Describe alternatives you've considered
N/A

Additional context

Publish isar-robot to PYPI

Robot does not have all capabilities - Fails default mission

Describe the bug
The robot only has drive_to and take_image capabilities, but it should have all capabilities since it is a test robot.

To Reproduce
Try to schedule default mission.
The mission will fail due to lacking capabilities.

Expected behavior
The mission should start.

Add __version__ attribute to the package

Describe the improvement you would like to see
Add version attribute to the isar-robot package. See how this is done in isar/src/isar/init.py.

How will this change existing functionality?
Enables the syntax isar_robot.__version__.

How will this improvement affect the current Threat Model?
None

Make isar-robot configurable

Automate update-dependencies branch to auto-merge if possible

Describe the improvement you would like to see
Investigate / implement some automation to get the auto-generated update-dependencies branch quicker into main.

How will this change existing functionality?
N/A11

How will this improvement affect the current Threat Model?
Quicker updates to latest version of dependencies

Add an action to promote to prod

Describe the improvement you would like to see
Similarly to what is done for other robots, there should be an action to promote isar-robot to prod.
The script can be similar to the one for isar-taurob

Improve open source robot implementation

Get isar-robot to fail some tasks

Get isar-robot to fail some task such that testing through isar-robot will touch larger parts of the code and to allow for testing of failure behaviour.

One option is to use environment variables to decide if it should fail or not.

Some different types of isar-robot that could have different behaviour:

• PlaceBot (successfully completes every task after x seconds)
• NoceBot (regular missions always fails)
• LostBot (localization step always fails)
• SlowBot (spends 1 minute per task)
• InstantBot (spends no time per task)
• VagaBot (never returns home)
• OfflineBot (Shuts down mid mission)

Prerequisite

• #118

Update issue templates

Update issue templates to be the same as in ISAR.

This also means adding the improvement and feature labels.

Implement MissionCapability fields in RobotInterface

Describe the new feature you would like to see
Add two boolean fields to this implementation RobotInterface:
can_perform_full_mission
can_perform_step_wise_mission

We should verify that at least one of these is true, or else the RobotInterface implementation is invalid.

This is caused by equinor/isar#416

How will this feature affect the current Threat Model?
N/A

Deployment pipelines as with the other robot repositories.

Describe the new feature you would like to see
Would like a pipeline that updates our deployment.
For merged PRs to main, dev should be updated.
For released new version, staging should be updated.

Describe the solution you'd like
Same GitHub actions as in other repositories.

How will this feature affect the current Threat Model?

Describe configuration in README

Describe the improvement you would like to see
Give a summary of the main configuration options in the README, especially including the settings for different behaviour (whether a robot should always fail, or how long time it should spend completing a mission etc, ref. #83)

How will this change existing functionality?
Nothing, just improved documentation.

How will this improvement affect the current Threat Model?
Better documentation

Implement use of step.id

Step ID is now being implemented in ISAR. The robot interface should be updated accordingly in robot-turtlebot. See this issue

Adapt to changes in transformation in ISAR

Is your feature request related to a problem? Please describe.
ISAR has moved transformation between maps from ISAR to the robot repository such that changes is required. See equinor/isar#203

Describe the solution you'd like
The repository is required to return asset frame poses rather than robot frame.

Describe alternatives you've considered
NA

Additional context
NA

Publish docker image for isar with isar-robot

Describe the new feature you would like to see
Build a docker image for ISAR with the isar-robot mock as selected robot package.

Describe the solution you'd like
Docker action which publishes new image to ghcr upon release.

How will this feature affect the current Threat Model?
Openly available image.

Extend readme with relevant information

Is your feature request related to a problem? Please describe.
It is difficult to contribute to this project as there are no descriptions on how to install or use the project.

Describe the solution you'd like
The readme should contain an installation guide, contribution guide and a note on how the project should be used (in combination with ISAR).

Describe alternatives you've considered
N/A

Additional context
N/A

Find a way to automatically upgrade to newest versions in requirements.txt

Describe the improvement you would like to see
This should happen automatically at for instance every push to the main branch, before building the docker image.

The solution should use pip-compile --upgrade to fetch the latest versions of the dependencies listed in pyproject.toml and save them to requirements.txt.

How will this change existing functionality?
The requirements.txt is kept up to date with the latest dependency versions

How will this improvement affect the current Threat Model?
Reduced time between each time we use the latest version of a dependency, at the same time as we maintain knowledge about which versions was used at which time, with source control

Remove `$` from commands in readme

Such that commands can be copy pasted directly

Add support for default inspections

Is your feature request related to a problem? Please describe.
The mock interface currently returns an empty list when collecting inspection references and it returns None when downloading the InspectionResult. In order to test data storage and offload in isar these should return a value which implies an inspection was performed.

Describe the solution you'd like
Add a default image which should be returned by default every time these functions are used.

Describe alternatives you've considered
N/A

Additional context

Gather thermal data as a time series?

Describe the new feature you would like to see
It would be interesting to use thermal cam to gather data on a time series format - if not, at least extract one data point as a temperature we can store in a time series format.

Describe the solution you'd like

How will this feature affect the current Threat Model?

Create new version of isar-robot

When fresh installing isar and isar-robot we get "TimeIndexPose" error, need new version of isar-robot.

Version isar-robot and publish to PyPi

Describe the bug
When attempting to update isar_robot as a dependency through pip, it does not get updated.
The only way to update it is to uninstall and reinstall it.

This would be solved by versioning the PyPi releases of the isar_robot package.

To Reproduce
Install an old version of isar_robot in your venv
Try to update using pip install isar_robot --upgrade
Witness that the version does not get updated,

Expected behavior
Should be updated to latest version.

Add license to the repository