ROTCTL(1)

💖 ROTCTL — control antenna rotators 💖

okay so this is the rotctl page from the Hamlib Utilities manual, section 1, and bestie it's literally your new favorite command. let's get into it 🦋

---

✨ NAME ✨

rotctl — control antenna rotators 🎀

---

🌸 SYNOPSIS 🌸

rotctl [-hiIlLuV] [-m id] [-r device] [-R device2] [-s baud] [-t char]
       [-C parm=val] [-o azoffset] [-O eloffset] [-v[-Z]] [command|-]

---

💅 DESCRIPTION 💅

Control antenna rotators. that's the whole vibe. 👑

rotctl accepts commands from the command line as well as in interactive mode if none are provided on the command line. so like, you can hand it a task directly, or you can just open it up and chat with it. both are valid. both are iconic. 💖

keep in mind that Hamlib is BETA level software 😭. while a lot of backend libraries lack complete rotator support, the basic functions are usually well supported. so like, she's still growing into herself, yk? but she's doing great fr fr.

please report bugs and provide feedback at the e-mail address given in the BUGS section below. patches and code enhancements sent to the same address are welcome. like genuinely, they want your contributions, come through 🫶

---

🌈 OPTIONS 🌈

this program follows the usual GNU command line syntax, no cap. short options that take an argument may have the value follow immediately or be separated by a space. long options starting with two dashes (‘-’) require an ‘=’ between the option and any argument. that's the rule, periodt.

here's a summary of the supported options, bestie — every single one, don't skip 💅

• -m, --model=id — select rotator model number. see model list (use rotctl -l). ✨ note: rotctl (or third party software using the C API) will use rotator model 2 for NET rotctl (communicating with rotctld). iykyk.
• -r, --rot-file=device — use device as the file name of the port connected to the rotator. it's often a serial port, but could be a USB to serial adapter. typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux, COM1, COM2, etc. on MS Windows. the BSD flavors and Mac OS/X have their own designations. see your system's documentation. 🔌
• -R, --rot-file2=device — use device as the file name of the port connected to the 2nd rotator, e.g. 2nd rotator used for elevation. second rotator, second vibe. still often a serial port, but could be a USB to serial adapter. typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux, COM1, COM2, etc. on MS Windows. the BSD flavors and Mac OS/X have their own designations. see your system's documentation. 🌸
• -s, --serial-speed=baud — set serial speed to baud rate. it uses the maximum serial speed from rotator backend capabilities as the default. 🔥
• -t, --send-cmd-term=char — change the termination char for text protocol when using the send_cmd command. the default value is ASCII CR (‘0x0D’). ASCII non-printing characters can be given as the ASCII number in hexadecimal format prepended with “0x”. you may pass an empty string for no termination char. the string -1 tells rotctl to switch to binary protocol. see the send_cmd command for further explanation. ✨ note: the semicolon (‘;’) is a common terminator for rotators that accept ASCII character strings. 💜
• -o, --set-azoffset — azimuth correction floating point — during set, value is added; during get, value is subtracted. math but make it cute. 🧚
• -O, --set-eloffset — elevation correction floating point — during set, value is added; during get, value is subtracted. same energy, different axis. 💫
• -L, --show-conf — list all configuration parameters for the rotator defined with -m above. peek behind the curtain bestie 👀
• -C, --set-conf=parm=val[,parm=val] — set rotator configuration parameter(s), e.g. stop_bits=2. use the -L option above for a list of configuration parameters for a given model number. 🎀
• -u, --dump-caps — dump capabilities for the rotator defined with -m above and exit. bye bestie, here's everything she can do 💅
• -l, --list — list all rotator model numbers defined in Hamlib and exit. the list is sorted by model number. ✨ note: in Linux the list can be scrolled back using Shift+PageUp/Shift+PageDown, or using the scrollbars of a virtual terminal in X or the cmd window in Windows. the output can be piped to more(1) or less(1), e.g. rotctl -l | more. 📜
• -i, --read-history — read previously saved command and argument history from a file (default $HOME/.rotctl_history) for the current session. available when rotctl is built with Readline support (see READLINE below). ✨ note: to read a history file stored in another directory, set the ROTCTL_HIST_DIR environment variable, e.g. ROTCTL_HIST_DIR=$HOME/tmp rotctl -i. when ROTCTL_HIST_DIR is not set, the value of HOME is used. 🕰️
• -I, --save-history — write current session (and any previous session(s), if -i option is also given) command and argument history to a file (default $HOME/.rotctl_history) at the end of the current session. complete commands with arguments are saved as a single line to be recalled and used or edited. available when rotctl is built with Readline support (see READLINE below). ✨ note: to write a history file in another directory, set the ROTCTL_HIST_DIR environment variable, e.g. ROTCTL_HIST_DIR=$HOME/tmp rotctl -I. when ROTCTL_HIST_DIR is not set, the value of HOME is used. 💾
• -v, --verbose — set verbose mode, cumulative (see DIAGNOSTICS below). she's a talker. 😭
• -Z, --debug-time-stamps — enable time stamps for the debug messages. use only in combination with the -v option as it generates no output on its own. ⏰
• -h, --help — show a summary of these options and exit. the classic. 🫶
• -V, --version — show version of rotctl and exit. 🏷️
• - — stop option processing and read commands from standard input. see Standard Input below. ⭐

