Skip to main content

Conversational Morse

AI Slop put to good use.

PyPI Python versions License: MIT

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.

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.

Using a transmitter

The WinKeyer's key and PTT outputs can be connected to a real rig. The app sets the PTT lead-in/tail delays and sidetone according to the configuration. If you only want to practise, leave the key output disconnected and listen to the WinKeyer's sidetone.

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.1.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.1.0
File Size Uploaded Provenance Actions
conversational_morse-0.1.0.tar.gz 33.8 kB Without provenance Details for conversational_morse-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 67.0 kB

Release files / conversational_morse-0.1.0.tar.gz

Download URL conversational_morse-0.1.0.tar.gz
Size 33.8 kB
Tags Source
SHA-256 checksum
How to use checksums
19dc3b6769b7559d425a71e36d8a269b38d425ad3d004e90a3983d3194d7302c
BLAKE2b-256 checksum
How to use checksums
6e110929e0e4d8c1ee79d46c78fd3b35d0429990148153ec1ca1dba1bc4f4272
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

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

Download URL conversational_morse-0.1.0-py3-none-any.whl
Size 33.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
40aa34cd9df83c958a919d54b184d4c53b358ca3e66000e5c1079aa6dd3ed911
BLAKE2b-256 checksum
How to use checksums
5318c3f36d05c8c36d1b83b85ae9c9488fa36c190d9e4b7b0b870e2f7c8d1238
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for conversational-morse 0.1.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.1.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