[WT-support] Proposal to use LUA APIs to support new contests in Win-Test

[Bob Wilson, N6TV]

Win-Test still does not support a number of popular contests, such as the
California QSO Party (Oct 3,4), most other state QSO parties, and many other
regional contests that have been requested here in the Win-Test reflector
over the years.

It seems that with a new API made of LUA scripts, it ought to be possible
for the users to develop and share contest-support scripts for new contests,
at least to some usable extent.

I'd be happy to try to make this work for the California QSO Party, as I am
very motivated to do that right now!  I've got one month.  The CQP script
could be used as a template for other contests.

Proposal:

Instead of reusing the /Scripts directory, Win-Test could look for a new
/UserDefinedContest directory for a list of .wts files, one file per
contest, e.g. CQP.wts, 7QP.wts, etc.

Inside the .wts file a developer would use LUA code to define a number of *
required* LUA functions.  Win-Test would call these LUA functions by name at
the appropriate time to get the information it needs to score the contest
and prompt for data, for example:

   - ContestName() -- Returns the name of the contest (for display in the
   Contest Configuration screen's contest list)
   e.g. "Calif. QSO Party - from CA" or "Calif. QSO Party - from outside CA"
   - ContestMonth() -- Returns a list of the typical months of the contest
   (for filtering contest by month, 1-12),
   e.g. "10" meaning October, or  "1_8" meaning January and August
   - ContestCategory() -- Returns a list of the categories of entry
   supported in that contest
   e.g. "Single-op_Single-op, Assisted_Multi-op_single xmtr_Multi-Multi")
   (underscore used as separator)
   - ContestModes() -- Returns a list of modes supported
   e.g. "CW_SSB_RTTY_Digital_Mixed"
   (underscore used as separator)
   - ContestOverlay(category) -- Returns a list of the contest overlay
   classes supported in that contest, given the specified entry category
   - ContestPowerClass(category, overlay) -- Returns a list of the power
   classes supported for that category and overlay
   e.g. "HIGH_LOW_QRP"
   - ContestOther() -- Returns the string to be used to prompt for the
   "Other" field at the bottom of the Config Window
   e.g. "Name", "Age", etc.
   - ContestExchangePrompt() -- Returns a string to be displayed to prompt
   the user what to enter in the "Exchange" boxes at the top of the Contest
   Configuration window
   e.g. "US and VE stations enter their state or province, all others enter
   \"DX\""
   - MultFile() -- Returns the name of the contest-specific mult file to
   use, if any
   e.g. "cqp_cnty.dat"
   - EquivFile() -- Returns the name of the contest-specific equivalence
   file to use
   e.g. "ca_cnty.dat"
   - RoversOK() -- Returns TRUE if roving stations can be counted again as
   valid, non-duplicate QSOs (see Mult() function below)
   - DupesOK() -- Returns 0 if dupes are not permitted, otherwise a number
   indicating number of intervening QSOs permitted before working the station
   again
   - UseSprintExchangeLogic() -- Returns TRUE or FALSE
   - MultsBy() -- Returns a constant indicating whether mults are counted
   once per contest, once per band, once per mode, or once per band and mode
   - Mult(callsign, exchange1, exchange2) -- Returns the multiplier string
   associated with that callsign
   This needs helper functions like GetDXCC(callsign),
   GetWAECountry(callsign), GetContinent(callsign), GetMult(callsign,
   exchange1, exchange2) that would be provided by Win-Test itself.
   GetMult() helper functino would use the previously-specified MultFile and
   EquivFile
   e.g. the Mult() function would returns county (from exchange), or "CA" or
   a DXCC prefix returned by the helper functions
   - ZoneMult() -- Returns "CQ", "ITU", or "None" indicating if zones count
   as additional multipliers.
   - QSOsBy() -- Returns a constant indicating whether QSOs are counted once
   per contest, once per band, once per mode, or once per band and mode
   - GetPoints(callsign, mycountry, mycontinent, country, continent, zone,
   multval, freq, mode, exchange1, exchange2) -- returns the no. of points for
   that QSO based on the given fields.
   multval would be something previously returned by the Mult function.
   - CabrilloQSOLine(date,time,band,mode, mycall, rstsent, myexchange1,
   myexchange2, callsign, restrecv, exchange1, exchange2, stnNum) -- returns a
   string in the proper format for a QSO: line in the Cabrillo file
   - CabrilloHeaderLines(callsign, cqzone, ituzone, exchange1, exchange2,
   category, mode, overlay, powerclass, other, club, soapbox) -- returns the
   Cabrillo header lines given the provided fields (from user-entered values on
   the Contest Config. window, which are passed to the function)
   - GetLoggingColumnCount() -- Return the number of fields to display on
   the data entry (logging window)
   - GetLoggingColumn(n) -- Given column n, return the title above that
   column, the width of that column and an indicator of what it represents (QSO
   number, callsign, exchange1, exchange2, rst, zone, etc.)

This gives you the general idea;  I could write a much more comprehensive
specification, but the main goal is to make it work with the existing
internals of Win-Test, so I think it's better if the Win-Test developers
tell us exactly what else they would need.  For example, I've only suggested
a maximum of two exchange fields in addition to RST, but maybe it should be
more generalized.

Though such a LUA API model will not be able to handle all the particular
idiosyncrasies of every possible contest, I think it could handle 80% of
them, and that would probably be good enough.

73,
Bob, N6TV
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.f5mzn.org/pipermail/support/attachments/20100902/d2b58418/attachment.htm