Elecraft KX3 Programmers Reference

ELECRAFT K3 AND KX3

PROGRAMMER'S REFERENCE

Rev. E11, Oct. 24, 2013

(For change history, see Appendix A)

Command Set Overview

All K3/KX3 remote control commands are listed in Table 1. The KX3 accepts all K3 commands, though some have no functional effect on the KX3 (*). Some commands are recognized only by the KX3 (**). For K2 commands, see the KIO2 Programmer’s Reference.

Table 1 K3/KX3 Control Commands. (*) = Not functionally applicable to KX3. (**) = KX3 only.

($) = Add ‘$’ for VFO B/sub RX (VFO B/dual watch for KX3).

Name

Description

Name

Description

Name

Description

! , @ *

Direct DSP control

Transmit VFO select

PO **

Power output read

AG $

AF gain

FW $

Filter bandwidth and #

Power-on/off control

Auto-info mode

AGC speed and on/off

RA $

RX attenuator on/off

AK **

Internal use only

Icon and misc. status

RIT/XIT offset clear

Antenna selection

Radio identification

RIT down

CW APF on/off

General information

RG $

RF gain

BC **

Internal use only

IO **

Internal use only

RIT/XIT offset (abs)

Bargraph read

IF shift

RIT on/off

BN $

Band number

K2 command mode

RIT up

Baud rate set

K3 command mode

Firmware revisions

BW $

Filter bandwidth

Keyer speed

Enter RX mode

Speech compression

KT **

Internal use only

Sub or dual watch

CW sidetone pitch

Keyboard CW/DATA

QSK delay

VFO B text

Internal use only

SM $

S-meter

DSP command trace

LK $

VFO lock (A or B)

SMH *

High-res S-meter

Internal use only

LN *

Link VFOs

SP *

Internal use only

DN/DNB

VFO move down

Memory channel

SQ $

Squelch level

VFO A text/icons

MD $

Operating mode

SWT/H

Switch tap/hold

Data sub-mode

Mic gain

Buffered text

DV *

Diversity mode

Monitor level

Transmit EQ

EL **

Error logging on/off

Menu entry number

Transmit query

Internal use only

Menu param read/set

Text-to-terminal

ESSB mode

MQ **

Menu param read/set

Exter TX mode

Internal use only

NB $

Noise blanker on/off

UP/UPB

VFO move up

VFO A frequency

NL $

Noise blanker level

VOX state

VFO B frequency

Option modules

XF $

XFIL number

FI *

I.F. center frequency

PA $

RX preamp on/off

XIT on/off

FN *

Internal use only

Power Control

Receive VFO select

PN *

Internal use only

Some commands emulate controls and display elements. For example, the SWT/SWH commands emulate switch TAP/HOLD, MN accesses menus, DS, DB, and IC read VFO A / B and icons, and BA and BG read bargraphs. Other commands directly read or modify radio parameters, such as the VFO A and B frequencies (FA and FB).

There is some overlap between emulation and parametric commands. For example, you can select the next operating mode using an SWT command to virtually "tap" the MODE switch, or set a specific mode using MD.

Using K3 Utility (or KX3 Utility) to Test Commands

The Command Tester screen of the K3 Utility and KX3 Utility PC application can be used to try individual control commands. You can even save useful commands (or strings of commands) as named macros for later use. A subset of these macros can be stored in the radio’s EEPROM memory, where they can be assigned to programmable function switches. See the Command Examples section (page 5).

Command Format

Note: In the remainder of this document, K3 references apply to the KX3 as well unless otherwise noted.

Commands sent from the computer to the K3 are considered either GETs or SETs. GET commands are used by the computer to get information from the K3; the K3 will then provide an appropriate response message (RSP). SET commands are sent by the computer to change the radio's configuration or initiate an event. A SET can be followed by a GET to verify the new settings, or the auto-info mechanism can be used for confirmation that something has changed (see AI in the Meta-commands section).

