4. FlatSat Ground Station

FlatSat Ground Station

FlatSat Ground Station is the official host-side software for FlatSat. It runs on your computer, finds the board over USB and gives you a web dashboard that shows the same information in a browser.

It is more than a remote control. The package contains a full protocol implementation, so it can decode the space packets that arrive over LoRa, tell you what each one carries, build new packets and transmit them. It also carries the training side of the project: a web application that is deliberately vulnerable, and a set of self-contained tools for RF analysis.

The same package drives CatSniffer hardware, which has a single LoRa radio, and it can run with no hardware connected at all, in simulated mode.

• Key capabilities:

  • Radio configuration: sets the frequency, spreading factor, bandwidth, coding rate, output power, preamble, sync word and IQ polarity of each radio, with a stage and apply cycle so that a change reaches the hardware only when you ask for it.
  • CCSDS frame capture, replay and transmission: listens on a radio, decodes every space packet it hears, saves the capture to a file, replays a capture back over the air, or transmits a payload you build yourself.
  • Web dashboard: a Flask and Socket.IO dashboard with live telemetry over WebSocket, a satellite control panel, a radio configuration panel and a mission log.
  • Training lab: three security levels that add vulnerabilities and protections progressively, from cleartext radio and plain web sessions to AES-128-CTR payload encryption and HMAC-SHA256 session signatures.

Warning

Several commands of this tool transmit over the air, and the web dashboard is intentionally vulnerable. Use FlatSat Ground Station only against hardware you own or are authorized to test, and only on frequencies allowed in your country.

FlatSat software

A FlatSat system combines two pieces of software:

1. The board firmware: a program in the separate FlatSat Ground Station repository. It boots the spacecraft, drives both LoRa radios, collects sensor telemetry, and answers USB commands. This firmware is required to communicate with the ground station.

2. The ground station: the flatsat-ground-station Python project. It gives you a command-line tool (flatsat), an interactive console, and a web dashboard to talk to the board over USB, decode CCSDS frames, and run the CTF laboratory. The ground station is the software you run on your computer. It discovers FlatSat boards over USB, connects to their CDC serial endpoints, and provides the CLI, a persistent console, and a web dashboard. It supports a hardware mode (real board) and a simulated mode for running without hardware.

Since the FlatSat Ground Station is build using Python this make it compatible accross must of the dektop operating systems such as Linux, macOS and Windows.

FlatSat Ground Station is also compatible with CatSniffer.

FlatSat Ground Station Installation

Find below the instructions and requirements to start using FlatSat ground station.

Method 1: Run with Docker Compose

Requirements:

• Docker Desktop
• Git/GitHub Desktop

1. Install Docker Desktop from the official website

2. Open Docker Desktop.

3. Open a new terminal in your computer.

4. Clone the repository by sending the command:

   git clone https://github.com/ElectronicCats/flatsat-ground-station.git

Note

You can also download the repository in the web or using GitHub desktop.

5. Navigate to the path where the repository was downloaded.

   cd flatsat-ground-station

   Point to the path where the files were saved.

6. Once in the directory of the FlatSat Ground Station, create a local database directory:

    mkdir -p db

7. Launch the docker container:

   docker compose up -d

   This method will install all the requirement libaries and files needed to make the web ui work, wait for the process to finish.

   Expected output after finishing:

   ✔ Image flatsat-gs:latest                Built                                                                    68.9s
   ✔ Network flatsat-ground-station_default Created                                                                   0.1s
   ✔ Container flatsat-ground-station       Started                                                                   3.2s

8. Open your web browser at the address localhost:5000

9. Enter the Ground station credentials:

   • Admin
     • Username: admin
     • Password: password
   • Operator
     • Username: operator
     • Password: operator123

Note

After closing the web browser tab you can access it again as long as the Docker container is running, to verify this open Docker Desktop and fo to the Container or images section and run the flatsat ground station again (This also applies when the docker container has stopped after restating the PC or similar).

Method 2: Natively run it with Python

Requirements:

• Python 3.11 or newer
• pip
• Git/GitHub Desktop

1. Install Python 3.9 or later from python.org and tick Add Python to PATH in the installer.

2. Open a new terminal in your computer.

3. Clone the repository by sending the command:

   git clone https://github.com/ElectronicCats/flatsat-ground-station.git

Note

You can also download the repository in the web or using GitHub desktop.

4. Navigate to the path where the repository was downloaded.

   cd flatsat-ground-station

5. Create a virtual enviroment:

   python -m venv .venv

6. Activate the virtual enviroment:

   • Linux/MacOS:

     source .venv/bin/activate

   • Windows:

     .\.venv\Scripts\Activate.ps1

The creation of the virtual environment can be confirmed if the terminal shows a text similar to this:

PS C:\Users\[username]\flatsat-ground-station> python -m venv .venv
PS C:\Users\[username]\flatsat-ground-station> .\.venv\Scripts\Activate.ps1
(.venv) PS C:\Users\[username]\flatsat-ground-station>

7. Once the virtual environment is active, run the following command to install the required libraries:

   pip install -r requirements.txt

8. Grant serial port permissions (Linux only):

   sudo usermod -aG dialout $USER

   Then log out and login after sending this command.

9. Set CTF Level (1: Easy, 2: Medium, 3: Hard)

   • Linux:

     export FLATSAT_LEVEL=1

   • macOs:

     export FLATSAT_LEVEL=1

   macOS Monterey and later versions uses port 5000 for AirPlay Receiver. use a different port:

   export FLATSAT_PORT=5001

   • Windows:

     $env:FLATSAT_LEVEL="1"

10. Start Ground Station Webapp:

    python -m webapp.app

11. Open your web browser at the address localhost:5000 or localhost:5001 (only MacOS).

12. Enter the Ground station credentials:

    • Admin
      • Username: admin
      • Password: password
    • Operator
      • Username: operator
      • Password: operator

Here is a short video on how it should look after the installation:

---