Getting Started

Everything you need to set up Morse-Pi and start practicing Morse code.

Quick Start

SSH into your Raspberry Pi and run these three commands:

1. Update package lists

sudo apt update

2. Upgrade installed packages

sudo apt upgrade -y

3. Install Morse-Pi (Rust backend)

curl -sSL https://raw.githubusercontent.com/Nerd-or-Geek/Morse-Pi/main/install-rust.sh | sudo bash

Features

Requirements

Minimum (software only)

• Rust backend: Any Linux system with a Rust toolchain (installed automatically)
• Python backend: Any computer with Python 3.9+
• A modern browser on the same machine or network

Full hardware setup (Raspberry Pi)

• Raspberry Pi — any model with 40-pin GPIO (Pi 3B+, Pi 4, Pi Zero 2 W, etc.)
• A piezo buzzer or small speaker wired to one or two GPIO pins
• A Morse key (straight key) or iambic paddle (two contacts)

For USB HID Keyboard mode

• Pi Zero, Zero W, Zero 2 W, or Pi 4 (must support USB OTG)
• A USB data cable (not power-only)
• Connect via the USB data port (on Pi Zero, the port labeled "USB" — not "PWR")

Installation

Option A — Rust backend Recommended

The Rust backend compiles to a single native binary with no runtime dependencies. SSH into your Raspberry Pi and run:

curl -sSL https://raw.githubusercontent.com/Nerd-or-Geek/Morse-Pi/main/install-rust.sh | sudo bash

The installer performs four steps:

1. USB HID Keyboard Gadget — configures the Pi to appear as a USB keyboard when plugged into a computer
2. Rust Toolchain — installs rustup, cargo, pigpio dev headers, and build-essential
3. Build — clones the repo and runs cargo build --release --features gpio
4. Auto-start — creates a systemd service so Morse-Pi runs on every boot

Option B — Python backend

The original Python/Flask backend. Faster to install, easier to modify:

curl -sSL https://raw.githubusercontent.com/Nerd-or-Geek/Morse-Pi/main/install.sh | sudo bash

The installer performs four steps:

1. USB HID Keyboard Gadget — configures the Pi to appear as a USB keyboard
2. Packages — installs python3, pip, git, flask, gpiozero, pigpio
3. Repository — clones the code to /opt/morse-pi
4. Auto-start — creates a systemd service so Morse-Pi runs on every boot

Once running, open your browser to the IP address shown on screen:

http://192.168.1.42:5000

Switching from Python to Rust

Already running the Python backend? Transition in-place without losing your settings:

curl -sSL https://raw.githubusercontent.com/Nerd-or-Geek/Morse-Pi/main/transition-rust.sh | sudo bash

This installs the Rust toolchain, builds the binary, backs up your data, replaces the Python files, and restarts the service.

Manual installation (Rust)

# 1. Clone
git clone https://github.com/Nerd-or-Geek/Morse-Pi.git
cd Morse-Pi/morse-translator-rust

# 2. Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# On Raspberry Pi, also install GPIO deps:
sudo apt install libpigpio-dev pigpio build-essential -y
sudo systemctl enable pigpiod --now

# 3. Build and run
cargo build --release --features gpio
./target/release/morse-pi

Manual installation (Python)

# 1. Clone
git clone https://github.com/Nerd-or-Geek/Morse-Pi.git
cd Morse-Pi

# 2. Install dependencies
sudo pip3 install flask --break-system-packages

# On Raspberry Pi, also:
sudo apt install python3-gpiozero pigpio python3-pigpio -y
sudo systemctl enable pigpiod --now
sudo usermod -aG gpio $USER

# 3. Run
cd morse-translator
python3 app.py

Then open http://localhost:5000 (or the Pi's IP from another device).

GPIO Wiring

Straight key (single-pin mode)

Iambic paddle (dual-pin mode)

GPIO header pinout (subset)

Ground output pins

If your paddle's common wire is soldered to a GPIO pin instead of a physical GND pin, you can assign that GPIO as a Ground Output in the CONFIG or diagnostic panels. The Pi will drive that pin permanently LOW so it acts as a ground reference.

Modes & Tabs

The Morse-Pi web UI is a single-page application with nine tabs along the top navigation bar:

SEND Mode

SEND is the primary Morse code practice mode. Key Morse using your hardware key, on-screen buttons, or keyboard shortcuts, and watch your input decoded in real time.

How it works

1. Press and hold your key (or Space) to generate dots and dashes
2. The symbol buffer shows your current dots/dashes as you key them
3. After a letter gap (3 dot units of silence), the character is decoded and appended to the output
4. After a word gap (7 dot units), a space is inserted

Input methods

ENCODE Mode

Type or paste any text into the input field and instantly see the Morse code translation. Each character is broken down showing the letter and its Morse equivalent.

• Click Play to hear the Morse code through the buzzer/speaker
• Supports letters A–Z, numbers 0–9, and common punctuation
• Spaces between words are shown as /

DECODE Mode

A quiz-style trainer: the app shows a random word or phrase in Morse code. You type your decoded answer and submit.

• Difficulty levels: Easy (short words), Medium, Hard (longer phrases)
• Click Play to hear the Morse phrase as an audio hint
• Tracks correct answers, wrong answers, current streak, and best streak
• New phrase generated on each submission or when switching to DECODE mode

SPEED Trainer

A speed drill that measures how fast and accurately you can key a displayed phrase.

1. A phrase is displayed on screen
2. Key the phrase using your paddle or keyboard
3. A timer starts automatically when you begin keying
4. Submit when done — the app compares your keyed Morse with the expected phrase

Results include:

• WPM — your measured words-per-minute
• Accuracy — character-by-character comparison
• Elapsed time

USB Keyboard (KB)

The KB tab controls USB HID keyboard mode. When enabled, decoded Morse characters are sent as real keystrokes to whatever computer the Pi is plugged into via USB.

See the USB HID Keyboard page for full setup and configuration details.

Networking (RADIO)

Multiple Morse-Pi devices on the same LAN automatically discover each other — no configuration needed.

How discovery works

• Each Pi broadcasts a UDP beacon on port 5001 every 3 seconds
• The beacon contains the device name, IP address, and port
• Other Pis listen for these beacons and maintain a peer list
• Peers that haven't been seen for 15 seconds are automatically removed

Sending messages

1. Open the RADIO tab
2. Select a discovered peer from the list
3. Type a message and click SEND, or key Morse using your paddle and send the decoded text
4. The message is sent via HTTP to the peer's /receive_morse endpoint
5. The receiving Pi plays the message through its speaker and shows it in the inbox

Statistics

The STATS tab shows your practice history:

• Total attempts — decode and speed drills combined
• Correct answers
• Current streak — consecutive correct answers
• Best streak

Stats are saved to stats.json and persist across restarts and updates. Click Reset to start fresh.

Configuration

All settings are configurable live from the CONFIG tab — no files to edit, no restarts needed.

See the Settings Reference for a full table of every setting.

Key sections

• Input Mode — switch between straight key (single pin) and iambic paddle (dual pin)
• Pin Assignment — choose which BCM pins are used for data, dot, dash, speaker, and ground
• Audio — dot frequency, dash frequency, volume, output type (speaker PWM or LED on/off)
• Speed — WPM target with a "Test WPM" button that plays "PARIS" at the configured speed
• Farnsworth Timing — toggle extra spacing on/off and set Farnsworth speed (WPM) below Character WPM
• Quiz — difficulty level and word categories
• Theme — dark or light UI theme
• Device Name — the name shown to other Pis on the network

Keyboard Shortcuts