Home‎ > ‎Macro Programming‎ > ‎

Chapter 4 Writing Macros - Some Rules of the Road

Chapter 2 and Chapter 3 have shown us the details of the Programmer’s Commands and how to use them when writing macros.  Before starting a programming project there are a number of caveats, presented here as Rules of the Road, to consider.

Elecraft’s Programmable Architectures, reviewed in Chapter 1.5, allows Elecraft firmware writers to update the firmware code that defines how our radios and panadapters operate.  By adding the capability for us to store sequences of these Programmer’s Commands in macros to be executed at the tap of a switch, Elecraft has given us the capability to customize our operation to our own specifications.

It is important to understand that Chapter 1.5 doesn’t tell us the whole story.  Each transceiver and panadapter has multiple processors working together to create the whole system.  We don’t have the details of how the system operates as a whole to be able to understand how, and when, and by which processor Programmer’s Commands are executed.  Nor do we know how they may depend upon one another.  Without this understanding we may find that a macro of Programmer’s Commands may not produce the result we expect due to conflicts in processing order, interdependencies, and timing.

The sections below give us some “rules of the road” to help us avoid some of the more common situations that cause incorrect or inconsistent results when executing a macro.

The successful execution of a macro can depend on the order of the commands in the macro.  One reason for this is that many operating parameters are saved on a per-band, per-mode, per-antenna, or per-VFO/receiver basis.  See Appendix B, Per-Band, Per-Mode Configurations, page 150.   For example, Mode (SSB, CW, DATA, AM, FM), is saved on each band.  If you were to execute this macro

MD2;MD$2;FT1;FA00014170000;FB00014175000;

to enter USB and split modes on 14.170 plus five, you might find that sometimes the macro has to be executed twice before the mode changes.  The reason for this is that the mode changes are done on the band you are currently on first and then the frequency/band change is done. 

Appendix B, Per-Band, Per-Mode Configurations, page 150, shows configurations that are saved on a per-band, per-mode, per-antenna, and per-VFO/receiver basis.  Some are saved on more than one basis.  For example, the ATU can be on or off on a per-band and per-antenna basis or the main and Sub receiver’s filter width can be different, depending on the operation mode (CW, SSB, etc.).  Rule 1, then, is:

 

Rule 1:  Inspect Appendix B, Per-Band, Per-Mode Configurations, page 150 to see the per-dependencies for each configuration you wish to change.  Make sure you set the dependencies (band, mode, antenna, receiver) before making changes to the configuration or parameter.

 


Exercise

Fix the macro above so it will perform as expected.

FA00014170000;FB00014175000;MD2;MD$2;FT1


 


Exercise

Write a macro that will turn the ATU on when on 20 meters and antenna 1 and off when on antenna 2.

BN05;AN1;MN023;MP002;MN255;AN2;MN023;MP001;MN255;


 


Exercise

Write a macro that will change to 80 meters, set the main receiver’s noise blanker off and the Sub receiver’s noise blanker on.

BN01;NB0;NB$1;


Programmer’s Commands are one or more letters, preceded by a command prefix, followed by numbers defining the parameter, and terminated by a semi-colon (;).  Some (IS, KY, RO) require a space or other character between the command and the parameter. VFO A and VFO B frequency specifications (FA and FB) 11-digit numbers (ggmmmkkkhhh, where gg = GHz, mmm = MHz, kkk = kHz, and hhh = Hz). 

P3 and PX3 commands use the # character as a command prefix.  Frequency specifications are similar to the K3 and KX3 except that they require a + or space character preceding the 11-digit frequency. 

A sequence of commands terminated by a semi-colon is a macro. 

Make sure there are no space characters between the semi-colon and the next command.

Rule 2:  Check your command syntax carefully.

 


Exercise

The FA0014025000; command is supposed to set VFO A to 14.025 MHz.  Why doesn’t it?.

Not enough digits in the frequency.  It should be FA000140250000;.


 

