AeroMorse is an open-source CircuitPython project directed by Jim Lubin — a ventilator-dependent quadriplegic who has used Morse code for computer access since 1989. Inspired by AirTalker, it turns an Adafruit Feather microcontroller into a USB HID keyboard and mouse that connects via USB-C and appears to the host as a standard keyboard and mouse with no drivers required. Works on Windows, macOS, Linux, iPadOS, Android, and ChromeOS.

Sibling project — MorseKey: the same Morse engine on an Adafruit TRRS Trinkey (thumb-drive sized) for AT switch input — one or two switches through the headset jack, no pressure sensor or display. Use it when you want the smallest possible switch-based Morse keyboard/mouse.

How this project was built — what's confirmed vs documented. Jim is the user, project lead, and source of all design decisions: hardware choices, input-mode requirements, Morse code-set conventions, accessibility trade-offs, and ongoing user feedback (his own and from other AAC users — Darci USB veterans in particular). The firmware (code.py), the build guide, and the comparison documents were written by Claude Opus 4.7 (Anthropic) acting as the coding assistant — a "vibe coding" workflow in which Jim directs and Claude writes. Jim does not write the firmware himself, and has not personally soldered or assembled every hardware combination listed here. Several options — particularly some board / display / speaker combinations — are documented from datasheets and Claude's understanding of the parts rather than from a verified build.

If you build a configuration, please report back via a GitHub issue — whether it works or doesn't. Confirmed-vs-theoretical is the single most useful signal this project can collect right now.

Input is by sip-and-puff (LPS33HW pressure sensor) or two standard AT switches. A short sip (or switch 1) is a dot; a short puff (or switch 2) is a dash. A small OLED display shows the active group, the Morse pattern as it builds, and the last action. An optional speaker beeps for every dot and dash.

Ten groups organize all functions — g0 plus g1–g9:

• Group 0 — always-available system layer; 8-symbol patterns jump directly to any other group from anywhere
• Group 1 — Keyboard: letters, numbers, punctuation, function keys, navigation, sticky modifiers (default group at boot)
• Group 2 — Mouse: movement, clicks, drag, repeat, and Windows shortcuts
• Group 3 — Macro: user-defined text strings
• Group 4 — Scanning: Enter, Space and F3–F12 on the 12 shortest codes — for iOS / Android Switch Control
• Group 5 — Media: USB HID Consumer Controls — play/pause, volume, mute, track skip, brightness, plus launchers for calculator, file explorer, browser, and mail
• Group 7 — Switch: no Morse — a sip holds Enter and a puff holds Space for as long as you keep going, like two real switches (games and switch apps). See AEROMORSE_SWITCH_MODE_GUIDE.md
• Groups 6, 8, 9 — Placeholders seeded with g1's letters and numbers, ready for you to customise

Groups cycle with a long sip or puff. An optional ESP-NOW wireless display mirrors the main screen on a second board up to ~30 m away — useful when the sensor is mounted behind the user.

Existing Darci USB users can drop in morse_map_darci.py to use their familiar code set. All Morse assignments are fully customizable in morse_map.py. Parts cost approximately $50–$100 in off-the-shelf components.

AeroMorse is a modern, open-source alternative to the WesTest Darci USB Morse-code input device (now end-of-life, Windows-only, ~$1000+).

If you are a current Darci user or know someone who is, AeroMorse provides:

• ✅ The same Morse codes you already know — letters A–Z, numbers 0–9, punctuation, F-keys, navigation, and modifiers can all use Darci's exact code set via the included morse_map_darci.py drop-in code map.
• ✅ Modern OS support — works on Windows 10/11, macOS, Linux, ChromeOS, iPadOS, and Android. No Windows-only Mouse Keys dependency.
• ✅ Lower cost — ~$50–$100 in off-the-shelf parts vs. ~$1000+ commercial device.
• ✅ Built-in sip-and-puff — no external interface required.
• ✅ Active development — open source, customisable, and supported.
• ✅ Optional wireless remote display — see the user's screen from across the room (no equivalent on Darci).

Read AEROMORSE_VS_DARCI.md for a full feature-by-feature comparison, an honest list of what AeroMorse cannot do (single-switch timed input, 3-switch end-of-character mode), and a migration checklist.

To preserve Darci muscle memory, rename morse_map_darci.py to morse_map.py on the CIRCUITPY drive. All codes in that file are transcribed verbatim from the Darci USB Owner's Manual (P/N 3001508).

If a pressure sensor is not available, two momentary normally-open switches can be wired instead. Set USE_SENSOR = False in code.py.

Wire each switch between the GPIO pin and GND. The firmware enables internal pull-up resistors, so no external resistors are needed.

With the sensor option, wiring is a single cable:

ESP32-S3 Reverse TFT Feather   ←—— STEMMA QT cable ——→   LPS33HW sensor
      STEMMA QT port                                       STEMMA QT port

No soldering required. The STEMMA QT cable carries power, ground, and I²C data. Plug the sip-and-puff tubing into the small port on top of the LPS33HW.

