Contest with F1–F8 Macros
In 20 minutes, go from "contest starts in 30 min" to "macros are set, CW flies at the press of a button, SSB voice is recorded".
Prerequisites
- CAT setup finished (Hamlib
send_morseneeds an active CAT connection, and so does SSB PTT) - Built-in microphone or USB mic for SSB recordings
- A radio partner or dummy load to test before the contest
Step 1 — Create a Contest Log
- Main window → sidebar → "Contest"
- Toolbar "+ Log" → a sheet opens
- Required fields:
- Contest template: e.g.
CQ-WW CW 2026orUSKA Field Day SSB(40 templates built in, see the Contest module) - Category-Operator:
SINGLE-OP(solo) orMULTI-OP-SINGLE/MULTI-OP-MULTI(see the Multi-Op tutorial) - Power, Mode, Assisted/Non-Assisted, Bands — Cabrillo header tags, taken straight from the template default; you only need to check them
- Contest template: e.g.
- "Create"
The log is now active. The F1–F8 macro row appears below the QSO entry form.
Step 2 — Mode Indicator Above the Buttons
Above the F1–F8 row you'll see a small indicator:
| Display | Meaning |
|---|---|
| 🔵 CW | TRX mode (from CAT) is CW → clicking sends via Hamlib send_morse |
| 🟠 SSB | TRX mode is LSB/USB/AM → clicking plays the .m4a recording via PTT toggle |
| ⚪ inactive | No CAT connection or no macro in the slot |
The beauty: you don't have to switch anything. When you move between CW and SSB during the contest (dual-mode contests), the macro behavior changes automatically too.
Step 3 — CW Macros (ready to use immediately)
The factory assignment matches the N1MM standard and works for 80% of all contests right away:
| Slot | Label | CW text |
|---|---|---|
| F1 | CQ | CQ TEST {MyCall} {MyCall} TEST |
| F2 | Exch | {TheirCall} {Snt} — {Snt} already contains the report; up to 1.56 "5NN" was sent twice from 1.57 |
| F3 | TU | TU {MyCall} |
| F4 | MyCall | {MyCall} |
| F5 | HisCall | {TheirCall} |
| F6 | ? | ? |
| F7 | 5NN | 5NN |
| F8 | AGN | AGN |
Available variables in CW templates:
| Variable | Replacement |
|---|---|
{MyCall} | Your callsign from Station settings (or per-log override) |
{TheirCall} | The contents of the call field in the form |
{Snt} | RST sent (default 599 for CW) |
{Rcv} | RST received (what you entered in the field) |
{Cnt} | Running QSO number (serial) |
{Exch} | Contest exchange (e.g. CQ zone, section) |
{Ref} | Your own reference of the active log (POTA park, SOTA summit, …) — empty in contests |
Step 4 — Customize Macros
- Settings → Macros (
⌘,→ "Macros" tab) - You see 8 slots as rows
- Per slot you can change:
- Label (what's printed on the button)
- CW text (template with variables)
- SSB audio (see next step)
Factory reset: the "Reset to factory assignment" button at the bottom — restores the N1MM defaults (all 8 slots at once).
Two profiles: Contest and General
There are two global 8-slot sets: Contest (below the contest form) and General (in the DX form and all outdoor forms, factory defaults with {Ref} for POTA/SOTA etc.). Each has its own reset. There are no per-template contest sets — adjust or reset when the contest changes.
Step 5 — SSB Voice Recordings
For SSB contests you replace the CW text with an audio file. On the first run, macOS asks for microphone permission — NSMicrophoneUsageDescription in the app's Info.plist explains why.
- Select a macro slot, button "Record" (or the microphone icon)
- A 3-2-1 recording runs with a seconds timer
- "Stop" → an AAC/m4a file is saved to
~/Library/Application Support/HAM-Tools/Macros/Contest/(Settings → Data → Voice-Keyer opens the folder) - "Preview" (without PTT) to check
- On a bad take: "Re-record" — the previous recording is kept until the new one has been saved successfully
Tips for clean recordings:
- Deliberately skip 2 seconds of leading silence — the PTT toggle needs no buffer at the start of the recording
- Leave 0.5 seconds of trailing time at the end — PTT is only released when the AudioPlayer finishes (
onFinishcallback) - A USB headset sounds audibly better than the Mac mic
- Avoid clipping — the TRX mic level does the rest
Step 6 — TRX Voice Keyer (ICOM V1–V4, Yaesu V1–V5) as an Alternative
If your TRX has a built-in voice keyer (ICOM IC-7300, IC-7610, IC-9700, IC-705; Yaesu FT-991/A, FT-710, FTDX-10/101), you can use the TRX's internal slots instead of the HAM-Tools macros.
Every entry form (DX, Contest, POTA, SOTA, WWFF, BOTA) has a V1 / V2 / V3 / V4 button row — it triggers the TRX slots over CAT. For Yaesu profiles, since 1.9.10 there's an additional V5 (Yaesu has five slots, ICOM four). There is deliberately no Stop button, and Esc only affects the HAM-Tools macros: Hamlib's stop_voice_mem has no effect on the Yaesu and ICOM rigs tested. Cancel a running TRX playback on the rig itself.
When is which worth it?
| Scenario | Recommendation |
|---|---|
| You have ICOM and want to mix CW + SSB | HAM-Tools macros (CW + SSB), voice keyer only as backup |
| You don't have a voice-keyer-capable TRX | HAM-Tools SSB recordings, no V1–V4 |
| You're doing SSB-only contest with an ICOM IC-7610 | TRX V1–V4 (better sound, less CPU load on the Mac) |
| You're doing CW only | HAM-Tools macros (V1–V4 is SSB-only) |
Recording the voice keyer
That's done via the TRX menu, not through HAM-Tools. On the IC-7300, for example: Menu → MEM/CH → VOICE → REC. HAM-Tools only triggers playback.
Step 7 — During the Contest
Keyboard workflow during the contest — F1–F8 trigger the slots, Esc stops, even while the cursor sits in a text field. macOS must deliver the F-keys as standard function keys (System Settings → Keyboard → “Use F1, F2, etc. keys as standard function keys”), otherwise hold fn as well.
- F1 → send the CQ call
- Type the caller into the call field (or double-click from the bandmap)
- F2 → send the exchange (CQ-WW:
K1AA 5NN 03, Field Day:K1AA 5NN 1A WMA) - The other station answers with their exchange — you type it into the RST/Exch field
- Return logs the QSO
- F3 → send TU, new round
Stop / abort: The red stop button or Esc sends Hamlib stop_morse for CW (whether the rig aborts mid-character depends on the backend) and, for SSB, stops the running recording including the PTT release. Safety workaround: turn off TRX VOX, then the manual PTT button locks everything.
Free-text CW: With the rig in CW, a text field appears next to Stop. Type the text, Enter sends it via send_morse; variables such as {TheirCall} are substituted here too. Handy for anything that doesn't fit a slot (“QRL?”, “PSE QSY 7033”).
Common Problems
F1 is pressed, but no tone / no transmit
→ CAT status green? radio.hamlibMode must be known. Test in the CAT tab whether the frequency is live. If not → walk through CAT setup again.
SSB recording doesn't play back
→ File present? Check ~/Library/Application Support/HAM-Tools/Macros/Contest/ for the .m4a. If it's there, it's probably a PTT problem — the TRX profile has supportsPTT: false, you need an external interface.
Variable {Cnt} shows 0
→ The serial counter only counts up once QSOs are logged. Before the first QSO, the serial is logically empty.
Microphone permission denied
→ System Settings → Privacy & Security → Microphone → turn on HAM-Tools. If the app doesn't appear in the list: try a recording once, and macOS will then ask automatically.
CW works but the send speed is too slow/fast
→ Hamlib uses the TRX's internal WPM setting. Change it in the TRX menu (IC-7300: speed knob top right, Yaesu FT-991A: menu item Z2-15).
Next Steps
- Multi-Op Contest — logbook with multiple OPs
- Contest module — templates, scoring, Cabrillo export
- Macros settings — settings overview
- The macro row is also available in the DX form and the outdoor forms (profile General, only while CAT is connected) — see Logbook module