SET commands use 2 or 3 characters, optional data fields, and a terminating semicolon (;). Examples:

KS020; Computer sets CW speed to 20 WPM (data = 020) MD1; Computer selects LSB mode (data = 1)

Many SET commands have a corresponding GET command, which is just the command letters with no data. The data format of the response message from the K3 (RSP) is usually identical to the format of the SET data. Exceptions are noted in the command descriptions.

Characters sent to the K3 can use either upper or lower case. The K3 will always respond with upper case, except when a lower-case character is a place-holder for a special symbol (e.g., the VFO B display command, DB).

Sub Receiver/VFO B Commands ($), Linked VFOs, and Diversity Mode

Some commands target VFO B (and the sub RX, in the case of the K3) if ($) is added after the command prefix. Examples include AG$, RG$, MD$, BW$, FW$, LK$. This is indicated in the reference section by a $ in the command title. (Some commands target VFO B itself and do not need the ‘$’, including FB, UPB, DNB, and DB.)

If the VFOs are linked (see LN), commands that affect the VFO A frequency also change VFO B. This includes FA, UP, DN, RU, RD, and RC. In Diversity mode, BW, FW and MD match the VFO B/sub receiver filter and mode settings, respectively, to the main receiver.

Extended Commands

Some commands have an extended data format which provides enhanced functionality or backward compatibility with older software applications. Such commands should be avoided in switch macros because of the need to use a meta-command to enable extended functionality (see Meta-commands section). Alternatives are available. For example, the BW (bandwidth) command should be used in macros rather of the legacy FW command, which depends on meta-command settings.

Response Time

The K3 will typically respond in less than 10 milliseconds. General worst-case latency is around 100 ms, except for commands that change bands, which can take up to 500 ms.

Since the K3 provides a full-duplex interface, the computer can send the K3 commands at any time. Continuous, fast polling (< 100 ms per poll for bar graph data in transmit mode, for example) should be carefully tested to ensure that it isn’t affecting radio operation. Polling during transmit not be used unless necessary.

Busy/Limited Access Indication (?;)

Some commands cannot be safely handled when the K3 is in a busy state, such as transmit, or in a limited-access state, such as BSET or VFO A/B reverse (REV switch). If a command cannot respond due to such a condition, the K3 will return “?;”. Future firmware releases will gradually become less restrictive in this regard.

You can use the TQ command to see if the K3 is in transmit mode, and the icon/status command (IC) to check for BSET mode (byte a, bit 6).

Meta-commands: AI, K2 and K3

Meta-commands change the behavior of other commands to provide automatic responses or compatibility with older application software. In general they should not be embedded in K3 or KX3 front-panel switch macros, as they may adversely affect software applications that control meta-command modes. The Command Reference section explains when to use them with specific commands.

AI (Auto-info mode): The AI meta-command can be used to enable automatic responses from the K3 to a computer in response to K3 front panel control changes by the operator. Application software may use AI1 or AI2 mode as an alternative to continuous polling. (Not appropriate for switch macros.)

AI0, No Auto-info: This is the default. The PC must poll for all radio information using GET commands; the K3 will not send any information automatically.

AI1, Auto-Info Mode 1: The K3 sends an IF (info) response within 1 second when any frequency or mode- related event occurs, either manually (at the radio itself) or when the PC sends commands. These events include: band change, mode change, VFO movement, RIT/XIT offset change or clear, and several additional switches (e.g., A/B, REV, A=B, SPLIT, CW REV, RIT, XIT). IF responses are suppressed during VFO movement. Notes: (1) putting the K3 into auto-info mode 1 (by sending AI1;) causes an initial IF response. (2) The K3 can be placed into AI1 mode without a PC by setting CONFIG:AUTOINF to AUTO 1. The user may do this to support non-PC devices that make use of auto-info, such as a SteppIR antenna controller. Application software can check for unexpected IF responses and turn AI off if required.

