Skip to main content

Conversational Morse

AI Slop put to good use.

PyPI Python versions License: MIT

Screenshot A PyQt6 desktop application that simulates a realistic amateur-radio CW (Morse code) contact so you can learn and practise sending and copying Morse. It drives a K1EL WinKeyer USB for both the code that the "other station" sends and the code you key on your paddles.

You can be either side of the contact:

  • Call CQ yourself and work a station that answers you, or
  • Answer a CQ sent by the simulated station.

The conversation follows the standard exchange documented in the CW QSO Protocol sheet (RST / QTH / name, then rig / antenna / weather, then age / years licensed / key, and finally the 73 / SK sign-off with the closing two dits).

Why the WinKeyer does the Morse

The WinKeyer generates perfectly timed Morse and, importantly, can echo every character you key on the paddles back to the computer. That is how the application "hears" your sending, logs it and grades how much of the required information you copied.

Requirements

  • Python 3.12 or newer.
  • A K1EL WinKeyer (WKUSB or similar) and, for sending, a set of paddles. The built-in simulator lets you practise with no hardware at all.
  • On macOS the WinKeyer appears as a /dev/cu.usbserial-* device.

Install

Install the released package from PyPI:

uv tool install conversational-morse

or into the active virtual environment:

pip install conversational-morse

Then launch it:

conversational-morse

To run from a source checkout instead (development):

uv sync
uv run conversational-morse   # or: uv run python main.py

Using the application

  1. Connect. Pick the WinKeyer port (the app tries to guess it), choose a speed and sidetone, then press Connect. If you have no hardware attached, tick Use simulator - the whole QSO flow still works and you can type your overs instead of keying them.
  2. Set up your station. Press Station setup... and enter your callsign, name, QTH and the details used to build your side of the exchange. Your settings are saved to ~/.config/conversational_morse/config.json.
  3. Start a contact with either I will call CQ or Answer the DX station, and choose how long the contact should be (short exchange, medium or a full rag-chew).
  4. Listen while the DX station sends, then send your over:
    • Key it on the paddles. Your sending appears live in Received from paddles and is submitted automatically after a short pause (configurable), or when you press End over. You can test your paddles as soon as the keyer is connected: keyed characters appear even before you start a contact.
    • Or type the text in the box at the bottom and press Enter; it is keyed through the WinKeyer so you hear it, and it counts as your over.
    • Or press Send the model answer for me to hear a correct example.
  5. After each of your overs you get a copy report showing which required pieces of information were present.

Correct-copy checking

With Require correct copy enabled (the default), the DX station checks each of your overs before the contact moves on. Every portion is checked — the CQ answer must carry your own callsign (that is all you send when answering a CQ), the protocol exchanges must carry their details (RST/QTH/name, rig/antenna/weather, age/years/key), the sign-off must include 73 and SK, and the ending needs the two dits. If something is missing or you send a callsign that belongs to neither station, the DX replies naming the missing items, for example W6ABC DE DL1ABC QTH? NAME? AGN, and asks you to try again. After three tries it accepts the over and continues so you never get stuck. Turn the checkbox off to return to advisory-only reporting.

Copying by ear

Untick Show DX output to hide what the DX station sends, so you have to copy it by ear - which is the point of the trainer. The contact still runs normally and the DX text is withheld from the log.

When you miss something, ask for it: send the item followed by a question mark and the DX sends it again. Use ?, or the part of the call you did copy (W6?, DL1?), to hear the callsign twice, or name a detail (RST?, QTH?, NAME?, RIG?, ANT?, WX?, AGE?, YRS?, KEY?) to have it resent. The same turn stays open afterwards so you can send your over.

How it works

Module Responsibility
keyer/protocol.py WinKeyer host-mode command bytes, prosign encoding, buffer chunking
keyer/device.py Device interface, events and the incoming byte decoder
keyer/winkeyer.py Real serial backend (pyserial) with reader/writer/poll threads
keyer/simulator.py Deterministic in-software WinKeyer for tests and hardware-free practice
qso/script.py Builds the conversation turns from the CW QSO protocol
qso/engine.py Walks the conversation and grades your overs
gui/controller.py Bridges keyer events to the QSO engine using Qt signals
gui/main_window.py The user interface

The keyer interface opens the port, issues Admin:Host Open, switches to WK2 mode, enables paddle echo and autospace, and then streams ASCII to the device. Incoming status bytes, speed-pot changes and character echoes are decoded on a background thread and surfaced to the UI as events.

Development

uv run ruff check --fix
uv run ruff format
uv run mypy .
uv run pytest

The test suite runs entirely against the simulated keyer, so it needs no hardware.

Acknowledgements

  • QSO exchange structure based on the CW QSO Protocol reference sheet by W6JIM.
  • WinKeyer protocol per the K1EL Winkeyer2 and WinKeyer3 IC datasheets.

Metadata

Release files for conversational-morse 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for conversational-morse 0.2.0
File Size Uploaded Provenance Actions
conversational_morse-0.2.0.tar.gz 38.1 kB Without provenance Details for conversational_morse-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for conversational-morse 0.2.0
File Interpreter ABI Platform Actions
conversational_morse-0.2.0-py3-none-any.whl Python 3 none any Details for conversational_morse-0.2.0-py3-none-any.whl

Total release size: 74.1 kB

Release files / conversational_morse-0.2.0.tar.gz

Download URL conversational_morse-0.2.0.tar.gz
Size 38.1 kB
Tags Source
SHA-256 checksum
How to use checksums
831566b00c4dd757c13af28f320d63f2979587e1e290f951ee5a20bc31ed4905
BLAKE2b-256 checksum
How to use checksums
2dbd7ede27b86049b6debdbf62e419e453b2943e60b0509d0abdc38bc22c77c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.1

Release files / conversational_morse-0.2.0-py3-none-any.whl

Download URL conversational_morse-0.2.0-py3-none-any.whl
Size 36.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a64c7da379c0a132363333de7a34115c517ee62b3bb23dd4537fbb4bd49f6c9a
BLAKE2b-256 checksum
How to use checksums
24676b55be3ff6997392714985a9160d089562e871c7019b8c8be04e5871d501
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.1

Security for conversational-morse 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page