Most of the Programmer’s Commands shown in Table 2-1 and Table 2-2 allow you to explicitly set a condition or parameter to a value.  Likewise, many of the Menu selections shown in Table 2-9 and Table 2-10 (those marked by ‡) allow you to follow a MNnnn; command with an MPnnn; command to set an explicit value also.  Macros that Enter a Menu and set a Parameter, page 52, shows how to set an explicit value in these menus.

However, many of the Menus in Table 2-9 and Table 2-10 (those marked with T) are toggling menus.[1]  You enter the menu with a MNnnn; command and follow it with an UP; or DN; command to toggle the parameter.  Because the state of the parameter at the end of the macro execution depends on its state before the macro is executed, the macro cannot be written to set the toggling menu to a specified setting; it merely toggles it to its opposite state.

 


Exercise

What does the following macro do?

MN116;DN;MN255;

It toggles the linking of VFO A and VFO B.


 

Many operating characteristics can be set by tapping or holding switches.  Some switches perform an operation and achieve a fixed result.  For example, tapping A>B (SWT13) achieves the specific result of transferring the frequency in VFO A to VFO B.  Conversely, holding SPLIT (SWH13) toggles between split on and split off.  Thus, SWH13 (SWH25 in the KX3) used in a macro toggles split mode so sometimes split will be on and sometimes off, depending on its state when you execute the macro.  Table 4-1 shows other toggling switch functions.

It may be better in these cases to use a Programmer’s Command or menu instead of a switch tap or hold because they allow you to deterministically set the state to get the outcome you wish.  Thus, in the split example, use FT1; (enter split mode) and FR0; (unsplit). 

 

Table 41.  Toggling switch parameters.

Switch

Switch Action

Command or Menu Alternative

Menu Parameter

ATU

Toggles ATU on/off.

KAT3 (ATU MD – KX3)

MN023;

MP001; (bYP)

MP002; (Auto)

LOCK

Toggle VFO LOCK on/off.

LK0; Unlock VFO A

LK1; Lock VFO A

LK$0; Unlock VFO B

LK$1; Lock VFO B

 

SPLIT

Toggle between Split and unsplit.

FT1; Use VFO B, activate split

FR0; Cancel split

 

RIT

Toggle between RIT on/off.

RT0; RIT off

RT1; RIT on

 

XIT

Toggle between XIT on/off.

XT0; XIT off

XT1; XT on

 

MODE

Tapping switches to the next mode.

MDnn; MD$nn; selects specific mode.

 

ANT

Tapping toggles between ANT 1 and ANT 2 for the Main receiver.

AN1; and AN2; select each.

 

RX ANT

When Sub is on, holding toggles between MAIN and AUX for the Sub receiver.

No equivalent.

 

 

Rule 3:  Wherever possible, avoid using switch taps or holds or toggling menus in macros where you want a defined state outcome.  Use, instead, a command that leaves the parameter in a defined state.

 

A problem with trying to understand how to write macros that achieve a consistent and reliable result is that we do not know how the multiprocessor systems implement macro processing.  One potential problem is that there may be no synchronization mechanism to account for differences in the execution time of different Programmer’s Commands.  The Programmer’s Reference Manual tells us that the K3 will typically respond in less than 10 ms with worst-case latency of around 100 ms except for band changes that may take up to 500 ms.  Some commands cannot be safely handled when the transceiver is in a busy state, such as transmit, or a limited-access state such as b SEt. 

Macros cannot use GET commands to ensure the Programmer’s Command has taken effect before proceeding to the next command the way external control programs can.  The problem is further complicated when commands are executed on different parts of the system, i.e. the K3S and the P3 or KX3 and PX3.  Information from Elecraft indicates that embedding semicolon “;” characters in the macro will generate a short delay.  It is not clear that inserting a semicolon between commands in a macro helps.  It seems that macro processing and interactions between commands is more complex than can be solved by delaying one command relative to another.  Nevertheless, a command that implements a delay might be useful to help synchronize a succession of commands or allow us to do more troubleshooting.  Until a delay command is developed, about the only solution available at this time is to try different ordering of commands and repeating commands within the macro, and repeating the macro.  Your mileage may vary.

 