note: some options may not be implemented by a given backend and will return an error. this is most likely to occur with the --set-conf and --show-conf options. not every rotator got the range, bestie 😭

be aware that the backend for the rotator to be controlled, or the rotator itself, may not support some commands. in that case, the operation will fail with a Hamlib error code. it's giving unsupported, and that's just how it is 💀

---

💬 COMMANDS 💬

okay so here's the tea: you can type a command as a single char or as its long name, dealer's choice bestie. Commands do not get a dash in front like the options do — that's an options thing, not a commands thing, don't mix them up 🙈.

You can type them when you're in interactive mode, or just hand them over as argument(s) in command line interface mode. And in interactive mode? Commands and their arguments can all go on one single line, like:

P 123 45

Now, the pattern that makes everything click: most Hamlib operations have a set and a get method, so UPPERCASE letters usually mean set and the matching lowercase letter means get. Every operation has a long name too — when you're in interactive mode, slap a backslash \ in front to use the long one.

Example: type \get_info in interactive mode and boom, you see the rotator's info ✨

Heads up: the backend for the rotator you're controlling (or the rotator itself) might just not support some commands. No shade, that's just how it is. When that happens the operation fails with a Hamlib error message 💀.

---

📥 Standard Input 📥

So instead of the READLINE interactive entry thing, or one single command per run, rotctl has a special little trick: pass a single dash - and it'll read commands from standard input (stdin) 🫶.

Commands gotta be separated by whitespace, same vibe as the commands you'd give on the command line. And you can drop comments in with the # character — everything from the # to the end of that line, # included, gets ignored entirely. So freeing.

A lil example for you:

$ cat <<.EOF. >cmds.txt
> # File of commands
> set_pos 180.0 10.0     # rotate
> pause 30  # wait for action to complete
> get_pos   # query rotator
>.EOF.

$ rotctl -m 1 - <cmds.txt

set_pos 180.0 10.0
pause 30
get_pos 180.000000
10.000000

$

---

🎡 Rotator Commands 🎡

Here's the whole summary of commands (bestie, quick note on reading this: for set commands the quoted italicized string gets replaced by the value in the description, and for get commands that quoted italicized string is the key name of the value that comes back 🎀):

• Q|q, exit rotctl — bail out of rotctl in interactive mode. When rotctl is driving the rotator directly, it'll close the rotator backend and the port. But when rotctl is connected to rotctld (that's rotator model 2), it just closes the TCP/IP connection to rotctld — and rotctld keeps on living, ready for another TCP/IP network connection 👑.
• P, set_pos 'Azimuth' 'Elevation' — set the position. 'Azimuth' and 'Elevation' are floating point values. Azimuth can be -180 to 540 depending on the rotator (this is so rotators facing south work, and it depends on what your rotator can actually do). Elevation can be -20 to 210, again depending on the rotator. For example:

P 163.0 41.0

Note: if your rotator doesn't support setting elevation (most don't, rip), just supply “0.0” for 'Elevation' 💅.

