Contributing

gr-satellites welcomes contributions: new satellites, telemetry parsers, deframers for new protocols, bug fixes and documentation. This page summarizes how to set up a development build, run the tests and style checks the CI runs, the coding and commit conventions, and the project policies that apply to contributors. It is based on the repository's CONTRIBUTING.md, CI workflows and policy documents.

Development Setup

Install GNU Radio 3.10 and the build dependencies (see Building from Source).

Clone the repository with the sample recordings:

git clone --recursive https://github.com/daniestevez/gr-satellites
cd gr-satellites

Build:
```
mkdir build
cd build
cmake ..
make
```
Run the unit tests from build/:
```
make test
```
Install (sudo make install && sudo ldconfig) to try the command line tool, or run the decoders in test.sh from the repository root to check that the sample recordings still decode:
```
sh test.sh
```
test.sh exports GR_SATELLITES_SUBMIT_TLM=0, so it never submits telemetry.

Development happens on the main branch (GNU Radio 3.10). Submit pull requests against main.

Tests

Unit tests are Python files named qa_*.py that use gnuradio.gr_unittest, registered with GR_ADD_TEST in the CMakeLists.txt of their directory. Examples:

Test	What it checks
`python/satyaml/qa_satyaml.py`	Runs `check_yaml()` on every bundled SatYAML file.
`python/qa_crc.py`, `qa_hdlc.py`, `qa_kiss.py`, `qa_rs.py`, `qa_viterbi.py`, ...	Low-level blocks.
`python/components/deframers/qa_ao40_fec_deframer.py`, `qa_mobitex_deframer.py`, `qa_usp_deframer.py`	Deframers against stored symbol files.
`python/telemetry/qa_by02.py`	A telemetry parser.

The project encourages including a unit test with changes when there is an obvious one.

The tests/ directory also contains Jupyter notebooks and scripts used to characterize the demodulators (BER, lock-in and TED gain studies).

Style Checks

The CI runs three workflows on every push and pull request:

Workflow	Command	Scope
`build-ubuntu-gr310`	builds and tests using the `daniestevez/gr-satellites-ci-action` action	Whole project
`pycodestyle`	`pycodestyle . --exclude python/ccsds,docs,tools,tests,examples,python/bindings`	Python (PEP 8)
`clang-format lint`	`clang-format -Werror --dry-run` on all `.cpp`, `.hpp`, `.h`, `.cc`, `*.c` files	C/C++

Run the same checks locally before opening a pull request:

pip install pycodestyle
pycodestyle . --exclude python/ccsds,docs,tools,tests,examples,python/bindings

find . -name '*.cpp' -o -name '*.hpp' -o -name '*.h' -o -name '*.cc' -o -name '*.c' | xargs clang-format -Werror --dry-run

Note: CONTRIBUTING.md mentions a tools/clang_format.py helper script, but the tools/ directory of the current main branch only contains waveform_plot.py. Use clang-format directly as above.

Coding Guidelines

gr-satellites follows GNU Radio's coding guidelines (GREP1), PEP 8 for Python, and clang-format for C++.
Python or C++: most of gr-satellites is Python, which speeds up development; performance is rarely critical at small-satellite data rates. Telemetry parsing is always Python with construct. When a block is equally simple in C++ or Python, C++ is preferred.
New telemetry parsers must be added to python/telemetry/__init__.py and python/telemetry/CMakeLists.txt (CONTRIBUTING.md calls the first one __index__.py). See Writing a Telemetry Parser.
New deframers go in python/components/deframers/, with a GRC block definition in grc/components/deframers/, and must be added to _deframer_hooks in python/core/gr_satellites_flowgraph.py and to the framings list in python/satyaml/satyaml.py to be usable from SatYAML files.

Commit Messages

Following GNU Radio's rules:

keep lines below 72 characters,
never leave a commit message empty,
explain the change in the message; the code explains the current state.

Project Policies

LLM usage policy

The project has an LLM usage policy (LLM_POLICY.md, adapted from the Rust project's policy). In short:

Private use of LLMs (asking questions about the code, private review, learning) is allowed.
Comments, issue bodies, PR descriptions and documentation originally created by an LLM are not allowed in the project, including CLI help text and error messages.
Some uses are allowed with disclosure: trivial changes, machine translation, LLM-assisted bug discovery that you verify yourself, and approved review bots with their own accounts.
LLM-created code is only accepted as an experiment: pre-arranged with a reviewer, high quality, well tested, well reviewed, disclosed, and labelled llm-assisted.
Being dishonest about LLM use is a Code of Conduct matter.

Read the full LLM_POLICY.md before contributing.

Satellite teams and commercial satellites

Teams building a ground station on gr-satellites are encouraged to upstream support for their satellite rather than maintain a fork (satellite_teams.md).
Contributions specifically for receiving commercial satellites need the operator's endorsement or acknowledgment; generic blocks are always accepted (commercial_satellites.md).

Code of conduct and support

The project has a Code of Conduct. Support and discussion happen only on GitHub issues and GitHub discussions, so that everyone benefits from the answers.

Upstream Documentation

The project's own documentation is a Sphinx site in docs/source/ (configured by readthedocs.yml and published on Read the Docs). docs/generate_supported_satellites.py regenerates the supported satellites list from the SatYAML files. Release notes are in the CHANGELOG, which follows the Keep a Changelog format and semantic versioning.