Skip to content

STARDOS Setup

Jump to bottom
Richard Snider edited this page Feb 16, 2024 · 15 revisions

STARDOS is currently on ROS2 version Humble. ROS2 versions mirror Ubuntu versions- so we'll need a machine with Ubuntu 22.04 installed to run Humble.

Automatic installation

There exist a collection of scripts to set up a STARDOS environment. They are found in the STARDOS quickstart repository. You should only need to run one of them. Which one to run depends on your use case.

  • computer-setup.bash is meant to set up a headless payload or copilot STARDOS machine on hardware you intend to use on a drone.
  • simulation-setup.bash is meant to set up a simulation or even a ground station.

The computer-setup.bash script removes netplan and sets up a custom network stack allowing a payload and a copilot to talk together without the use of a router. Because of this, it is not ideal to use this script for a computer that still needs to connect to the internet normally. simulation-setup.bash, on the other hand, just installs STARDOS's dependencies, pulls some STARDOS packages, and installs (but does not enable) the STARDOS systemd services.

Manual installation

You can also get everything yourself using the following steps.

Installing 22.04

If you're setting up STARDOS for testing, you may want to use 22.04 Desktop.

If you're setting up on a payload, VM, or other headless STARDOS machine, you'll want 22.04 Server.

To start off, you'll probably want to remove any snaps from the system. They add bloat and interop poorly with other programs. The process needs to be updated now and again, but this guide can show you the general idea.

Install the version required for your hardware as normal. Make sure you install python and pip, as well as some common build dependencies:

sudo apt install python3 python3-pip build-essential

Installing ROS2

Next, install Humble from the instructions provided on the ROS2 wiki. Make sure you install the ros-humble-desktop-full package to include build dependencies like colcon.

