2. Getting Started with Starling

2.1 Contents

2.2 Install Docker

The only dependency of running and using Starling locally is the [Docker] containerisation software. Please visit docker's installation page for further details. We recommend using Starling on linux based systems, but it should work on Windows and possible Mac depending on the state of the Docker.

2.2.1 Linux/ Ubuntu

2.2.1.1 Install Script

For linux, we have provided a helpful install script. First you will need to clone the Murmuration github repository:

git clone https://github.com/StarlingUAS/Murmuration.git

Then run:

sudo ./starling install

Once that completes you should be all good to go for the next step.

2.2.1.2 Manual Installation

For Linux systems, see the following install page. There are multiple ways of installation docker, but we recommend installing using the repository method:

  1. Update the apt repository and install requirements

    sudo apt-get update

sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

  2. Add Docker's official GPG key:

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

  3. Install Docker (and docker-compose!):

    sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli docker-compose containerd.io

  4. Test Docker installation:

    sudo docker run hello-world

This will install Docker, accessible using sudo root privileges only. To use docker without sudo, run the following (be aware of issues with this)

  1. Run the following

    sudo groupadd docker
sudo usermod -aG docker $USER

  2. Log out and log in again to enforce changes (may need to restart)

  3. Verify that it was successful:
    docker run hello-world

That is Docker on Linux installed. See the original page for any further details.

2.2.2 Windows

For Windows systems, please see the windows installation instructions for full details. You will need to install Docker Desktop for Windows.

Follow the instructions and tutorial below, but refer to our Windows Support page if you have issues.

Starling has been fully tested on Windows, and both single and multi-agent cluster testing is available through the use of the Starling CLI. However it is recommended that you use WSL rather than powershell.

2.2.3 Mac OS

For Mav systems, please see the Mac Os installation instructions for full details. You will need to install Docker Desktop for MAC OS.

Starling has not be tested on MAC OS, so there is no guarantee that it is functional. However in theory the single-agent non-cluster (docker-only) application should be compatible.

2.3 Get Starling

For simple usage, or for usage as a simulator, you can use the Murmuration repository which gives a number of starling examples and a command line interface.

git clone https://github.com/StarlingUAS/Murmuration.git

For more advanced usage, or to see examples of the core elements, clone the Starling repository:

git clone https://github.com/StarlingUAS/ProjectStarling.git

2.4 Using Starling

Starling provides a framework for users to implement almost any drone related experiment or application. However, we have identified that most applications fall into the following categories. Therefore we have provided detailed user guides for these use cases. It is recommended that the user follow these guides to run starling before starting your own implementation as these guides will also slowly introduce you to the concepts and details Starling uses.

These user guides are all located on the side navigation bar for easy access.

A key idea is the fact that the controller you develop, whether onboard or offboard, will be identical regardless of which step you are in. This therefore designs a workflow for the development of controllers.

2.4.1 Single Drone Applications

For single drone applications, there are 3 steps to the development of a controller running onboard (on the 'drone' itself) or offboard (on a separate machine):

  1. Step 1: Single Drone testing on local machine using Docker only

    • Follow the following user guide
    • Simplest deployment method and the quickest way to get a simulation (gazebo) and drone (px4, mavros) instance running.
    • Quick and easy way to test the basic functionality of your controller without worrying about too may other factors.
    • Step 2: Single Drone testing on local cluster
    • Follow the following user guide
    • Once you have your controller mostly working and debugged, the next step is to test it within the network and system architecture used when flying real drones.
    • This will require learning a little bit about the cluster architecture and how Starling works under the hood.
    • Step 3: Single Drone flying at the Robotics Laboratory
    • Follow the following user guide
    • Detailing how to run your controller on real drones at the Bristol Robotics Laboratory

2.4.2 Multiple Drone Applications

For multiple drone applications, there are also 3 steps to the development of a centralised or decentralised, onboard or offboard controller.

  1. Step 1: Single Drone testing on local machine using Docker only
    • Follow the following user guide
    • Simplest deployment method and the quickest way to get a single simulation (gazebo) and drone (px4, mavros) instance running.
    • Quick and easy way to test the basic functionality of your controller without worrying about too may other factors.
    • Can be used to quickly protype controllers before testing with multiple vehicles.
  2. Step 2: Multiple Drone testing on local cluster
    • Follow the following user guide
    • The cluster facilitates the multi-agent capability of starling.
    • The guide takes you through the basic concepts required for running multi-agent applications
  3. Step 3: Multiple Drones flying at the Robotics Laboratory
    • Follow the following user guide
    • Detailing how to run your controller on real drones at the Bristol Robotics Laboratory

2.5 FAQs