AI2, Auto-Info Mode 2: The K3 sends an appropriate response (FA, FB, IF, GT, MD, RA, PC, etc.) whenever any front-panel event occurs. This applies to all of the events mentioned for mode AI1, and ultimately to all rotary control changes and switch presses. At present only a subset of controls generate responses.

AI3, Combination: This is similar to mode AI2 and is provided only for compatibility with existing programs.

K2 (K2 command mode): The K2 meta-command modifies the set/response format of some commands. Avoid

using this command in switch macros.

K20, K2 Normal mode: This is the default; K2 command extensions are disabled.

K21, K2 Normal/rtty_off: Same as K20, except that MD and IF report RTTY and RTTY-reverse modes as LSB

and USB, respectively. This may be useful with programs that don’t support a separate RTTY mode.

K22, K2 Extended mode: Enables all K2 command extensions.

K23, K2 Extended mode/rtty_off: Enables all K2 extensions, but like K21, alters the MD and IF commands.

K3 (K3 command mode): The K3 meta-command modifies the set/response format of some commands. Avoid using this command in switch macros.

K30, K3 Normal mode: This is the default; K3 command extensions are disabled.

K31, K3 Extended Mode: Enables all K3 command extensions (see, for example, FW). Typically, K3

applications will place the K3 in K31 mode except when K30 mode is needed due to the use of certain commands.

Command Examples

Macros

Macros – strings containing one or more control commands – can be used to automate K3/KX3 front panel switch sequences. Table 2 lists some examples. See Creating and Using Macros (page 6) for complete instructions.

Table 2 Sample Macros. These can be altered or combined as needed (see the Command Reference section).

Label

Description

Command string

SPLIT+2

CW DX split starting point: A>B twice, enter SPLIT, move VFO B up 2 kHz, RIT/XIT off

SWT13;SWT13;FT1;UPB5;RT0;XT0;1 EQ MIC1

Boost 100-Hz TX EQ band by 8 dB; others “flat”

TE+00+08+00+00+00+00+00+00;

WEAKSIG

Diversity mode, main/sub preamps on, 200-Hz bandwidth, no IF shift

DV1;PA1;PA$1;BW0020;IS 9999; CLEANUP

Turn off split/RIT/XIT; unlink VFOs; open squelch

FT0;RT0;XT0;LN0;SQ000;

WWV 10

30 m, AM mode, VFO A to 10.0 MHz, 3 kHz AF bandwidth (requires 6 kHz IF crystal filter)

FA00010000000;MD5;FA00010000000; BW0300;2

OLDIES

Switch to AM radio station at 1550 kHz; 4 kHz BW, attn. on, preamp off

FA00001550000;MD5;FA00001550000; BW0400;IS 9999;RA01;PA0;

LCD BRT

Set the MAIN:LCD BRT menu parameter to 6

MN003;MP005;MN255;3

MEM32

Load frequency memory #32 into VFOs A and B

MC032;

LOCKA&B

Lock both VFOs

LK1;LK$1;

PWRTEST

Send “BT” at 100 W, 10 W, and 1 W, then restore power to 100 W (“=” embeds a BT prosign)

PC100;KYW =;PC010;KYW =; PC001;KYW =;PC100;

TUN 10W

Set power to 10 W and enter TUNE mode

PC010;SWH16;

AMP ON

Turn on an external amplifier and set K3 drive to 65 W (see CONFIG:DIGOUT1, Owner’s Manual)

MN019;MP001;MN255;PC065; 599FAST

Send “5NN” at 40 WPM, “TEST ” at 30 WPM

KS040;KYW5NN ;KS025;KYWTEST ;

MUTE AF

Set main and sub AF GAIN to zero

AG000;AG$000;

MON OFF

Set monitor volume to zero (present mode)

ML000;

SCANNOW (K3 only)

