Macros

Macros are short text statements that contain imbedded references to text data used by the program fldigi.   Macro definition files(s) are located in the $HOME/.fldigi/macros/ directory and all have the extention ".mdf".  The default set of macros are contained in the file $HOME/.fldigi/macros/macros.mdf.  Fldigi will create this file with a set of default macros on its first execution.

Fldigi supports up to 48 macro definitions in sets of 12.  Macro definitions are not recursive, that is; a macro cannot reference another macro or itself.

The imbedded references are similar to those used by DigiPan and other fine modem programs.  The imbedded reference is an uppercase plain text descriptor contained with the <> brackets.

Macro tags

<FREQ> my frequency
<MODE> mode
<MYCALL> configuration call
<MYLOC> configuration locator
<MYNAME> configuration name
<MYQTH> configuration QTH
<MYRST> my RST
<ANTENNA>
configuration antenna
<VER> Fldigi version


<CALL> other stations callsign
<INFO1> S/N or other data contained in first info field of status bar
<INFO2> IMD or other data contained in second info field of status bar
<LOC> other stations locator
<NAME> other stations name
<QTH> other stations QTH
<RST> other stations RST


<MAPIT> map other stations locator on google
<MAPIT:adr | lat | loc> map other stations address, latitude-longitude or locator as specified


<CLRRX> clear RX pane
<CLRTX> clear TX pane


