5. FlatSat CLI

FlatSat CLI

What is FlatSat CLI?

FlatSat CLI is a rich-powered terminal interface for device discovery, RF sniffing, payload forging, and shell access.

FlatSat CLI Installation

Method 1: Windows Only

Download the install_windows.bat from the releases section of the flatsat-ground-station repository.
Download the setup_windows.ps1 file from the main page of the flatsat-ground-station repository.
- Click on the setup-windows.ps1 file.
- Click on the "Download raw file" ⬇️
Open the setup_windows.ps1 file by right-clicking on it and select Run with Powershell. Note: If you receive a Smart App Control warning, you will need to disable this Windows feature. This warning is caused by an unsigned executable file.
Open the install_windows.bat.

Now FlatSat CLI is installed systemwide; you can open a new terminal session and write the command flatsat to confirm the installation.

Method 2: Natively run it with Python (Windows, Linux & macOS)

Requirements:

Python 3.11 or newer
pip
Git/GitHub Desktop

Install Python 3.9 or later from python.org and tick Add Python to PATH in the installer.
Open a new terminal on your computer.

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.

Navigate to the path where the repository was downloaded.
```
cd <flatsat-ground-station-path>
```
Create a virtual enviroment:
```
python -m venv .venv
```

Activate the virtual enviroment:

Linux/macOS:
```
source .venv/bin/activate
```
Windows:
```
.\.venv\Scripts\Activate.ps1
```

Once the virtual environment is active, run the following command to install the required libraries:
```
pip install -r requirements.txt
```
Grant serial port permissions (Linux only):
```
sudo usermod -aG dialout $USER
```
Then log out and log in after sending this command.
Autocompletion integration (Linux & macOS only). Run the command:

flatsat completion install

Now that FlatSat CLI is installed, send the command flatsat to confirm the installation.

FlatSat CLI Usage

To start using FlatSat CLI, you can use the command in a terminal session:

flatsat

Expected output:

╭─ Electronic Cats - PWNLAB ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                                                                                               │
│        :=--             --=-       |                                                                                                                                                                          │
│        -====-         -=====       |                                                                                                                                                                          │
│        :===================-       |                                                                                                                                                                          │
│         ===================:       |                                                                                                                                                                          │
│    -   :==--===========--==-   -   |  flatsat                                                                                                                                                                 │
│   -===:===-   :=====-   -==-.-=--  |  vx.x.x                                                                                                                                                                  │
│  --    ====-   :===-   -====    -- |  Your FlatSat control terminal.                                                                                                                                          │
│  -=:   :===================-   .=- |                                                                                                                                                                          │
│   ---=-- -===============-  -=---  |                                                                                                                                                                          │
│   ---       --=======--        --  |                                                                                                                                                                          │
│                                                                                                                                                                                                               │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Usage: flatsat [OPTIONS] COMMAND [ARGS]...

  FlatSat Host CLI: manage and configure your FlatSat boards easily.

Options:
  -V, --version      Show the version and exit.
  -d, --device TEXT  Target FlatSat board: index from `flatsat devices` or its
                     serial number.
  -p, --port TEXT    Force direct connection to a custom shell port (e.g.
                     /dev/ttyACM3).
  -h, --help         Show this message and exit.

