Command Line Options

Wsprry Pi normally runs as a systemd service, but you can also work with it directly from the shell for testing, calibration, and one-off transmissions.

Note

Only one instance of Wsprry Pi may run on the system at the same time.

systemd Service

The wsprrypi executable is managed by Linux systemd. It runs in the background after boot, and only one instance is allowed at a time. Stop the daemon before running manual CLI commands.

Useful commands:

  • sudo systemctl status wsprrypi
    Show current status and recent logs.

  • sudo systemctl restart wsprrypi
    Restart the daemon and reload configuration.

  • sudo systemctl stop wsprrypi
    Stop the daemon. It will start again on reboot unless disabled.

  • sudo systemctl start wsprrypi
    Start the daemon manually.

  • sudo systemctl disable wsprrypi
    Prevent daemon startup on boot.

  • sudo systemctl enable wsprrypi
    Enable daemon startup on boot.

Command Line Overview

The CLI supports two primary modes:

  • Direct CLI mode
    Run WSPR or CW-based transmissions directly.

  • INI (daemon-style) mode
    Use -i to load and monitor a configuration file.

Usage

(sudo) wsprrypi [options] CALLSIGN GRID POWER FREQ [FREQ...]
(sudo) wsprrypi -i /path/to/wsprrypi.ini
(sudo) wsprrypi --test-tone RF_FREQ [backend/options]
(sudo) wsprrypi --mode QRSS --cw-message TEXT --cw-base-frequency FREQ

Common Examples

  • wsprrypi --help
    Display help text.

  • sudo wsprrypi --test-tone 780e3
    Transmit a constant RF tone at 780 kHz.

  • sudo wsprrypi N9NNN EM10 33 20m
    Transmit a single WSPR message.

  • sudo wsprrypi --use-ntp N9NNN EM10 33 20m
    Use NTP calibration before transmission.

  • sudo wsprrypi --repeat --offset --use-ntp N9NNN EM10 33 40m
    Continuous transmissions with offset randomization.

Positional Arguments

These are required for direct WSPR transmission unless provided via INI:

  • CALLSIGN
    Your callsign or supported WSPR identity form. Standard Type 1 WSPR messages use a normal callsign that fits the classic WSPR field. When the supplied identity cannot be represented as a single Type 1 message, the planner can use paired WSPR message planning where supported. This allows Type 2 and Type 3 message forms for extended callsign/grid combinations rather than requiring every direct CLI transmission to fit the older six-character Type 1-only form.

  • GRID
    Maidenhead grid square or locator value used by the WSPR planner. Standard Type 1 messages use the normal four-character Maidenhead grid square. For identities that require paired planning, the grid and callsign are evaluated together so the planner can select the appropriate Type 2/Type 3-capable message strategy when available.

  • POWER
    Transmit power in dBm. The value is rounded to valid WSPR steps and included in the transmitted WSPR message where the selected message type supports it.

  • FREQ
    One or more frequencies or band aliases.
    Examples: 20m, 14097100, 0 (skip slot)

General Options

  • -h, --help
    Display help text and exit. This is processed early and does not require root.

  • -v, --version
    Print version information and exit.

  • -i, --ini-file <file>
    Load configuration from an INI file. When used, CLI transmission options are disabled or restricted, and the program runs in daemon-style mode.

  • -r, --repeat
    Repeat transmissions indefinitely in direct CLI mode.

  • -x, --terminate <count>
    Stop after a specified number of transmissions.

  • -J, --journald
    Send logs to the systemd journal instead of stdout.

  • -D, --date-time-log
    Prefix log lines with UTC timestamps.

  • --debug-logging, --no-debug-logging
    Enable or disable debug-level logging output.

WSPR Behavior

  • --planner-preference <auto\|prefer_paired\|require_paired>
    Controls WSPR message planning. The default auto mode uses a normal single WSPR frame when possible and allows the planner to choose paired handling when needed. prefer_paired asks the planner to use paired handling when it is available. require_paired rejects a transmission if the supplied identity cannot be represented with the paired-message strategy.

  • -o, --offset
    Apply a small random frequency offset to reduce collisions.

  • --no-offset
    Disable random offset.

