Metadata-Version: 2.4
Name: qrss-ei
Version: 0.3.0
Summary: A simple QRSS CW (very slow Morse code) transmit software.
Author-email: "Dr. Andreas Krüger, DJ3EI" <dj3ei@famsik.de>
License-Expression: MIT
Project-URL: Homepage, https://codeberg.org/omwb/qrss-ei
Project-URL: Repository, https://codeberg.org/omwb/qrss-ei
Project-URL: Issues, https://codeberg.org/omwb/qrss-ei/issues
Keywords: ham,amateur radio
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Communications :: Ham Radio
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: morse2sound~=1.0.7
Dynamic: license-file

# qrss-ei: Software to transmit QRSS CW signals with regular radios

## Introduction to QRSS CW

### What is it?

QRSS CW is very slow Morse code.

In normal Morse code, the beginner's slow speed is 60 cpm (characters per minute),
which is the same as 12 wpm (words per minute).  At that speed, the fundamental unit,
the "dot length", is 100 ms.  In QRSS, the dot length is much longer, commonly 3 seconds
and more.  In other words, QRSS is Morse code with a speed of 2 cpm = 0.4 wpm or less.

Normal CW is on-off-keying. QRSS is commonly sent as
frequency-shift-keying, with the "key engaged" frequency typically
being 5 Hz above the "key released" frequency.

Finally, typical QRSS receiving software assumes that the QRSS
transmission is repeated a few times, once every 10 minutes,
preferably with exactly the same timing as 10 minutes earlier.  This
can be used to "stack" or "integrate" several transmissions, so the
information can be fished out of the noise better.

