Metadata-Version: 2.4
Name: tinygs
Version: 0.1.0
Summary: TinyGS ground station integration - MQTT client, telemetry, and radio control
Author: LibreCube
License-Expression: MIT
Project-URL: Homepage, https://github.com/LibreCube/tinyGS-integration
Keywords: tinygs,ground-station,lora,satellite,mqtt,amateur-radio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Ham Radio
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paho-mqtt<3,>=1.6
Requires-Dist: softlora>=0.3
Provides-Extra: sdr
Requires-Dist: pyrtlsdr; extra == "sdr"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: amqtt; extra == "dev"
Dynamic: license-file

# TinyGS

[![Google Summer of Code 2026](https://img.shields.io/badge/Google%20Summer%20of%20Code-2026-fbb040?logo=google&logoColor=white)]()

A Python ground station for the [TinyGS](https://tinygs.com) 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](mailto:info@librecube.org)** with your setup: SDR,
> antenna, location, the satellites you caught, and anything that went wrong.
> Thanks :)

## Install

```bash
pip install tinygs
```

That brings the LoRa decoder ([softlora](https://pypi.org/project/softlora/))
with it. To drive an RTL-SDR dongle, add the hardware backend too:

```bash
pip install 'tinygs[sdr]'
```

## Run a station

```bash
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](https://t.me/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](docs/SDR_SETUP_GUIDE.md)** covers it, along with antennas,
credentials and troubleshooting.

## Use it from Python

```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/](tinygs/adapters/README.md), and [examples/](examples/)
for runnable versions of all of this.

## Tests

```bash
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](docs/SDR_SETUP_GUIDE.md)
- [TinyGS MQTT protocol](docs/MQTT_PROTOCOL.md) — the wire format this
  implements, reverse-engineered from the ESP32 firmware

## About

Developed with [LibreCube](https://librecube.org), 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](https://gitlab.com/librecube/prototypes/gsoc-lora-sat-receiver),
comes from the same effort.

MIT licensed. See [LICENSE](LICENSE).
