Loading...
 

Standards for Function Key Files

1. Benefit of Standardized Function Key files

  • Our target audience is beginners. The Macros used in these Messages should embrace the KISS principle
  • Reduce the steep learning curve encountered by new users when attempting to operate their first contest on N1MM Logger
  • Design Function Key files that can be downloaded and used as-is without editing by the user
  • Instill consistency across our Function Key files

2. Terminology and Definitions

Although we cannot correct the confusing nomenclature regarding function keys and macros among all hams worldwide, we should at least strive for consistency within our own sphere of influence - the N1MM Logger software and its documentation.

2.1. Function Key File

A collection of pre-defined Messages which are sent repeatedly during a contest, usually the result of pressing a keyboard function key or clicking on a button. In N1MM Logger, a Function Key file is stored on disk with a .MC file suffix, and is referenced during contest setup by identifying the file in the >File >Open Log in Database >Associated files menu. Each single mode contest has one Function Key file associated with it. Multi-mode contests may have as many as three Function Key file associations, one for each mode: phone, cw, and digital.

2.2. Label

The text displayed on a button in N1MM Logger. Each line of a Function Key file begins with a Label and ends with a Message. The Label and Message are separated by a comma. For example: Call CQ, CQ CQ CQ DE W1AW K As of v12.02.01, the use of the pound sign (#) to identify a Comment on a line prevents any label for a normal message from beginning with a pound sign.

2.3. Message

A phrase consisting of text and Macros which are pre-defined for repetitive contest tasks. Each line of a Function Key file begins with a Label and ends with a Message. For example: calling CQ, sending an exchange, requesting a repeat transmission. There can be as many as 24 Messages in a Function Key file. The first 12 define Run Messages; the second 12 define Search & Pounce Messages.

2.4. Macro

Within a Message, either a special character (#, !, *, @) or a reserved expression surrounded by curly braces { }. The computer will identify and perform special operations upon encountering a Macro. Some operations replace the Macro with contest-related information at the time of transmission, for example: {EXCH}, {MYCALL}. Other operations execute a program function, for example: {RUN} to switch to Run mode, {CTRLF1} to start a CQ on the opposite radio in SO2R, or {CLEARRIT} to return the transceiver's RIT to zero.

  • In accordance with the new terminology, the website menu >File gallery would be renamed Sample Function Key Files
  • Maintain the current structure which differentiates between phone, cw and digital files
  • Add a “Description” column (see the >Files >Latest Updates page for example) for short descriptions of each Function Key file
  • Any special instructions would be inserted in the Description column
  • Define standard columns for all Function Key gallery pages: Filename, Description, Size, Last Modified, Hits. Other file information available upon clicking the Info button: Creation date, Last Modified by

4. A Style Guide for Messages

  • Publish, at least initially, only one Function Key file per major contest
  • Filenames should be the same expression as the >File >New Contest database term, followed by .mc. For example, if the Contest Setup filename is ARRLRTTY, then the associated sample filename should be ARRLRTTY.mc. (upper case contest name, lower case suffix)
  • Filenames could contain a suffix, when necessary, to allow for multiple Function Key files per contest.
    • For multi-mode contests, the suffix should be the contest name separated from the mode by a dash. For example, ARRL10-SSB.mc
    • For special purpose files, the suffix should provide some explanation of purpose. For example, ARRL10-SSB-SO2R.mc
  • Message labels should be in Mixed Case - often called Camel Case - easier to read and uses less space on the buttons. For example: Call CQ, State?, His Call
  • Macro expressions should be listed in UPPER CASE. For example: {MYCALL} {TX} {EXCH}
  • To minimize editing by the user, include macro expressions rather than literal text. For example: {MYCALL} not “K8UT”
  • Create messages for all 24 rows of Run and S&P definitions, even if they are exact duplicates of previous rows
  • Tailor messages to function properly in either ESM or non-ESM operation. If there is some feature of a Message that precludes non-ESM operation, use Comments to note that fact
  • Beginner Macro Terms
    • "!" rather than {CALL}
    • {MYCALL} rather than "*" - The macros perform identical functions but MYCALL has the advantage of being self-documenting
    • ... not a complete list - will add as we build the files
  • Advanced Macro Terms - after defining the set of beginner macro terms; everything else should be considered advanced
    • Includes the following: {CLEARRIT} {SENTRST} {LOGTHENPOP}

5. Comments in Function Key Files

Comments can be placed in Function Key files beginning with version 12.02.00. There are strict rules for comment lines:

  • Cannot follow other text (an existing message) on a line
  • Must exist alone on a line (cannot precede a message on a line)
  • Comments describing a Message should be inserted on the line beneath the Message
  • The syntax for a comment line is: <pound sign>label text<comma>comment text
    • Must begin with a # (pound sign)
    • Can optionally contain up to 29 characters for a label
    • Must use a , (comma) to separate the comment label from the comment text
    • Cannot contain any additional commas within the comment text
    • Maximum length of comment text is 256 characters, but for practical purposes (editor display) it should be kept much shorter

5.1. Function Key File comments in practical use:

#NEW VERSION, This Function Key File requires N1MM Logger V12.02.00 or newer 
#EDITS REQUIRED, before using this file-----------------------------------------
#REM, none
#SPECIAL INSTRUCTIONS, ---------------------------------------------------------
#REM, none
#ADVANCED FUNCTIONS, -----------------------------------------------------------
#REM, none
#RUN MESSAGES, begin here ------------------------------------------------------
F1 always CQ
F2 always Exchange
F3 always TU
F4 basic MyCall - advanced may be LogThenPop? LogThenGrab?
F5 always His Call (!)
F6 basic spare; advanced may be Worked B4 in SS
F7 always repeat my Exchange
F8 always AGN?
F9 request repeat of an Exchange parm 1
F10 request repeat of an Exchange parm 2
F11 Run spare - advanced may be Grab?
F12 always Wipe
#S&P MESSAGES, begin here ------------------------------------------------------
F1 always CQ
F2 always Exchange
F3 always TU (rarely used in S&P)
F4 always Call Him
F5 always His Call (!)
F6 always {MYCALL}
F7 always repeat my Exchange 
F8 always AGN?
F9 request repeat of an Exchange parm 1
F10 request repeat of an Exchange parm 2
F11 S&P spare - advanced may be Grab?
F12 always Wipe

Last Modification: 07 February 2012 16:55:34 EST by K8UT.