WSPR Message Types

The CLI is no longer limited to classic Type 1-only callsign handling. Direct CLI WSPR input is passed through the same WSPR planning path used by the rest of the application.

  • Type 1 is the normal single-frame WSPR message form for standard callsign, grid, and power combinations.

  • Type 2 supports compound or extended identity cases by transmitting a callsign-hash-oriented frame as part of a paired strategy.

  • Type 3 supports the complementary extended identity information needed for paired decoding.

For ordinary callsigns and four-character grid squares, no special option is usually needed. For identities that require Type 2/Type 3 handling, use --planner-preference when you want to prefer or require paired planning.

Backend Selection

  • --backend <gpio\|si5351>
    Select RF output method.

    • gpio: Direct RF from Raspberry Pi GPIO (limited models).

    • si5351: External clock generator via I2C.

  • --power-level <level>
    Set transmit power for the active backend:

    • GPIO: 0–7

    • Si5351: 1–4

  • --gpio-power-level <0-7>
    Explicitly set GPIO drive strength.

  • --si5351-power-level <1-4>
    Set Si5351 output drive strength.

GPIO Backend

  • --transmit-gpio <4\|20>
    Select GPIO pin used for RF output.

  • --transmit-pin <4\|20>
    Legacy alias for transmit GPIO.

  • -n, --use-ntp
    Enable NTP-based frequency calibration.

  • --no-use-ntp
    Disable NTP calibration and use manual PPM.

  • -p, --ppm <value>
    Apply manual frequency correction (-200 to 200 ppm).

Si5351 Backend

  • --si5351-i2c-bus <bus>
    Select I2C bus (default: 1).

  • --si5351-i2c-address <addr>
    Set device address (decimal or hex).

  • --si5351-reference-frequency <hz>
    Define reference oscillator frequency.

  • --si5351-tx-output <CLK0\|CLK1\|CLK2>
    Select output clock. This option is not exposed in the Web UI.

CW / QRSS / FSKCW / DFCW Modes

  • --mode <WSPR\|QRSS\|FSKCW\|DFCW>
    Select transmission mode.

  • --cw-message <text>
    Message to transmit in CW-based modes.

  • --cw-base-frequency <freq>
    Base RF frequency. Supports Hz, kHz, MHz, GHz suffixes.

  • --cw-shift-hz <hz>
    Frequency shift for FSK-based modes.

  • --cw-dot-seconds <seconds>
    Length of a Morse “dot”.

Timing

  • --cw-start-minute <0-59>
    Start minute for scheduled transmissions.

  • --cw-repeat-minutes <minutes>
    Interval between transmissions.

Spacing

  • --cw-intra-element-gap <multiple>
    Gap between elements of a character.

  • --cw-inter-character-gap <multiple>
    Gap between characters.

  • --cw-inter-word-gap <multiple>
    Gap between words.

Envelope Control

  • --cw-fade-shape <none\|linear\|raised_cosine>
    Shape of amplitude transitions.

  • --cw-fade-in-ms <ms>
    Fade-in duration.

  • --cw-fade-out-ms <ms>
    Fade-out duration.

  • --cw-fade-slice-ms <ms>
    Resolution of fade steps.

Service and GPIO Controls

  • --no-web
    Disable Web UI and WebSocket server.

  • -w, --web-port <port>
    HTTP REST API port (default: 31415).

  • -k, --socket-port <port>
    WebSocket port (default: 31416).

  • -l, --led_pin <gpio>
    Set TX LED GPIO.

  • --led-pin <gpio>
    Alias for LED pin.

  • --use-led, --no-led
    Enable or disable LED.

  • -s, --shutdown_button <gpio>
    Set shutdown button GPIO.

  • --shutdown-button <gpio>
    Alias.

  • --use-shutdown, --no-shutdown
    Enable or disable shutdown monitoring.

Test Tone

  • -t, --test-tone <frequency>
    Generate a continuous RF tone. Useful for calibration and testing.

Notes

  • CLI options override INI values unless restricted.

  • Some advanced features are CLI-only.

  • Root privileges (sudo) are required for RF output.