Stores VFO A & B in per-band quick-memory M4 and starts scan (> 2 second hold starts “live” scan); VFO B frequency must be > VFO A

SWT15;SWT39;SWT23;SWT39;SWH41;4 STEPPIR

Send frequency info to a device attached to the serial port, such as an antenna controller or ATU

IF;5

SWT13 is a switch-emulation command that has the same effect as tapping A>B. The KX3 has different SWT codes. FT1 enters split mode. The number 5 in UPB5 is not a value in kHz, but an index into the table of step sizes (in this case 2 kHz); see the DN command in the command reference for full details. RT0 and XT0 turn off RIT and XIT.

The first FA command in this macro may cause a band change. MD (mode) is sent after it, so the mode change will apply to the new band. The second FA command is only required if auto-offset-on-mode-change is in effect. (In CONFIG: CW WGHT, tapping 5 alternates between VFO NOR and VFO OFS. In the latter case, the VFO frequency is adjusted when switching between CW and any other mode.)

MN accesses menu entries. MP can then be used (in some cases) to read or set the parameter value. In the LCD BRT macro, MP005 sets LCD BRT to 6 . You can determine a menu entry’s parameter range by manually setting the parameter to the lowest/highest values, typing “MP;” each time in the command test box at the top of the Command Tester screen.

This example uses per-band memory M4 (SWT39), but any of M1-M4 could be used, or quick memories 0-9 (see SWT/SWH command). If scanning is started with a macro, the last switch emulation command in the macro must be SWH41 (SCAN).

IF is a GET command (general transceiver info, including VFO A’s frequency and mode). When the K3 encounters a GET command in a macro, it sends the response to any device attached to the serial port, just as if a computer had requested it. Multiple GET commands could be placed in a macro if necessary; examples include FA and FB (VFO A and B frequencies).

Creating and Using Macros

K3 Utility and KX3 Utility can be used to create and test macros. The first eight of these can be sent to the transceiver, where they can be assigned to any of the programmable function switches. Macros can have a length of up to 120 characters, along with a label of up to 7 characters.

Example (“SPLIT+2”): A>B, A>B, SPLIT, VFO B up 2 kHz, RIT/XIT off, assigned to PF1

To create this macro and assign it to a K3 front panel switch, you’ll need to complete all of steps 1-8 below. The instructions are similar for the KX3, except that KX3 Utility is used, and some SWT/SWH codes are different.

1. Run K3 Utility.

2. Click on the Command Tester/K3 Macros tab.

3. Click on the Edit Macros button at the top of the screen. This brings up the macro edit window.

4. In MACRO 1’s Macro Label field, enter the label “SPLIT+2”.

5. In the Macro Commands field, enter:

SWT13;SWT13;FT1;UPB5;RT0;XT0; (the KX3 has differenent SWT/SWHxx codes)

Note: The number 5 in the “UPB5” command is not a value in kHz; it is an index into a table of step sizes. UPB5 moves VFO B up 2 kHz, DNB5 moves it down 2 kHz, etc. (there are similar commands for VFO A). For the full list of UP/DN command variations, see the DN (down) command (page 8).

6. Click on Send Macros 1-8 to K3. Exit the edit window by clicking Save. The macro can now be tested from within the Command Tester by clicking on its associated button. (The label won’t flash on VFO B when this is done from K3 Utility – only when using the assigned switch at the K3.)

7. At the K3, locate CONFIG:MACRO x menu entry. Tap ‘1’ if the menu entry label is not already “MACRO 1”.

8. Hold PF1 to assign PF1 to MACRO 1. Exit the menu.

From then on, using PF1 will flash SPLIT+2 and execute the above sequence.

Important Restrictions: (1) Macros normally only use SET commands, since they can’t make use of the response from a GET. For a very useful exception to this rule, see the last sample in Table 2. (2) Macros should not use meta-commands (like K31;) as this can interfere with software applications that control meta-modes. (3) Macros can be used to send direct DSP commands (see ! and @, page 7), but at present this only works from K3 Utility, not from K3 front-panel switches.

