equinor / flotilla

Flotilla is the main point of access for operators to interact with multiple robots in a facility.

Flotilla

Flotilla is the main point of access for operators to interact with multiple robots in multiple facilities.
The application consists of a frontend in React, a backend in ASP.NET and a Mosquitto MQTT Broker.

Deployments

We currently have 3 environment (Development, Staging and Production) deployed to Aurora.

Environment	Deployment	Status
Development	Frontend Backend
Staging	Frontend Backend
Production	Frontend Backend

Setup

For development, please fork the repository. Then, clone the repository:

git clone https://github.com/equinor/flotilla

Please see separate installation guides for frontend, backend, and Broker. For the environment setup, either run the script as described below or do it manually as described in each component.

Automatic environment setup

Run the setup.sh to automatically set up your dev environment for the components. This script will ask you for the Client Secret for the backend and the MQTT broker server key for the MQTT broker.

Run with docker

Install docker and docker compose.

Build the docker container:

docker compose build

Setup a .env file in the backend directory with the following environment variables:

AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_CLIENT_SECRET

Start Flotilla by running:

docker compose up

or

docker compose up --build

Contributions

Equinor welcomes all kinds of contributions, including code, bug reports, issues, feature requests, and documentation. Please initiate your contribution by creating an issue or by forking the project and making a pull requests. Commit messages shall be written according to this guide.

flotilla's Issues

Establish MQTT broker for Flotilla

Describe the new feature you would like to see
The Flotilla application should have an associated MQTT broker/server which is responsible for streaming data from the different ISAR applications and robots on the facility to Flotilla. In addition, the broker should bridge to a fleet management broker to enable streaming at scale.

