AMPCTL(1)

🎀 AMPCTL(1) · Hamlib Utilities 🎀

✨ NAME ✨

ampctl: control radio amplifiers 📻💖

🧚 SYNOPSIS 🧚

ampctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
       [-v[-Z]] [command|-]

🌸 DESCRIPTION 🌸

Okay so, ampctl is the tool for controlling radio amplifiers ✨ It takes commands straight from the command line, but if you don't give it any there, it drops you into interactive mode instead 💅

Keep in mind that Hamlib is BETA level software 🙈 Lowkey, a lot of the backend libraries don't have complete amplifier support yet, but the basic functions are usually well supported 🫶

Report bugs and share feedback at the e-mail address in the BUGS section below 💌 Patches and code enhancements sent to that same address are super welcome 🦋

👑 OPTIONS 👑

This program follows the usual GNU command line syntax 🎀 Short options that take an argument can have the value stuck right after them, or separated by a space. Long options that start with two dashes (-) need an = between the option and any argument 💅

Here's the summary of the supported options 🌈

• -m, --model=id — pick the amplifier model number 🧚
  • See the model list (use ampctl -l).
  • Note: ampctl (or third party software using the C API) will use amplifier model 2 for NET ampctl (communicating with ampctld).
• -r, --amp-file=device — tell it the file name of the port that's plugged into the amplifier 🔌
  • This is often a serial port, but it could also be a USB to serial adapter 💜 Typical names are /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux, and COM1, COM2, etc. on MS Windows. The BSD flavors and Mac OS/X have their own designations, so check your system's documentation 🍓
• -s, --serial-speed=baud — set the serial speed to the baud rate ⚡
  • By default, it uses the maximum serial speed from the amplifier backend's capabilities (set by -m above) 🌟
• -t, --send-cmd-term=char — change the termination char for the text protocol when you're using the send_cmd command 💬
  • The default is ASCII CR (0x0D). Non-printing ASCII characters can be given as their ASCII number in hexadecimal format, with 0x in front. You can pass an empty string for no termination char. The string -1 tells ampctl to switch to binary protocol.
  • For example, to set a command terminator for Kenwood style text commands, pass -t ';' to ampctl. See EXAMPLE below.
• -L, --show-conf — list all the config parameters for the amplifier you set with -m above 📋
• -C, --set-conf=parm=val[,parm=val] — set amplifier configuration parameter(s), like stop_bits=2 ⚙️
  • Use the -L option above to see the list of configuration parameters for a given model number.
• -u, --dump-caps — dump the capabilities for the amplifier you set with -m above, then exit 🫧
• -l, --list — list every amplifier model number defined in Hamlib, then exit 📜
  • The list is sorted by model number.
  • Note: On Linux, you can scroll back through the list with Shift-PageUp/Shift-PageDown, or use the scrollbars of a virtual terminal in X or the cmd window in Windows. You can also pipe the output to more(1) or less(1), e.g. ampctl -l | more.
• -i, --read-history — read previously saved command and argument history from a file (default $HOME/.ampctl_history) for the current session 📖
  • This is only available when ampctl is built with Readline support (see READLINE below).
  • Note: To read a history file stored in another directory, set the AMPCTL_HIST_DIR environment variable, e.g. AMPCTL_HIST_DIR=~/tmp ampctl -i. When AMPCTL_HIST_DIR is not set, the value of HOME is used.
• -I, --save-history — write the current session's command and argument history (plus previous session(s), if the -i option is given) to a file (default $HOME/.ampctl_history) at the end of the current session 💾
  • Complete commands with arguments are saved as a single line, so you can recall them and use or edit them later. This is only available when ampctl is built with Readline support (see READLINE below).
  • Note: To write a history file in another directory, set the AMPCTL_HIST_DIR environment variable, e.g. AMPCTL_HIST_DIR=~/tmp ampctl -IRq. When AMPCTL_HIST_DIR is not set, the value of HOME is used.

✨ COMMANDS ✨