Simple Application Program

The pseudo-code program below displays the VFO A frequency (8 digits) while watching for the user to request a frequency change via the PC keyboard. For details on individual commands, see the Command Reference section.

VfoControlLoop { SendCommand( “FA;” ) // GET frequency of VFO A StringF = GetResponse( TIMEOUT_100MS ) // wait for response; include a timeout, just in case Display( StringSubset( StringF, 5, 12 ) ) // show MHz through Hz digits on PC screen If( KeyboardInput = “+” ) // up/down control could be a mouse click instead SendCommand( “UP;” ) // this is a SET command that moves VFO A up If( KeyboardInput = “-” ) SendCommand( “DN;” ) }

Command Reference

Note: Commands marked with a dollar sign ($) apply to VFO B (and the sub receiver, in the case of the K3).

Commands marked with an asterisk (*) are not functionally applicable to the Elecraft KX3, but the KX3 will accept and reply to all K3 commands. For K2 commands, see the KIO2 Programmer’s Reference.

This section describes all K3 GET, SET and RSP (response) command formats. Unless otherwise noted, the GET format is just the 2 or 3 letters of the command followed by a semicolon. The SET and RSP data formats are identical unless noted otherwise. When K2 or K3 extended modes are in effect (typically K22 or K31), some commands have an extended format (see Meta-commands). Both Basic and Extended formats are described here.

! and @* (Direct Main/Auxiliary DSP control)

Elecraft releases documentation on specific DSP commands as user needs for them arise. DSP commands can cause side effects and should be used with caution. NOTE: At present, DSP commands can not be used in

combination with regular commands in K3 Utility macros. Also, they will not work as K3 switch macros.

AG $ (AF Gain; GET/SET)

SET/RSP format: AGnnn; or AG$nnn; where nnn is 000-255.

AI (Auto-Information; GET/SET)

SET/RSP format: AIn; where n is 0-3. See Meta-commands for details. Note: The AI power-up default is normally AI0, corresponding to K3 menu setting CONFIG:AUTOINF = NOR. AUTOINF can also be set to AUTO 1, which makes the default AI1 on power-up. This is useful for K3s controlling a StepIR antenna, etc.

AK (KX3, Internal Use Only)

SET/RSP format: TBD.

AN (Antenna Selection; GET/SET)

SET/RSP format: ANn; where n is 1 for antenna 1, and 2 for antenna 2.

AP (Audio Peaking Filter; GET/SET)

SET/RSP format: APn; where n is 0 for APF OFF and 1 for APF ON. Applies to CW mode only, and only if CONFIG:DUAL PB is set to APF.

BG (Bargraph Read; GET only)

RSP format: BGnnx; where nn describes which bars are turned on and x (K3 only) indicates receive (R) or transmit (T). Returns S-meter level in receive (also see SM/SM$ command), and power or ALC level in transmit. CWT, SWR, and CMP readings not yet available. K3, Receive: nn is 00 - 21 (CWT off) or 00 - 09 (CWT on). K3, Transmit: nn is 00 - 12 (PWR) or 00 - 07 (ALC) depending on METER setting. K2, Receive or Transmit: nn is 00 - 10 (DOT mode) or 12 - 22 (BAR mode).

BN $ (Band Number; GET/SET)

SET/RSP format: BNnn; where nn is 00-24, the present “logical” band for VFO A (use BN$nn for VFO B). Also see MC command (memory channel set). Note: BN SET command applies only to VFO A at present.

BN GET works with either VFO A or B. If a band change occurs, allow 300 ms before sending other commands.

nn is defined as follows: 0=160 m, 1=80 m, 2=60 m, 3=40 m, 4=30 m, 5=20 m, 6=17 m, 7=15 m, 8=12 m, 9=10

m, 10=6 m, 11-15 reserved for future expansion, 16=Xvtr band #1, 17=Xvtr band #2… 24=Xvtr band #9.

BR (Serial I/O Baud Rate; SET only)

SET format: BRn; where n is 0 (4800 b), 1 (9600 b), 2 (19200 b), or 3 (38400 b). Note: The K3 firmware download utility automatically sets the K3 to 38400 baud for downloads, then restores the baud rate to the user’s selection (made using the K3’s CONFIG:RS232 menu entry).

BW $ (Filter Bandwidth; GET/SET)

SET/RSP format: BWxxxx; where xxxx is 0-9999, the bandwidth in 10-Hz units. May be quantized and/or range limited based on the present operating mode.

Notes: (1) BW is a dervative of the legacy FW command. BW is safer to use in switch macros, because it makes no assumptions about meta-command settings (K2x and K3x). FW may be preferred in applications. (2) In diversity mode, BW matches the sub receiver’s filter bandwidth to the main receiver’s. (3) Both BW and BW$ can be used in BSET mode (one exception: at present, BW/BW$ SET can’t be used in BSET mode with diversity receive in effect).

CP (Speech Compression; GET/SET)

SET/RSP format: CPxxx; where xxx is 000-040 (speech compression level).

CW (CW Sidetone Pitch; GET only)

RSP format: CWxx; where xx is 30-80 (sidetone pitch in 10 Hz units).

DB (VFO B Display Read/Write; GET/SET; K3 and KX3 variants)

GET format: DB; (no data). Returns text displayed on VFO B, including decimal points and colons if present. VFO B normally displays only uppercase alphabetic characters. DB returns the following lower-case characters that represent symbols: a (antenna), b (mu), c (slashed 0), d (itself), e (sigma), f (<-), g (->), h (II), i (left-justified “1”), j (delta, large), k (delta, small), l (right-justified “1”).

There are two SET formats with different functions:

DBn; where n is an ASCII character to send to VFO B, entering at the right end of the display and scrolling left as additional characters are entered. This can be used to create scrolling messages to alert the operator to something regarding the computer, send extended help text, insert a newsfeed, report a DX spot, test special characters, etc.

DBnn; where nn is one of the available VFO B alternate display modes:

K3: 00=normal, 01=time, 02=date, 03=RIT/XIT offset, 04=supply voltage, 05=supply current, 06=PA

heatsink temp, 07=front panel temp, 08=PLL1 voltage, 09=PLL2 voltage, 10=AFV, 11=dBV. (Note: Modes 08 and higher require CONFIG:TECH MD = ON.)

KX3: 00=normal, 01 = time, 02 =supply voltage, 03=supply current, 04=PA temp, 05=OSC temp, 05=AFV, 06=dBV

DL (DSP Command Debug On/Off; SET only)

SET format: DLx; where x = 2 to turn DSP command debugging OFF, 3 to turn it ON. When it’s ON, all commands sent from the MCU to the DSP are echoed to the K3’s serial port, with a few exceptions such as during program loading. The DVR icon will flash as a reminder.

DN/DNB (Move VFO A or B, or Menu Entry/Parameter Down; SET only)

SET format: DN; or DNB; or DNn; or DNBn; where n is an optional VFO change specification. DN; and DNn; move VFO A (or the menu parameter) down. DNB; and DNBn; move VFO B (or the menu entry) down. VFO displacement, n: 0=1 Hz; 1 or not used=10 Hz; 2=20 Hz; 3=50 Hz; 4=1 kHz; 5=2 kHz; 6=3 kHz; 7=5 kHz; 8=100 Hz; 9=200 Hz. Note: If the VFOs are linked (non-SPLIT), DN; and DNn; set VFO B to the same frequency as VFO A.

+ 18 hidden pages

Elecraft KX3 Programmers Reference

Specifications and Main Features

Frequently Asked Questions

User Manual