3. First time using FlatSat - ElectronicCats/FlatSat GitHub Wiki

First time using FlatSat

Using the FlatSat Ground Station web app

Requirements:

  • A FlatSat board with its firmware loaded and a data-capable USB-C cable.
  • An antenna on each SMA connector that you plan to use for a radio test.
  • FlatSat Ground Station Web app installed; check out the instructions on FlatSat Ground Station Installation.
  • A second FlatSat or CatSniffer board if you want to test the radio link between two boards.

Local hardware verification with FlatSat GroudnStation

  1. After running the FlatSat Ground Station web app, either using the Docker or Python method, go to the web browser and open a new tab.
  2. Write in the search bar localhost:5000 (use port 5001 for macOS: localhost:5001). This will redirect you to the main page:

  1. Enter the credentials to login.

  2. Once in the main view, click on the Scan USB button to detect the FlatSat connected through USB.

  3. In the drop-down menu that appears next to the Scan USB button, select the FlatSat you would like to work with.

  4. After selecting the FlatSat board, click on Connect. If there are other FlatSat or devices transmitting under the same configuration, you will read the packets caught by FlatSat right away.

Using FlatSat Ground Station CLI

Requirements:

  • A FlatSat board with its firmware loaded and a data-capable USB-C cable.
  • An antenna on each SMA connector that you plan to use for a radio test.
  • FlatSat CLI installed on Windows, macOS, or Linux.
  • A second FlatSat or CatSniffer board if you want to test the radio link between two boards.

Local hardware verification

  1. Connect the USB-C port of FlatSat to your computer. The board starts by itself and appears as three serial ports at 115200 baud, one for each radio and one for the shell console.

  2. Check that the board is detected

flatsat devices

Expected output:

Found 1 FlatSat device(s)

 Device          Radio 0 (CDC0)  Radio 1 (CDC1)  Shell (CDC2)   Health
 [0] FLATSAT0001 /dev/ttyACM0    /dev/ttyACM1    /dev/ttyACM2   HEALTHY

The serial number of your board and the names of the ports depend on your computer, so expect different values. The Health column tells you whether all the ports of the board could be opened. HEALTHY means everything is ready; PARTIAL means the shell is open, but at least one radio port was not found.

[!IMPORTANT] On Linux, a board is listed but its ports cannot be opened when your user does not have permission on them. Complete FlatSat CLI- Natively run wi with Python Linux and MacOS and log in again before you continue.

  1. Read the board status

Once the board is detected, read what the t reports:

flatsat status

Expected output:

SYSTEM STATUS
FW: dev-f81af0b-dirty
Git: f81af0b (dirty)
Built: 2026-08-11T20:38:22Z
Compiler: GNU 12.2.0
Flat-Sat FW: dev-f81af0b-dirty  Active Radio: 0 (TX: 1, RX: 0)
  RadioManager State: LISTENING
  Radio0: LoRa  mode=stream  lora_init=1  fsk_init=0  (Ready)
  Radio1: LoRa  mode=stream  lora_init=1  fsk_init=0  (Ready)

The first three lines identify the firmware. The following lines show the state of each radio.

  1. Read the onboard sensors
flatsat sensors

Expected output:

TELEMETRY SENSORS
x=12 mg y=-4 mg z=1021 mg
Temp: 23.5 C
Press: 101325 Pa
Humid: 48%

The first line is the accelerometer; the three values that follow come from the BME280. Reading them twice a few seconds apart gives slightly different values, which confirms that the board is really measuring.

Listening to the telemetry downlink

This part needs a second FlatSat board or a CatSniffer, one acting as the satellite and one acting as the ground station.

  1. Set the satellite board to mission mode on the board that must transmit telemetry:
flatsat mode mission

Expected output:

ℹ mode sat -> OK role: satellite
ℹ lora_mode ALL stream -> LoRa mode set to STREAM (slow blink)
✓ Mode set to 'mission'.
ℹ Identifying the board that changed mode (blinking LEDs)...
⚠ Identifying board...

The board blinks its status LED in white color so that you can tell at a glance which board changed its role.

  1. Set the ground station board and listen on the second board:
flatsat mode ground_station
flatsat sniff

Expected output:

mode gs -> OK
lora_mode ALL command -> OK
lora_apply ALL -> OK
Mode set to 'ground_station'.
Identifying the board that changed mode (blinking LEDs)...
Sniffing Radio 0 (telemetry downlink) for 30s (SDLS level 1)...
#1: TM APID=0x010 seq=42 CRC=OK (18 bytes, RSSI -87)
#2: TM APID=0x011 seq=43 CRC=OK (18 bytes, RSSI -86)

FlatSat will blink in a green color when streaming or blue when in command mode; a long blue light will indicate a packet was caught by the FlatSat.

Each line is one space packet that arrived over the air. TM is telemetry, APID identifies which subsystem sent it, seq is the sequence counter, and CRC tells you whether the frame arrived intact.

  1. Open the web dashboard

If you prefer to watch the telemetry in a browser, start the web dashboard of FlatSat Ground Station and open the address it prints:

[!Important] Installing FlatSat Ground Station webapp is required. Check: FlatSat Ground Station Installation.

flatsat-web

Log in with the credentials.

You can then follow the instructions from the first method described in this same page.