• p, get_pos — get the position. 'Azimuth' and 'Elevation' come back as double precision floating point values.
• M, move 'Direction' 'Speed' — move the rotator in a specific direction at a given rate, go bestie go 🔥. 'Direction' is an integer or keyword, defined as: ‘2’ = UP, ‘4’ = DOWN, ‘8’ = LEFT or CCW, ‘16’ = RIGHT or CW, ‘32’ = UP_LEFT or UP_CCW, ‘R64’ = UP_RIGHT = UP_CW, ‘128’ = DOWN_LEFT or DOWN_CCW, ‘256’ = DOWN_RIGHT or DOWN_CW. And 'Speed' is an integer between 1 and 100 — use -1 if you want no change to the current speed.

Note: not every backend that implements the move command even uses the Speed value. iykyk 🙈

• S, stop — stop the rotator. Simple. Iconic.
• K, park — park the rotator.
• C, set_conf 'Token' 'Value' — set a configuration parameter. 'Token' is a string — go peep the -C option and the -L output for those. 'Value' is a string of up to 20 characters.
• R, reset 'Reset' — reset the rotator. 'Reset' takes an integer value of ‘1’ for “Reset All”.
• _, get_info — get miscellaneous info about the rotator. Returns 'Info' “Model Name” at the moment.
• dump_state — returns certain state information about the rotator backend.
• 1, dump_caps — not a real rot remote command, it just dumps capabilities, meaning what the backend knows about this model and what it can do. Kind of a vibes report 📋.
• w, send_cmd 'Cmd' — send a raw command string to the rotator. An ASCII CR (or whatever the --send-cmd-term value is, see the -t option) gets appended automatically at the end of the command for text protocols. For binary protocols, enter hexadecimal values like “\0xAA\0xBB”.

---

🗺️ Locator Commands 🗺️

These commands are all about conversions: Degrees Minutes Seconds to other formats, Maidenhead square locator conversions, and distance + azimuth conversions. Math but make it cute 🌸.

• L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len' — returns the Maidenhead 'Locator' for the given 'Longitude' and 'Latitude'. You supply floating point values. The precision of the square you get back is controlled by 'Loc Len', which should be an even numbered integer value between 2 and 12. Like so:

L -170.0 -85.0 12

which returns:

Locator: AA55AA00AA00

• l, loc2lonlat 'Locator' — returns 'Longitude' and 'Latitude' in decimal degrees, at the approximate center of the Maidenhead grid square you asked for. 'Locator' can be from 2 to 12 characters in length. West longitude comes back as a negative value, south latitude comes back as a negative value. For example:

l AA55AA00AA00

returns:

Longitude: -169.999983 Latitude: -84.999991

Note: even though it's using double precision variables internally, some rounding error is gonna happen. Lowkey unavoidable 😭.

• D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W' — returns 'Dec Degrees', a signed floating point value. 'Degrees' and 'Minutes' are integer values. 'Seconds' is a floating point value. 'S/W' is a flag: ‘1’ means South latitude or West longitude, ‘0’ means North or East. Why do we need the flag? Because computers don't recognize a signed zero, even though in DMS notation it's typically only the 'Degrees' value that's signed. Computers stay doing the most 🙄.
• d, dec2dms 'Dec Degrees' — returns 'Degrees' 'Minutes' 'Seconds' 'S/W'. Values work the same as in dms2dec above.
• E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W' — returns 'Dec Degrees', a signed floating point value. 'Degrees' is an integer value. 'Dec Minutes' is a floating point value. 'S/W' is a flag, same as in dms2dec above.
• e, dec2dmmm 'Dec Deg' — returns 'Degrees' 'Minutes' 'S/W'. Values are as in dmmm2dec above.
• B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2' — returns 'Distance' and 'Azimuth'. 'Distance' is in km. 'Azimuth' is in degrees. The Lon/Lat values you supply are signed floating point numbers.
• A, a_sp2a_lp 'Short Path Deg' — returns 'Long Path Deg'. Both the argument you supply and the value that comes back are floating point values within the range of 0.00 to 360.00.

Note: supplying a negative value will return an error message. So don't 💀.

• a, d_sp2d_lp 'Short Path km' — returns 'Long Path km'. Both the argument you supply and the value that comes back are floating point values.
• pause 'Seconds' — pause for the given whole (integer) number of 'Seconds' before sending the next command to the rotator. Chill for a sec bestie 🧚.

---

⌨️ READLINE ⌨️

