TinyGS

A Python ground station for the TinyGS satellite network.

Plug in an RTL-SDR dongle and it connects to TinyGS over MQTT, takes the satellite assignments the server sends you, decodes the packets the SDR picks up, and reports them back to the network. A simulator is included, so you can try it without hardware.

This project is in hypercare and needs extensive field testing. It works, but it has not yet run on many antennas, SDRs or sky views. If you deploy it, we would genuinely like to hear how it went, a working station is as useful to us as a broken one. Open an issue, or email info@librecube.org with your setup: SDR, antenna, location, the satellites you caught, and anything that went wrong. Thanks :)

Install

pip install tinygs

That brings the LoRa decoder (softlora) with it. To drive an RTL-SDR dongle, add the hardware backend too:

pip install 'tinygs[sdr]'

Run a station

tinygs-create    # answer some questions once -> station.json
tinygs-run       # go live: connect, receive, report
tinygs-stop      # go offline

tinygs-create asks for your MQTT credentials (send /mqtt to @tinygs_personal_bot on Telegram), your location, and your SDR settings. tinygs-run then keeps the station online.

One catch: the server only assigns satellites to stations with Auto Tune turned on, and that's a setting on the tinygs.com website. The setup guide covers it, along with antennas, credentials and troubleshooting.

Use it from Python

import tinygs
from tinygs.adapters import SimulatorRadio

config = tinygs.StationConfig(
    user="...",              # from the Telegram bot
    password="...",
    mac="AABB11223344",      # any stable 12 hex chars; becomes the MQTT client id
    station_name="my_gs",    # the name shown on tinygs.com
)

tinygs.GroundStation(config, SimulatorRadio(interval=2.0)).run()

StationConfig.from_env() reads the same settings from TINYGS_* variables. For a real station, swap in RtlSdrRadio(sample_rate_hz=250_000.0, gain=30.0).

RtlSdrRadio is just an IQ source plus a decoder, so supporting a different SDR like HackRF, a ZMQ stream, a recorded file, only means a different source.

See tinygs/adapters/, and examples/ for runnable versions of all of this.

Tests

pip install '.[dev]'
python -m pytest

The integration tests run a local MQTT broker, so nothing touches the real TinyGS network.

Docs

• Setting up a live SDR station
• TinyGS MQTT protocol — the wire format this implements, reverse-engineered from the ESP32 firmware

About

Developed with LibreCube, an open source initiative for space and earth exploration systems, as a Google Summer of Code 2026 project. The LoRa decoder it builds on, softlora, comes from the same effort.

MIT licensed. See LICENSE.