Rotor / Antenna Control

HAM-Tools turns your antenna rotator via Hamlib (rotctld). 22 models come preconfigured: SPID, Yaesu GS-232, Hy-Gain, Idiom Press, Green Heron, EA4TX, Prosistel, M2, and for satellite work Easycomm/LVB/Fodtrack (the Hamlib backend knows more beyond that — the 22 are the curated profiles with verified factory defaults).

New in 1.29.0

Rotator control is new. You set it up under Settings → Rotor (⌘,). Like SSTV it's still young — feedback from users with a rotator connected is welcome.

Connection Types

Pick it in the "Path" picker in the Connection section of Settings → Rotor — selectable per configuration:

Connection	What's behind it
USB (Serial)	The standard: HAM-Tools starts its own rotctld on the USB serial port. A separate Hamlib is not needed — the binary ships with the app
Network (rotctld)	Dock onto an already running rotctld — e.g. a remote rotator on another machine on the LAN

Loopback-only on the USB path

The rotctld started by HAM-Tools deliberately listens on 127.0.0.1 only — so the rotator is not reachable over the LAN. For a rotator you deliberately expose on the network, use the Network path against your own rotctld.

Network (rotctld) — External Hamlib Server

If a rotctld is already running on another machine (or started locally by hand), HAM-Tools just docks onto it:

• Host: 127.0.0.1 for the same machine, otherwise the LAN IP of the shack PC
• Port: the standard rotctld port is 4533

First Setup (USB)

This is how to set up the standard path via a USB-serial adapter:

1. Connect the rotator controller to the Mac via a USB-serial adapter, power it on
2. ⌘, → Rotor tab
3. Pick the manufacturer (SPID / Yaesu / Hy-Gain / … / Hamlib Dummy for testing without hardware)
4. Pick the model — the factory defaults (baud, data bits, parity, handshake) and the azimuth / az-el capability load automatically
5. Leave the connection on USB (Serial)
6. Pick the USB port — the dropdown lists the available /dev/cu.* (the 🔄 button refreshes the list)
7. Click "Connect" — the status light at the top goes from grey (Not connected) to orange (Connecting…) to green (Connected), and the live azimuth appears

→ Step by step with driver check and troubleshooting: Tutorial: Rotor Setup

Rotator Models

The model picker (manufacturer → model) covers the common controllers. Each profile brings the matching Hamlib rotor number, verified serial defaults and the azimuth / az-el capability:

Manufacturer	Models	Az/El
SPID	Rot1Prog (e.g. RAU), Rot2Prog (e.g. RAS), MD-01/02	Rot1Prog: az only · others az/el
Yaesu	GS-232A (G-800/1000/2800DXA, G-5500), GS-232B, GS-232 Generic (clones)	az/el
Hy-Gain	DCU-1/DCU-1X (Ham-IV, T2X), DCU2/DCU3/YRC-1	az only
Idiom Press	Rotor-EZ, RotorCard	az only
Green Heron	RT-21 (DCU-1)	az only
DF9GR	ERC (Easy Rotor Control)	az only
EA4TX	ARS RCI (Az/El), ARS RCI (azimuth only)	depends on variant
Prosistel	D (azimuth), Combi-Track (Az/El)	depends on variant
M2	RC2800	az/el
Easycomm	Easycomm II (SatPC32/Gpredict), Easycomm III	az/el
AMSAT	LVB Tracker	az/el
XQ2FOD	Fodtrack	az/el
Hamlib	Dummy rotor (test without hardware)	az/el

Below the picker you see the Hamlib rotor no. and whether the model does az/el or azimuth only. "Reset factory settings" brings the verified defaults back if you have changed the serial parameters.

Serial defaults are editable

The preset values (baud rate, data bits, stop bits, parity, handshake) come from Hamlib. If your controller differs — say a different baud rate on the device — adjust them under Serial interface. Example: SPID runs at 600 Bd, Hy-Gain DCU-1 at 4800 Bd, Yaesu GS-232 at 9600 Bd.

Calibration & Rotation Range

In the Calibration & rotation range section:

Field	Description
North offset	Degrees added to the rotor's reading. If the rotor reports 0° while the antenna points to 10°, enter 10. Display, targets and spot bearings are then true directions
Rotation range	Mechanical range in rotor degrees (before the north offset), default 0–360. from 1.56 For rotators with overlap e.g. 0–450: the app picks the allowed position closest to the current one. If a target lies outside, the rotor doesn't turn and "Target cannot be reached with this north offset and rotation range. Please check the target and calibration." appears
Use elevation (az/el)	Only visible on az/el models — leave off for azimuth-only beams (hexbeam). When on, the manual target gets an elevation slider (0–90°), the current elevation is shown, and a spot click turns azimuth only and keeps the current elevation from 1.56. When off, every move goes with elevation 0