Board without a STEMMA QT port? (e.g. the Feather nRF52840 Express.) Wire the sensor to the board's I²C pins instead — use a STEMMA QT to male-header cable (#4209) or solder wires:

No config change is needed: code.py uses the STEMMA QT port when the board has one and otherwise falls back to board.I2C() on the SDA/SCL pins (firmware v1.4+). The serial console notes when it does.

The CIRCUITPY drive is the FAT filesystem that appears when the feather is connected to a computer.

These are pre-compiled .mpy files from the Adafruit CircuitPython Bundle. Download the bundle matching your CircuitPython version and copy the listed items from its lib/ folder.

The Build Guide §9 has the full walk-through (with Thonny, the serial console, and troubleshooting). Here's the short version:

1. Go to https://circuitpython.org/downloads
2. Search for your Feather board name (e.g. "ESP32-S3 Reverse TFT").
3. Download the latest stable .uf2 file — not a pre-release / "absolute newest" build. (An older Feather bootloader may fail to flash a much newer CircuitPython; if the drive won't switch to CIRCUITPY, try the previous stable major version.)
4. Plug the Feather into your computer with the USB-C data cable (a charge-only cable won't show a drive).
5. Double-tap the small Reset button quickly (two taps within about half a second).
   • The NeoPixel LED on the Feather turns green.
   • A drive named FTHRS3BOOT (or similar) appears on your computer.
6. Drag the .uf2 file you downloaded onto that drive.
7. The Feather reboots automatically. After a few seconds a drive named CIRCUITPY appears. Done.

If CIRCUITPY already appears when you plug in (without double-tapping), CircuitPython is already installed — skip to step 2. If you see FTHRS3BOOT every time you plug in without double-tapping, the board just has no code loaded yet — that's normal, continue.

1. Go to https://circuitpython.org/libraries
2. Download the Bundle that matches your CircuitPython version. To find your version, open boot_out.txt on the CIRCUITPY drive — it says something like Adafruit CircuitPython 10.2.0, so download the matching major version (9.x or 10.x).
3. Open the .zip; inside is a folder called lib.
4. On the CIRCUITPY drive, open (or create) the lib folder, and copy in the items from the Required Libraries table above (from the bundle's lib folder — you don't need the whole bundle).
   • Two are easy to miss: neopixel.mpy (a bare file with no adafruit_ prefix, so it sorts to the bottom of the bundle's lib) and adafruit_lps35hw.mpy (your sensor is the LPS33HW, but the driver is named lps35hw — the same file covers both).

Download the four AeroMorse files from the repo — green < > Code button → Download ZIP, then unzip. Copy these from the ZIP's root to the root of CIRCUITPY:

boot.py   code.py   config.py   morse_map.py

Always get these from https://github.com/jlubin2001/AeroMorse — copies posted elsewhere may be older. Each file's header comment shows its version and release date; keep all four at the same version.

Safely eject the drive and press the Reset button (or unplug and replug). On power-up the device calibrates for one second (hold the tube still — do not sip or puff), then the TFT display shows the start screen:

• the device's name (DEVICE_NAME in config.py, e.g. AeroMorse Green),
• the AeroMorse version (e.g. v1.15),
• the CircuitPython version (e.g. CP 9.2.9).

The device is now ready. Your first sip, puff or switch press only closes the start screen — it types nothing — and the display changes to [ KEYBOARD ]. From then on every sip/puff counts. (To see the start screen again later, use the Mouse-group version command, ...-.)

The firmware uses a three-state machine that matches standard Morse timing:

• DIT — sensor is below sip threshold
• DAH — sensor is above puff threshold
• IDLE — pressure is within the neutral band

Each time the sensor transitions from DIT or DAH back to IDLE, that element (dot or dash) is recorded. After 0.2 seconds of continuous IDLE with at least one element recorded, the accumulated pattern is looked up in the code table and the matching action fires.

Holding a sip or puff for the LONG_PRESS duration cycles through groups 1–9 instead of recording an element (Group 0 is skipped — its 8-symbol patterns remain available in the background at all times):

The Switch group (Group 7) is skipped when cycling: long presses don't change group inside Switch mode (games need long holds), so cycling into it would leave you stuck. Enter Switch mode on purpose with ...-----.

With ten groups, cycling all the way around is slow — use the 8-symbol Group 0 jump codes below to go straight to any group from anywhere.

The device has ten groups: g0 (always-on) plus g1–g9. The active group determines which code table is used for pattern lookup. Group 0 is always checked first, regardless of the active group — its 8-symbol patterns are available at all times.

These 8-symbol patterns work in any group and jump directly to the named group. The codes use a "count of trailing dashes" scheme: 8 dots = g1, then add trailing dashes to reach the higher groups.

The default group after power-on. Provides letters, numbers, punctuation, function keys, navigation keys, and modifier keys.

Two non-standard patterns free up codes for high-frequency control keys:

7-symbol patterns. The dash/dot boundary shifts one step per key:

Modifier keys are sticky: press the pattern once to arm the modifier. The modifier symbol will appear on the TFT display. The next key pressed fires with that modifier held, then the modifier automatically releases. Press the modifier pattern again while it is armed to disarm it without firing.