Morsewurst Keyer

Overview

Morsewurst Keyer is a custom ESP32-S3-based device designed for practical Morse training. It reads a straight key or an iambic paddle, produces a headphone sidetone, shows basic information on an OLED display, and sends raw timing telemetry to Morsewurst running on a computer.

The key idea is that the ESP32-S3 measures key press timings and sends them as JSON telemetry. Morsewurst can then analyse rhythm, timing, gaps, speed, accuracy and problem characters much more precisely than simple text input.

Required parts

Electronics

• Adafruit ESP32-S3 Feather with STEMMA QT 8MB, or a similar ESP32-S3 board with native USB.
• 128x64 I2C OLED display, for example SSD1306 or SH1106 compatible.
• KY-040 or similar rotary encoder with push button.
• 3.5 mm stereo jack for the iambic paddle.
• 3.5 mm stereo jack for the straight key.
• 3.5 mm stereo headphone jack, preferably a switched model if headphone detection is wanted.
• 10 kΩ logarithmic mono potentiometer for volume.
• Two 1 kΩ metal film resistors.
• One 2.2 kΩ or 10 kΩ metal film resistor for the headphone output pull-down.
• Wire in several colours.
• Optional Wago connectors, ground rail or another neat way to join GND wires during prototyping.

Tools and mechanical parts

• Soldering iron and solder.
• Wire strippers and side cutters.
• Small drill or hand drill for cleaning up holes.
• 3D printer and PETG filament.
• Screws or other fasteners suitable for the enclosure.

Arduino IDE settings

The firmware is intended for an ESP32-S3 board with native USB. Use a real USB data cable, not a charge-only cable.

USB Mode:        USB-OTG or TinyUSB
USB CDC On Boot: Enabled
Upload Mode:     USB-OTG CDC or TinyUSB

If USB CDC On Boot is not enabled, Morsewurst may not find the telemetry serial port correctly. If USB-OTG or TinyUSB mode is not enabled, USB HID Keyboard mode may not work.

Arduino sketch folder

Arduino sketches should be stored so that the folder and the main .ino file have the same name. For example:

morsewurst_keyer_1_0/
└── morsewurst_keyer_1_0.ino

Bootloader mode

If the computer does not recognise the ESP32-S3 board for programming, try this sequence:

1. Hold the BOOT button down.
2. Press the RESET button.
3. Release RESET.
4. Release BOOT.

Display

The project uses a 128x64 I2C OLED display. In practice, many OLED displays can work as long as the correct U8g2 driver is selected for the display controller chip.

U8G2_SH1106_128X64_NONAME_F_HW_I2C u8g2(
  U8G2_R2,
  U8X8_PIN_NONE
);

Although a display may be sold as SSD1306, the SH1106 driver may work better in some setups. If the image is shifted, partly wrong or shows artefacts, try another U8g2 driver.

U8G2_R2 rotates the image 180 degrees. This is useful if the display is physically installed upside down in the enclosure.

Pinout

All key and encoder inputs use the internal INPUT_PULLUP resistor. This means that the button or key connects the signal pin to ground when pressed.

Keys and encoder

Straight key

const int STRAIGHT_KEY_PIN = 12;

Iambic paddle

const int DIT_PIN = 9;
const int DAH_PIN = 10;

If DIT and DAH are reversed, fix it by swapping the wires in the jack or by using the firmware’s paddle swap setting.

Rotary encoder

const int ENC_CLK_PIN = 5;
const int ENC_DT_PIN = 6;
const int ENC_SW_PIN = 13;

If the rotation direction is reversed, swap GPIO5 and GPIO6.

Sidetone and headphones

The sidetone is produced from ESP32 GPIO11 as a PWM square wave. It is intended for headphone-level output, not for driving a speaker directly.

const int AUDIO_PIN = 11;

Potentiometer wiring

Resistors from the middle terminal

GPIO11 -> potentiometer outer terminal
GND    -> other potentiometer outer terminal

Potentiometer middle terminal
  ├── 1 kΩ -> headphone jack TIP
  ├── 1 kΩ -> headphone jack RING
  └── 2.2 kΩ or 10 kΩ -> GND

Headphone jack SLEEVE -> GND

Headphone detection, optional

The project reserves support for a switched 3.5 mm headphone jack. The idea is that the jack can pull the A3 pin to ground when headphones are connected.

const int HEADPHONE_DETECT_PIN = A3;

bool headphonesConnected() {
  return digitalRead(HEADPHONE_DETECT_PIN) == LOW;
}

This feature is mainly a reserved extension option. If you use a normal headphone jack without detection, you can leave it unused.