Describe the solution you'd like
This issue aims to get started with the MQTT broker for the Flotilla application. The bare minimum is adding an MQTT broker (https://www.hivemq.com/) which runs through a docker container and may be started together with the Flotilla application through docker compose.

How will this feature affect the current Threat Model?
The first iteration will only include a broker which is local to the Flotilla system and as such no data streaming out of the internal network.

• Authentication to the broker must be handled for all applications which should subscribe/publish
• Communication security must be handled when bridging to a fleet management broker (future task)

Establish timeseries database for Flotilla

Describe the new feature you would like to see
The Flotilla system will have access to timeseries streamed from the MQTT broker which should be stored in a timeseries database. Examples are mission status, battery level, pose etc.

Describe the solution you'd like
The MQTT broker established as part of #47 should stream all relevant topics to the database where it is stored in a functional format. An example of a timeseries database is InfluxDB which is available in Azure.

EDIT by Torstein:

While looking into this, I think that PostreSQL and timescale db is a good option for us.
By using that we can link the timeseries relationally to the rest of our database.

https://azure.microsoft.com/nb-no/blog/power-iot-and-time-series-workloads-with-timescaledb-for-azure-database-for-postgresql/
https://docs.timescale.com/getting-started/latest/

How will this feature affect the current Threat Model?
Access to the timeseries database must be managed.

• Note that the first iteration will only be a database available locally on the facility tightly coupled with Flotilla.

Setup report endpoints

Describe the new feature you would like to see
The backend should provide endpoints for getting information about reports (which represents a performed mission).

Describe the solution you'd like
Setup the endpoints related to reports according to the api-specification at FlotillaOpenApi. Use the standard authentication. Setup appropriate tests for the api-endpoints.

How will this feature affect the current Threat Model?
No changes since the endpoints not update the database.

Setup Access Control List for the MQTT-broker

Describe the improvement you would like to see
The security of the broker can be improved by using authorization on the different topics. The mosquitto broker offers the opportunity to use an Access Control List (ACL) to perform authorization. In ACL you can specify which topics a certain user can publish/subscribe to. A brief introduction can be found here. Different users (with passwords) should be generated for the different roles (streaming of telemetry, status from isar, flotilla backend, flotilla frontend).

How will this change existing functionality?
This will improve the security of the broker and will have potential effects to all clients of the broker, both publishers and subscribers.

How will this improvement affect the current Threat Model?
This should reduce the risk of unauthorized publishing to the broker and leak of information (listening to certain topics).

Create List with header component

Many of the components in figma is based on displaying a list with headers (e.g Robot Overview/Mission Overview). Create a customizable list with header component that can be reused in multiple components.

Update dependencies to remove vulnerabilities

Is your feature request related to a problem? Please describe.
When the application is installed a warning listing up a high number of vulnerabilities is shown, some of which is critical. Most of them is due to using old versions of the dependencies. Using the automatic audit function leads to the app breaking.

Describe the solution you'd like
Go through the dependencies and upgrade them to newer version and check that the number of vulnerabilities is reduced. Check that the app is able to run or make the necessary adjustments.

Generate typescript models based on API-specification

There exist tools for automatically generate typescript models based on an OpenAPI-specification (e.g. OpenAPI Generator or OpenAPI Editor). Using these type of tools, generate typescript models based on the API-specification of the back-end that can be used by the front-end.

Set up mission endpoints

In the API-specification the /mission and /mission/{mission_id} is used to get information about available missions on the asset. The information about available missions should be retrieved from Echo. Set up the endpoints using information from Echo.

Move documentation of api-specification to FlotillaOpenApi

Describe the improvement you would like to see
Currently the documentation fro the Flotilla API is published in Flotilla. This should be moved to FlotillaOpenaAPI, where the specification actually lives.

How will this change existing functionality?
Publish the specification for the Flotilla API to the github.io page for FlotillaOpenAPI similar to what is done in Flotilla now. This should be removed from Flotilla.

How will this improvement affect the current Threat Model?
No changes.

Add event handler

Describe the new feature you would like to see
The user have the opportunity to schedule mission to start at a specified time through the event concept. The events are then stored in the database and the user expects the backend to start the mission on the scheduled time. To do this, the backend needs an event handler that continuously checks the database for events that should be started and starts the corresponding robot.

Describe the solution you'd like
A handler that runs in a separate thread that continuously checks for overdue events and starts the right robot. The handler should check for conflicts with already started events and handle them appropriately (delay the event until the robot is available, notify the user of the conflict, etc).

How will this feature affect the current Threat Model?
No change.

Add pagination to certain GET requests

Describe the improvement you would like to see
When receiving a GET requests for multiple entries we should restrict the amount returned using a pagination system with default parameters that may be overwritten in the query. The parameter for page size should have an upper limit.
This is in accordance with the RESTful API principles.

How will this change existing functionality?
This will throttle our API and protect it from being overloaded in the future when we might have a large amount of data being retrieved by these calls.
Better to implement it now in anticipation as it might be easy to forget in the future as the database will probably grow slowly.

How will this improvement affect the current Threat Model?
This improvement should make our API more reliable in the long run and possibly prevent downtime.

Setup Event endpoints

Describe the new feature you would like to see
The backend of flotilla offers endpoints for adding and removing events from the schedule of a robot. These endpoints should be made available to be used by the frontend.

Describe the solution you'd like
Endpoints according to the api-specification in FlotillaOpenApi that updates the database accordingly. Only support for creating single events are needed. Some basic verification of the event should be included (checking that the event is not in the past and not to soon) before adding it to the database.

How will this feature affect the current Threat Model?
Care should be taken not to add invalid events to the schedule.

Create RobotOverview component

In the interface for flotilla, displayed here, an overview of all the robots on the asset is displayed. A robot overview component should be created that takes in an array with all the robots on the asset and displays the desired information. Connected to #6

Change name of database models to use DB prefix

Describe the improvement you would like to see
There is an overlap of the names between the models used in the API interface and the database. This leads to conflict when both models are used in the same file. A solution to this is to add a DB prefix to the database models to make it clear that the models originated from the database and that all other models is from the API.

How will this change existing functionality?
This will make the code easier to read and less confusing when both models are used.

How will this improvement affect the current Threat Model?
No changes

Accessing the database in api-tests

Describe the new feature you would like to see
Some of the endpoints that are tested in the api-tests update the database. It would be beneficial to check that the expected updates to the database is done correctly.

Describe the solution you'd like
An easy method for accessing the same database as used by the test client should be found and setup this for the appropriate test.

How will this feature affect the current Threat Model?
No changes

Add video component

Consider how to stream video from different vendors

Convert this issue to use template

Deploy Flotilla to the cloud with multiple ISAR instances

Describe the new feature you would like to see
Deploy the Flotilla application to the cloud and connect to multiple ISAR instances running with isar-robot to create a test environment for the robotics system.

Describe the solution you'd like

1. The Flotilla deployment should be automated and scaleable - infrastructure as code.
2. Flotilla must be able to connect to multiple instances of ISAR through database entries.
3. Flotilla should be deployed through docker-compose.
4. The infrastructure may be chosen, but Azure VM, Azure Container Instances, Radix, Azure App Service are good options.

How will this feature affect the current Threat Model?
This is the first deployment of Flotilla to the cloud.

1. Keep in mind that all endpoints should be protected by proper authentication.
2. The deployment will be outside any internal network and contain no sensitive data.
3. Secret management - Client secrets and connection strings should be kept secret.

Add check for time conflicts for the post event endpoint

Describe the improvement you would like to see
Currently there is no check in the post event endpoint if an event is already scheduled in the time-slot that the user want to schedule the event. This should be avoided, and the user should be notified that an event is already scheduled for that time period.

How will this change existing functionality?
This will change the existing functionality by making it possible for the backend to reject posted events in case of conflicts.

How will this improvement affect the current Threat Model?
No change.

Add basic hello world backend implementation

Create a basic hello world backend with one endpoint responding with hello world.

This will be the starting point for future functionality and should include a basic test framework.

Describe the new feature you would like to see
Create a basic application in (python/C#) which is a skeleton for a backend API which has a basic hello world endpoint and a framework for writing tests available. This will be the building stone for the rest of the backend API.

Describe the solution you'd like
See above.

How will this feature affect the current Threat Model?
The application itself has effects on the threat model, but that is beyond the scope of this issue. Note that there is not authentication enabled on this application in the beginning, but this should be added later.

Create Active Mission Status Component

The Mission Overview displays a list of all the currently active missions on the asset. The status (In progress, Stopped, No Connection) of each active mission is displayed.

Create an Active Mission Status component. Connected to #8

Handle refresh tokens for authentication

Describe the bug
If the user authenticates in the OpenAPI documentation the authentication token will not be automatically refreshed after 1 hours (token timeout). This should be handled.

To Reproduce
Steps to reproduce the behavior:

• Authenticate in OpenAPI
• Wait 1 hour
• MAke a request

Expected behavior
Instead of failing authentication a refresh token is used to authenticate again and from the users POV there is no change.

Screenshots

Dockerize backend

Describe the improvement you would like to see
Run the backend using a docker container.

How will this change existing functionality?
The functionality should remain the same.

How will this improvement affect the current Threat Model?
Leave blank for maintainers to fill out if you are uncertain about this.

Change default port for Flotilla frontend

Describe the improvement you would like to see
The port should be changed from 3000 as that is the default port of the ISAR application.

How will this change existing functionality?
Instead port 3001 could be used.

• Update dockerfile for frontend to also use this port.
• Make the frontend application start by default on port 3000.

How will this improvement affect the current Threat Model?
NA

Create Active Mission Information Component

In the Robot Overview in https://www.figma.com/file/q6vsNRogzV6r9vTCCDsocd/First-Draft?node-id=0%3A1 a list of all ongoing missions is displayed. The list contains information about all the active mission instance that can be used to monitoring the progress of the mission and some information about the robot doing the mission.

Create an Active Mission Information component that can be used to populate the list of active missions. An Mission Instance object should be created and the information about the robot and mission is connected to the robot object in #6 and mission object in #7.

Add basic hello world React application

Add a basic React application which has the basic framework ready for further development.

A suggestion is to setup a Create-React-Application as a base case to build further on.

https://reactjs.org/docs/create-a-new-react-app.html#create-react-app

Remove '$' from README

Remove '$' from README.md such that when copying commands, you can paste them into a terminal and execute directly.

Create Robot Status Component

The Robot Overview in figma display the status of each robot. For each robot the current status (available/mission in progress/offline) is displayed. Create a robot status component according to the design in figma that can be used by the robot information component. Connected to #6.

Create Robot Information Component

The Robot Overview component in figma displays information about all the robots on the asset. Each item in the list corresponds to the newest available information about a robot.

Create a Robot Information Component that can be used to display the desired information about a robot. Each sub-component don't need to be implemented. A robot object to represent a robot should be created at the same time for easy passing of the state of the robot between different components.

Address warning that Each child should have a unique "key" prop

Describe the bug
The robot overview component seem to create a table without providing the elements with an unique key.

To Reproduce
When running the test from #52 the following warning arise: Warning: Each child in a list should have a unique "key" prop.

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots

Create Start Mission Button

The Mission Overview of available missions in figma have a play button that is used to start the connected mission. Clicking the button should open an popover menu where the user can select which of the available robots to use for the mission and then press play to activate the mission. A basic implementation of this button should be created. The button don't need to be able to start the mission, but should display the described information and interfaces. Connected to #7.

Create Mission Information Component

The Available Mission Overview Component in figma displays a list of all the available missions on a certain asset. Each item in the list corresponds to a single mission and displays some basic information about the mission together with a start mission button.

Create a Mission Information Component that displays all the information as described in figma. The sub-components don't need to be created. A mission object that can be used to pass information about mission around should be created.

Document MQTT endpoints through Async API

Describe the new feature you would like to see
AsyncAPI is a tool similar to OpenAPI which may be used to document subscribe and publish options for a message broker like MQTT. This could be used to document which topics Flotilla expects to receive publishes too and which topics are available to be subscribed on. https://www.asyncapi.com/

Describe the solution you'd like
The AsyncAPI documentation is the go to location for figuring out which topics should have relevant information on them.

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

Set up CI testing and linting for backend

Is your feature request related to a problem? Please describe.
Currently there is no testing of the code in the backend before allowing merging. This can lead to faulty code in the repository and implementing CI testing would possibly catch bugs and errors that are not discovered during traditional code review.

Describe the solution you'd like
A similar test workflow as ISAR that is run and needs to pass before allowing merging of code in to the backend.

Create Battery Status Component

In the Robot Overview in https://www.figma.com/file/q6vsNRogzV6r9vTCCDsocd/First-Draft?node-id=0%3A1 the battery status for each robot is displayed. A component that can be used to display the battery status in accordance with the design should be created. This is issue is connected with #6.

Set up models for database

Create Robot Manager

Describe the new feature you would like to see
The main functionality of Flotilla is to monitor all robots on the asset and give the operator a single point of access to all robots. In the back-end a "robot manager" is needed to monitor each robot and handle communication to and from the robot (start/stopping missions, status from mission etc).

Describe the solution you'd like
A framework for handling the communication from the robot. The manager for each robot should run in its own thread and all the managers should be "gathered" so it's easy for other modules like the API-endpoints for starting and stopping robots to find the right manager and communicate with it. The managers should be generated based on the information about the robots on the asset in the database (name, ip-address and port for ISAR instance, etc). When new robots are added to the database, a new manager for that robot should be added and the robot manager should become available for the API-endpoints.

Example:
A post to the /robots/{robot_id}/start/{mission_id} is received. The API-endpoint should then be able to lookup in an overview of robot managers and find the one matching the robot_id. The endpoint should then be able to send a start signal with the given mission and receive response from the manager if the mission was successfully started or if there is some issues that makes it unable to start the mission. The manager uses the ISAR-endpoint to start the mission.

How will this feature affect the current Threat Model?
The connection to the ISAR-instances might introduce vulnerabilities and should be handled with care (tokens for authentication etc).

Set up endpoints for retrieving robot information.

In the API-specification the /robot endpoint is used to discover and get information about all robots available on the asset and the /robots/{robot_id} is used to get information about a specific robot. Set up both endpoints and use the database to retrieve information about the robots on the asset. This task depends on #33 and #31

Run tests and linter for frontend components

Describe the new feature you would like to see
An automated job should be triggered whenever changes are made to the frontend directory which checks linting and runs tests for the frontend.

Describe the solution you'd like
Using Github actions.

• The tests should be required to pass before merge.

How will this feature affect the current Threat Model?
Should have a positive effect by finding bugs and structuring code.

Update issue templates

Update issue templates to be the same as in ISAR.

This also means adding the improvement and feature labels.

Use single try catch in controllers

The controllers should mostly do input and output handling and let other functions do work.
See this comment in a PR: https://github.com/equinor/flotilla/pull/63/files#r800754192

Generate API-framework using API-specification

There exist multiple tools for generating server framework based on an OpenAPI specification. Based on the API-specification generate this framework using OpenAPIGenerator and do the necessary cleaning of the code to form a base to build the implementation of the endpoints on.

Use https instead of http for endpoints

Describe the improvement you would like to see
Currently http is used as communication protocol for the back-end endpoints. HTTP requests and responses is not encrypted, which is problematic if the content of the requests/responses contains sensitive information.

How will this change existing functionality?
This will lead to some changes in the backend, but most of the work is about generating the appropriate certificates etc. Information about HTTPS and FastAPI can be found here.

How will this improvement affect the current Threat Model?
This will make the application more secure and potentially remove some of the current threats.

Create Robot Extra Information Button

In the Robot Overview and Mission Overview in figma information buttons that are used to display information that don't fit in the list are used. The button should open a popover on click that shows the additional information. The extra information should be customizable and able to show different type of information. Create a Information Button Component that can be used for both robots and mission. Connected to #6 and #7.

Raise exception instead of returning none for database operations

Describe the improvement you would like to see
Currently the output of read operations from the database is returned directly. The return value might include none, which needs to be checked in the controller. This makes the controller logic more complicated. Instead the crud operations should raise some custom errors that can be handled in the controller.

How will this change existing functionality?
Make error handling uniform in the controller. The issue is related to #74

How will this improvement affect the current Threat Model?
No changes.

Setup start/stop missions endpoints

Describe the new feature you would like to see
The backend should provide the frontend with endpoints for starting and stopping robots/missions.

Describe the solution you'd like
Endpoints that forwards the request to start a robot with a given mission to the appropriate ISAR endpoint. Similarly for stop commands.

How will this feature affect the current Threat Model?
The potential to create harm with these endpoints are greater than the others. Different scope/authorization for making calls to these endpoints should be considered.

Set up authentication for API

OAuth2 is used in the API for authentication. This should be based on the general AAD authentication scheme that is used with in the company. In the specification to different scopes are used to differentiate between users with different kind of access: Read and Write. Users with the read scope only have access to the GET endpoints, while users with write scope can access all endpoints including POST and DELETE endpoints. Different types of authentication schemes (no authentication and AAD) should be set up and the desired authentication scheme should be a configurable option for the user.

Dockerize frontend

Describe the improvement you would like to see
Run the frontend application from as a docker container.

How will this change existing functionality?
The functionality should remain the same.

How will this improvement affect the current Threat Model?
Leave blank for maintainers to fill out if you are uncertain about this.

Logging in backend

Describe the new feature you would like to see
For easier debugging, logging should be added to the backend.

Describe the solution you'd like
Every request made to the API should be logged and information that can be useful for debugging (like external requests) should be added. Logging of calls to the database should also be considered (all add, update and delete operations).

How will this feature affect the current Threat Model?
Logging of personal data might lead to GDPR infringement.

Add map component

Log api requests and responses to api logger

Describe the new feature you would like to see
Log api requests and responses to api logger

Describe the solution you'd like
Consider to log api requests and responses to the api logger. If this is implemented, please make sure that the logged data is informative and is logged in a readable way.

How will this feature affect the current Threat Model?
Make sure not to log sensitive information