<GET> text to NAME/QTH
<TALK:on | off | t> Digitalk On, Off, Toggle; this is a Windows only tag and Digitalk must be running
<LOG> save QSO data to logbook immediately
<LNW> log at xmt time
<CLRLOG> clear log fields
<EQSL:[message>
submit the current log entry to www.eQSL.cc
This macro tag should be put before <LOG> or <LNW>


<QSOTIME> insert current logbook time HHMM, ie 0919
<ILDT> insert current local date-time in iso-8601 format, ie 2011-08-28 04:16-0500
<LDT> insert Local date-time, ie 2011-08-28 04:16-0500
<IZDT> insert Zulu date-time in iso-8601 format, ie 08/28/2011 04:16 CDT
<ZDT> insert Zulu date-time, ie 2011-08-28 09:16Z
<LT> insert local time, ie 0416
<ZT> insert zulu time, ie 0916Z
<LD> insert local date, ie 2011-08-28
<ZD> insert Zulu date, ie 2011-08-28
<WX>
<WX:xxxx>
insert current weather data from METAR as specified on WX configuration tab. see WX configure
replace xxxx with the 4 letter METAR designator for a report on a station other than the one specified on the weather configuration tab.


<CNTR> insert current value of contest counter
<DECR> decrement contest counter
<INCR> increment contest counter
<XIN> send exchange in string
<XOUT> send exchange out string
<XBEG> mark exchange in start
<XEND> mark exchange in end
<SAVEXCHG> save marked text to contest exchange in


<RX> receive
<TX> transmit
<TX/RX> toggle Transmit / Receive


<SRCHUP> search UP for next signal
<SRCHDN> search DOWN for next signal


<GOHOME> return to waterfall cursor to sweet spot
<GOFREQ:NNNN> move waterfall cursor to freq NNNN Hz
<QSYTO> same as left-clk on QSY button
<QSYFM> same as right-clk QSY button
<QSY:FFF.F[:NNNN]> Qsy to transceiver frequency in kHz, optional waterfall (Audio) frequency in Hz (If not specified, it i not changed). Several QSY frequencies, or ranges of frequencies provided by one increment, can be proposed, in which case the first frequency after the current frequency is chosen.


<RIGMODE:mode> send CAT command to transceiver to change to a valid mode
<FILWID:width> send CAT command to transceiver to change to a valid filter width

example to QSY to sweetspot (center of bandpass filter) and select narrow filter

<QSYTO><FILWID:200>

example to restore previous waterfall cursor frequency and bandwidth

<QSYFM><FILWID:2700>


<FILE:> insert text file; a file selection box will open when this tag is selected during editing


<IDLE:NN.nn> transmit idle signal for NN.nn sec
<TIMER:NN> repeat this macro every NN sec
<TUNE:NN> transmit single tone tune signal for NN sec
<WAIT:NN> insert delay of NN seconds before transmitting
<REPEAT> repeat macro continuously
<SKED:hhmm[:YYYYDDMM]>
schedule execution to begin at time and optionally date specified


<CWID> transmit a CW callsign identifier
<ID> transmit mode ID using waterfall video text
<TEXT> transmit video text defined on ID configuration tab
<TXRSID:on | off | t> transmit RSID on, off, toggle
<RXRSID:on|off|t> receive RSID on, off, toggle
<NRSID:NN>
transmit multiple RsID bursts
 - NN < 0 will transmit NN bursts for current modem and then return to Rx
   NN > 0 will transmit NN bursts for current modem and continue in Tx
   NN = 0 will transmit 1 bursts and continue (same as NN = 1)
<DTMF:[Wn:][Ln:]tones
transmit DTMF tone sequence at start of transmission; options
W-wait n msec, default 0
L-tone symbol length n in msec; default 50 msec
'-', ' ' and ',' insert silence symbol
eg: <DTMF:W250:L100:1-256-827-3200>


<POST:+/-nn.n> CW QSK post-timing in milliseconds
<PRE:nn.n> CW QSK pre-timing in milliseconds
<RISE:nn.n><RISE:nn.n> CW rise time in milliseconds
<WPM:ww[:ff]> CW WPM, ww = word rate, optional ff = Farnsworth rate


<AFC:on | off | t> AFC  on, off, toggle
<LOCK:on | off | t> lock waterfall cursor; on, off, toggle
<REV:on | off | t>
Reverse on, off, toggle


<QRG:text>
Insert current operating info with "text" into Rx stream, ie:
info text <<2013-01-12T21:18Z RTTY @ 14005000+0760>>
which can be used to return to a mode, rf, audio frequency.
<PAUSE>
Cause transmission to pause at place of occurance in macro text.  "Pause/Break" key on keyboard resumes transmission
<TXATTEN:nn.n>
set fldigi tx attenuator to value -30 dB <= val <= 0
<COMMENT:text>
allow macro to contain a comment field; everything between < and > is ignored by macro parser
<SAVE>
save the current macro definitions to the current file


<MACROS:> load a new macro defs file; file prompt when editing macro

      * Added macro to insert QRG text into Rx stream
        <QRG:text to insert>
      * Added save macro <SAVE> tag
      * Added export strings
        - FLDIGI_LOG_FILE - current logbook file name
        - FLDIGI_MACRO_FILE - current macro file name
      * Added <PAUSE> tag
        - returns to receive, but does not clear Tx buffer
      * Added <TXATTEN:nn.n> <!TXATTEN:nn.n> tag to control
        transmit attenuator control from within a macro.
      * Added <COMMENT:text> macro tag
        a do nothing that disappears from the transmitted
        text

Modem macro tags

Macro tags are also assigned to each supported modem type and sub-modem type that is supported by fldigi:

<MODEM:CW> <MODEM:MFSK-8> <MODEM:BPSK31> <MODEM:OLIVIA> <MODEM:THOR4>
<MODEM:DomEX4> <MODEM:MFSK16> <MODEM:BPSK63> <MODEM:OLIVIA:250:8> <MODEM:THOR5>
<MODEM:DomEX5> <MODEM:MFSK-32> <MODEM:BPSK63F> <MODEM:OLIVIA:500:8> <MODEM:THOR8>
<MODEM:DomEX8> <MODEM:MFSK-4> <MODEM:BPSK125>
<MODEM:OLIVIA:500:16> <MODEM:THOR11>
<MODEM:DomX11> <MODEM:MFSK-11> <MODEM:BPSK250> <MODEM:OLIVIA:1000:8> <MODEM:THOR16>
<MODEM:DomX16> <MODEM:MFSK-22> <MODEM:BPSK500> <MODEM:OLIVIA:1000:32> <MODEM:THOR22>
<MODEM:DomX22> <MODEM:MFSK-31> <MODEM:QPSK31> <MODEM:RTTY> <MODEM:THROB1>
<MODEM:FELDHELL> <MODEM:MFSK-64> <MODEM:QPSK63> <MODEM:RTTY:170:45.45:5:90> <MODEM:THROB2>
<MODEM:SLOWHELL> <MODEM:MT63-500> <MODEM:QPSK125> <MODEM:RTTY:170:50:5:100> <MODEM:THROB4>
<MODEM:HELLX5> <MODEM:MT63-1XX> <MODEM:QPSK250> <MODEM:RTTY:850:75:5:150> <MODEM:THRBX1>
<MODEM:HELLX9> <MODEM:MT63-2XX> <MODEM:QPSK500> <MODEM:RTTY:shift:baud:bits:bandwidth>
<MODEM:THRBX2>
<MODEM:FSK-HELL>
<MODEM:PSK125R>
<MODEM:THRBX4>
<MODEM:FSK-H105>
<MODEM:PSK250R>
<MODEM:WWV>
<MODEM:HELL80>
<MODEM:PSK500R>
<MODEM:ANALYSIS>





<MODEM:NULL>
null modem - Rx stream is discarded. Tx stream is silent but PTT is enabled



Local references are specified during the program configuration and can be changed during program operation.

Remote references are all part of the qso log field definitions and are routinely changed from contact to contact.

Global references are for items like Greenwich Mean Time.

The macros.mdf file can be edited with any ascii text editor such as kedit, gedit, geany, nano etc.  But it is much easier to use the built-in macro editor provided in the program.

Right click on any macro key (or the alternate set) and a macro editing dialog opens with the current copy of that macro and its label.  This looks very similar to the DigiPan macro editor at the urging of Skip Teller, KH6TY.



The Text box is a mini-editor with a very limited set of control functions.  You can mark, bound and select text for deletion (ctrl-X), copy (ctrl-C), and paste (ctrl-V).  Marked text can also be deleted with the delete or the backspace keys.  Marked text modification can also be invoked by using the mouse right click after highlighting.  

The macro reference in the pick list can be transfered to the current editing cursor location.  Highlight the desired macro reference and then press the double << arrow key for each occurance of the reference to be put into the macro text.  You can change the label name but any more than 8 characters may exceed the width of the button for the default sized main dialog.

The <TIMER:NN> and <IDLE:NN> macro tags should have the NN replaced with the time interval in seconds.

<TX><IDLE:5>CQ CQ de <MYCALL> <MYCALL> k<RX><TIMER:20>
The label associated with each macro key can be individually annotated with a symbol.  Here are the symbols that are recognized by the button label drawing routine:


The @ sign may also be followed by the following optional "formatting" characters, in this order:

Thus, to show a very large arrow pointing downward you would use the label string "@+92->".

Here are my macro buttons suitably annotated:



There are 4 sets of 12 macro functions.  You can move between the 4 sets using the keyboard and the mouse.
  1. Left click on the "1" button to move to set #2.  Right click on the "1" button to move to set #4.
  2. Move the mouse to anywhere on the macro buttons.  Use the scroll wheel to move forward  & backward through the macro sets
  3. Press the Alt-1, Alt-2, Alt-3 or Alt-4 to immediately change to that macro set.

You could use any label that is symbolic to the function required. Refer to the FLTK web site for a full list of label types.

If you modify the macros and do not save them ("Files/Save Macros" on the main window) fldigi will prompt you to save the macros when you exit the program if you have the "Nag me" option selected.

Inline Macro Tags

The following macro tags will be parsed and acted upon when they occur during the transmission of the macro.

Tag
Description
<!WPM:NN> CW words per minute
<!POST:+/-nn.n> CW post delay
<!PRE:nn.n> CW pre delay
<RISE:nn.n><RISE:nn.n> CW rise/decay time
<!MODEM: ....
change to specified modem with parameters
<!GOHOME> move audio carrier to mode sweet spot frequency
<!GOFREQ:NNNN> move audio carrier to specific audio frequency
<!QSY:FFF.F[:NNNN]> move to specific RF and Audio frequency
<!IDLE:NN.nn> transmit idle signal for specified number of seconds
<!WAIT:NN> wait (no audio) for specified number of seconds
<!WPM:ww[:ff]>
CW - ww = WPM, optional ff = Farnsworth wpm
<!TXATTEN:nn.n>
set fldigi tx attenuator to value -30 dB <= val <= 0

Note that each of these tags is identical to their immediate mode counterparts.  The exception is the addition of the exclamation mark following the leading '<'.  The use of these tags is best explained by example.


Example: CW Code Practice Transmission

<MODEM:CW><TX>
<!GOFREQ:600><!WPM:10:15>
NOW IS THE TIME - now 180 wpm
<!IDLE:2><!RISE:1.0><!PRE:0.4><!POST:+0.2><!WPM:180>
FOR ALL GOOD MEN TO COME TO THE AID of their country.
now 30 wpm<!IDLE:2>
<!WPM:30>de <MYCALL> k
<RX>

This is a more complex macro that might be used for a code practice transmission such as the W1AW broadcast on 3580 KHz.

<MODEM:NULL>
<!QSY:3579.200:800>
<TX>
<!MODEM:CW>
<!WPM:5:15><!IDLE:2><FILE:/home/dave/fldigi.ft950/scripts/practice-5wpm.txt>
<!WPM:10:15><!IDLE:5><FILE:/home/dave/fldigi.ft950/scripts/practice-10wpm.txt>
<!WPM:15:15><!IDLE:5><FILE:/home/dave/fldigi.ft950/scripts/practice-15wpm.txt>
<!WPM:18><!IDLE:10><FILE:/home/dave/fldigi.ft950/scripts/bulletin.txt>
<!IDLE:5>end of broadcast de <MYCALL> k
<RX>



Example: QSY:ffff.f:aaaa test

<MODEM:NULL><TX>
<!QSY:3583.0:1750>
<!MODEM:RTTY:170:45.45:5>
RYRYRYRYRYRY de <MYCALL> k
<RX>


Advanced QSY operations

Several QSY frequencies, or ranges of frequencies provided by one increment, can be proposed, in which case the first frequency after the current frequency is chosen.

ARRL style broadcast in multiple modes

<MODEM:NULL>
<!QSY:3594:915>
<!MODEM:RTTY:170:45.45:5><!IDLE:2>
<FILE:/home/dave/arrl_test/bulletin.txt>
<!MODEM:NULL><!GOFREQ:1000><!IDLE:5><!MODEM:BPSK31><!IDLE:2>
<FILE:/home/dave/arrl_test/bulletin.txt>
<TX><RX>

Inline tags in tx buffer ( ^! )

^!
^!^!
QST de W1HKJ
Test bulletin for 9/7/2011
QST de W1HKJ SK

^!^!^!^!^!
QST de W1HKJ
Test bulletin for 9/7/2011
QST de W1HKJ SK

^r

This is the contents of the ARRL broadcast macro text at the time the macro button is pressed.  Each of the <!... macro tags has been specified by the string "^!" which the Tx processor inteprets as the command to process the top most tag in the first-in, first-out sequence of tags.  As each "^!" is executed the referenced tag is printed to the Rx buffer using color coded text.
Do not attempt to enter the "^!" combination manually!

<!QSY:3594:915>
<!MODEM:RTTY:170:45.45:5>
<!IDLE:2>

QST DE W1HKJ
TEST BULLETIN FOR 9/7/2011
QST DE W1HKJ SK


<!MODEM:NULL>
<!GOFREQ:1000>
<!IDLE:5>
<!MODEM:BPSK31>
<!IDLE:2>

QST de W1HKJ
Test bulletin for 9/7/2011
QST de W1HKJ SK


Exec Macro

The <EXEC> ... </EXEC> macro is designed to be used on the Linux OS as it supports fully functional pipes.  Windows' version of file pipes is not fully POSIX compliant, but the function might work in the environment.  Consider all that the following allows you to do from within fldigi and you might want to consider changing over to Linux.

The <EXEC> macro defines an external child process (or processes) that will be called by fldigi when the macro key is invoked.  

Exported variables

Fldigi exports a set of variables to the child process and adds ~/.fldigi/scripts to the PATH variable before running the shell code.   This is the directory location for all executable scripts and programs which you might want to call from within the macro.  Some examples will be given later.  Open the macro editor for an undefined macro key and enter the following:
Save the macro; call it ENV.  Then press the newly defined macro key.  All of the exported variables will be shown in the transmit window.
Here is an example of the results:

FLDIGI_VERSION=3.21.66
FLDIGI_PID=28643
FLDIGI_RX_IPC_KEY=9876
FLDIGI_TX_IPC_KEY=6789
FLDIGI_ARQ_ADDRESS=127.0.0.1
FLDIGI_ARQ_PORT=7322
FLDIGI_XMLRPC_ADDRESS=127.0.0.1
FLDIGI_XMLRPC_PORT=7362

FLDIGI_MODEM=BPSK31
FLDIGI_MODEM_LONG_NAME=BPSK-31
FLDIGI_MY_CALL=W1HKJ
FLDIGI_MY_NAME=Dave
FLDIGI_MY_LOCATOR=EM64qv

FLDIGI_FREQUENCY=14071760
FLDIGI_DIAL_FREQUENCY=14070000
FLDIGI_LOG_FREQUENCY=14071.760
FLDIGI_AUDIO_FREQUENCY=1760

FLDIGI_LOG_CALL=W3NR
FLDIGI_LOG_NAME=Ed
FLDIGI_LOG_TIME_ON=1550
FLDIGI_LOG_TIME_OFF=1545
FLDIGI_LOG_QTH=Chickamauga
FLDIGI_LOG_LOCATOR=EM74IV
FLDIGI_AZ=090
FLDIGI_LOG_NOTES=Edward S Dout
FLDIGI_LOG_RST_IN=599
FLDIGI_LOG_RST_OUT=599

FLDIGI_CONFIG_DIR=/home/dave/fldigi.ft950/
FLDIGI_MACRO_FILE=/home/dave/fldigi.ft950/macros/macros.mdf
FLDIGI_LOG_FILE=/home/dave/fldigi.ft950/logs/logbook.adif

All of the above envelope variables can be referenced in a shell script that is called from within fldigi.

Detection of existing scripts

In anticipation of a collection of useful "fldigi scripts", the macro browser contains a macro line for each executable file found in the scripts directory.

The EXEC macro allows the text that is read from the child process to be parsed for more fldigi macros. For example, try this macro:

<EXEC>cat foo</EXEC>

where foo is a file that contains:

<MYCALL>

This may have some interesting uses but, if it is undesirable, it can be suppressed with an extra layer of redirection. Instead of <EXEC>command</EXEC>, you would use <EXEC>noexp command</EXEC> where noexp is the following very simple script: 

snip---------------------------------------
#!/bin/bash

echo -n "<STOP>"
"$@"     # run the command
r=$?     # save its exit code
echo -n "<CONT>"
exit $?
snip---------------------------------------

There are three additional MACRO definitions that expand the capability of the <EXEC> command: <STOP>, <CONT> and <GET>.

The <STOP> and <CONT> macros stop and resume the expansion of all <MACRO> strings. For example, <STOP><MYCALL><CONT><MYCALL>  would only expand the second <MYCALL>. By wrapping the command output in this way we can be sure that no text will be expanded. You might even use

"$@" | sed "s/<CONT>//g"

if you feel paranoid. 

You can "fork and forget" with an exec macro defined as: <EXEC>exec command -args >/dev/null</EXEC>

Any of the text that appears between the <EXEC> and </EXEC> can reference an executable program or shell command found in the ~/.fldigi/scripts directory.

Any text output that is returned by the program or script program (or the result of the in-line command) is always returned to the transmit buffer and appears as appended to the transmit window.

Querying an external database

The <GET> command captures returned text from the external process and parses it for the following content:

$NAMEtext_name$QTHtext_qth

If either $NAME or $QTH is present the trailing text is transferred to the LOG_NAME or LOG_QTH widgets respectively.  This means that you can create a script that accesses a local or net based database of callsign data and parse that data to form the above console output.  Fldigi will accept that output, parse it and populate the associated log entries.  Cool!  Now for some examples.  Here is a perl script that performs the above for the University of Arkansas on-line callsign database, ualr-telnet.

The matching macro key definition for the above is:

<EXEC>ualr-telnet.pl $FLDIGI_LOG_CALL</EXEC><GET>

which I named "ualr ?"

Google Earth Map

Here is a really cool perl script, Google Earth Mapping, that accepts the current "Loc" field in the logging area and generates a Google Earth map which is displayed in your default browser.  The macro call is <EXEC>map.pl</EXEC>

Custom dates/times

You can use <EXEC> to create custom date/time entries. For example, BARTG contesters use %H%M, but in other circumstances a user might prefer %H:%M or %H.%M etc.

Create the following script file in the ~/.fldigi/scripts directory, call it mytime:

snip---------------------------------------

#!/bin/sh
date --utc "+%H:%M"

snip---------------------------------------

date calls strftime, the same C function used by fldigi for the ZDT/LDT expansion, so it has an equally vast number of format strings to choose from. Look for them in its manual page.

Give "mytime" execute permissions with a file manager or with chmod: chmod u+x ~/.fldigi/scripts/mytime.

Test it on the command line and make sure it works correctly: ~/.fldigi/scripts/mytime

Restart fldigi. The mytime script will now appear at the end of the list in the macro browser, and can be entered with the << button as usual. Test that macro and you will see that <EXEC>mytime</EXEC> inserts the datetime in the specified format.  

Of course you could have entered:

<EXEC>date --utc "+%H:%M"</EXEC>

in the macro body text directly

Many other uses for the <EXEC>...</EXEC> macro pair can be imagined when used the with ENV parameters.  For example you could send Azimuth data to an automated antenna rotor.  The exported variables should be sufficient for a script writer to create custom loggers and clients.

Advanced QSY operations


The <QSY:FFF.F[:NNNN]> macro tag and its delayed flavour <!QSY:FFF.F[:NNNN]> allows the user to set the transceiver frequency to FFF.F (In kHz) and optionaly set the audio frequency to NNNN (In Hz).

It is possible to give several frequencies, which specify a frequency set. When the macro is executed, it choses the first frequency of this set greater than the current one. If the current frequency is greater than any frequency of the set, then the macro choses the smallest, first frequency of this set.

The utility of this feature is to allow a scan of a range of frequencies by re-executing the same macro over and over.  Each time the macro is executed, the next frequency of the set is selected. It can typically be used to iteratively try several frequency for a given test.

The frequency set can be specified in two distinct ways, which can be freely combined together.

Distinct frequencies

Several distinct separated with a semi-column, in increasing order. For example:

<QSY:2616.6;3287.6;3853.1;4608.1;4780.1;7878.1;8038.1:1900>

It means that the transceiver frequency will be set to 2616.6 kHz, then at next execution to 3853.1 kHz etc... and will loop back to 2616.6 kHz. Each time the same (optional) audio frequency will be set to 1900 Hz. In this specific case, it allows to test several Weather Fax broadcast stations, until the operator finds an active one.

Frequencies with increments

A frequency can come with an increment: This means an implicit range of frequencies from this one to the next frequency. If the last frequency has an increment, it is never taken into account: The last frequency is always an upper limit. Let's consider this example:

<QSY:89000+100;102000>

It is equivalent to:

<QSY:89000;89100;89200;89300;...;101900;102000>

In this case, it allows fldigi to scan all FM frequencies by clicking the macro button.

Combination with <TIMER> macro tag.

If the macro is automatically reexecuted using the <TIMER>, the same logic applies. At each run of the macro, the next frequency is chosen. The following macro transmits the same message on the frequencies 144800 MHz, 144900 ... until 146000 then loops back, waiting five seconds between each transmission.

<TX><QSY:144800.00+100;146000><MODEM:NULL><!MODEM:PACKET>
<FREQ> CQ CQ de <MYCALL><RX><TIMER:5>

Execution errors.

Several error messages can be displayed in the macro editor in case of a parameter. If this happens, the execution of the macro is stopped. Here is the list of possible messages:

Invalid frequency range

There must be valid frequencies. This macro will display the message:
<QSY:abcdef>

Increment must be positive

The frequency increment must be positive. This macro will fail:
<QSY:89000-1000;88000>

Frequency not positive

All frequencies must be strictly positive.

Frequencies must be increasing

The sequence of frequencies must be strictly increasing. An error message can appear with a macro such as:

<QSY:89000;88000>

Contest macro tags

Refer to Contest-How-To