3D-printable enclosure

The Morsewurst Keyer enclosure is supplied as two separate STL files: the lower box and the lid. Print both parts separately. The design is intended for PETG, and small differences in displays, jacks, encoders or printer calibration may require minor cleanup or adjustment after printing.

• Material: PETG.
• Layer height: 0.2 mm works, but 0.10 to 0.15 mm is recommended for a cleaner result.
• Infill: about 15 to 30 percent.
• Walls: 2 to 3 perimeters.
• Printer: Prusa i3 MK3S Plus or similar.

If holes are too tight, clean them carefully by hand. Do not use too much force, because the enclosure may crack.

Telemetry for Morsewurst

The device sends timing events over USB CDC Serial in JSON format. Morsewurst reads these lines and uses them to analyse timing, rhythm and decoding during practice.

Straight key tone event

{
  "v": 1,
  "type": "tone",
  "src": "straight",
  "t0": 123456789,
  "t1": 123556789,
  "dur": 100000
}

Iambic tone event

{
  "v": 1,
  "type": "tone",
  "src": "iambic",
  "el": ".",
  "t0": 123456789,
  "t1": 123516789,
  "dur": 60000,
  "unit": 60000,
  "wpm": 20.0
}

The important point is that t0, t1 and dur are measured by the ESP32 itself. USB and Python latency affect when the event appears on the computer, but they do not change the timestamps already measured by the device.

Measurement accuracy

uint64_t nowTime() {
  return (uint64_t)esp_timer_get_time();
}

Timestamps are stored in microseconds, but practical accuracy is not exactly one microsecond. With the current polling-based implementation, realistic practical accuracy in good conditions is about 50 to 200 microseconds.

Serial API for compatible devices

Morsewurst’s most important hardware interface is line-based JSON telemetry sent over a USB CDC Serial connection. The interface is effectively one-way. The device sends timing data to Morsewurst, and Morsewurst does not need to send commands back to the device.

Serial connection

115200 baud
one JSON object per line
line ending: \n

Device identification

Useful message types for identification are hello, heartbeat and tone. A compatible device should send a hello message after startup and heartbeat messages regularly when idle.

Hello message

{"v":1,"type":"hello","app":"morsewurst","device":"Morsewurst Keyer","fw":"1.0","mode":"raw_timing"}

Heartbeat message

{"v":1,"type":"heartbeat","app":"morsewurst","device":"Morsewurst Keyer","fw":"1.0","mode":"raw_timing","uptime":5000000,"wpm":20,"telemetry":true}

Tone message fields

Practical minimum implementation

1. Open a USB CDC Serial connection at 115200 baud.
2. Send a hello message when the connection is available.
3. Send a heartbeat message regularly.
4. Measure the start time of the key press in microseconds.
5. Measure the release time of the key press in microseconds.
6. Calculate the duration in microseconds.
7. Send one tone message for each press.

{"v":1,"type":"hello","app":"morsewurst","device":"Morsewurst Keyer","fw":"1.0","mode":"raw_timing"}
{"v":1,"type":"heartbeat","app":"morsewurst","device":"Morsewurst Keyer","fw":"1.0","mode":"raw_timing","uptime":5000000,"wpm":20,"telemetry":true}
{"v":1,"type":"tone","src":"straight","t0":6000000,"t1":6100000,"dur":100000}

Build order

1. Load the Arduino sketch into the Arduino IDE.
2. Select the correct ESP32-S3 board and USB settings.
3. Test ESP32 programming with a USB-C data cable.
4. Connect the OLED display and make sure the image appears correctly.
5. Connect the rotary encoder and test menu control.
6. Connect the straight key to GPIO12 and GND.
7. Connect the iambic paddle to GPIO9, GPIO10 and GND.
8. Build the sidetone circuit with the potentiometer and resistors.
9. Test the headphone output at low volume.
10. Test USB serial telemetry in Morsewurst.
11. Test USB keyboard mode if needed.
12. Print the enclosure from PETG.
13. Clean up the holes carefully.
14. Solder the final wiring.
15. Install the parts in the enclosure.
16. Do a final test before closing the enclosure.

Safety and reliability notes

• Use 3.3 volt logic.
• Do not feed 5 volts into ESP32 GPIO pins.
• Do not drive a speaker directly from GPIO11.
• Start headphone tests at low volume.
• Make the final wiring as short and mechanically solid as possible.
• Avoid loose connectors in a tight enclosure.
• Clearly mark GND wires.
• Test each part separately before final assembly.

This guide describes the practical build path for the current Morsewurst Keyer. Details may change as the hardware and firmware evolve.