[WT-support] ESM and introduction to scripting

[Laurent HAAS - F6FVY]

Hi !

We read with much attention all comments regarding the ESM 
implementation in Win-Test v4, and we must confess we were ready to read 
them. Actually, they even came much later than we thought ;-)

Because ESM is such a personal feeling to everyone of us, we decided to 
make an additional effort to leave to the user the full freedom to 
customize it. In other words, you will be able to modify _YOURSELF_ the 
way the ESM mode is handled by Win-Test and tailor it to fit EXACTLY 
your needs.

Having said that, we are not going to touch the default behavior of ESM 
as it is built in WT. As it stands, it is a simple implementation that 
serves as both as a reference and as a starting point for someone who 
wants more advanced behavior.

The customization is achieved using a scripting language. The scripting 
language gives, in our opinion, the unique possibility to achieve 
dynamic tasks in WT. And it also offers the possibility to share your 
work with other WT users who don't have time or skill to build it.

The ESM is the first area in Win-Test where the scripting language Lua 
is used. The ESM function itself is a Lua script, embedded in Win-Test 
(not modifiable). But, it has been designed to be totally overriden by a 
user-written script if wanted. It means you can write and use you own 
script to replace some ESM actions, or even to totally override the 
embedded script.

How to do this ? The minimum requirement is to know some basics of 
programming. No pain, no gain... The Lua syntax is *very* easy, almost 
simplistic for easy tasks. You can read this reference manual 
(http://www.lua.org/manual/5.1/ see Chapter 2) to be convinced. If 
you're comfortable with ANY programming language, you will learn Lua in 
minutes, at least for basic scripting involved in Win-Test. We also 
provide several WT API/functions to allow actions. Check the list below :

wtApp:AlertBox(Text)
Opens a standard Windows alert box with text.

wtApp:SendFKey(Key)
Key is one of "F1".."F12" + "Insert" + "Plus" + "Esc"

wtContest:IsExchangeRequired()
Return a boolean. True if the current contest requires an exchange 
(associated with RST)

wtContest:GetContestId()
Return the current contestID

wtKeyer:Play(Message)
Message is a plain string to be played, a saved message ($F1 etc.) or a 
variable ($xxx)

wtKeyer:Stop()
Stop the current message

wtQso:IsCallsignEmpty()
Return a boolean : True if the callsign field of the active Qso is empty

wtQso:IsCallsignIncomplete()
Return a boolean : True if the callsign field of the active Qso contains 
a "?"

wtQso:IsExchangeEmpty()
Return a boolean : True if the exchange field of the active Qso is empty

wtQso:IsExchangeSent()
Return a boolean : True if the exchangeSent flag of the active Qso is set

wtQso:SetExchangeSent()
Set the exchangeSent flag of the active Qso (see 
wtQso::IsExchangeSent()) - Similar to the use of $SETEXCHSENT

wtQso:ResetExchangeSent()
Reset the exchangeSent flag of the active Qso (see 
wtQso::IsExchangeSent()) - Similar to the use of $RSTEXCHSENT

wtQso:ClearStatus()
Clear the status flags of the active Qso

wtQso:IsCallsignRepeated()
Return a boolean. True if the callsign hasn't changed since the last Enter

wtQso:IsOperatingModeRun()
Return a boolean. True if the operating mode of the active Qso is RUN 
(and False if S&P)

wtQso:IsModePhone()
Return a boolean. True if the mode of the active Qso is Phone (SSB and 
FM), and False otherwise

wtQso:IsQsoApproved()
Return a boolean. True if all requested fields of the active Qso are 
filled (contest dependent)

wtQso:IsDupe()
Return a boolean. True if the current callsign is a dupe

wtQso:IsCurrentFieldCallsign()
Return a boolean : True if the current field is the callsign field

wtQso:IsCurrentFieldExchange()
Return a boolean : True if the current field is an exchange field

wtQso:IsCurrentFieldOther()
Return a boolean : True if the current field is not the callsign field 
or an exchange field

wtQso:IsCurrentFieldEmpty()
Return a boolean : True if the current field is empty (except RST for 
the exchange field)

Notes:

1/ WT maintains two different Qso status : One for each radio. They are 
automatically cleared when the QSO is entered, if the operating mode 
(RUN / S&P) is switched or if the wtQso:ClearStatus() is executed.
2/ Lua global variables are persistent between scripts calls. If you 
don't want this behavior, use local variables instead (keyword local).

Until we provide a more comfortable IDE (we are working on it) to help 
script writing and debugging, you will have very basic output 
information (read syntax error messages etc.) in a standard Windows alert.

Write your script with a plain text editor, and save it as "esm.wts" 
(mandatory name) in the {AppData}/All Users/Win-Test/scripts/ directory. 
The value returned by YOUR script will then indicate to Win-Test what to 
do after it is executed : If the return value is 0 (or if there is no 
return value), WT will run its own embedded script after yours. If the 
the return value is 1, WT will continue the Enter key process, without 
calling its embedded script. And if the return value is -1, WT will stop 
the Enter key process, without calling its embedded script.

Basic Examples :

1/

-- esm.wts
wtApp:AlertBox("Enter key ! ESM rulez...");
return 0; -- This line can be omitted
-- end

No return value (or 0) => WT will execute this script (the alert box 
will be displayed), and the embedded script will be called after it.

2/

-- esm.wts
wtApp:AlertBox("Enter key ! The key is processed by WT");
return 1;
-- end

The return value is 1 => After executing the script (the alert box will 
be displayed), WT will continue its own process and act exactly as if 
someone hit Enter. Read : It silently enters the QSO if it is OK. The 
embedded ESM script is ignored.

3/

-- esm.wts
wtApp:AlertBox("Enter key ! The key processing is stopped");
return -1;
-- end

The return value is -1 => After executing the script (the alert box will 
be displayed), the embedded ESM script is ignored and WT will also 
ignore the Enter key process (no QSO is entered).

For convenience, you can find below the current ESM embedded script. 
Note that the real returned values are somewhat different from the ones 
described above, because of the nature of this script (embedded), but it 
is a good source of inspiration for your own masterpiece. As Lua is an 
interpreted language, the good news is that you can edit your script 
while WT is running. No need to exit WT, enter modifications, and start 
WT again. Just edit esm.wts while WT is running, save it, and try it 
immediately !

Finally, note that we currently restrict for now the usage of scripting 
to the ESM. We have other projects in mind, but we must setup a more 
convenient IDE before going any further. Please don't ask for other 
functions/API or script interface for now !

73

Larry - F6FVY

--------------------------------------------------------------------

-- v1.1 Dupes taken into account in the S&P mode
-- v1.0 Initial version

-- Send functions

function sendCq()
   wtQso:ResetExchangeSent();
   wtApp:SendFKey("F1");  -- Always use the function key
end;

function sendExchangeRun()
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("F2");
   else
     wtKeyer:Play("$INSERT");
   end;
   wtQso:SetExchangeSent();
end;

function sendExchangeAgain()
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("F2");
   else
     wtKeyer:Play("$F5 $F7"); -- $LOGGED ?
   end;
end;

function sendTu()
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("PLUS");
   else
     wtKeyer:Play("$PLUS");
   end;
   wtQso:ClearStatus();
end;

function sendQuestionMark()
   wtQso:ResetExchangeSent();
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("F7"); -- Again ?
   else
     wtKeyer:Play("$F7");
   end;
end;

function sendMyCall()
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("F4"); -- My call
   else
     wtKeyer:Play("$F4");
   end;
end;

function sendExchangeSAndP()
   if (wtQso:IsModePhone()) then
     wtApp:SendFKey("F2");
   else
     wtKeyer:Play("$F2");
   end;
   wtQso:SetExchangeSent();
end;

-- ESM core code

-- Return 0 (or return nothing) if we want the CR
-- to be processed also by WT (ie log QSO) and -1 if not.

if (wtQso:IsOperatingModeRun()) then -- Run
   if (wtContest:IsExchangeRequired()) then -- Usual contests
     if (wtQso:IsExchangeEmpty() or not wtQso:IsQsoApproved()) then
       if (wtQso:IsCallsignEmpty()) then
         sendCq();
       else
         if (wtQso:IsCallsignRepeated()) then
           sendExchangeAgain();
         else
           sendExchangeRun();
         end;
       end;
     else
       if (wtQso:IsExchangeSent()) then
         sendTu()
       else
         sendExchangeRun();
       end;
     end;
   else -- DXPed etc.
     if (not wtQso:IsQsoApproved()) then
       if (wtQso:IsCallsignEmpty()) then
         sendCq();
       else
         if (wtQso:IsCallsignRepeated()) then
           sendExchangeAgain();
         else
           sendExchangeRun();
         end;
       end;
     else
       if (wtQso:IsExchangeSent()) then
         sendTu();
       else
         sendExchangeRun();
       end;
     end;
   end;
else -- S&P : The automatic exchange fill (if enabled) is disabled by WT
   if ( (wtQso:IsExchangeEmpty() and wtContest:IsExchangeRequired())
         or not wtQso:IsQsoApproved() ) then
     if (wtQso:IsCallsignEmpty()) then
       sendQuestionMark();
     else
       if (not wtQso:IsDupe()) then -- Call only if not dupe
         sendMyCall();
       end;
     end;
   else
     if (wtQso:IsExchangeSent()) then
       wtQso:ClearStatus();
       return 1 -- Log it silently _Caution_ : embedded script returns 0
     else
       if (not wtQso:IsDupe()) then -- Sent exchange only if not dupe
         sendExchangeSAndP();
       end;
     end;
   end;
end;

return -1; -- This script overrides the Win-Test CR process