Commands:
  cmd         Send a raw shell command to the FlatSat console
  color       Set custom RGB color on the NeoPixel LED
  completion  Install shell tab completion for flatsat.
  config      Stage and apply LoRa radio configuration settings
  console     Open a persistent interactive serial console session with...
  devices     List all connected FlatSat boards and their endpoints
  difficulty  Get or set workshop security/difficulty level
  flight      Get or set flight operational state (idle, nominal, safe,...
  identify    Trigger board LED identification blink
  mode        Get or set satellite operation mode
  reboot      Reboot the board into the BOOTSEL bootloader
  replay      Replay captured CCSDS frames from a file back over RF
  sensors     Read live telemetry data from BME280 and LIS2DH sensors
  sniff       Sniff CCSDS frames over LoRa and optionally save them to a...
  status      Read system status and firmware information
  transmit    Transmit a custom hex or text string over RF

Available commands

Usage:

flatsat <OPTIONS> <COMMAND> <ARGS>

Argument `<OPTIONS>`	Description
`-v`, or `--version`	Show the version and exit
`-d`, or `--device`	Target FlatSat board: index from 'flatsat devices' or its erial number
`-p`, or `--port`	Force direct connection to a custom shell port (e.g., /dev/ttyACMX)
`-h`, or `--help`	Show the available options and commands

Argument `<COMMAND>`	Description
`cmd`	Send a raw shell command to the FlatSat console
`color`	Set custom RGB color on the NeoPixel LED for 3 seconds
`completion`	Install shell tab completion for flatsat
`config`	Stage and apply LoRa radio configuration settings
`console`	Open a persistent interactive serial console session
`devices`	List all connected FlatSat boards and their endpoints
`difficulty`	Get or set flight operational state
`identify`	Trigger board LED identification blink
`mode`	Get or set satellite operation mode
`reboot`	Reboot the board into the BOOTSEL bootloader
`replay`	Replay captured CCSDS frames from a file back over RF
`sensors`	Read live telemetry data from BME280 and LIS2DH sensors
`sniff`	Sniff CCSDS frames over LoRa and optionally save them
`status`	Read system status and firmware information
`transmit`	Transmit a custom hex or text string over RF

Every command except devices and completion talks to a board, and picks the only board connected. With two or more boards connected, select one with -d or --device, using the index or the serial number printed by flatsat devices.

Checking the connected devices

devices command finds every FlatSat board plugged in to the computer and prints the three serial ports of each one. It is the first command to run after installation.

Usage:

flatsat devices

Expected output:

                             Found 2 FlatSat device(s)
╭──────────────────────┬────────────────┬────────────────┬──────────────┬─────────╮
│ Device               │ Radio 0 (CDC0) │ Radio 1 (CDC1) │ Shell (CDC2) │ Health  │
├──────────────────────┼────────────────┼────────────────┼──────────────┼─────────┤
│ [0] 503342353230000E │ \\.\COMXX      │ \\.\COMXX      │ \\.\COMXX    │ HEALTHY │
│ [1] E661A89753656A35 │ \\.\COMXX      │ \\.\COMXX      │ \\.\COMXX    │ HEALTHY │
╰──────────────────────┴────────────────┴────────────────┴──────────────┴─────────╯

The Health column reports HEALTHY when every port of the board could be opened, PARTIAL when the shell is open but at least one radio port was not found, and CRITICAL when the shell could not be opened.

Important

When no board is listed, check the USB cable and the serial port permissions.

Command `identify`

Makes the board identify itself by blinking its status LED for a couple of seconds. Use it to find out which physical board a -d index refers to.

Usage:

flatsat identify

Configuration commands

Command `color`

Sets the color of the status LED. Each channel takes a value from 0 to 255.

Usage:

flatsat color R G B

Option	Description	Default
`R`	Red channel, from 0 to 255	Required
`G`	Green channel, from 0 to 255	Required
`B`	Blue channel, from 0 to 255	Required

Example:

flatsat color 145 0 255

Command `config`

Reads, stages, and applies the LoRa settings of a radio. Frequency, spreading factor, bandwidth, coding rate, output power, preamble, IQ polarity, and sync word are staged on the board, and the --apply is what writes them to the hardware.

Usage:

flatsat config <OPTIONS>

Argument `<OPTIONS>`	Description
`--radio`	Radio to configure: `0`, `1` or `ALL` (default: 0)
`--freq`	LoRa frequency in Hz (e.g. 915000000)
`--sf`	Spreading Factor (7-12)
`--bw`	Bandwidth in kHz: `125`, `250` or `500`
`--cr`	Coding rate denominator, from 5 to 8
`--power`	Transmit power in dBm, from -9 to 22
`--syncword TEXT`	Sync word: `public`, `private` or a hex value such as `0x2D`
`--mode`	Radio output mode: `stream` or `command`, applied at once
`--apply`	Apply staged changes immediately
`-d`, or `--device TEXT`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, or `--port TEXT`	Force direct connection to a custom shell port (e.g., /dev/ttyACM3).
`-h`, or `--help`	Show this message and exit.

With no option, the command prints the current settings of the selected radio:

Example:

flatsat config --radio 0 --freq 915000000 --sf 7 --apply

In this example the radio 0 is configured to a frequency of 915 MHz and a spread factor of 7.

Command `difficulty`

Reads or sets the security level of the lab, from 0 to 3.

Usage:

 flatsat difficulty <VALUE>

Options	Description
`VALUE`	Security level, from 0 to 3
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g., /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.

Note

difficulty level 0 is not available throug FlatSat CLI as it is ment for training.

Example:

flatsat difficulty -d 1 2

The number after difficulty:, once the command is sent, is the level reported by the board. The same level decides how much protection the payloads of the radio link use, so set it on both boards of a link.

Command `flight`

Reads or sets the flight operational state: idle, nominal, safe or debug. This command can be used for boards acting as satellites and ground_station. See section Command mode.

Usage:

flatsat flight <OPTIONS> <flight-mode>

Flight mode available:

idle
nominal
safe
debug

Argument `<OPTIONS>`	Description
`--difficulty`	SDLS level for the RF telecommand (ground station only). Defaults to the board's difficulty. (0<=x<=3)
`-d`, or `--device TEXT`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, or `--port TEXT`	Force direct connection to a custom shell port(e.g. /dev/ttyACM3).
`-h`, or `--help`	Show this message and exit.

Example:

flatsat flight safe --difficulty 3

Command `mode`

Reads or sets the role of the board: whether it behaves as a satellite, as a ground station, or as a raw radio bridge.

Usage:

 flatsat mode <OPTIONS> <mode>

Argument `<OPTIONS>`	Description
`--profile`	TinyGS profile to spoof (only with 'tinygs'). [default: norbi]
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.

Argument `<mode>`	Description
`mission`	Set FlatSat in satellite role (radios stream)
`ground_station`	Set FlatSat in ground station role (radios stream)
`raw`	Ground station firmware, radios stream
`tinygs`	Ground Station firmware, norbi profile by default

Example:

flatsat mode -p COM34 tinygs --profile norbi

Utility commands

Command `cmd`

Sends one raw command to the shell of the board and prints its answer. Use it for shell commands that have no dedicated command in this tool.

Usage:

flatsat cmd "RAW"

Option	Description
`RAW`	Shell command to send, in quotes

Example:

flatsat cmd "lora_config R0"

Command `console`

Opens an interactive session. Everything you type is sent to the shell of the board, and the answer is printed immediately, without leaving the prompt. Type exit, quit or q to close the session.

Usage:

flatsat console <OPTIONS>

Argument `<OPTIONS>`	Description
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.

Example:

Connected to FlatSat interactive console.
Type any command (e.g. status, identify, mode gs, flight nominal) and press Enter.
Type 'exit' or 'quit' to close the session.

flatsat> mode gs
mode: gs
flatsat> exit
Closing interactive console session...

Command `reboot`

Usage:

flatsat reboot <OPTIONS>

Argument `<OPTIONS>`	Description
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.

Command `replay`

Sends the frames of a capture file back over the radio, in the same order and with the same protection level that the capture was made with.

Usage:

flatsat replay <OPTIONS> CAPTURE_FILE

Argument `<OPTIONS>`	Description
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.
`CAPTURE_FILE`	Capture file written by `sniff --output`
`--delay`	Seconds to wait between two frames
`--modify-seq`	Increment the sequence counter of every frame
`--difficulty`	SDLS level applied to the frames, from 0 to 3

Example:

flatsat replay uplink.json --delay 0.5 --difficulty 3

With --modify-seq, each line also reports the old and the new sequence counter. It is the flag to use against a board that rejects frames it has already seen.

Command `sensors`

Reads the accelerometer and the environment sensor. Acceleration is reported in milligrams of gravity (mg) for the three axes, temperature in degrees Celsius, pressure in pascals, and humidity as a percentage.

Usage:

flatsat sensors

Expected output:

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

Command `sniff`

Listens on one radio, decodes every CCSDS space packet that arrives, and optionally saves the capture to a file (if enabled). This is the command that shows you what the other board is sending.

Usage:

flatsat sniff <OPTIONS>

Argument `<OPTIONS>`	Description
`-d`, `--device`	Target FlatSat board: index from `flatsat devices` or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.
`-r`, `--radio`	`0` to listen to the telemetry downlink, `1` to listen to the telecommand uplink
`-t`, `--duration`	Seconds to listen; `0` runs until you press `Ctrl+C`
`-o`, `--output`	File to write the captured frames to. By default the CLI does not save the sniffing session
`-n`, `--count`	Stop after this many frames; `0` means no limit
`--difficulty`	SDLS level used to decrypt the payloads, from 0 to 3

Example:

flatsat sniff -t 0 -o capture.json

Expected output:

Sniffing Radio 0 (telemetry downlink) until Ctrl+C (SDLS level 1)...
Output: capture.json
#1: TM APID=0x010 seq=42 CRC=OK (18 bytes, RSSI -87)
#2: TM APID=0x011 seq=43 CRC=OK (18 bytes, RSSI -86)
Captured 2 frames -> capture.json

Each line is one frame: TM or TC for telemetry or telecommand, the APID of the subsystem that sent it, the sequence counter, whether the CRC-16-CCITT checksum is valid, the size in bytes, and the signal strength in dBm when the board reports it.

When nothing arrives, the tool tells you so:

No CCSDS frames captured. Is the satellite transmitting on this radio?

Command `status`

Reads the firmware version and the state of both radios from the board.

Usage:

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)