In the Polling section you set the poll interval (default 1000 ms, minimum 200 ms — smaller values are raised) — how often the live azimuth is read from the rotator.

Spot Click → Turn to the DX Bearing

Like a CAT QSY

Just as a spot click turns the radio to the frequency, it optionally turns the antenna to the bearing.

In the DX spots section, enable "Automatically turn to the bearing when clicking a spot". After that, a click on a DX cluster spot turns the rotator to the great-circle bearing to the DX station:

• The bearing is computed from your QTH locator (station settings) and the DXCC location of the spot.
• Works only with a connected rotator.
• The north offset and the rotation range (see above) are taken into account.

Turning Manually & Status

The Status section at the very top shows a compass rose with the actual needle (red) and a target marker, plus the current azimuth in degrees:

• Connect / Disconnect — starts or ends the rotctld connection. "Disconnect" is already available during "Connecting…" and cancels the attempt
• Manual target — slider 0–360°, "Turn" drives the rotator there
• Stop — halts a running rotation immediately

While the rotator moves, "turning to X°…" shows below the azimuth. It disappears as soon as the rotator is within 2° of the target. Error messages appear in red directly below.

Configuration changed while connected from 1.56

If you change the active configuration while the rotator is connected, an orange "Rotor configuration changed. Stop still controls the previously connected rotor. Disconnect and reconnect to use the new configuration." appears. "Turn" and the spot click are then blocked; "Stop" still acts on the previous rotator. Only "Disconnect" and "Connect" again apply the change (poll interval and north offset too). Renaming alone doesn't count as a change. If the configuration is changed during "Connecting…", the app aborts with "Rotor configuration changed while connecting. Please connect again."

Multi-Config

You can save several configurations — e.g. one per rotator:

1. Make the settings for rotator A (model + port + calibration)
2. "Save as…" → enter a name (e.g. SPID Big-Yagi) → Save
3. Configure rotator B (switch model/port)
4. "Save as…" again → Green Heron VHF
5. Switch between configs: in the "Active config" picker at the top

WARNING

Changes apply to the currently active config. If you switch rotator in the picker, the other config stays untouched — it's saved.

Hamlib Under the Hood

HAM-Tools ships with its own rotctld binary (Universal2, static, in Contents/Helpers/rotctld in the app bundle, Developer-ID signed). You don't need to install a separate Hamlib.

On the USB path, rotctld is started as a subprocess:

rotctld -m <hamlibRotNumber> -r <port> -s <baud> -C data_bits=8,stop_bits=1,… -T 127.0.0.1 -t 4533

HAM-Tools then talks to rotctld via TCP on 127.0.0.1:4533 (Hamlib text protocol p = read position, P <az> <el> = set, S = stop). On the network path there's no own subprocess — the app connects directly to your rotctld on the configured host/port.

Troubleshooting

Symptom	Possible cause
Light red, "No serial port selected." or "No rotator model selected."	Pick the USB port under Serial interface or the model under Rotor
Light turns red "Error"	Port busy (another app/old rotctld instance), wrong baud rate, cable unplugged, or wrong model number. from 1.56 HAM-Tools no longer ends a leftover rotctld instance (e.g. after a crash) by itself — run pkill rotctld in Terminal
Reconnected right after "Disconnect": "The rotor service is still shutting down. Please wait a moment and reconnect." from 1.56	On the USB path the old rotctld is still winding down — wait a moment, then "Connect" again
Suddenly red during operation, e.g. "Connection to rotctld lost."	Cable, controller or network rotctld gone — the app disconnects and does not reconnect automatically. Fix the cause, then "Connect"
Connected, but azimuth stays on "—°"	The baud rate doesn't match the controller, or the model doesn't answer position queries — check the device's factory baud
Antenna turns to the wrong angle	Calibrate the north offset; for overlap rotators set the rotation range correctly (e.g. 0–450)
Elevation missing / ignored	The model is "azimuth only", or the "Use elevation" toggle is off
Spot click doesn't turn	Toggle in DX spots off, rotator not connected, or no own QTH locator in the station settings. from 1.56 Also blocked if the configuration was changed since connecting (orange message) or the target lies outside the rotation range
Port doesn't appear in the dropdown	Press the 🔄 button; the USB-serial driver may be missing (FTDI / Silicon Labs CP210x)

For reproducible problems → Report a bug (⌘⇧B) with the diagnostics attachment enabled.

Tips

• Test without hardware: pick manufacturer Hamlib, model "Dummy rotor (test without hardware)" — the app connects to a simulated rotator, good for UI and spot-click tests.
• Several rotators: one config per rotator, switch via the picker.
• Remote rotator: start rotctld on the shack PC and use the Network path in HAM-Tools with its LAN IP.

→ Related: DX Cluster (spot source), CAT / Radio Control (same Hamlib foundation), Settings → Rotor