vARIM Messaging Program v1.10 Help

Introduction

ARIM means "Amateur Radio Instant Messaging" and the vARIM program is a GUI host mode program for the VARA HF Modem developed by EA5HVK.

vARIM is written in C and C++, distributed as source code under the terms of the GPL 3.0 license. Developed on Ubuntu Linux, it should compile and run on any modern Linux installation (including Raspbian for Raspberry Pi 3). Compiling the source code is easy, the only build dependency beyond the standard C libraries are the fltk and zlib development libraries. Using Microsoft Windows? No problem, vARIM will build and run in the excellent Cygwin environment for Microsoft Windows, or in the Linux Subsystem for Windows (WSL).

Features include:

• Uses a GUI (graphical user interface). The vARIM window is resizable, and the font size is adjustable.
• Attaches to VARA HF software modems running on the local host or remote hosts over a TCP connection.
• Supports sending of CQ frames, a feature introduced in VARA HF v4.4.9.
• Receives and displays S/N reports from the VARA modem when receiving data in an ARQ session, a feature introduced in VARA HF v4.5.0.
• Allows multiple ports to be defined in the configuration file. Operator may attach or detach from any of them while vARIM is running.
• Supports hardware PTT over serial ports for rig keying using DTR or RTS signals. A PTT monitor protects the transmitter if communication with the VARA modem fails when PTT state is ON.
• Allows file uploads and downloads (both text and binary file types), with a compression option. This sends the message or file in RFC 1950 "zlib" format, using the "deflate" compression method documented in RFC 1951. The data is automatically decompressed at the receiving station to recover the original file or message.
• Supports mutual authentication of ARQ sessions using a digest access authentication scheme. This can be used to confirm the identity of the connected station or control access to designated "access-controlled" shared files directories.
• Supports access control by call sign using either a whitelist or a blacklist. When this feature is active, only the stations granted access are allowed to make ARQ connections to the local station.
• Displays a "calls heard list" view showing stations heard on the air, including timestamp and type of frame last heard.
• Displays a "recents list" view showing recently received messages from other stations.
• Displays a "connection history" view showing ARQ connection activity including grid square locators, session start and duration times, and number of bytes sent and received.
• Displays an "ARQ file history" view showing ARQ file transfer activity including transfer start and duration times, file size, checksum, file name and whether compression was used.
• Displays a traffic monitor view showing heard VARA control and data frames, with a 500 line scrollback buffer and optional timestamps.
• Displays a modem command/response view allowing the operator to issue commands to the modem and monitor its "async response" stream.
• Allows exchange of stored text messages with the remote station during an ARQ session. Messages may be composed "off-line" and stored to the message outbox to be sent later.
• Offers option for automatically purging messages from mailboxes aged beyond a specified number of days. Alternatively, this process can be invoked manually from the message listing views.
• Allows query of connected station for information such as vARIM versions, grid square, calls heard list, shared text files and text generated by scripts (dynamic files).
• Offers option for message tracing using RFC-822 style Received: headers. In this way a record of the message's progress through a network is built up as it is forwarded from station to station.
• Offers options for separate message traffic logging and debug trace logging with automatic daily log rotation.
• Includes text file editor for files in the shared files directory as well as the varim.ini configuration file.
• Includes log file viewer for vARIM logs.

The vARIM program is a work in progress and I am interested in feedback. I monitor the Digital-mode-radio group at Groups.io and can be reached there, or at the arim-ham group at Groups.io where files and other information will be posted.

The vARIM screen layout

The vARIM screen is divided into different sections. Some of these are tabbed and host more than one "view".

• Main Menu Use this to configure and control vARIM. Almost anything that can be done from the command line can be done from a menu.
• Top Status Bar This includes:
  • MYCALL, port number and port name when attached to a port.
  • New File and New Message indicators. These can be reset from the View->Clear menu (or press <CTRL-N>)
  • LISTEN button toggles the modem's listen setting. When enabled, the modem will respond to ARQ connection requests. When disabled, the VARA modem will ignore ARQ connection requests from remote stations.
• Traffic Monitor View Tab Displays inbound and outbound data traces, together with modem status notifications. These are timestamped and identified by a type code:
  • << indicates outbound data (to the remote station).
  • >> indicates inbound data (from the remote station).
  • ** indicates an ARQ session status update.
  • !! indicates an error condition.
  A 500 line scrollback buffer allows review of past traffic. Traces for outbound data sent from vARIM to the modem are printed in bold text to make them stand out.
• Message Inbox Tab Displays a listing of the message inbox.
• Message Outbox Tab Displays a listing of the message outbox.
• Send Messages Tab Displays a listing of sent messages.
• Local Files Tab Displays a listing of shared files on the local station.
• Remote Files Tab Displays a listing of shared files on the remote station if the /FLGET command is issued in an ARQ session.
• Modem Command Monitor Tab This displays the stream of modem async responses when attached, together with any commands sent to the modem by the vARIM program, or by the operator. The operator can send modem commands by pressing <SP> for the command prompt, and entering the command prefixed by the ! (bang) character. The direction of data flow is shown by the << (outbound) and >> (inbound) arrows. Outbound commands sent from vARIM to the modem are printed in bold text to make them stand out.
• Recents Tab Displays a listing of recently received messages.
• Connect History Tab Displays the ARQ connection history.
• ARQ File History Tab Displays the ARQ file transfer history.
• Command Line Press <SP> to open a command prompt here. Commands can be directed to the modem (if attached) by prefixing them with the '!' character. During an ARQ session text entered here is sent to the connected station.
• Calls Heard List Here are the call signs of stations that have been connected to your station or from whom a CQ frame was received since vARIM was started. They are listed in reverse chronological order (most recent first), and each call sign appears only once. Each entry is timestamped, either last time heard, indicated by "(LT)" in the list title, or elapsed time since last heard, indicated by "(ET)". The format is HH:MM:SS for last time heard, and DD:HH:MM for elapsed time. << indicates an ARQ connection initiated by your station (outbound) and >> indicates an ARQ connection initiated by the remote station (inbound). Outbound connections are printed in bold text to make them stand out. CQ indicates an CQ frame received from a remote station. Right-click on a call sign in the list to open a pop-up menu of operations:
  • Connect... Choose this to start an ARQ session with the station.
  • Send a message... Choose this to send a message to the station. When not connected the message is stored in the message outbox.
  The Connect... option is not available during an ARQ session.

  

• Bottom Status Bar This includes, from left to right:
  • Notification area - Warning and status update messages appear here.
  • ARIM status indicator - Shows ARIM protocol activity. When vARIM is busy, the background color changes and new operations are blocked.
  • ARQ session information
    • Remote station call sign - The suffix + is appended to the call sign if the ARQ session is authenticated.
    • Connection bandwidth - Shows the maximum bandwidth negotiated when the ARQ connection was made, for example BW:500.
  • VARA modem status indicator
    • BUSY indicator - Displays BUSY on a magenta background when the channel is busy. BUSY notifications are not sent by the modem to vARIM during an ARQ session.
    • TX indicator - Displays TX on a red background when the modem is transmitting (PTT is ON).
    • S/N indicator - Displays the signal-to-noise ratio reported by the VARA modem when receiving data from another station. The S/N measurement in dB is shown on a red background when S/N is <= -15 dB, a yellow background when the S/N is <= -10 dB, and a green background when S/N is above -10 dB. This is the same color scheme used in the S/N meter in the VARA HF modem. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
    • Beacon countdown indicator - Displays time remaining until the next CQ beacon transmission when beaconing is enabled and no ARQ session is active. The time is shown on a magenta background when less than one minute remains, yellow background when less than 5 minutes remain, and the normal gray background when 5 or more minutes remain before the next beacon will be sent.
  • On the left side of the status bar, a progress meter appears during data transfer operations:
    • ARQ message transfers - Message uploads and downloads (/MPUT, /MGET).
    • ARQ file transfers - Binary file uploads and downloads (/FPUT, /FGET).
    • ARQ file listing transfers - File listing uploads and downloads (/FLGET, /FLPUT).

Downloading and installing

The prerequisite for vARIM is the VARA HF software modem, version 4.5.5 or higher. Download links and information about installing and running the VARA HF modem are found here:

• EA5HVK Software home page.

If you plan to run vARIM in the Cygwin environment on Windows, then Cygwin must be installed first. The installer for this is the Cygwin Setup program found on the Installing and Updating Cygwin Packages page. The Cygwin Walkthrough and Beginner's Guide may be helpful in getting started. The X Window System must be installed in Cygwin for GUI programs like vARIM to run. Follow these instructions to install X in Cygwin and run vARIM in an X window. To learn more, consult the Cygwin/X User's Guide. When using Cygwin, you will work in the Cygwin Terminal. A shortcut to the Cygwin Terminal should be placed on your Windows desktop by the Cygwin Setup program. This setup works well to run vARIM and the VARA modem on the same Windows computer.

If you plan to run vARIM in the WSL environment on Windows 10, then you will need to install a standalone X Server for GUI programs like vARIM to run. A good choice is VcXsrv. The installer for this can be downloaded from the VcXsrv download page on SourceForge. This runs on the Windows side and displays vARIM when it is executed in the WSL terminal. Details of configuration may vary depending on which Linux distribution is running in WSL. I've had good luck running Pengwin Linux, which works with VcXsrv without any special configuration. This combination works well to run vARIM and the VARA modem on the same Windows 10 computer.

Next, you need to either build vARIM from source or download a "portable" precompiled binary package.

• To build from source, download the source code tarball:

  Current vARIM Version 1.10 source code and help file

  Enter this command:

  tar xzvf varim-1.10.tar.gz

  to unpack the varim-1.10 directory. This contains source code files and other information including build instructions and this help file.

  To compile and install vARIM, change directory to varim-1.10 and enter these commands:

  ./configure
make
sudo make install (Linux, Raspbian, WSL)
  or