If the Readline library development files are found at configure time, rotctl will be conditionally built with Readline support for command and argument entry. Slay. Readline command key bindings are at their defaults, exactly as described in the Readline manual. rotctl sets the name “rotctl”, which you can use in Conditional Init Constructs in the Readline Init File ($HOME/.inputrc by default) to get custom keybindings that are unique to rotctl ✨.

Command history is available with Readline support, as described in the Readline History manual. Command and argument strings get stored as single lines even when arguments are prompted for input one at a time. And ngl, commands and arguments are not validated — they're stored exactly as typed, with values separated by a single space.

Normally session history is not saved, but if you use either the -i/--read-history or -I/--save-history options when starting rotctl, that'll cause any previously saved history to be read in, and/or the current plus any previous session history to be written out when rotctl closes (assuming you gave -i and -I together). Each option is mutually exclusive, meaning either one may be given separately or in combination. This is lowkey so useful for saving a set of commands and reading them later — but not writing the modified history — so you get a consistent set of test commands in interactive mode, for example 🎀.

History is stored in $HOME/.rotctl_history by default, though you can change the destination directory by setting the ROTCTL_HIST_DIR environment variable. When ROTCTL_HIST_DIR is unset, the value of the HOME environment variable is used instead. At this time, only the destination directory can be changed. That's it, that's the whole deal 🙈.

If Readline support is not found at configure time, the original internal command handler is used instead. And heads up: Readline is not used for rotctl commands entered on the command line, regardless of whether Readline support is built in or not.

Note: Readline support is not included in the MS Windows 32 or 64 bit binary builds supplied by the Hamlib Project. Running rotctl on the MS Windows platform in the ‘cmd’ shell does give you session command line history, but it is not saved to disk between sessions. Sorry babes 😭.

---

🩺 DIAGNOSTICS 🩺

The -v, --verbose option lets different levels of diagnostics go out to stderr, and they line up like this: -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE. Very demure, very escalating 😌.

A given verbose level is useful for giving the developers the debugging information they need at the email address below. For example, TRACE output shows all of the values sent to and received from the radio, which is extremely useful for radio backend library development — and it may be requested by the developers. So if they ask, you deliver 💅.

---

🚪 EXIT STATUS 🚪

rotctl exits with:

1. 0 — if all operations completed normally;
2. 1 — if there was an invalid command line option or argument;
3. 2 — if an error was returned by Hamlib.

---

✨ EXAMPLES ✨

okay bestie, let's actually do the thing 💅 here's how you spin this up for real:

Kick off rotctl for RotorEZ using the first serial port on Linux:

$ rotctl -m 401 -r /dev/ttyS0

Start rotctl for RotorEZ using COM2 on MS Windows:

> rotctl -m 401 -r COM2

Connect to a running rotctld with rotator model 2 (“NET rotctl”) on the local host, specifying the TCP port, and querying the position:

$ rotctl -m 2 -r localhost:4533 t_pos

Start rotctl for INDI using an address other than the default localhost:5764:

$ rotctl -m 2001 -r example.com:12345

Start rotctl for INDI using the local domain on Linux:

$ rotctl -m 2001 -r @/tmp/indiserver

---

INDI (Instrument Neutral Distributed Interface) is an LGPLv2 software to control astronomical equipment, including telescope mounts that can be used to rotate antennas. 🛰️✨

For more information see indilib.org 👑

---

🐛 BUGS 🐛

Found something cursed? Report bugs to:

• Hamlib Developer mailing list

(no cap, they wanna hear about it 🙈)

---

📜 COPYING 📜

This file is part of Hamlib, a project to develop a library that simplifies radio, rotator, and amplifier control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications. 💖

Copyright © 2001-2011 Stephane Fillod Copyright © 2002-2017 the Hamlib Group (various contributors) Copyright © 2003-2020 Nate Bargmann

This is free software; see the file COPYING for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 🫶

---

👀 SEE ALSO 👀

• less(1)
• more(1)
• rotctld(1)
• hamlib(7)

---

🌈 COLOPHON 🌈

Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org. 🦋

---

and that's the whole page, bestie — this one's from the Hamlib era, dated 2025-09-01, and it lives at ROTCTL(1). now go point some antennas at the sky, you absolute icon 👑📡💅