Rule 4:   If erratic behavior persists, try changing the order of the commands in the macro or repeating commands.

 

4.5.1        Switch Emulation and Timing

Table 42 shows some anomalies where extra Programmer’s Commands are needed to produce a consistent and expected result. 

Table 42.  Switch emulation problems.

Problem Switch Taps/Holds

Problem

Potential Solution

SWH58; SWT13;SWT13;

Normalize VFO A filter; transfer all to VFO B.

VFO B not normalized.

SWH58; SWT13;SWT13;SWT13;

A third SWT13; is needed.

SWT11;SWH58; SWT11;

Swap A<>B; normalize VFO A filter; swap A<>B back.

VFO B not normalized.

SWT11;SWH58; SWT11;SWT11;

A second SWT11; is needed.

MC001;

Recall memory 01.

VFO B not recalled.

MC001;SWT13;MC001;

When VFO IND Yes, VFO B is not recalled.

MC001;SWT13;MC001;SWH41;

Recall memory 01 and start scan.

Recalls the memory but doesn’t start the scan.

MC001;SWT13;MC001;MC001;SWH41;

The third  MC001; is needed.

 

Rule 5:  Some switch emulation commands may require that the following command be duplicated to complete the command sequence properly.

 


Exercise

Write a macro to normalize VFO A filter and transfer all filter data and VFO A frequency to VFO B.

SWH58;SWT13;SWT13;SWT13;


The execution of the SWH58 command seems to collide with the first SWT13; adding another seems to fix it.

 

4.5.2        Switch Emulation and Command Alternatives

“The switch emulation commands (SWT/SWH) were always intended as a backup method in cases where dedicated two-letter commands hadn't yet been written. Given that SWT/SWH trigger switch events as if they were coming from the front panel, interactions with other in-line commands are inevitable.”[2] 

It is always better to use a two-letter command when one is available instead of a switch tap or hold.  Appendix D, page 165, summarize K3 and KX3 switch tap and hold commands that can be achieved with another Programmer’s Command.  Unfortunately, not all SWT and SWH commands have equivalent two-letter commands.

 

Rule 6:  Use a two-letter command instead of a switch tap or hold emulation whenever possible.

 

·         If VFOs are linked (LN1;), commands that affect the VFO A frequency also change VFO B.  These include FA, UP, DN, RU, RD, and RC.

·         In diversity mode (DVn;), BWnnnn;, MDnn; and DTn;  match VFO B filter bandwidth and Sub receiver mode to VFO A.  IS nnnn; also shifts the VFO B filter center.  Turn on diversity (DV1;), make the changes to VFO A, and then turn diversity and the Sub receiver off (SB0;).  See CW mode VFOA, VFO B all bands, page 103. 

 


Exercise

Write a macro that will set both VFO A and VFO B filters to 500 Hz bandwidth centered on the passband.

DV1;BW0050;IS 9999;SB0;


 

·         The switch commands for the reverse switch on the K3 (SWT12;) and KX3 (SWH25;) apply to swapping repeater input/output frequencies in FM mode only.

·         When making changes to VFO B filter, if possible, swap A/B (SWT11; or SWT24;) , make changes to VFO A, and then swap back.

 


Exercise

Write a macro that will set VFO B filter to 500 Hz bandwidth centered on the passband.

SWT11;BW0050;IS 9999;SWT11;


 

·         If you are using a KPod to execute macros, remember that holding F1F8 executes Macro 1 – Macro 8 and tapping F1F8 executes Macro 9 – Macro 16.  See Chapter 5, page 73.  A hold is > 0.5 second.