make install (Cygwin)

  This installs the varim executable, varim(1) and varim(5) man pages, and additional documentation including this Help file. The varim(1) man page documents varim command line options and the varim(5) man page documents the varim.ini configuration file (use the command man 5 varim to read it).

  To compile from sources you need the GNU compiler, gcc, the make utility and the fltk and zlib development libraries and headers. The INSTALL file included with the source distribution contains detailed instructions for installing these and building vARIM from source.

  To run vARIM, enter:

  varim

  at the command prompt. The first time vARIM runs it will create a directory named varim in your home directory containing data files and a model varim.ini configuration file. It also contains three subdirectories: files for shared files, doc with symbolic links to documentation including this Help file, and log for log files. Once created, the contents of the varim directory will not be overwritten by subsequent installations of vARIM or deleted if vARIM is uninstalled. The links in the doc directory will always point to the most recently installed documentation files.

  To configure vARIM, open the varim.ini file in a text editor and edit as needed. You must define at least one port by setting call signs, the grid square locator, and VARA modem IP address and port number. Be sure to change the font size to your liking.

  • If editing the file in Windows, use a text editor that understands the Unix text file format, like Wordpad or the freeware text editor Programmer's Notepad.
  • On Cygwin, 'localhost' may not work as the address for an VARA modem running on the same Windows PC. Use the IP address of the Windows host instead, e.g. "192.168.1.54". This can be discovered by running ipconfig from the command line in the Cygwin terminal.

• If you prefer to install precompiled "portable" versions of vARIM, here are download links for 64-bit Ubuntu Linux (and derivatives like Linux Mint) and 32-bit Raspbian (on Raspberry Pi 3):

  Current version 1.10 binary and help file (64-bit Ubuntu Linux 20.04 and derivatives)

  Current version 1.10 binary and help file (32-bit Raspbian on Raspberry Pi 3)

  Current version 1.10 binary and help file (32-bit Cygwin/X on Windows)

  Current version 1.10 binary and help file (64-bit Cygwin/X on Windows)

  The precompiled portable version for Linux is known to work only on Linux Mint 20 - it's best to compile vARIM from the source code on any other Linux OS to avoid versioning issues with dynamically linked libraries.

  Download the one you need and enter this command:

  tar xzvf filename

  to unpack the varim-1.10 directory. This contains the executable file, data files and a model varim.ini file. It also contains three subdirectories: files for shared files, doc with copies of documentation files including this help file, and log for log files. The varim-1.10 directory can be copied anywhere (e.g. a USB flash stick) and vARIM run from it locally, so it's called the "portable" installation. It's self-contained, with messages, shared files and log files moving with the directory if it's relocated.

  To run vARIM, change directory to varim-1.10 and enter:

  ./varim

  The "./" preceding the file name tells the system to run the copy of varim located in the current directory.

  To configure vARIM, open the varim.ini file in a text editor and edit as needed. You must define at least one port by setting call signs, the grid square locator, and modem IP address and port number. Be sure to change the font size to your liking.

  • If editing the file in Windows, use a text editor that understands the Unix text file format, like Wordpad or the freeware text editor Programmer's Notepad.
  • On Cygwin, 'localhost' may not work as the address for a VARA modem running on the same Windows PC. Use the IP address of the Windows host instead, e.g. "192.168.1.54". This can be discovered by running ipconfig from the command line in the Cygwin terminal.

Run varim with the --help option to print out command line options:

Usage: varim [OPTION]
  -v, --version            print version information
  -f, --config-file FILE   use configuration file FILE
  -p, --print-conf FILE    print configuration file listing to FILE
  -h, --help               print this option help message

Configuration

By default, vARIM reads an "ini" format configuration file named varim.ini at startup. If you are using the portable binary vARIM distribution, this file is located in the same varim-1.10 directory containing the vARIM executable file and data files. If you compiled and installed vARIM from the source distribution, this file is located in the varim data directory in your home directory. To override the default configuration file location, run varim with the --config-file command line option, for example:

varim --config-file /home/nw8l/HF/varim-net.ini

To open the configuration file, choose File->View or Edit Config File... from the main menu:

If you make changes, press Save to save them, or Cancel to abandon them. Saved changes won't take effect until vARIM is restarted.

Multiple ports can be defined. A subset of the VARA modem parameters are initialized here, but these can be overridden from the command line after the program starts. Most options have reasonable default values which are used if they are not found in the configuration file.

• [port] Each port is configured in a separate [port] section. The first [port] section in the file defines port 1, the second port 2, and so on. The limit is 10 port definitions.
  • ip-addr The IPv4 address of the host on which the VARA modem is running. This can be in "dotted quad" numerical form or a host name e.g. 'localhost' or 'DELL-1520.example.net'. Max length for host names is 253 characters. Default: 127.0.0.1. NOTE: On hosts with IPv6 enabled, 'localhost' may not work as the address for a VARA instance running on the same host. Use the IPv4 address of the host, e.g. "192.168.1.54", or the IPv4 loopback address "127.0.0.1" instead. The IPv4 address can be discovered by running ipconfig from the command line.
  • tcp-port The TCP port on which the VARA modem is listening. Default: 8300.
  • mycall The station call sign, e.g. NW8L or NW8L-4, max length 10 characters. Call must be no longer than 7 characters and may have optional SSID in the ranges -0 to -15. vARIM will respond to ARQ connection requests addressed to this call. Default: NOCALL.
  • gridsq The station's grid square locator, returned in response to the 'gridsq' query. It must be a well formed Maidenhead locator, either 4, 6 or 8 characters long. Examples: DM65 or DM65qf or DM65qf15. Letter pairs are not case-sensitive. Default: DM65.
  • name A name assigned to the port, returned in response to the 'pname' query. Max length is 31 characters. Default: Empty.
  • info Information describing the port, returned in response to the 'info' query. Use the character pair \n to indicate a line break if you want to format the text into multiple lines; this will be converted to a newline character in the response. Max length is 127 characters. Default: Empty.
  • listen Control whether the modem listens for ARQ connection requests from other stations. Set to ON to enable listening for ARQ requests or OFF to disable listening. Default: ON.
  • chat-mode Control whether the modem listens for CQ frames and sends S/N reports to vARIM when receiving data from the remote station during an ARQ session. Set to ON to enable or OFF to disable chat mode. Default: ON.
  • ptt-mode Selects the PTT mode. Set to VOX if hardware PTT is not used. Set to DTR or RTS if serial port hardware PTT is used. Default: VOX.
  • ptt-device Selects the serial port device for hardware PTT. Default: /dev/ttyUSB0.
  • modem-timeout The inactivity timeout for modem communications in seconds. When idle, vARIM should receive IAMALIVE messages from the modem's control port periodically. If vARIM receives nothing for more than modem-timeout seconds, the port is detached. Range is 120-1800, or set to 0 to disable the feature. Default: 300.
  • modem-init-cmd Specifies a modem initialization command to send when attaching to a port. For example:
    modem-init-cmd = LISTEN OFF
    Commands are send verbatim without validation of the command name or its parameters. Max length is 128 characters. You may define no more than 16 modem-init-cmd parameters. Default: None.
  • arq-bandwidth The ARQ connection bandwidth in Hz, either 500, 2300 or 2750 (VARA HF 4.3.0 and higher). Default: 500.
  • arq-timeout The inactivity timeout for ARQ connections in seconds. Range is 30-600. Default: 120.
  • arq-sendcr Control whether CRLF line endings are sent in ARQ mode, instead of Unix style LF endings. Set to TRUE to send CR, FALSE to send only LF. Default: TRUE.
  • beacon-enable Set to TRUE to enable CQ beacons, FALSE to disable them. Default: FALSE.
  • beacon-time The CQ beacon interval time in minutes. Range is 15 to 999. Default: 60.
  • beacon-time-limit The CQ beacon time limit in hours. Range is 1 to 48. Beacons are automatically disabled when the time limit is reached. Default: 24.
  • log-dir The directory where log files are located if port specific logging is enabled. This can be an absolute path or a relative path rooted in the user's home directory. Max length is 255 characters. Default: the user's home directory.
  • debug-log Set to TRUE to enable debug logging for this port in the directory specified by the log-dir parameter, FALSE to disable it. Default: FALSE.
  • traffic-log Set to TRUE to enable traffic logging for this port in the directory specified by the log-dir parameter, FALSE to disable it. Default: FALSE.
