Configuration

gr-satellites keeps its persistent settings in two small files in your home directory: config.ini for station details and telemetry server credentials, and sat.cfg for per-satellite default command line arguments. One environment variable overrides the telemetry submission switch. This page documents where these live, every key, the exact parsing rules, and the pitfalls found in the code.

File Locations

Both files live in the .gr_satellites directory under your home directory (Python's Path.home()):

File Linux/macOS Windows
config.ini ~/.gr_satellites/config.ini C:\Users\<you>\.gr_satellites\config.ini
sat.cfg ~/.gr_satellites/sat.cfg C:\Users\<you>\.gr_satellites\sat.cfg

The directory and config.ini are created automatically the first time gr_satellites runs (or the first time a flowgraph with a Telemetry Submit block runs). sat.cfg is never created for you.

config.ini

Default contents

[Groundstation]
callsign = 
latitude = 0
longitude = 0
submit_tlm = no

[FUNcube]
site_id = 
auth_code = 

[PW-Sat2]
credentials_file = 

[BME]
user = 
password =

Keys

Section Key Type Default Effect
Groundstation callsign string empty Your callsign, sent as source to SatNOGS and SIDS servers. Empty disables those submissions.
Groundstation latitude float, degrees (N positive) 0 Station latitude for SatNOGS/SIDS.
Groundstation longitude float, degrees (E positive) 0 Station longitude. If both latitude and longitude are 0, SatNOGS/SIDS submission is disabled.
Groundstation submit_tlm boolean no Master switch for telemetry submission.
FUNcube site_id string empty FUNcube Warehouse site ID.
FUNcube auth_code string empty FUNcube Warehouse authentication code.
PW-Sat2 credentials_file path empty JSON credentials file from the PW-Sat2 server.
BME user string empty BME telemetry server user name.
BME password string empty BME telemetry server password.

submit_tlm is read with configparser's getboolean(), which accepts 1, yes, true, on, 0, no, false, off, case-insensitively.

Parsing notes

  • The file is read with Python's configparser. Keys must stay in their sections; the section names are case-sensitive ([PW-Sat2], not [pw-sat2]).
  • If you delete a section, the code that reads it fails with a KeyError or NoSectionError when that server is used. Delete the whole file to get a fresh template instead.
  • The file is only created when it does not exist. New sections added in future versions are not merged into an existing file.
  • config.ini stores passwords in plain text. Restrict its permissions on shared machines.

See Telemetry Submission for what each server does with these values.

GR_SATELLITES_SUBMIT_TLM

Variable Values Effect
GR_SATELLITES_SUBMIT_TLM 1, yes, true, on, 0, no, false, off Overrides submit_tlm from config.ini for this run.

Unlike config.ini, the environment variable is looked up directly in configparser's table of boolean strings, which is lower case only. GR_SATELLITES_SUBMIT_TLM=True or =YES raises a KeyError and the tool exits with a traceback. An empty value also fails.

# Never submit, whatever config.ini says
export GR_SATELLITES_SUBMIT_TLM=0

The variable only affects the gr_satellites command line tool (and other code that builds gr_satellites_flowgraph without grc_block=True). The Telemetry Submit block in GNU Radio Companion always submits.

sat.cfg: Per-Satellite Default Arguments

sat.cfg lets you store command line arguments per satellite. They are used only when you pass --satcfg.

Format

One satellite per line: the NORAD ID, a space, then the arguments separated by single spaces.

39444 --f_offset 12000
46276 --disable_dc_block --deviation 500 --clk_bw 0.15
35933 --clk_bw 0.3

How it is applied

  1. gr_satellites resolves the satellite (name, NORAD ID or file) and gets its NORAD ID.
  2. If --satcfg appears literally among the arguments, it scans sat.cfg from the top and takes the first line whose first field equals that NORAD ID.
  3. The rest of that line is inserted before your command line arguments.
  4. argparse keeps the last occurrence of an option, so anything you type overrides the file.

Flags (options without a value, such as --disable_fll) cannot be "turned off" from the command line once sat.cfg sets them.

Pitfalls

The parser is deliberately simple (row.strip().split(' ')), which leads to these rules:

Rule Why
Separate fields with exactly one space. Two spaces produce an empty argument, which argparse rejects as an unrecognized argument. Tabs are not separators.
No comments. Every non-empty line's first field is converted with int(). A line such as # my settings raises ValueError and stops the tool.
No quoting. Arguments containing spaces cannot be expressed.
Blank lines are fine. They are skipped.
A line with only a NORAD ID is skipped. It has no arguments.
Use options that exist for the satellite. Otherwise the run fails with unrecognized arguments, unless you also pass --ignore_unknown_args.

The file is read even for satellites given by SatYAML path, using the norad field of that file.

Other Environment Variables

Variable Used for
PYTHONPATH Must include the directory containing the installed satellites Python package when it is not on Python's default path (see Installation).

See Also