·         When testing macros using the K3S/P3 or KX3/PX3/KXPA100 systems, if a macro doesn't work as expected, remove intervening peripherals to simplify.  For example, connect the KX3 Utility directly to the KX3 without wiring up the KXPA100 and PX3.  If it works, then add back the PX3 and confirm the macros works.  Ditto the KXPA100.  In this way, you can eliminate RS232 traffic to confirm the macro actually works.3

·         Beware the use of "COM port concentrators".  These software solutions consolidate multiple COM ports in the Windows OS so that multiple programs can each access the radio, including any macros being run.  This is accomplished by sending commands to the radio as they arrive at different times.  This may well impact what your intended macro actually does.  For this reason, Elecraft Customer Service recommends that macros not be run with COM port concentrators that allow multiple programs to be run at the same time.[3]

 

 

Command

Operation

IS 9999;

Not implemented for VFO B unless in diversity mode.

UPB;DNB;

Not implemented for KX3 VFO B yet.

DV;

No diversity in KX3.

LN;

VFOs not linked in KX3.

ANn;

Antenna selection only for Main receiver.

BN$nn;

Not implemented for VFO B.

XTn;

XIT disabled in QRQ CW mode.

 

 

Because there may be complex interactions between Programmer’s Commands, particularly without an ability to synchronize execution times, it is best when writing a complex macro program to start small and test each component part individually before combining them in a complex macro. 

Use the K3 or KX3 Utility Command Tester to confirm expected macro behaviors. 

For example, take the CLEANUP macro from page 87.  The complete macro is:

 

Normalize transceiver.

Group

K3S/K3


1

FT0;

Transmit on VFO A.

SB0;

Sub receiver off.

2

SWH58;

Normalize VFO A bandwidth and center.

SWT13;SWT13;SWT13;

Transfer VFO A to VFO B.

3

RT0;XT0;

Set RIT and XIT off.

LK0;LK$0;

Unlock VFO A and VFO B.

DB00;

Set normal VFO B display.

4

FT0;SB0;SWH58;SWT13;SWT13;SWT13;RT0;XT0;LK0;LK$0;DB00;

 

We can identify three “logical” groupings of commands – 1, 2, and 3.  Our testing and development strategy will be to use the Utility program to test each of the commands separately and then to gradually add each group, testing as we go.  For each test, we must try a set of different initial conditions to check that the group works properly.  For example, to test group 1, a logical set of initial conditions would be to set the transceiver in split mode with the Sub receiver on.  You should also test it with split mode off and the Sub receiver on and off.  Try as many combinations as you can think of.

To test group 2 we start with the command sequence

SWH58;SWT13;SWT13;

whose goal is to normalize and center the VFO A filter and then transfer the filter settings and frequency to VFO B.  Testing will show that VFO B filter is not normalized. It seems that we have to add an additional SWT13; to reliably normalize VFO B filter. 

Test group 3 and then start combining the groups, repeating the testing conditions used for each group.

In the end, you should reach group 4 with a fully working macro.

 

Rule 7:  Start small; test each component separately; apply Rules to fix unexpected behaviors, and continue testing as components are added.

 

 

Finally, the programming needed to process macros is complex.  There are many real-time-system constraints such as what the transceiver is doing at the moment, processing time for an individual command, and synchronization of multiple processors to be considered.  A simple macro such as

SWH33;SWT25;SWT25;    Normalize KX3 VFO A and VFO B

may work fine until embedded in a more complex macro.  You may have to resort to breaking complex macros into smaller elements to be executed separately.

 

Rule 8:  Some commands, while they may work fine in isolation, simply do not seem to produce consistent results reliably when in a longer macro sequence of commands.  Consider breaking complex macros into separate elements.

 

 



[1]   Toggling means that the value of a parameter or control flips back and forth between two states each time the command is executed.  A programmable function key can be assigned to a menu that toggles, as shown in Using a Function Key as a Shortcut to a Menu Item, page 15.

[2]   Information from Wayne, N6KR, in email 1/3/2017.

[3] Thanks David Shoaf, Elecraft Customer Service for these two hints.

Comments