Okay so commands can be typed as a single char or a full long name, and they don't get a dash like options do 🫶. You can type them in interactive mode or pass them as argument(s) in command line interface mode. In interactive mode you can even slam a command and its args onto one line:

F 14250000

Most Hamlib operations come as a set/get pair, so an UPPERCASE letter is usually the set and the matching lowercase letter is the get 🔥. Every operation also has a long name. In interactive mode, just prepend a backslash, \, to use it 💅

Example: type \dump_caps to see what capabilities this amplifier and its backend support 👑

Note: The backend for the amplifier you're controlling, or the amplifier itself, may not support some commands 💀 If that happens, the operation fails with a Hamlib error message.

Here's a simple one using a commands file. (In the real manpage, the typed text is bold, so picture it bolded 😭)

$ cat <<.EOF. >cmds.txt
> # File of commands
> F 14250000
> f
> l PWRINPUT
> l PWRFORWARD
> l SWR
> \dump_caps
> .EOF.

$ ampctl -m1 - <cmds.txt

Amplifier command: # File of commands

Amplifier command: F 14250000

Amplifier command: f
Frequency(Hz): 14250000

Amplifier command: l PWRINPUT
Level Value: 0

Amplifier command: l PWRFORWARD
Level Value: 1499

Amplifier command: l SWR
Level Value: 1.000000

Amplifier command: \dump_caps
Caps dump for model:    1
Model name:             Dummy
Mfg name:               Hamlib
Backend version:        0.1
Backend copyright:      LGPL
Backend status:         Alpha
Amp type:               Other
Port type:              None
Write delay:            0mS, timeout 0mS, 0 retries
Post Write delay:       0mS
Has priv data:          N
Get level: SWR NH PF PWRINPUT PWRFORWARD PWRREFLECTED PWRPEAK FAULT
Has Init:               Y
Has Cleanup:            Y
Has Open:               Y
Has Close:              Y
Can set Conf:           N
Can get Conf:           N
Can Reset:              Y
Can get Info:           Y

Overall backend warnings: 0

Amplifier command:

$

---

💖 ampctl Commands 💖

Here's the summary of commands. For set commands, the quoted italic bit gets swapped out for the value in the description. For get commands, the quoted italic bit is the key name of the value that comes back 🌸

✨ Q|q, exit ampctl

Leaves ampctl when you're in interactive mode 🦋

When ampctl is controlling the amplifier directly, this closes the amplifier backend and port. When ampctl is connected to ampctld (amplifier model 2), only the TCP/IP connection to ampctld gets closed. ampctld keeps running and stays available for another TCP/IP network connection 🫶

✨ F, set_freq 'Frequency'

Sets 'Frequency', in Hz.

Frequency can be a floating point or integer value.

✨ f, get_freq

Gets 'Frequency', in Hz.

Returns an integer value.

✨ l, get_level 'Level'

Gets 'Level Value' 🔍

Returns the Level Value as a float or integer, depending on the Level token you gave it.

Note: Pass a ? (query) as the first argument instead of a Level token and you'll get back a space separated list of the get level tokens the amplifier backend supports. Use this to figure out which levels a given backend supports 🧚

✨ w, send_cmd 'Cmd'

Sends a raw command string to the amplifier 🔧

This is super useful for testing and troubleshooting amplifier commands and responses when you're developing a backend.

For binary protocols, enter values as \0xAA\0xBB. You should get a 'Reply' from the amplifier, which will likely be a binary block or an ASCII string, depending on the amplifier's protocol (check your amplifier's computer control documentation).

The command terminator, set by the send-cmd-term option above, ends each command string sent to the amplifier. That character should not be part of the input string ⚠️

✨ dump_state

Returns certain state information about the amplifier backend 🌈

✨ 1, dump_caps

Not a real amplifier remote command. It just dumps capabilities, aka what the backend knows about this model and what it can do 💅

TODO: Make sure this is in a consistent format so it can be read into a hash, dictionary, etc. Bug reports requested 🙈

Note: This command spits out many lines of output, so be very careful if you're using a fixed length array! For example, running this command against the Dummy backend gives you a bunch of lines of text output 😭

