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.
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.
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.
Install
That brings the LoRa decoder (softlora) with it. To drive an RTL-SDR dongle, add the hardware backend too:
Run a station
tinygs-createasks for your MQTT credentials (send/mqttto @tinygs_personal_bot on Telegram), your location, and your SDR settings.tinygs-runthen 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
StationConfig.from_env()reads the same settings fromTINYGS_*variables. For a real station, swap inRtlSdrRadio(sample_rate_hz=250_000.0, gain=30.0).RtlSdrRadiois 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
The integration tests run a local MQTT broker, so nothing touches the real TinyGS network.
Docs
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.