Command `transmit`

Builds and transmits one payload of your own.

flatsat transmit [OPTIONS] DATA

Argument `<OPTIONS>`	Description
`-d`, `--device`	Target FlatSat board: index from 'flatsat devices' or its serial number.
`-p`, `--port`	Force direct connection to a custom shell port (e.g. /dev/ttyACM3).
`-h`, `--help`	Show this message and exit.
`DATA`	Payload to transmit, as hexadecimal or as text with `--text`
`--text`	Send `DATA` as plain ASCII or UTF-8 text instead of hex
`--protect`	Apply SDLS protection before transmitting
`--repeat`	Number of times to transmit the payload
`--delay`	Seconds to wait between repeats
`--difficulty`	SDLS level used with `--protect`, from 0 to 3

Without --protect, the bytes you give are transmitted as they are. With --protect, the payload is wrapped in a CCSDS telecommand and protected with the security level of the board before it goes on the air.

Example of a raw frame:

flatsat transmit 1af0c30500ab

Example of a text payload:

flatsat transmit --text "HELLO SAT"

5. FlatSat CLI

FlatSat CLI

What is FlatSat CLI?

FlatSat CLI Installation

Method 1: Windows Only

Method 2: Natively run it with Python (Windows, Linux & macOS)

FlatSat CLI Usage

Available commands

Checking the connected devices

Command identify

Configuration commands

Command color

Command config

Command difficulty

Command flight

Command mode

Utility commands

Command cmd

Command console

Command reboot

Command replay

Command sensors

Command sniff

Command status

Command transmit

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Command `identify`

Command `color`

Command `config`

Command `difficulty`

Command `flight`

Command `mode`

Command `cmd`

Command `console`

Command `reboot`

Command `replay`

Command `sensors`

Command `sniff`

Command `status`

Command `transmit`