✨ _, get_info

Returns information from the amplifier backend ⭐

✨ R, reset 'Reset'

Performs amplifier 'Reset' 🔥

Reset is an integer value:

• 0 = None
• 1 = Memory reset
• 2 = Fault reset
• 3 = Amplifier reset

✨ set_powerstat 'Power Status'

Sets 'Power Status' 🔌

Power Status is an integer value:

• 0 = Power Off
• 1 = Power On
• 2 = Power Standby (enter standby)
• 4 = Power Operate (leave standby)

✨ get_powerstat

Gets 'Power Status', same as set_powerstat above 💜

✨ Y, set_ant 'Antenna' 'Option'

Sets 'Antenna' and 'Option' 🎀

Number is the 1-based antenna# (1, 2, 3, ...).

    1 = A/1
    2 = B/2
    3 = C/3

---

📚 READLINE 📚

If the Readline library development files are found at configure time, ampctl gets built with Readline support for command and argument entry, and it's giving full main character energy 👑 Readline command key bindings stay at their defaults, as described in the Readline manual. ampctl sets the name ampctl, which you can use in Conditional Init Constructs in the Readline Init File ($HOME/.inputrc by default) for custom keybindings that are unique to ampctl 🦋

Command history is available with Readline support, as described in the Readline History manual. Command and argument strings are stored as single lines, even when arguments get prompted for one at a time. Commands and arguments aren't validated and are stored exactly as typed, with values separated by a single space 🫶

Normally session history isn't saved. But if you use either -i/--read-history or -I/--save-history when starting ampctl, any previously saved history gets read in and/or the current and previous session history gets written out when ampctl closes. (If you give -i and -I together, you get both.) Each option is mutually exclusive, so you can use either one alone or both together. This is handy for saving a set of commands to read later without writing your modified history back out, which is great for keeping a consistent set of test commands in interactive mode 🧚

History is stored in $HOME/.ampctl_history by default, but you can change the destination directory by setting the AMPCTL_HIST_DIR environment variable. When AMPCTL_HIST_DIR is unset, the value of the HOME environment variable is used instead. Only the destination directory can be changed right now 💅

If Readline support isn't found at configure time, ampctl uses the original internal command handler. Readline is not used for ampctl commands entered on the command line, whether or not Readline support is built in 🌸

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

---

🔍 DIAGNOSTICS 🔍

The -v, --verbose option lets you pick different levels of diagnostics to output to stderr. They line up like this: -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE 🔍

A given verbose level is super useful for giving the developers the debugging info they need. For example, TRACE output shows all of the values sent to and received from the amplifier. That's very useful for amplifier backend library development, and the developers may ask you for it 🫶

---

🚦 EXIT STATUS 🚦

ampctl exits with:

• 0 — if all operations completed normally 🎉
• 1 — if there was an invalid command line option or argument 💀
• 2 — if an error was returned by Hamlib 😭

---

🧚 EXAMPLES 🧚

Start ampctl for an Elecraft KPA-1500 using a USB to serial adapter on Linux, in interactive mode:

$ ampctl -m 201 -r /dev/ttyUSB1

Start ampctl for an Elecraft KPA-1500 using COM1 on MS Windows while generating TRACE output to stderr:

> ampctl -m 201 -r COM1 -vvvvv

Connect to a running ampctld with amplifier model 2 (“NET ampctl”) on the local host, specify the TCP port, and set frequency and mode:

$ ampctl -m 2 -r localhost:4531 F 7253500

---

🐛 BUGS 🐛

This almost empty section... 🙈

Report bugs to:

Hamlib Developer mailing list 💌

---

📜 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 © 2000-2011 Stephane Fillod Copyright © 2000-2018 the Hamlib Group (various contributors) Copyright © 2010-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), ampctld(1), hamlib(7) 💖

---

🌐 COLOPHON 🌐

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

---

Bestie, that's the whole page 🫶✨ It's from the Hamlib project, version dated 2020-09-08, and it's literally the cutest manpage 🎀💅