• [arim] This section holds settings for the ARIM messaging protocol.
  • mycall The call sign used as the "from" address for messages stored in the outbox when not attached to a port. Default: NOCALL.
  • files-dir The directory in which files available for other stations to read are located. This can be an absolute path or a relative path rooted in the vARIM working directory and must be terminated with a '/' character. Max length is 255 characters. Default: files/
  • add-files-dir Specifies an additional shared files directory accessible by remote stations. This must be a path relative to the shared files root directory specified by the files-dir parameter. By default, only files in the shared files root directory may be listed or downloaded, and any directories it contains are hidden. If you need to share files organized into multiple directories, use one or more add-files-dir parameters to expose them. For example:
    add-files-dir = forms/
    This allows limited access to the forms directory in the shared files root directory. A remote station may list, read or download the files it contains, but any subdirectories are hidden. To grant full access to a directory, including the hierarchy of subdirectories rooted there, append the '*' wildcard character to the end of the path. For example:
    add-files-dir = contests/*
    This grants full access to the contests directory in the shared files root directory. This exposes not only the files in contests, but also the hierarchy of subdirectories rooted there. Subdirectories such as contests/2016 or contests/2016/June are visible, and a remote station may list and download the files they contain. Max length is 255 characters. NOTE: you may define no more than 16 add-files-dir parameters. Default: None.
  • ac-files-dir Specifies an access-controlled shared files directory, accessible only by authenticated stations in an ARQ session. This must be a path relative to the shared files root directory specified by the files-dir parameter. If you need to limit the sharing of certain files to authenticated stations, use one or more ac-files-dir parameters to expose them. For example:
    ac-files-dir = admin/
    This allows limited access to the admin directory in the shared files root directory. An authenticated station may list, read or download the files it contains, but any subdirectories are hidden. To grant full access to a directory, including the hierarchy of subdirectories rooted there, append the '*' wildcard character to the end of the path. For example:
    ac-files-dir = admin/*
    This grants full access to the admin directory in the shared files root directory. This exposes not only the files in admin, but also the hierarchy of subdirectories rooted there. Subdirectories such as admin/2016 or admin/2016/June are visible, and a remote station may list and download the files they contain. Max length is 255 characters. NOTE: you may define no more than 16 ac-files-dir parameters. Default: None.
  • ac-allow Specifies a list of remote station call signs which are allowed to make ARQ connections to the local station. ac-allow parameters take precedence over ac-deny parameters, which are ignored if non-empty ac-allow parameters exist. Call signs must be separated by commas (whitespace is tolerated). You can use a wildcard (*) character at the end of a call sign to include tactical call variations, e.g. NW8L* will match NW8L, NW8L-1, NW8L-2 etc. For example:
    ac-allow = W1AW, NW8L*, KA8RYU-1
    Max length is 255 characters. Zero or more ac-allow parameters are allowed. If multiple ac-allow parameters are present then their contents are combined. The total number of call signs is limited to 512. Default: None.
  • ac-deny Specifies a list of remote station call signs which are not allowed to make ARQ connections to the local station. vARIM immediately disconnects from inbound ARQ connections from these stations, and ignores any FEC messages and queries sent by them. ac-allow parameters take precedence over ac-deny parameters, which are ignored if non-empty ac-allow parameters exist. Call signs must be separated by commas (whitespace is tolerated). You can use a wildcard (*) character at the end of a call sign to include tactical call variations, e.g. NW8L* will match NW8L, NW8L-1, NW8L-2 etc. For example:
    ac-deny = W1AW, NW8L*, KA8RYU-1
    Max length is 255 characters. Zero or more ac-deny parameters are allowed. If multiple ac-deny parameters are present then their contents are combined. The total number of call signs is limited to 512. Default: None.
  • max-file-size The maximum size of files that can be transferred in an ARQ session. This is the size after file compression. To disable access to shared files, set this to 0. Max is 32768 bytes. Default: 10000.
  • max-msg-days The maximum age, in days, for messages to be kept in the inbox, outbox and sent messages mailbox. Messages that exceed this limit are automatically purged whenever the corresponding message viewer is opened in vARIM (using the 'li', 'lo' or 'ls' commands). Set to 0 to disable the automatic message purge feature. Default: 0.
  • msg-trace-en Set to TRUE to enable message tracing, FALSE to disable it. Default: FALSE. When enabled, headers like Received: from KA8RYU by NW8L; Jan 30 2019 05:01:48 UTC are inserted into messages at the time of receipt. If the message is forwarded to another station with tracing enabled, another Received: header is added by the receiving station, and so on. In this way a record of the message's progress through a network is built up as it is forwarded from station to station (read from bottom to top).
  • dynamic-file A dynamic file definition of the form alias:command where alias is a "dummy" file name used to invoke the command command, with a colon ':' separating the two, for example:
    spwxfc:python /home/nw8l/scripts/forecast.py
    Use absolute paths to script files when vARIM is built from source and installed. Relative paths can be used for "portable" binary installations where the script files are contained in same directory as the arim executable file. Dynamic files are used to return the output of a script or system command in response to a file query. alias must be unique among any other dynamic file definitions and file names in the shared files root directory. In response to the query sq file alias, command will be executed in a shell and its output returned in the response. command can be a batch file, a script invocation like python myscript or a system command like date or uname -a. The output size in bytes is limited by the max-file-size parameter. Errors generated by dynamic file scripts are written to a file named dyn-file-error-YYYYMMDD.log in the log directory. Max length is 128 characters. NOTE: you may define no more than 16 dynamic-file parameters. Default: None.
• [log] Logging settings appear in this section.
  • debug-log Set to TRUE to enable debug logging in the default log directory, FALSE to disable it. Default: TRUE. May be overridden by the debug-log setting in a [port] section.
  • traffic-log Set to TRUE to enable traffic logging in the default log directory, FALSE to disable it. Default: TRUE. May be overridden by the traffic-log setting in a [port] section.
• [ui] User interface settings appear in this section.
  • last-time-heard Selects the timestamp format used in various views. Set to CLOCK to indicate time station was last heard, in HH:MM:SS format (either local time or UTC). Set to ELAPSED to indicate elapsed time since station last heard, in DD:HH:MM format. Default: CLOCK.
  • utc-time Selects the time zone used for timestamps in the UI and log output. Set to TRUE for UTC, and FALSE for local time. Default: TRUE.
  • font-size Sets the size of text fonts in vARIM. Values in the range 12 to 24 are practical, adjust to suit your screen resolution. Default: 14.

To print the configuration file parameters to a file for analysis, run vARIM with the -p option. For example:

arim -p dump.txt

In the file is a listing of the parameters and their values after processing, which can be helpful for troubleshooting. Any invalid parameter values will be replaced with default values, and parameters with misspelled names will be absent.

Attaching to a port

Make sure the VARA modem is running. Choose Port->Attach from the main menu and select a port:

vARIM will open a TCP connection to the modem. Initialization commands from vARIM to the modem will scroll by in the modem Command Monitor. The Port Status Line will display the number and name of the attached port.

After attaching to the modem, you can use the Port->Enable Chat Mode checkbox to enable or disable the VARA-HF chat mode feature. This is enabled by default for vARIM to take advantage of these chat mode features:

• The VARA modem listens for CQ frames
• During an ARQ session, the VARA mode reports S/N ratio measurements to vARIM when data is received
• The ARQ handover exchange is optimized for keyboard to keyboard chat

To detach from the port, choose Port->Detach from the main menu.

If you prefer to use the keyboard, press <SP> to open the command prompt. To attach, enter the att n command where n is the port number. To detach, enter the det command. To enable or disable chat mode, enter the chatmode v command where v is ON or OFF.

Rig Control/PTT

Options include VOX and serial port PTT using the DTR or RTS pins. These settings are normally controlled by the ptt-mode and ptt-device parameters in the varim.ini configuration file but can be changed on-the-fly by the operator.

To configure PTT, vARIM must be attached to a VARA modem. Choose Rig->PTT Settings... from the main menu to open the PTT Settings dialog:

Choices are:

• VOX - use transmitter VOX.
• DTR - use serial port DTR signal.
• RTS - use serial port RTS signal.

If using DTR or RTS, choose the serial port device used for PTT. If using a built in serial port on a Linux computer, the device name will have the form '/dev/ttySx' where x is a number. If using a USB-to-Serial converter, the device name will have the form '/dev/ttyUSBx' where x is a number, starting with '0'. In this case, make sure the device is plugged into your computer before making the selection. Press OK to close the dialog. Then make sure your rig is configured to use the selected PTT signal, DTR or RTS.

If vARIM cannot open the selected serial port, you'll see this error message after pressing OK:

On Linux, your user must be a member of the 'dialout' user group to access the serial port. If not, then add your user with this command: sudo adduser $(whoami) dialout and try again ('sudo' because admin privileges are needed for 'adduser'). This does not apply to Cygwin/X on Windows. Because the serial port is used only for PTT, not data, you don't need to configure other settings like baud rate, etc.

If running vARIM on Cygwin/X on Windows, follow these steps to get started:

• Plug your USB-to-Serial converter into your Windows PC.
• Open Windows Device Manager and find your COM port:
  
  In this example it's COM3, which maps to /dev/ttyS2 in Cygwin (COM4 maps to /dev/ttyS3 and so on). If in doubt, run this command: ls /dev in a Cygwin terminal. In this example you should see /dev/ttyS2 listed.
• Attach to a port, then open the PTT Settings dialog and select /dev/ttyS2 as the serial port device. If /dev/ttyUSB0 appears in the list, ignore it.

If running vARIM on Windows Subsystem for Linux (WSL), follow these steps to get started:

• First make sure you are a member of the 'dialout' user group. If not, enter this command: sudo adduser $(whoami) dialout
• Plug your USB-to-Serial converter into your Windows PC.
• Open Windows Device Manager and find your COM port:
  
  In this example it's COM3, which maps to /dev/ttyS3 in WSL (COM4 maps to /dev/ttyS4 and so on).
• Attach to a port, then open the PTT Settings dialog and select /dev/ttyS3 as the serial port device. If /dev/ttyUSB0 appears in the list, ignore it.

Generally, it's best to put PTT settings in the varim.ini configuration file so they are loaded when vARIM starts. Use these parameters in each [port] section:

• ptt-mode Selects the PTT mode. Set to VOX if hardware PTT is not used. Set to DTR or RTS if serial port hardware PTT is used. Example: ptt-mode = DTR.
• ptt-device Selects the serial port device for hardware PTT. Example: ptt-device = /dev/ttyS2.

PTT settings for each port are independent so that multiple rigs can be keyed by vARIM using different serial devices. The specified serial port is opened when vARIM attaches to a port, and it is closed when vARIM detaches from a port.

vARIM keys the transmitter in response to PTT ON and PTT OFF commands from the VARA modem. A PTT monitor protects the transmitter if communication with the VARA modem fails when the PTT state is ON and DTR or RTS are asserted. If PTT is asserted longer than 20 seconds, PTT is de-asserted and vARIM detaches from the port.

View Quick Help

Choose Help->Quick Help... from the main menu:

Here are a listing of hot keys and commands, a key to status bar indicators, and other information. Press Done to quit.

View Recent messages

Select the Recents tab:

This is a listing of headers for messages recently received. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

• Message number, most recent first.
• Sending station call sign
• Date and time
• Destination station call sign
• Size over-the-air transfer size in bytes, decimal format (before compression).
• Checksum 16-bit CRC, in hexadecimal format.
• Status flags where R means read, Y means replied to, F means forwarded, S means saved and - means flag not set.

To read a message, right-click its header line and choose Read... from the pop-up menu:

This opens the message viewer.

Press Done to quit. Shortcut: double-click a header line to read the message.

Several actions can be taken here:

• Kill - delete the message from the Inbox.
• Save - save the message to a text file.
• Reply - reply to sender. This is not available during an ARQ session if you are not connected to the station that sent the message. The message is opened for editing, after which it can be then sent (if connected to the station you are replying to) or stored in the Outbox to send later.
• Forward - forward to a station other than the sender. The message is opened for editing, after which it can be then sent (if connected to the station you are forwarding it to) or stored in the Outbox to send later.

These are shortcuts for the pop-up menu options described below.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

To save a message to a text file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To reply to a message, right-click its header line and choose Reply... from the pop-up menu:

The Reply to Message dialog box opens:

Enter your reply text. If connected, press Send to send the message. Otherwise, press Save to Outbox to store the message in the Outbox to be sent later. Press Cancel to abandon any edits and close the dialog box. During an ARQ session, the Reply... option is available only if the callsign of the sender matches the callsign of the remote station. The Use compression option is available only during an ARQ session.

To forward a message to another station, right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

If not connected, enter the call sign of the destination station. Add or edit text in the message body. If connected, press Send to send the message. If not connected, press Save to Outbox to store the message in the Outbox to be sent later. Press Cancel to abandon any edits and close the dialog box. The Use compression option is available only during an ARQ session. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

To clear the Recents view, choose View->Clear->Recents from the main menu.

View Connection History

Select the Connect History tab:

Here is a listing of connection reports resulting from both inbound and outbound ARQ sessions. The history shows a line for each session, sorted in reverse chronological order (most recent on top). Each line includes, from left to right:

• Call sign of the station that initiated the connection (source station)
• Call sign of the responding station (destination station)
• Session start date and time in format: Mon DD HH:MM:SS
• Session time duration in format: HH:MM:SS
• Number of bytes received
• Number of bytes transmitted
• Maximum bandwidth

Connections initiated by the local station (you) are printed in bold text to make them stand out. To clear the view, choose View->Clear->Connect History from the main menu.

View ARQ File History

Select the ARQ File History tab:

Here is a listing of ARQ file transfer reports. The history shows a line for each transfer, sorted in reverse chronological order (most recent on top). Each line includes, from left to right:

• Direction of the file transfer, inbound (>>) or outbound (<<)
• Call sign of the remote station
• Transfer start date and time in format: Mon DD HH:MM:SS
• Transfer time duration in format: HH:MM:SS
• Compression flag, -z if compression was invoked, or blank if not
• File size in bytes
• File payload checksum
• Average S/N ratio reported by the receiving station
• File name and path, relative to the local shared files directory

To clear the view, choose View->Clear->ARQ File History from the main menu. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.

Change the Calls Heard timestamp format

Choose View->Calls Heard from the main menu and select an option from the fly-out menu:

• Last Time Heard (LT) in HH:MM:SS format.
• Elapsed Time (ET) in DD:HH:MM format.

This affects the timestamps shown in the Calls Heard list.

Shortcut: Press <CTRL-T> to toggle the timestamp format.

Clear the new message and file counters

Choose View->Clear->New Msg and File Counters from the main menu. This clears both counters, which are located at the end of the Port Status Line.

The counters increment when a new message or file is received. They are helpful as indicators of activity during periods of unattended operation. New messages are listed in the convenient Recent Messages view. New message and file counter values are lost when the program is closed.

Shortcut: Press <CTRL-N> to clear the new message and file counters.

Press <ESC> to abort send or receive

Sometimes it's necessary to abort a transmission in progress or halt a receive operation instead of waiting for it to time out. To do this press the <ESC> key to cancel the ARQ session and return vARIM to the idle state. This is a unilateral action resulting in a "dirty disconnect". Use <CTRL-X> to attempt a clean disconnect before resorting to <ESC>.

Using the command line

Open the program and press the spacebar to open the command prompt (or click it with the mouse), and enter a command.

Commands fall into these general categories:

• Modem commands These are prefixed with the '!' character and are sent directly to the VARA modem e.g. !LISTEN OFF Commands sent directly to the VARA modem are case sensitive, e.g. "LISTEN" not "listen".
• ARQ chat During an ARQ session text entered here is sent out over the air to the connected station.
• vARIM commands For brevity, typing the first 4 letters of a command is usually enough for it to be recognized.
  • Port control commands
    • att nbr Attach to a port. nbr indicates the port number.
    • det Detach from the currently attached port.
    • mycall call Set the station's call sign to call.
    • gridsq loc Set the grid square locator to loc. This is the response to the gridsq query from another station.
    • pname name Set the port name to name. This is the response to the pname from another station.
    • listen ON or OFF Control whether the modem listens for ARQ connection requests from other stations. Set to ON to enable listening for ARQ requests or OFF to disable listening. Default: ON.
    • chatmode Control whether the modem listens for CQ frames and sends S/N reports to vARIM when receiving data from the remote station during an ARQ session. Set to ON to enable or OFF to disable chat mode. Default: ON.
    • cq [bw] Transmit a CQ frame. bw is an optional connection bandwidth in Hz. It can be either 500, 2300 or 2750. This is the ARQ bandwith advertised in the VARA CQ frame. If bw is specified, the modem's ARQ bandwidth setting is immediately updated with that value.
    • benable TRUE or FALSE Enable or disable the CQ beacon. Set to TRUE to enable beaconing and FALSE to disable it.
    • btime tm Set the CQ beacon interval time where tm is time in minutes. Range is 15 to 999.
    • blimit tm Set the CQ beacon time limit where tm is time in hours. Beacons are automatically disabled when the time limit is reached. Range is 1 to 48.
    • reloadp Reloads settings from the [port] sections of the varim.ini configuration file. This command can be executed only when not attached to a VARA modem.
  • ARQ session commands
    • conn call [bw] Initiate ARQ connection with remote station call. bw is an optional connection bandwidth in Hz. It can be either 500, 2300 or 2750.
    • arqbw bw Set the ARQ connection bandwidth in Hz. bw is a specifier which must be one of: 500, 2300 or 2750.
    • arqto nbr Set the ARQ session inactivity timeout. nbr is the time in seconds, in the range 30 to 600.
  • Messaging commands at main prompt
    • cm call Compose message for station call. The message composer opens for input. When done the message is stored in the outbox for sending later.
  • ARQ session messaging commands at main prompt
    • /sm [-z] [msg] Send message to the connected station. The -z option compresses the message to minimize transfer time. The message text may follow, but if not given then the message composer opens for input.
    • /mlist Return a list of messages in the remote station's outbox that are addressed to your station. Requires that your station be authenticated with the remote station. If not, then the remote station will respond with an authentication challenge.
    • /mget [-z] [nbr] Download messages addressed to your station from the remote station's outbox to your inbox. The -z option compresses the message to minimize transfer time. nbr optionally specifies the maximum number of messages to download. The default is 10. Requires that your station be authenticated with the remote station. If not, then the remote station will respond with an authentication challenge.
  • ARQ session query commands at main prompt
    • /gridsq Query the Maidenhead locator (grid square) of the connected station.
    • /heard Query the calls heard list of the connected station.
    • /info Query the info text of the connected station.
    • /pname Query the port name of the connected station.
    • /version Query the vARIM version running on the connected station.
    • /snr Query the running average S/N ratio calculated by vARIM at the remote station as data frames are received. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
    • /csnr Query the current S/N ratio. This is the last raw S/N value reported by the VARA modem to vARIM at the remote station. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
  • ARQ session file transfer commands at main prompt
    • /flist [dir] Return a list of shared files and directories. dir is an optional directory path, relative to the shared files root directory, e.g. contests/2016/FOBB. If dir is not given, then the the shared files root directory is listed; otherwise the specified directory is listed. By default only files in the shared files root directory and dynamic files are listed. Subdirectories are not listed unless they are made visible by an add-files-dir configuration file parameter. Access-controlled subdirectories defined by the ac-files-dir configuration file parameter are indicated with the ! (bang) character like this: !DIR.
    • /flget [-z] [dir] Downloads a list of shared files and directories, then displays it in the remote shared files viewer. The -z option compresses the file to minimize transfer time. dir is an optional directory path, relative to the shared files root directory, e.g. contests/2016/FOBB. If dir is not given, then the the shared files root directory is listed; otherwise the specified directory is listed. By default only files in the shared files root directory and dynamic files are listed. Subdirectories are not listed unless they are made visible by an add-files-dir configuration file parameter. Access-controlled subdirectories defined by the ac-files-dir configuration file parameter are indicated with the ! (bang) character like this: !DIR. The viewer shows a numbered list of files and directories, making it easy to read or download files without typing in lengthy file names. Learn more about using /flget here.
    • /file fn Print a file to the Traffic Monitor view. fn is the name of a file in the shared files directory, or a file path relative to it, e.g. contests/2016/FOBB.log
    • /fget [-z] fn [> dir] Download a file to the local station. The -z option compresses the file to minimize transfer time. fn is the name of a file in the remote station's shared files directory, or a file path relative to it, e.g. contests/2016/FOBB.log. The optional dir parameter specifies the destination directory at the local station, relative to the shared files root directory, e.g. contests/2016. The destination directory must made visible by an add-files-dir configuration file parameter at the local station. If dir is not specified, the file is stored in the download subdirectory in the local station's shared files root directory.
    • /fput [-z] fn [> dir] Upload a file to the remote station. The -z option compresses the file to minimize transfer time. fn is the name of a file in the local station's shared files directory, or a file path relative to it, e.g. contests/2016/FOBB.log. The optional dir parameter specifies the destination directory at the remote station, relative to the shared files root directory, e.g. contests/2016. If dir is not specified, the file is stored in the download subdirectory in the remote station's shared files root directory. The destination directory must made visible by an add-files-dir configuration file parameter at the remote station.
  • Digest authentication commands
    • /auth Manually trigger the mutual authentication process.
    • passwd client-call server-call password Create or change a password in the local password digest file. client-call is the call sign of the client station. This is a station whose operator will connect to another station, the server station, and use the password to authenticate when challenged. server-call is the call sign of the port at the server station to which the client station connects. This is the call sign set by the mycall parameter in the corresponding [port] section in the varim.ini configuration file at the server station. password is the password, which may include any printable character, and has a maximum length of 32 characters. Note: passwords are case sensitive!
    • delpass client-call server-call Delete a password in the local password digest file. client-call is the call sign of the client station, and server-call is the call sign of the server station.
  • Housekeeping commands
    • clrmon Clear the Traffic Monitor view
    • clrheard Clear the Calls Heard view
    • clrrec Clear the Recent Messages view
    • clrconn Clear the Connection History view
    • clrfile Clear the ARQ File History view
    • clrcntrs Clear the New File and New Message counters

Basic line editing features are available on the command prompt. The left and right arrow keys, HOME, END, DEL and backspace keys work as expected. This makes it easy to correct mistakes in typing, whether a entering a command or composing a message.

The command prompt has a history buffer which holds the last 15 unique commands entered. Use the UP and DOWN keys to browse command history when you want to reuse a previously sent command.

Sending commands to the VARA modem

A port must be attached. Press the spacebar to open the command prompt.

Prefix the command with the '!' character. Press ENTER to send the command to the modem. The command trace will appear in the modem command view, followed by the modem's response. To set a parameter, follow the command with the parameter, e.g. !LISTEN OFF. Complete control over the modem is available using this interface. VARA modem commands are documented in VARA Protocol Native TNC Commands by EA5HVK, contained in the VARA Documentation download at EA5HVK website.

Remote station access control

Access to the local station can be controlled using either a "whitelist" and "blacklist" (but not both). If access is denied to a remote station, it cannot establish an ARQ connection to the local station.

• Whitelist Defined by one or more ac-allow parameters in the [arim] section of the varim.ini configuration file. Only stations whose call signs appear in the list are allowed to make ARQ connections to the local station. vARIM immediately disconnects from inbound ARQ connections from all other stations.
• Blacklist Defined by one or more ac-deny parameters in the [arim] section of the varim.ini configuration file. Stations whose call signs appear in the list are not allowed to make ARQ connections to the local station. vARIM immediately disconnects from inbound ARQ connections from the listed stations.

A non-empty whitelist takes precedence over the blacklist, which is ignored in that case. If the whitelist is empty or doesn't exist, then the blacklist takes effect. If neither list exists then all remote stations are granted access to the remote station by default.

Composing a message (to outbox)

Whether or not connected to another station, messages can be composed and stored in the message outbox. Choose Message->Compose... from the main menu to open the Compose Message dialog box:

If not connected to another station, enter the call sign of the destination station or choose a call sign from the drop-down list (the last 5 previously addressed stations appear here for easy recall). Enter the message into the text editor window, or paste text copied from another application into the text editor. Press Save to Outbox to save the message.

The Use compression option is available only during an ARQ session. In that case the To station: field is automatically populated with the call sign of the connected station.

Enter the message into the text editor window or paste text copied from another application into the text editor. Press Save to Outbox to save the message, or Send to transmit it to the connected station.

Press Cancel to cancel the message.

ARQ: Connecting to a remote station

vARIM must be attached to a port and the RF channel must not be busy. Choose ARQ->Connect... from the main menu to open the ARQ Connect dialog box.

Enter the Call sign of the target station or choose a call sign from the drop-down list (the last 5 previously called stations appear here for easy recall). Choose the desired ARQ bandwidth from the drop-down list, either 500, 2300 or 2750 Hz. Press OK to start. Connect requests and responses are displayed in the monitor view.

If the RF channel is busy, vARIM won't send the connection request, and an error message will be shown on the status bar.

When the connection is made, text entered at the command prompt is sent directly to the remote station rather than processed as an ARIM command. The line editing and history recall features of the command prompt work as usual but the '!' prefix won't work to send commands directly to the modem.

All text sent and received will be displayed on the Traffic Monitor, and the status bar will show the call sign of the remote station, the connection bandwidth and the current ARIM protocol state.

The local files, message inbox, message outbox and sent messages viewers work as usual during an ARQ session. Files can be uploaded to the remote station from the local files viewer. Previously composed messages can be sent to the remote station from the message outbox viewer, and messages can be forwarded to the remote station from the message inbox and sent messages viewers.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the conn call [bw] command where call is the call sign of the target station and bw is an optional ARQ bandwidth in Hz, either 500, 2300 or 2750.

To disconnect, press <CTRL-X>, choose ARQ->Disconnect from the main menu, or enter the special command '/dis' at the command prompt and press ENTER.

You'll be prompted to confirm:

Press Yes and a clean disconnect will be attempted.

ARQ behavior is controlled by these parameters in the [port] section of the varim.ini configuration file:

• listen Control whether the modem listens for ARQ connection requests from other stations. Set to ON to enable listening for ARQ requests or OFF to disable listening. Default: ON.
• chat-mode Control whether the modem listens for CQ frames and sends S/N reports to vARIM when receiving data from the remote station during an ARQ session. Set to ON to enable or OFF to disable chat mode. Default: ON. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
• arq-bandwidth The ARQ connection bandwidth in Hz, either 500, 2300 or 2750. Default: 500.
• arq-timeout Set the inactivity timeout for ARQ connections, in seconds. The value must be in the range 30 to 600. Default: 120.
• arq-sendcr Control whether CRLF line endings are sent in ARQ mode, instead of Unix style LF endings. Default: TRUE.

These parameters can also be modified on-the-fly from the vARIM command prompt by the operator.

ARQ: Sending messages to the remote station

When connected to a vARIM station, single-line messages can be sent using the /sm [-z][msg] command where the -z option invokes compression, and msg is the message text. This is convenient when the message is short and you wish to bypass the message composer. Press the spacebar to open the command prompt and enter the command like this:

The remote station saves the message to its inbox and returns an /OK response to confirm receipt. If S/N reporting is enabled at the remote station, the /OK response will include an average S/N ratio report for the message transfer. A copy of the message will be stored in your sent messages mailbox.

For longer, multi-line messages, choose Message->Compose Message... from the main menu to open the Compose Message dialog box:

Enter the message into the text editor window, or paste text copied from another application into the text editor. Check Use compression if you wish to have the message compressed to reduce transfer time. Press Send to send the message to the connected station.

The remote station saves the message to its inbox and returns an /OK response to confirm receipt. If S/N reporting is enabled at the remote station, the /OK response will include an average S/N ratio report for the message transfer. A copy of the message will be stored in your sent messages mailbox.

While the upload is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the upload, press CTRL-X to close the ARQ connection.

If the remote vARIM station encounters an error saving the message, it returns an /ERROR response and the message is discarded.

Existing messages in a local mailbox can also be sent to the remote station from one of the message view tabs.

Previously composed messages stored in the outbox can be sent to the remote station. Select the Msg Outbox tab:

Right-click on the desired message header and choose Send... from the pop-up menu. This opens the Send Message dialog box:

You can make last minute changes if you like. Check Use compression if you wish to compress the message to reduce transfer time. Press OK to send the message to the connected station. This is a more efficient method than composing the messages during the ARQ session itself.

Messages in the inbox can be forwarded to the remote station in the same manner. Select the Msg Inbox tab and right-click on the desired message header. Choose Forward... from the pop-up menu.

Messages in the sent messages mailbox can also be forwarded to the remote station. Select the Sent Messages tab and right-click on the desired message header. Choose Forward... from the pop-up menu.

If the remote vARIM station encounters an error saving the message, it returns an /ERROR response and the message is discarded.

ARQ: Downloading messages from the remote station

In an authenticated ARQ session, you can retrieve messages addressed to your station that are queued in the remote station's outbox. This is useful if you are on the air only intermittently; the operator at the remote station can compose a message when convenient, leaving it in the outbox for you to download later.

To list your messages, choose ARQ->Get My Message Listing from the main menu.

The remote station responds:

In this example, the command triggers the mutual authentication process automatically. After that, the listing is received. The messages are listed in chronological order (oldest first).

To download the listed messages, choose ARQ->Get My Messages... from the main menu. The Get My Messages from Remote Station dialog box opens:

Select the maximum number of messages to download, and check Use compression if you wish to compress the messages to reduce transfer time. Press OK to start the message download to the local station.

The progress of the download is reported as each message is received. As each message is received, the receiving station stores the message in its inbox and sends a /OK response to confirm receipt. If S/N reporting is enabled at the receiving station, the /OK response will include an average S/N ratio report for the message transfer. The sending station then deletes the message from its outbox.

If the either station encounters an error, it sends an /ERROR response to the other and the download is canceled. In that case the message is not deleted from the outbox at the sending station.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the download, press CTRL-X to close the ARQ connection.

ARQ: Listing shared files on the remote station

When connected to a vARIM station, choose ARQ->Get File Listing... from the main menu to download a listing of shared files it offers. The Get File Listing from Remote Station dialog box opens:

Enter the path of the remote directory to list or leave it blank for a listing of the root shared files directory. Check Use compression if you wish to compress the listing to reduce transfer time. Press OK to start the file listing download.

When the download is complete an /OK response is sent by the local station to confirm receipt. If S/N reporting is enabled at the local station, the /OK response will include an average S/N ratio report for the file transfer. While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the download, press CTRL-X to close the ARQ connection.

When the download is finished the file listing appears in the Remote Files tab:

The contents of the directory are listed, one to a line, and the remote file path is shown at the bottom of the view. For files, the name and size in bytes are shown. For subdirectories, the name is shown. Access-controlled subdirectories are indicated with the ! (bang) character like this: !DIR.

To read a file, right-click on its listing and choose Read from the pop-up menu.

The file will be downloaded and printed to the Traffic Monitor view:

To download a file, right-click on its listing and choose Get... from the pop-up menu.

The Get Remote File dialox box opens:

Check Use compression if you wish to compress the listing to reduce transfer time. To download the file to a directory other than the default download directory, enter its path in the To local directory: field or click the browse button and navigate to the desired directory in the Select Local Destination Directory dialog box. The destination directory must made visible by an add-files-dir configuration file parameter at the local station. If no destination directory is specified, the file is stored in the download subdirectory in the local station's shared files root directory. Press OK to get the file.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the download, press CTRL-X to close the ARQ connection.

To list a subdirectory, right-click on its listing and choose Open Directory... from the pop-up menu.

The Open Remote Directory dialog box opens:

Check Use compression if you wish to compress the listing to reduce transfer time. Press OK to start the file listing download.

The directory listing will be downloaded and displayed in the Remote Files tab, replacing the previous contents.

The Remote Files tab is automatically cleared when the ARQ session is closed.

The mutual authentication process will be triggered automatically if a access-controlled directory is listed when the session is not yet authenticated.

ARQ: Reading files from the remote station

When connected to a vARIM station the shared text files it offers can be read in the Traffic Monitor view. Only text files and dynamic files with text output can be printed to the screen.

To read a file, choose ARQ->Read File... from the main menu to open the Read File from Remote Station dialog box:

Enter the name of the file, which can include a path to a subdirectory under the root shared files directory on the remote station. In this example the file test.txt is known to be located in the directory net. Press OK to start reading.

The text is printed the the Traffic Monitor view line by line as it is received.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

ARQ: Downloading files from the remote station

When connected to a vARIM station any shared files it offers can be downloaded. Both text and binary file types can be transferred over the ARQ connection. A compression option can be invoked to reduce transfer time for many file types, and you can specify a destination directory at the local station other than the default.

To download a file, choose ARQ->Get File... from the main menu to open the Get File from Remote Station dialog box:

Enter the name of the file and check Use compression if you wish to compress the file to reduce transfer time. To download the file to a directory other than the default download directory, enter its path in the To local directory: field or click the browse button and navigate to the desired directory in the Select Local Destination Directory dialog box. The destination directory must made visible by an add-files-dir configuration file parameter at the local station. If no destination directory is specified, the file is stored in the download subdirectory in the local station's shared files root directory. Press OK to start the download.

The progress of the download is reported as each data frame is received. When it's complete an /OK response is sent to the remote station to confirm receipt. If S/N reporting is enabled at the local station, the /OK response will include an average S/N ratio report for the file transfer.

If the remote ARIM station encounters an error sending the file, it returns an /ERROR response and the download is canceled.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

While the download is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the download, press CTRL-X to close the ARQ connection.

ARQ: Uploading files to the remote station

When connected to a vARIM station local files can be uploaded to the remote station. Both text and binary file types can be transferred over the ARQ connection. A compression option can be invoked to reduce transfer time for many file types, and you can specify a destination directory at the remote station other than the default.

To upload a file, choose ARQ->Send File... from the main menu to open the Send File to Remote Station dialog box:

Enter the name of the file or click the browse button and select the file in the Select File to Send dialog box. Check Use compression if you wish to compress the listing to reduce transfer time. To upload the file to a directory other than the default download directory at the remote station, enter its path in the To remote directory: field This path must be relative to the shared files root directory, e.g. contests/2016 and must made visible by an add-files-dir configuration file parameter at the remote station. Press OK to start the upload.

The progress of the upload is reported as each data frame is sent. When it's complete an /OK response is received from the remote station to confirm the file was saved. If S/N reporting is enabled at the remote station, the /OK response will include an average S/N ratio report for the file transfer.

If the remote vARIM station encounters an error receiving the file, it returns an /ERROR response and the upload is canceled.

The mutual authentication process will be triggered automatically if a file in an access-controlled directory is specified.

While the upload is in progress no text or commands are accepted from the command prompt. This condition is indicated by the yellow background color in the ARIM status indicator:

To cancel the upload, press CTRL-X to close the ARQ connection.

ARQ: Session Authentication

The optional Mutual Authentication feature provides a way to verify the identities of the stations in an ARQ session. This works by making each station prove to the other that it possesses a shared secret (password) known only to the two stations involved. This is done using a Digest Access Authentication scheme very similar to that specified in RFC 2069 with the exception that the MD5 hash function is replaced by the more modern and secure Blake2 hash function. The exchange of proofs is accomplished without sending the password itself over the air. The process is automatic and requires no operator intervention. This feature can be used to:

• verify the identity of the station you connect to in ARQ mode
• grant another station access to controlled resources located on your station

Once an ARQ connection is established, the operator can invoke the mutual authentication process pre-emptively. If it succeeds, the identity of the remote station is proven and the operator can read, upload or download files with confidence. If it fails, because one station or the other doesn't know the shared secret (password), the operator is presented with a warning message and given the choice of either continuing or terminating the ARQ session.

For example, to authenticate pre-emptively, choose ARQ->Authenticate from the main menu.

The remote station sends a challenge which is the first of 3 messages (A1, A2 and A3) exchanged during the authentication process.

If the remote station cannot authenticate your station, you are alerted and asked if you want to disconnect:

Likewise, if your station cannot authenticate the remote station, you are alerted and asked if you want to disconnect:

In either case the problem is likely to be missing or incorrect password digest file entries.

If you prefer to use the keyboard, press <SP> to open the command prompt and enter the /auth command to authenticate.

The authentication challenge/response protocol

1. The process begines when the operator at one station (the client), connects to another station (the server) and:
   • attempts to access a controlled resource for the first time
   or:
   • invokes authentication pre-emptively
2. At the server station, vARIM receives the command and recognizes that authentication is required. It searches its password digest file for an entry with the client station's call sign as the client and its own call sign as the server. If it cannot find such an entry, it responds with /EAUTH and the operator at the client station is informed that authentication has failed. If vARIM does find such an entry, it responds with an authentication challenge in the form of the /A1 command. The challenge includes an opaque nonce, a token whose content it controls and which must be incorporated into the response made by the client station.
3. At the client station, vARIM receives the /A1 command. It searches its password digest file for an entry with its own call sign as the client and the server station's call sign as the server. If it cannot find such an entry, it responds with '/EAUTH' and the operator at the client station is informed that authentication has failed. If the needed entry is found, vARIM computes a response token which proves that it knows the shared secret. The response is:
   • H(HA1:nonce:HA2)
   where:
   • H(x) is the Blake2 hash of an array of data 'x'.
   • HA1 is H(client_call:server_call:password), the password hash token stored in the password digest file at the client station.
   • nonce is the token sent by the challenger to influence the response hash value.
   • HA2 is H(method:path) where method' is FPUT, FGET, FLIST or FILE and path is the directory or file path referenced by the command.
   Thus the response to each challenge is unique, in a way dependent on the nature of the request and the nonce issued by the challenger. This makes "replay" attacks difficult to mount and recovery of the password from the response token computationally infeasible. vARIM sends the response token plus a challenge nonce to the server station in the form of the /A2 command.
4. At the server station, vARIM receives the /A2 command and checks the challenge response token it contains. It does this by computing the response token it expects using the password digest token (HA1) stored in the password digest file it owns. It compares this with the response token received from the client station. If they don't match, then the client station must not have the same password digest that vARIM has stored locally. In this case vARIM will send /EAUTH to the client station where the operator will be informed that authentication has failed. If they match, then the client station has proven its authenticity and vARIM will send a response to the challenge contained in the /A2 command. As before, this is computed as H(HA1:nonce:HA2), using the challenge nonce received from the client station. It sends this response to the client station in the form of the /A3 command.
5. At the client station, vARIM receives the /A3 command and checks the challenge response token it contains. It does this by computing the response token it expects using the password digest token (HA1) stored in the password digest file it owns. It compares this with the response token received from the server station. If they don't match, the server station must not have the same password digest that vARIM has stored locally. In this case vARIM will inform the operator that authentication has failed. If they match, then the server station has proven its authenticity and vARIM re-sends the command that triggered the process, unless it was the /auth command. In that case there is no work to do, so vARIM simply sends the /OK response to signal that the mutual authentication is complete.

To strike a reasonable balance between security and the "air time" cost of the challenge/response data exchanges, challenge nonces contain 6 bytes of data and the Blake2 response hash is truncated to 21 bytes, or 168 bits (big enough for excellent collision resistance). These are sent in base64 encoded form making the over-the-air sizes 8 and 28 bytes respectively.

ARQ: File access control

Shared files directories at a station can be designated as access-controlled with the ac-files-dir parameter in the varim.ini configuration file. These resources are available only to stations that successfully authenticate themselves in an ARQ session. By default, the authentication process is triggered automatically on the first attempt by a station to access a controlled resource. Here is an example:

The operator at NW8L connects to KA8RYU and attempts to download a access-controlled file, admin/contact-list.txt. This triggers an authentication challenge from KA8RYU in the form of the /A1 command. The mutual authentication succeeds, so the download command /FGET is automatically repeated and the file is downloaded.

If mutual authentication succeeds, subsequent accesses of controlled resources on the remote station proceed normally.

Alternatively, the operator at NW8L can send the authenticate the remote station pre-emptively before attempting to access controlled directories and their contents. In this case, if station KA8RYU is unable to find a password digest file entry for NW8L, it sends the /EAUTH response and the operator at NW8L is alerted:

Otherwise the authentication process proceeds as usual.

Note: shared files directories defined by add-files-dir parameters in the varim.ini configuration file are not access-controlled. These are accessible by any station. Likewise, the root shared files directory is always accessible by any station for file listing, uploads and downloads.

ARQ: Password management

Passwords are created within vARIM and stored in digest ("hashed") form in a file. Passwords are hashed with a salt (the call signs of the corresponding stations), so that any given password results in unique hash for different call sign pairs. This hash is identical to the HA1 term used in the digest authentication scheme, so it can be read out of the password digest file when needed, making it unnecessary to store the original password. Mathematically, the Blake2 hash function is a strong one way function; it is computationally infeasible to recover the password from the hash. Because the password hash is stored in a file the authentication process can operate without operator intervention; there's no need to remember and enter the password each time.

In the context of an ARQ session, the term client refers to the station where an operator triggers the authentication process by:

• sending the /auth command to the other station
• attempting to access a controlled resource at the other when the ARQ session is not yet authenticated.

When this happens the other station assumes the role of server and responds with an authentication challenge. These definitions imply that an operator is always present at the client station, but not at the server station, which is assumed to be operating automatically. However, once an ARQ connection is established between two stations, the operator at either end can seize the client role by being the first to trigger the mutual authentication process.

Let's assume that client call sign is KA8RYU, and the server call sign is NW8L. Choose ARQ->Create or Change Auth Password... from the main menu to open the Create or Change Auth Password dialog box. Enter the call sign of the client station, the call sign of the server station, and the password:

Press OK to store the password.

The operation will be confirmed.

This command must be executed at both stations to store the password digest on each. If this is done, KA8RYU can connect to NW8L and successfully authenticate if challenged. However, this doesn't mean that the reverse is true: NW8L can't connect to KA8RYU and do the same. To make this possible the process must be repeated at each station with NW8L specified as the client, and KA8RYU as the server:

Now either station can connect to the other and play the role of client to the other station's role of server in the authentication process. Note that a different password is used; this is the best practice. If we read the arim-digest password digest file at either station by choosing File->View Auth Password File... from the main menu we see the newly created password entries:

There are two entries, one for KA8RYU as client and NW8L as server, and another for NW8L as client and KA8RYU as server. This allows both one-way and two-way relationships to be defined. For instance, a station serving as a document repository can issue passwords to multiple stations who connect to it as clients and access the controlled files it offers. However, no such password is issued to the repository station by the client stations; it cannot connect to any of them in the client role and authenticate for the purpose of accessing any controlled resources they publish.

To protect against accidental disclosure of password digest file contents, any file named 'arim-digest', or variations like 'arim-digest.bak', no matter where located in the file system, are protected against access by a remote station. Avoid easy-to-guess passwords, and never include the call signs of the client or server stations in the password. While the base64 encoded Blake2 digest (HA1) may look quite random, it contains only as much entropy as the original password, so choose passwords well. Note: passwords are case sensitive!

Choose ARQ->Delete Auth Password... from the main menu to delete a password digest from the arim-digest file. The Delete Auth Password dialog box opens:

Let's assume we want to delete the password digest for client-call KA8RYU, and server-call NW8L. Enter these calls and press OK You will be prompted to confirm the deletion:

Press Yes to delete the password digest from the file.

ARQ: Sending queries to the remote station

When connected to a vARIM station, the following queries may be sent to the remote station:

• /VERSION Return the software version numbers for vARIM.
• /GRIDSQ Return the Maidenhead locator (grid square).
• /INFO Return the info statement.
• /PNAME Return the port name.
• /HEARD Return the calls heard list.
• /SNR Query the running average S/N ratio calculated by vARIM at the remote station as data frames are received. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
• /CSNR Query the current S/N ratio. This is the last raw S/N value reported by the VARA modem to vARIM at the remote station. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
• /FLIST Return a list of shared files and directories. An optional directory path can be specified, relative to the shared files root directory, e.g. contests/2016/FOBB. If this is left blank, then the the shared files root directory is listed; otherwise the specified directory is listed. By default only files in the shared files root directory and dynamic files are listed. Subdirectories are not listed unless they are made visible by an add-files-dir configuration file parameter. Access-controlled subdirectories defined by the ac-files-dir configuration file parameter are indicated with the ! (bang) character like this: !DIR.
• /FILE Print a file to the Traffic Monitor view. Enter the name of the file in the shared files root directory at the remote station, or a file path relative to it, e.g. contests/2016/FOBB.log.

Choose ARQ->Send Query... from the main menu.

Select the desired query and press OK. Here we see the some queries and responses:

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter one of the commands listed above, for example:

• /version
• /snr
• /flist
• /flist logs/2019
• /file logs/2019/may.txt

These are not case sensitive so /VERSION and /version will both work.

CQ: Sending and receiving CQ frames

vARIM must be attached to a port and the RF channel must not be busy. Choose CQ->Send CQ... from the main menu to open the Send CQ dialog box.

Choose the desired ARQ bandwidth from the drop-down list, either 500, 2300 or 2750 Hz. The ARQ bandwidth setting is included in CQ frames as a hint for remote operators. Press OK to start.

If the RF channel is busy, vARIM won't send the CQ frame, and an error message will be shown on the status bar.

If you prefer to use the keyboard, press <SP> to open the command prompt. Enter the cq [bw] command where bw is an optional ARQ bandwidth in Hz, either 500, 2300 or 2750.

Outbound and inbound CQ frames are displayed in the monitor view. When CQ frames are received, the station's callsign also appears in the Calls Heard List. To initiate an ARQ session with a station in the list, right-click on the call sign and choose Connect.. from the pop-up menu:

To send a message to a station in the list, right-click on the call sign and choose Send Message... from the pop-up menu. When not connected the message is stored in the message outbox.

CQ behavior is controlled by these parameters in the [port] section of the varim.ini configuration file:

• chat-mode Control whether the modem listens for CQ frames and sends S/N reports to vARIM when receiving data from the remote station during an ARQ session. Set to ON to enable or OFF to disable chat mode. Default: ON. The S/N reporting feature in VARA modem v4.5.5 and higher works only when chat-mode is set to ON.
• arq-bandwidth The ARQ connection bandwidth in Hz, either 500, 2300 or 2750. Default: 500.

These parameters can also be modified on-the-fly from the vARIM command prompt by the operator. Generally, it's best to use the LISTEN button to enable or disable listening for CQ frames and ARQ connection requests.

CQ: Beaconing

VARA CQ frames can be used as a beacon, automatically transmitted at time intervals set by the operator. Beacons are sent only when vARIM is attached to a port, no ARQ session is in progress and the RF channel is not busy. Beaconing is time limited. Once enabled, beacons are automatically disabled after the time limit set by the operator is reached. To view or change beacon settings, choose CQ->CQ Beacon... from the main menu to open the CQ Beacon dialog box:

Click the Enable beacon checkbox to enable or disable beaconing. Adjust Beacon repeat time (mins) to set the repeat time interval in minutes. The minimum is 15 minutes and the maximum is 999 minutes. Adjust Beacon time limit (hrs) to set the time limit in hours. The minimum is 1 hour and the maximum is 48 hours.

When beaconing is enabled and no ARQ connection is active, a countdown timer is shown in the modem status section of the status bar:

This shows the time remaining to the next beacon transmission in HH:MM:SS format.

• If time remaining is less than 1 minute, it's shown on a magenta background.
• If time remaining is less than 5 minutes, it's shown on a yellow background.
• If time remaining is 5 minutes or more, it's shown on the normal gray background.

When a beacon is sent, a trace is printed to the Traffic Monitor. If the RF channel is busy, vARIM waits for 2 minutes and then tries to send the beacon again, but only once. If the second attempt fails then vARIM will give up and reset the beacon timer to the current beacon-time value.

CQ beaconing behavior is controlled by these parameters in the [port] section of the varim.ini configuration file:

• beacon-enable Set to TRUE to enable CQ beaconing, FALSE to disable it. Default: FALSE.
• beacon-time The CQ beacon interval time in minutes. Range is 15 to 999. Default: 60.
• beacon-time-limit The CQ beacon time limit in hours. Beacons are automatically disabled when the time limit is reached. Range is 1 to 48. Default: 24.

These parameters can also be modified on-the-fly from the vARIM command prompt by the operator.

Working with the message inbox

Select the Msg Inbox tab.

This is a listing of headers for messages received. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

• Message number, most recent first.
• Sending station call sign
• Date and time
• Destination station call sign
• Size over-the-air transfer size in bytes, decimal format (before compression).
• Checksum 16-bit CRC, in hexadecimal format.
• Status flags where R means read, Y means replied to, F means forwarded, S means saved and - means flag not set.

To read a message, right-click its header line and choose Read... from the pop-up menu:

This opens the message viewer.

Press Done to quit. Shortcut: double-click a header line to read the message.

Several actions can be taken here:

• Kill - delete the message from the Inbox.
• Save - save the message to a text file.
• Reply - reply to sender. The message is opened for editing, after which it can be then sent (during an ARQ session) or stored in the Outbox to send later.
• Forward - forward to a station other than the sender. The message is opened for editing, after which it can be then sent (during an ARQ session) or stored in the Outbox to send later.

These are shortcuts for the pop-up menu options described below.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

To save a message to a text file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To reply to a message, right-click its header line and choose Reply... from the pop-up menu:

The Reply to Message dialog box opens:

Enter your reply text. If connected, press Send to send the message. Otherwise, press Save to Outbox to store the message in the Outbox to be sent later. Press Cancel to abandon any edits and close the dialog box. During an ARQ session, the Reply... option is available only if the callsign of the sender matches the callsign of the remote station. The Use compression option is available only during an ARQ session.

To forward a message to another station, right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

If not connected, enter the call sign of the destination station. Add or edit text in the message body. If connected, press Send to send the message. If not connected, press Save to Outbox to store the message in the Outbox to be sent later. Press Cancel to abandon any edits and close the dialog box. The Use compression option is available only during an ARQ session. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Working with the message outbox

Select the Msg Outbox tab.

This is a listing of headers for outbound messages ready to be sent. Previously composed messages and messages saved after a failed send operation are stored here. They are numbered in reverse chronological order (most recent first). Headers contain the following information, from left to right:

• Message number, most recent first.
• Sending station call sign
• Date and time
• Destination station call sign
• Size over-the-air transfer size in bytes, decimal format (before compression).
• Checksum 16-bit CRC, in hexadecimal format.
• Status flags where R means read, Y means replied to, F means forwarded, S means saved and - means flag not set.

To read a message, right-click its header line and choose Read... from the pop-up menu:

This opens the message viewer.

Press Done to quit. Shortcut: double-click a header line to read the message.

Several actions can be taken here:

• Kill - delete the message from the Inbox.
• Save - save the message to a text file.
• Send - send the message (disabled if not connected to a port). The message is opened for editing, after which it can be then sent (during an ARQ session) or stored in the Outbox to send later.

These are shortcuts for the pop-up menu options described below.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

To save a message to a text file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

During an ARQ session, you can send a message in the outbox to another station. Right-click its header line and choose Send... from the pop-up menu. The Send Message dialog box opens:

You can edit the message if needed. Press OK to send the message. Press Cancel to abandon any edits and close the dialog box. The Use compression option is only available in ARQ mode. In that case the message is sent to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Working with sent messages

Select the Sent Messages tab.

This is a listing of headers for messages previously sent. Headers contain the following information, from left to right:

• Message number, most recent first.
• Sending station call sign
• Date and time
• Destination station call sign
• Size over-the-air transfer size in bytes, decimal format (before compression).
• Checksum 16-bit CRC, in hexadecimal format.
• Status flags where R means read, Y means replied to, F means forwarded, S means saved and - means flag not set.

To read a message, right-click its header line and choose Read... from the pop-up menu:

This opens the message viewer.

Press Done to quit. Shortcut: double-click a header line to read the message.

Several actions can be taken here:

• Kill - delete the message from the Inbox.
• Save - save the message to a text file.
• Forward - forward to a station other than the sender. The message is opened for editing, after which it can be then sent (during an ARQ session) or stored in the Outbox to send later.

These are shortcuts for the pop-up menu options described below.

To kill a message, right-click its header line and choose Kill from the pop-up menu. The message is deleted from the Inbox.

To save a message to a disk file, right-click on its header line and choose Save... from the pop-up menu. The Save Message dialog box opens:

Navigate to the desired directory, enter a meaningful file name, and press OK to save.

To forward a message to another station, right-click its header line and choose Forward... from the pop-up menu. The Forward Message dialog box opens:

If not connected, enter the call sign of the destination station. Add or edit text in the message body. If connected, press Send to send the message. If not connected, press Save to Outbox to store the message in the Outbox to be sent later. Press Cancel to abandon any edits and close the dialog box. The Use compression option is available only during an ARQ session. In that case the message is forwarded to the connected station, whose call sign is automatically entered and cannot be changed.

To clear the status flags for a message, right-click its header line and choose Clear flags from the pop-up menu.

Message tracing

The optional message tracing feature inserts headers like Received: from KA8RYU by NW8L; Jan 30 2019 05:01:48 UTC into received messages. If the message is forwarded to another station with tracing enabled, another Received: header is added by the receiving station, and so on. In this way a record of the message's progress through a network is built up as it is forwarded from station to station (read from bottom to top).

The Received: headers are visible in the message viewer together with the From: and To: headers. However, being message header lines, they are not visible and cannot be changed when sending or forwarding a message. This feature is compatible with previous versions of vARIM and ARIM.

The timestamp included in the Received: headers indicates time of receipt, either local time or UTC time at the receiving station, as set by the utc-time parameter in the [ui] section of the varim.ini configuration file. No time zone is included for stations configured for local time stamps (utc-time=FALSE).

Message tracing is enabled or disabled by the value of the msg-trace-en parameter in the [arim] section of the configuration file. Set to TRUE to enable tracing or FALSE to disable it. The default value is FALSE.

Working with the local shared files viewer

Select the Local Files tab.

The viewer opens in the shared files root directory defined by the files-dir parameter in the [arim] section of the varim.ini configuration file. The directory path is shown in the title of the viewer window.

The contents of the directory are listed, one to a line. For files, the name, size in bytes and the last-modified date are shown. For subdirectories, the name and last-modified date are shown. Access-controlled subdirectories defined by the ac-files-dir configuration file parameter are indicated with the ! (bang) character like this: !DIRECTORY.

To send a file to the remote station during an ARQ session, right-click its listing and choose Send File... from the pop-up menu:

The Send File dialog box opens.

Check Use compression if you wish to compress the file to reduce transfer time. To upload the file to a directory other than the default download directory at the remote station, enter its path in the To remote directory: field This path must be relative to the shared files root directory, e.g. contests/2016 and must made visible by an add-files-dir configuration file parameter at the remote station. Press OK to start the upload.

To open a file for viewing or editing, right-click its listing and choose Open File... from the pop-up menu. The Open Text File editor window opens:

If you make changes, press Save to save them to file and close the editor. Shortcut: double-click a file listing to open it for viewing or editing.

To open a directory, right-click its listing and choose Open Directory from the pop-up menu:

The contents of the tab will be replaced with a listing of the newly opened directory. The listing includes the parent directory (..) as item number 1. Shortcut: double-click a directory listing to open it.

To reload a directory listing, right-click and choose Reload Directory from the pop-up menu.

Viewing and editing files

Text files listed in the shared files viewer can be opened for viewing and editing from the vARIM menu. Choose File->Open Text File... from the main menu. The Open Text File dialog box opens. Select the file, then press OK to open the file in the Open Text File editor window. If you make changes, press Save to save them to file and close the editor.

Serving dynamic files

Dynamic files are used to return output from a script or system command executed by vARIM in response to a file query.

Dynamic file aliases appear in listings of the shared files root directory at a remote station. Because the size of the output is not known in advance, no file size is shown; instead the DYN identifier appears, like this:

Here's a sample of the spwxfc dynamic file output as seen in an ARQ session:

Dynamic file aliases are defined in the [arim] section of the varim.ini configuration file. The format is alias:command where alias is the name used to access the file and command is the invocation of the command or script, separated by a : (colon) character. For example:

dynamic-file = spwxfc:python /home/nw8l/scripts/forecast.py

Make sure that alias is unique among the other dynamic file definitions and file names in the shared files directory. Use absolute paths to script files when vARIM is built from source and installed. Relative paths can be used for "portable" binary installations where the script files are contained in same directory as the arim executable file. You may define no more than 16 dynamic files.

In response to the query sq file alias, command will be executed in a shell and its output returned in the response. command can be a batch file, a script invocation like python myscript or a system command like date or uname -a. The output size in bytes is limited by the max-file-size parameter in the [arim] section of the varim.ini configuration file. Errors generated by dynamic file scripts are written to a file named dyn-file-error.log in the log directory.

RF channel busy detect

vARIM listens for BUSY notifications from the VARA modem, which are sent to the host program when a signal is detected in the RF channel. When the channel is busy, vARIM displays the BUSY indicator in the status bar:

vARIM will check the RF channel busy status when the operator initiates an ARQ connection. If the RF channel is busy, vARIM will cancel the operation and an error message will be shown on the status bar. This helps prevent collisions between transmissions on a busy channel.

The modem does not send BUSY notifications to the host program during an ARQ session.

Logging

Logging can be enabled or disabled in the [log] section of the varim.ini configuration file. These are the traffic log and the debug log.

• The traffic log is enabled by default and records data and messages sent and received by the modem, with timestamping of each entry.
• The debug log is disabled by default. It logs all modem commands sent and received by the vARIM program as well as exceptions encountered in operation like data wait timeouts, communication errors etc.

These log files are created in the logs subdirectory of the vARIM working directory. By default, logging output for all ports is directed here.

However, this arrangement doesn't work well if more than one instance of vARIM is running at the same time. In this case, logging output from each instance can be directed to separate directories with settings in the [port] sections for each port in the varim.ini configuration file. Settings made here override the default settings in the [log] section when that port is attached. This prevents intermingling of the logging output from different ports in the default log files.

• To configure default log settings in the [log] section of the varim.ini configuration file:

  Set the traffic-log parameter to TRUE to enable traffic logging and to FALSE to disable it.

  Set the debug-log parameter to TRUE to enable debug logging and to FALSE to disable it.

• To configure port specific log settings in the [port] section of the varim.ini configuration file:

  Use the log-dir parameter to specify the directory where log files are located if port specific logging is enabled. This can be an absolute path or a relative path rooted in the user's home directory. Max length is 255 characters. Default: the user's home directory.

  Set the traffic-log parameter to TRUE to enable traffic logging and to FALSE to disable it.

  Set the debug-log parameter to TRUE to enable debug logging and to FALSE to disable it.

  If one or both of traffic-log and debug-log are set to TRUE, then logging output for this port is directed to the directory specified by log-dir. If traffic-log and debug-log are both absent or both set to FALSE, then the global settings in the [log] section are used, and logging output is directed to the default log directory.

Another log file, the dynamic file error log, is always enabled. It logs error messages from scripts or programs that generate dynamic file text output.

By default, logs are kept in the log subdirectory of the vARIM working directory (or the $HOME/varim directory if vARIM is installed) unless directed to a different location for a particular port by parameters in the [port] section of the varim.ini configuration file. Logs are automatically rotated every 24 hours. The file name format is name-YYYYMMDD.log where name is either traffic, debug or dyn-file-error, followed by the date, e.g. traffic-20161114.log.

To view a log file, choose File->View Log File... from the main menu. The Select Log File dialog box opens in the currently active log file directory. Select a log file and press OK to open it for reading.

Running vARIM on Cygwin/X

If you are already running ARIM on Cygwin, it's easy to run vARIM also if the X Window System is installed (Cygwin/X).

To install the X Window System:

• Start the Cygwin Setup program appropriate for your Cygwin installation (32-bit or 64-bit) and advance to the Select Packages screen. Change View to Full and add the following packages:
  • xorg-server  (the X Window Server)
  • xinit  (for the startxwin program used to start the X Server)
  • libfltk  (FLTK libraries for vARIM)

  

  

  

• It's easier to search for them by name as seen above.
• Click Next and finish the installation. The X Window System is installed, but not running yet.

To start the X Window System on Cygwin:

• Open a Cygwin Terminal and enter the startxwin command:

  

• The Cygwin/X Server and X applications menus appear as icons in the Windows System Tray on the Task Bar:

  

To install vARIM on Cygwin/X:

• Download the appropriate vARIM binary distribution package for your Cygwin installation (32-bit or 64-bit) into a directory of your choosing.
• Open a Cygwin Terminal and extract the files:

  

• Edit the varim.ini file as needed, configuring at least one port. Set the font-size parameter in the ui section to your liking.
• You may also build vARIM from source and install it on Cygwin/X. See the INSTALL file in the source code distribution for instructions.

To start vARIM on Cygwin/X:

• Choose System Tools->XTerm from the X applications menu in the Windows System Tray:

  

• An XTerm terminal window opens. This terminal provides the correct environment for vARIM to run in Cygwin/X. Navigate to the directory into which the vARIM files were extracted, and enter the ./varim & command:

  

• vARIM opens:

  

• The ./varim & command runs vARIM as a background program, so you can close the XTerm window now if you like.

To shut down the X Window System on Cygwin:

• Choose Exit... from the Cygwin/X Server menu in the Windows System Tray:

  

• The Exit Cygwin/X? dialog box opens:

  

• Click Exit to shut down the X server.

Copyright © 2016-2022 by Robert Cunnings NW8L.  Last modified: 22 January 2022.