Make sure you set your environment variables for ROS2 by adding the setup.bash (matching your shell's extension) to your shell's rc file.

Installing STARDOS

There are multiple ways to acquire the STARDOS source files.

Acquiring the STARDOS repositories

Master STARDOS repository

Clone the aggieair/STARDOS repo to the VM. You may need to add a new SSH key to your account first, to validate who you are. This may not be fully up-to-date, and it may not be comprehensive but it can work.

git clone git@github.com:AggieAir/STARDOS.git && git submodule init && git submodule update

Individual STARDOS repositories

You can also download STARDOS packages individually by placing them all in /opt/stardos/workspace/src. All STARDOS repositories are hosted on GitHub and owned by AggieAir. They all begin with stardos_, except for the two libraries.

Note that sometimes a drone will contain multiple computers. Typically, in this scenario, one computer will be designated as the copilot and will handle all communication with the ground station and the other will be designated as the payload and will handle the data collection. The two will communicate over an ethernet connection. If there is only one computer on the aircraft, it will fill both the payload and copilot roles. This is called a hybrid configuration.

At the very minimum, you will need:

  • stardos_interfaces: provides the ROS interfaces needed for STARDOS nodes to communicate with each other.
  • stardos_control: the defining program that runs on a STARDOS computer. Starts up all other STARDOS nodes according to a mission configuration.
  • stardos_utilities: contains scripts, configuration files, and systemd service files used by stardos nodes.
  • stardos_system_status: provides a STARDOS node that reports the status of the computer, viewable on the ground station.

For a computer that will run on a drone, you will also need:

For ground stations and copilot (or hybrid) computers, you will need:

  • stardos_datalink: provides a means for systems to communicate with each other across a radio link.

For payload (or hybrid) computers, you will additionally need:

  • libstardos: a C++ library that can power a data collection or processing node
  • pylibstardos: the python version of libstardos
  • stardos_capture_groups: a collection of capture group nodes.
  • stardos_tagger: a node that uses a stream of data from an autopilot to tag images with data bout where the image was taken.
  • stardos_writer: a node that writes data to the disk, typically at the end of a pipeline.
  • Additional pipeline nodes, which will be specific to your system:
    • Any relevant camera nodes, traditionally published with the stardos_sensors_ prefix.
    • Any relevant processing nodes and sink nodes.

Building the packages

Once you have all of the STARDOS repositories installed, try running colcon build in the root directory of the workspace (/opt/stardos/workspace). If you receive an error like /usr/lib/python3.10/site-packages/setuptools/command/install.py:34: SetuptoolsDeprecationWarning: setup.py install is deprecated. Use build and pip and other standards-based tools, follow the instructions on this ROS Answers question to downgrade the setuptools package to the appropriate version.

Creating the configuration files

computer.json

STARDOS requires the existence of the file /opt/stardos/computer.json, which provides context for the control node when it starts up. It should be a dictionary containing the following arguments:

  • role: an integer representing what role this computer plays in STARDOS. See here for current roles.
  • system: the name of the system. Attested system names are gcs for a GCS, simulation for a simulated payload, or the name of the aircraft for an aircraft.
  • name: the name of the computer. Attested computer names are copilot for a standalone copilot (in fact, STARDOS assumes this one), apl-xxx for standalone payloads (where xxx is a three-digit number assigned sequentially pursuant to AggieAir's payload naming convention), and apls-xxx for simulated payloads, mimicking the standard for payload naming.
  • computer: should be the same as name, for backwards compatibility. It may be okay to omit this on a new installation.
  • domain: the ROS domain. For a ground control computer, this should be 2. For an aircraft computer, it should be 1.

A template for the GCS computer is as follows:

{
    "role": 3,
    "computer": "gcs",
    "system": "gcs",
    "name": "gcs",
    "domain": 2
}

A template for a simulated hybrid computer is as follows:

{
    "role": 0,
    "computer": "apls-000",
    "system": "simulation",
    "name": "apls-000",
    "domain": 1
}

Other computer.json files can be derived from these examples and the documentation above.

settings.json

STARDOS also expects to see /opt/stardos/settings.json, which provides context for the control node when it starts up. It should be a dictionary with the keys representing distinct roles, namely payload, copilot, and gcs. The keys should only be present for the roles the computer will be fulfilling. Hybrid computers will have payload and copilot present; all other computers should only have the file that fits their role.

The settings for each role are as such:

  • gcs:
    • mavlink_url: a connection URL to pass to mavlink-router for opening a connection.
  • copilot:
    • mavlink_url: same as the setting in gcs
  • payload:
    • config_loading_mode: (defined here) how and when to load mission configs. Must be one of the following strings.
      • "upload": Wait for a config to be uploaded. Do not automatically parse stored configs that have been previously uploaded.
      • "boot": Automatically read and parse stored config from disk when the system boots.
      • "start": Boot to READY_FOR_MISSION_START state, read and parse configured config from disk when start is pressed. Fail if config fails to parse.
    • enforce_date: a boolean. If true, the payload will reject all configs whose dates do not match the computer's date.
    • allow_pilot_control: a boolean. If true, the payload will listen to a switch on the remote to start and end missions. See here for implementation. This may not work on your hardware. If you don't know, keep this false.
    • aircraft: The name of the aircraft. As far as I can tell, this is never used; however, make it accurate for compatibility, and don't change this without changing computer.json.
    • config_to_load: a string. If config_loading_mode is not "upload", then this field specifies which config should be considered the default. It must be the name of the file (sans-extension) from /opt/stardos/configs/. Files are named based on their UUIDs, which can be a bit confusing; alternatively, latest refers to the most-recently uploaded mission file.

After all of this, you can change these variables using the StarCommand interface.

Installing StarCommand

StarCommand is a browser-based ground control system that provides a robust user interface for monitoring the status of STARDOS nodes running on a remote system.

First, clone StarCommand into /opt/starcommand. Once that's done, clone the StarCommand relay into /opt/stardos/workspace/src. Make sure to build the package using colcon.

Navigate to /opt/starcommand and run npm install to fetch the dependencies. Run npm run dev and following the instructions in your terminal to see the interface and make sure it works. Installing the service will be described in the next section.

Installing scripts and services

Finally, navigate to the stardos_utilities directory and run install.sh. Input your password when prompted. This will install some scripts (full list here) and some services (full list here).

You will need to enable some of these services. Which ones you will need are determined by which kind of machine you are installing on. See this table:

Service Copilot Payload Hybrid GCS
stardos-control ✔️ ✔️ ✔️ ✔️
stardos-datalink-ground ❌ ❌ ❌ ✔️
stardos-datalink-aircraft ✔️ ❌ ✔️ ❌
stardos-settings-server ✔️ ✔️ ✔️ ✔️
stardos-status ✔️ ✔️ ✔️ ❌
stardos-starcommand ❌ ❌ ❌ ✔️

A reboot may be necessary for all changes to take effect.

Clone this wiki locally