QRSS activity on a band typically happens in a very small
segment of that band, usually ± 100 Hz around one designated frequency.
Here is one [QRSS frequencies list](https://swharden.com/blog/2020-10-03-new-age-of-qrss/#qrss-frequency-bands).

QRSS is very much a QRP or QRPP mode.  Typical transmitters put out a few
100 mW or so, some even considerably less.  Powers above 1 W are somewhat frowned
upon by the community: Strong signals might clog up receivers trying
to copy the QRP and QRPP signals.

### What can I do with QRSS?

QRSS is mostly about propagation study.

To that end, what people typically do is beacon activity. It works like this:

- Run a transmitter that keeps sending your call sign, repeated every ten minutes,
  over and over again, for hours, on a frequency somewhere in the QRSS
  [frequency ranges](https://swharden.com/blog/2020-10-03-new-age-of-qrss/#qrss-frequency-bands).
- Head over to the grabber exhibition at [https://swharden.com/qrss/plus/](https://swharden.com/qrss/plus/),
  poke around and see whether you can find your own signal.

Have a look at the traces your signal left on those grabber signals.
You can often learn a thing or two about propagation from doing so!
For some examples:

- When which band opens and closes,
- how quickly so,
- how volatile short band openings are,
- how do unusual propagation phenomenons act out 
  (you might even see occasional greetings  from  people like Mr. Mögel,
  Mr. Dellinger, and sometimes Mr. Doppler).

It is really quite instructive.

For this, your signal should remain compatible with what the grabbers expect.
It is important you keep to the ten-minute transmit period.  For best results:

- Do not let your signal overlap a full ten-minute boundary.
- If you want your signal to repeat itself (which is recommended),
  repeat with a period of 10 minutes.

### Find an open frequency

Common operationg practice in all of amateur radio follows the time-honored approach:

> Listen before you transmit, and do not transmit when the frequency is occupied.

Now QRSS transmissions, once started, often keep going on for hours.
To see what QRSS is worth, you want to try that, too. 
Then, there is an additional thing or two to consider, to not step on other ops' toes.

Say, you want start your transmission in the early morning.
You want to get a feeling when and how quickly a certain band opens.

Now the other stations (you don't want to interfere with) tend to transmit
their beacons on the always-same frequencies. But you won't be hearing them
before the band opens.

So, in this situation, a head start will be helpful: Let a receiver
run for a few hours _the day before, at a time when the band is open._
Or else, check the [public grabbers](https://swharden.com/qrss/plus/) the
day before.

Use that info to find a frequency that had been open the day before.
Most likely, it will be open today, too.

### More information on QRSS 

- To read up on it: [Scott Harden + Andy
  resources](https://swharden.com/qrss/plus/)
- To meet others doing it (and read up some more), join the [QRSS Knights
  mailing list](https://groups.io/g/qrssknights) mailing list.

### But I want to have a QSO!

Most QRSS activity these days is beacon activity, as explained above.

So trying to complete a QSO means engaging in an unusual activity.  Don't
expect it to be easy!

That said, if you still want a QSO, you can try any of the following:

- Receive in one of the QRSS band segments and wait for a CQ signal.
  But chances are that you'll have to wait for a _looooong_ time.
  Actually hearing a CQ seems to be a bit like winning a lottery!
- You face a much better chance if you pre-arrange a QSO.
- You could also try to repeatedly call CQ yourself for a long time.
  This way, people who only occasionally check will become aware of your CQ.
  Now obviously, those people need to have a means to know
  at which time you're listening for their answer. How to do that
  is a puzzle for you to solve.

Beacon activity can be done nicely with dot lengths of 5 or even 10 seconds,
depending on the length of your callsign. Long dot length is beneficial for reach!
But for QSO activity, you'll have to shorten the dot length to maybe 3 seconds.
Even though, you will have to work hard to reduce the texts you send to the
bare minimum.

### Is this even legal?

That depends on circumstances, what you actually do, and the rules your
administration imposes on you.  Be informed and obey your local rules!

For your amusement, here are some musings:

I believe having an amateur radio *reception* station up and running
is allowed for everyone (in all jurisdictions I'm aware of).
This includes QRSS signals. So you can run your own private grabber
any time, even if you are not a radio amateur yourself.

In Germany, if you want to establish an amateur radio beacon that transmits
24 hours 7 days a week, you'd need a special permit.  Obtaining that permit
is not something to engage in lightly.

But, as far as I can tell, I act in perfect compliance with local
German rules if

- my radio amateur station transmits only while I'm personally present
  on premise and
- the transmission is not forever, but will eventually stop of its own
  if I do not occasionally prod it along.

But I'm not a lawyer by profession. Saying these things, I do not want
to engage in providing legal advice. I'm only exercising my right to free
speech by voicing opinions regarding my own behavior.

## What is this project?

Much of the beacon activity is done with special purpose transmit hardware.
Such hardware can be purchased, but a QRSS transmitters can also be a nice
project to homebrew.  The main challenge seems to be frequency stability.

But most radio amateurs initially don't have such special purpose hardware.
They might have a regular transceiver.

This software allows to transmit QRSS signals via the regular transceiver
you might already have.

### A warning: Long duty cycle!

**There is one real danger** I'm aware of.

Most regular transceivers are meant for transmissions that last only a minute or two.
And mostly for transmission modes like SSB voice or CW. These cause the average
output power to be considerably below the maximum output power.

As a FSK mode, QRSS transmissions can be much longer.
If you use your rig to transmit QRSS, you need to make sure it does not overheat.

Check your radio's manual. Maybe, your rig does not overheat if you reduce
output power sufficiently.  If so, do that.

Whatever you do: Once your rig exhales the proverbial "magic smoke" after
so many minutes into an extended QRSS transmission and remains
a non-transmitter forever after, that is entirely your problem, not mine.
You may also want to read this software's [License](./LICENSE).

### What is needed to run this?

This is a Pyathon programm. It does not talk to your radio directly, but it only talks to
[rigctld](https://hamlib.sourceforge.net/html/rigctld.1.html) from the well-known [hamlib](https://hamlib.github.io/) software package.

For those in the know of network things: That talking happens via plain
clear-text TCP/IP.

So you'll need some computer that runs both Python and `rigctld` from the hamlib package,
plus a transceiver that is  controllable via that `rigctld` instance.
The second can be paraphrased: You need CAT ("computer aided tuning").

You do **not** need to configure any sound card setup. If you have such a setup,
say, for FT8 work, that does not hurt.  But QRSS with this software will not use it.

The program sets the radio to RTTY mode. This will cause a carrier to be sent
whenever PTT is pressed. No actual characters are ever emitted to be sent via RTTY.
Also, this program uses the "data" variety of "PTT", to make doubly sure a bare,
unmodulated carrier is sent.

If your transceiver does not come with built-in RTTY support,
you can use some other mode that causes a carrier to be transmitted.
Both AM and FM work just as well. But if you use those, you have
to make sure there is no modulation. You could try unplugging your microphone
or setting the mic gain to 0.

When the virtual Morse key is pressed, we want to change frequency.
For that, the PTT is briefly released, the frequency shifted (typically 5 Hz up),
and the PTT again pressed.  When the virtual Morse key is released, again,
PTT is briefly released, the frequency shifted back, and PTT again pressed.

I'm not sure whether this PTT juggling is actually needed.  I fancy it reduces
bandwidth occupied.  The program does it, and it doesn't seem to hurt.

This software is strictly a command-line utility.  It needs only plain
Python without any modules that need compilation.  It does make use of
the [morse2sound](https://gitlab.com/4ham/morse2sound) software by the
same author, which has the code to convert text into Morse code
characters.  (`morse2sound` is plain Python as well.)

## Installation

The following steps should give you an executable script `qrss_ei`
intended to be run in a terminal.  To actually send QRSS, you will
also need to run
[rigctld](https://hamlib.sourceforge.net/html/rigctld.1.html) from the
well-known [hamlib](https://hamlib.github.io/) software package to
actually connect to your rig.  `qrss_ei` has no code to connect to your
radio, it only knows to connect to `rigctld` (via TCP/IP).

Once you have it running, the output of `qrss_ei -h` gives you
more information. But how to get it running?

In any event, you need to install [Python](https://www.python.org/downloads/)
to your computer if it is not already there.
Any version 3.12.X or any higher version will work. You can find out
the Python version by typing either `python -V` or `python3 -V`.

Once Python has been installed, there are various equally good ways
to install `qrss_ei`.  The main ones are: Plain Python or
(for the experts) with the `uv` package manager.

After installation, type `qrss_ei -h` at the shell prompt or
into the DOS box or wherever you activated your virtual environment.
It will hopefully give you all you need to know to get you started.

### Installation with plain Python

- Construct a plain Python [virtual
  environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments)
- activate it
- `pip install qrss-ei`

### Installation with uv

If you use the [uv](https://docs.astral.sh/uv/) Python dependency
manager:

- Construct a uv virtual environment with `uv venv`
- activate it
- `uv pip install qrss-ei`

### Sample invocation

If I want to do a four-hour almost continuous transmission
on the 30 m band, I might say:

>     qrss_ei --intext dj3ei --dotlength=10 --qrg=10139815 --repeat=24

I typically test this by initially adding `--count`. The
output gives me some data to fiddle with `--dotlength`, which.
I sometimes do.

### What do I use to *receive* QRSS CW?

This software does not help you to receive QRSS CW.
To do that, I presently use [Lopora](https://www.qsl.net/pa2ohh/11lop.htm).

#### Installation hints on Lopora:

The Lopora ZIP has installation instructions, once you unpack it,
in the `documentation` directory.
Those address somewhat unconventional installation targets.
On my plain Python installation on my plain Linux Debian Trixie Laptop,
I found I just needed an active [virtual
environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments)
with this pre-installation:

```
pip install numpy pillow pyaudio
```

(Could be the same virtual environment you use to run `qrss_ei`.)

On my Debian Linux Trixie box, I'm using "pipewire" as the "audio
device for input".  I then set the input device actually used via the
standard Gnome configuration.  (This basically ties up audio while
Lopora is being used.)

## The name "qrss-ei" / "qrss_ei"

Has two sections: The "qrss" part stands for what you can transmit
with this, the "ei" part is derived from the suffix of my, the
[author](https://dj3ei.famsik.de)'s, radio amateur call sign DJ3EI.

Should you want to fork this software and develop it into some
direction of your own, you are requested to rename your fork
and **not** call it anything "-ei". 

There is some confusion whether to separate the two name parts
with `-` or `_`. I would have liked to use `_` everywhere,
but Pypi does not allow `_` in Python projects.
So the project and the repo use `-`,
but the Python package and the script have `_`.
