Ham Radio Deluxe and WSJT-X Modes with JTAlert and QSO Relay
Editorial de Mike, WA9PIE; HRD Software, LLC
We here at HRD Software would like to extend a great deal of gratitude to Chris Fredericks, VK2BYI. QSO Relay provides functionality at a very important and fast moving time in ham radio. QSO Relay enables Ham Radio Deluxe users to enjoy the benefits provided by JTAlert and WSJT X for digital modes such as JT65, JT9, and a mode that has taken the ham radio community by storm - FT8.
Chris worked with us patiently to sort out problems with our API to make this happen. Chris gave us permission to reproduce his instructions on how to setup QSO Relay with JTAlert and WSJT X to enable Ham Radio Deluxe users to enjoy these digital modes and log FT8 QSOs into Ham Radio Deluxe Logbook AUTOMATICALLY. Please enjoy these instructions.
Visit the VK2BYI webpage at http://www.vk2byi.com.au/
Hams ask me the following question often, "Does Ham Radio Deluxe support FT8?" Through his efforts, Chris has made this possible for Ham Radio Deluxe users. We're very grateful.
Thank you, Chris!
QSO RELAY
Contact Forwarding for JTAlertX and Ham Radio Deluxe Logbook v6.x
CHRIS FREDERICKS, VK2BYI
Release 1.7
20 September 2017
Copyright © VK2BYI. All rights reserved. (Used with Permission)
Microsoft, Excel, Word and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
QSO Relay is a Windows desktop application that runs as a System Tray application that listens for contacts being forwarded from JTAlertX via the User Datagram Protocol (UDP). As datagrams are received, they are logged locally in a SQLite database and then relayed via Transmission Control Protocol (TCP) to a Ham Radio Deluxe Logbook v6.x database.
Features
- Runs as a minimised application with an icon in the System Tray.
- Works with HRD Logbook v6.x with full support for logbooks hosted on the following database platforms: Microsoft Access, Microsoft SQL Server and Oracle MySQL Server.
- Database synchronisation allows JTAlertX to update its Wanted Alert requirements.
- Helps prevent duplication of contacts in HRD Logbook.
QSO Relay was developed as a proxy application that accepts contacts being forwarded by the ‘Last QSO API’ in JTAlertX, and then relays the contact to the HRD Logbook database. QSO Relay enables Ham Radio Deluxe Logbook v6.x to continue being used with JTAlertX with version 2.9.7 onwards
Fig 1.
As confirmations of contacts are subsequently received from various sources such as LoTW, eQSL.cc and QSL Cards, the corresponding rows in the HRD Logbook database are updated. QSO Relay has a feature whereby contact confirmations in the HRD Logbook database can be updated in the QSO Relay database as well. This synchronisation process is requested by selecting a QSO Relay menu item.
Fig 2.
This in turn should be followed by a ‘Scan Log and Update…’ in JTAlertX to update its Wanted Alert requirements.
System Requirements
QSO Relay is a Windows desktop application that has been designed to use the Microsoft .NET Framework 4.6 which is supported by Microsoft to run on the following workstation and server operating systems:
- Windows 10
- Windows 8.1
- Windows 8
- Windows 7 SP1
- Windows Vista SP2
Windows 10 comes with the Microsoft .NET Framework 4.6 pre-installed. The .NET Framework 4.6 will need to be downloaded and installed for the other operating system versions listed above if it hasn’t already been installed by other .NET applications run on the workstation.
Refer to https://www.microsoft.com/en-au/download/details.a... for further details on how to install the Microsoft .NET Framework 4.6 using the Microsoft .NET Framework 4.6 (Web Installer) for Windows Vista SP2, Windows 7 SP1, Windows 8, Windows 8.1.
Hardware Requirements
Processor: 1GHz (32-bit or 64-bit)
RAM: 512 MB
Disk space (minimum)
- 32-bit: 4.5 GB
- 64-bit: 4.5 GB
(The hardware requirements listed above are those specified by Microsoft for the .NET Framework 4.6 itself.)
Installing QSO Relay
You can download the latest release of the QSO Relay installation program from the VK2BYI website at http://www.vk2byi.com.au/qsorelay.
Once the download is complete, click on the downloaded .MSI file to start the Windows Installer.
Click the Next push button to continue.
Leave Everybody (all users) selected and click the Next pushbutton to continue.
Read the license agreement and if you agree to the terms and wish to continue installing the software, select I accept the terms in the License Agreement and click the Next pushbutton.
You can read the release notes now, or later. A copy of the release notes will be installed in the same folder as the software. Click the Next pushbutton to continue.
Leave the suggested Folder unchanged and click the Next pushbutton to continue.
Click the Install pushbutton when you ready to proceed with the installation.
It may take several minutes, but the Status: text, and the progress bar will update as the installation progresses.
Once the installation complete, you can leave the checkbox ticked to launch QSO Relay and click the Finish button. Start Menu desktop shortcuts will be created, so you can also use them to start QSO Relay.
Starting QSO Relay
Click on the QSO Relay desktop shortcut to start the QSO Relay application. When the QSO Relay application is running, a red
icon will be displayed in the system tray.
The application user interface is kept minimal so as not to increase desktop clutter on an already busy computer screen as found in most amateur radio stations. A single left or right-mouse button click on the icon will open a menu on which the various functions of the application can be invoked.
The desktop shortcut created by the QSO Relay installation can be copied into the Windows start-up folder so that the program is automatically launched each time Windows starts up.
Copy the Desktop shortcut into the following folder:
C:\Users\
If you are upgrading from either version 1.1 or 1.2 of QSO Relay, you may receive the following message the first time that version 1.3 or later is run:
This is because the method used to capture contacts coming from JTAlertX to be logged has changed with version 1.3 onwards, and it is necessary to change the default Incoming UDP Port number.
Configure JTAlertX Logging Settings
Starting with version 1.3 onwards, QSO Relay utilises the ‘Standard ADIF File’ and ‘Last QSO API’ logging features in JTAlertX version 2.9.7 onwards, to relay contacts to HRD Logbook. The following steps describe how to configure JTAlertX to work with QSO Relay:
1. Select Standard ADIF File from the Logging node in JTAlertX settings and tick the Enable Standard ADIF File Logging;
2. Click on the Create New pushbutton in the Log File group of controls and browse to a suitable folder, and create an ADIF that is to be used for logging the contacts. JTAlertX will suggest creating the file in the following folder:
C:\Users\
However, you may wish to create the file in the same folder as QSO Relay stores its application data, as in the following screen capture:
C:\Users\
3. Select Last QSO API from the Logging node in JTAlertX settings, and take note of the value in the UDP Port text box, as this value must be entered into the Incoming UDP Port: setting in the QSO Relay Options dialog:
4. The ADIF File Location setting is set by default and cannot be changed.
Configure QSO Relay Settings
Click on thetray icon and select the Configure QSORelay… item from the menu:
The Options dialog will be displayed and will be partially populated with default values on initial installation:
UDP Incoming
The UDP Incoming group of controls specify the UDP port that QSO Relay listens on for incoming contacts from JTAlertX. The values of 127.0.0.1 and 2333 are the default values used by the ‘Last QSO API’ in JTAlertX. In most cases values can be left unchanged.
JTAlertX ADIF Log File
The JTAlert ADIF Log File group of controls specify the filename of the ADIF Log File that was created in JTAlertX for Standard ADIF File logging. Refer to the Configure JTAlertX Logging Settings section at the end of this document for further details on configuring JTAlertX to work with QSO Relay.
To specify the JTAlertX ADIF Log File, click on the Select pushbutton to display a file Open dialog that can be used to browse the desired file to be selected:
Select the ADIF Log File you created in JTAlertX, and click on the Open pushbutton to open the ADIF file.
The full pathname will be displayed in the JTAlert ADIF Log File text box:
Ham Radio Deluxe v6.x Logbook
The IP Address and TCP Port values in the Ham Radio Deluxe v6.x Logbook control group, are the default values that HRD Logbook uses for its Logging API. These values can typically be left unchanged as well.
The Logbook Database drop down listbox will be populated with the list of all Logbook Databases defined in HRD Logbook. Select the logbook database to be used for logging new contacts. The combination of IP Address, TCP Port and Logbook Database are used by QSO Relay to log new contacts coming from JTAlertX into HRD Logbook.
To read existing contacts from the logbook database, QSO Relay utilises a universal database provider platform that works with all database technologies that HRD Logbook supports – Microsoft Access, Microsoft SQL Server and Oracle MySQL. This requires the appropriate connection string to be defined by clicking on the Properties link.
The following sections describe the properties to be specified depending upon the database platform hosting the HRD Logbook.
Microsoft Access
The Microsoft Access data source connection string only requires one value to be entered – the full pathname to the Microsoft Access (*.mdb) Standard JET Database file used as the HRD Logbook database.
Click on the ellipsis
pushbutton to display a file Open dialog that can be used to browse to, and select, the desired Access database file used by the HRD Logbook:
The typical path to this file will be like the following:
C:\Users\(your username)
Click on the Open pushbutton to close the file open dialog and the full pathname will be displayed in the Data Source text box.
You can click on the Test Connection pushbutton to verify that QSO Relay can create a shared connection to the Access database.
Click on the OK pushbutton to close the Connection Properties dialog and apply the new data source connection properties.
Click on the Cancel pushbutton to close the Connection Properties dialog without applying any changes to the data source connection string properties.
Microsoft SQL Server
The Microsoft SQL Server data provider connection string requires Server, Username, Password and Initial Catalog values to be specified.
If the workstation that QSO Relay has been installed on, is also the host for the Microsoft SQL Server, the default localhost value can be used for the Server: value. This would typically occur when an Express edition of Microsoft SQL Server is being used. If Microsoft SQL Server is running on another computer, you will need to enter its IP Address.
Enter the name of the SQL Server Login being used to access the HRD Logbook database on the SQL Server for the Username: value.
Enter the password of the Server Login being used to access the HRD Logbook database on the SQL Server for the Password: value.
Once the Server, Username and Password have entered, you can click on the Initial Catalogue: drop down list box and select the database being used for the HRD Logbook on the SQL Server.
You can click on the Test Connection pushbutton to verify that QSO Relay can create a connection to the SQL Server database.
Click on the OK pushbutton to close the Connection Properties dialog and apply the new data source connection properties.
Click on the Cancel pushbutton to close the Connection Properties dialog without applying any changes to the data source connection string properties.
Oracle MySQL
The Oracle MySQL data provider connection string requires Server, Username, Password, Database and Port values to be specified.
If the workstation that QSO Relay has been installed on, is also the host for the MySQL server, the default localhost value can be used for the Server: value. This would typically occur when a Community edition of Oracle MySQL server is being used. If MySQL server is running on another computer, you will need to enter its IP Address.
Enter the name of the user being used to access the HRD Logbook database on the MySQL server for the Username: value.
Enter the password of the user being used to access the HRD Logbook database on the MySQL server for the Password: value.
Once the Server, Username and Password have entered, you can click on the Database: drop down listbox and select the database being used for the HRD Logbook on the MySQL server.
The Port: value of 3306 is the default for MySQL. Change the value to the port being used if the default value is not being used.
You can click on the Test Connection pushbutton to verify that QSO Relay can create a connection to the MySQL database.
on the OK pushbutton to close the Connection Properties dialog and apply the new data source connection properties.
Click on the Cancel pushbutton to close the Connection Properties dialog without applying any changes to the data source connection string properties.
Logbook Extract
When a Synchronise Databases operation (described in the next section) is performed, an extract of rows from the HRD Logbook is written as an ADIF file that JTAlert can read during a Scan Log and Update to update its Wanted Alert requirements.
The extract can be qualified by selecting from the choices in the Logbook Extract drop down listbox:
- All contacts – all rows in HRD Logbook are extracted. This is the default setting.
- JT Mode contacts only – only those rows where the mode is one of the modes supported by WSJT X are extracted;
- Digital mode contacts only – all rows except those where the mode is AM, ATV, CW, DSTAR, FAX, FM, LSB, SSB, SSTV, USB.
Typically, you would specify that All contacts are to be extracted. However, if Alert tracking by all modes in JTAlert is not required, the size of the extract can be reduced by selecting the JT Mode contacts only or Digital mode contacts only settings as appropriate to your Alert tracking requirements.
QSO Relay SQLite Database
QSO Relay uses a SQLite database file for its contact database. The QSO Relay SQLite Database group of controls are used to specify the filename to use for the QSO Relay SQLite database:
To create a new SQLite database, click on the Create pushbutton to display a file Save As dialog that can be used to specify the desired filename to be used for the QSO Relay contact database:
Type in a name for the file in the File name: textbox and click on the Save pushbutton to create the SQLite database file. The full pathname will be displayed in the SQLite Database File: text box.
To open a previously created SQLite database, click on the Select pushbutton to display a file Open dialog that can be used to browse the desired file to be selected as the QSO Relay contact database:
Select the existing file, or type the filename in the File name: textbox, and click on the Open pushbutton to open the SQLite database file.
The full pathname will be displayed in the SQLite Database File: text box:
Session Tracing
A session tracing feature has been implemented, that when enabled, will capture detailed diagnostic information to a session log file for later analysis.
To start session tracing, check the Enable tracing checkbox and close the Options dialog. A file will be created using the following name format:
Session yyyyMMddHHmmss.log
where yyyyMMdd is the current date and HHmmss is the current local time.
The session log files are written to the following folder:
C:\Users\
To stop session tracing, uncheck the Enable tracing checkbox and close the Options dialog, and the session log file will be closed.
During the time that session tracing is running, diagnostic information will be appended to the session log regarding contacts being relayed to HRD Logbook, and data being transferred during database synchronisation. This session information, along with any exception logs, can be useful when trying to isolate the cause of an issue you might be experiencing and can be forwarded to the QSO Relay authors for further analysis.
Note: You should not try to open the session log file while tracing is running. You must uncheck the Enable tracing checkbox and close the Options dialog, or shut down QSO Relay, so that any pending information is written, and the log file is closed.
If the Enable tracing checkbox is left checked when QSO Relay is shut down, a new session log will be created when QSO Relay is restarted, and tracing will resume until QSO Relay is shut down again, or the Enable tracing checkbox is unchecked and the Options dialog is closed. Therefore, you may wish to uncheck the Enable tracing checkbox before shutting down QSO Relay so that it is not forgotten about, and copious amounts of diagnostic information slowly fills up disk space.
Synchronise Databases
To initially populate the QSO Relay database, and subsequently to ensure that the QSO Relay database is kept up-to-date with changes made in the HRD Logbook database, e.g. by confirmations received via LoTW, eQSL.cc and QSL Cards, click on the tray iconand select the Synchronise Databases… item from the menu:
QSO Relay will then perform the following steps:
Checks the HRD Logbook for duplicate contacts, that is, where there is more than one row with identical QSO Date, Time On, Call, Band and Mode values. If duplicates are found, the details will be written to the report file (see below), and the database synchronisation will stop; Add any QSO Relay contacts that have not already been relayed to HRD Logbook. This could occur where HRD Logbook was not running at the time a JT-Mode contact was forwarded by JTAlertX to QSO Relay; Truncate and reload QSO Relay database rows with the current details of all mode contacts, only JT mode contacts or only digital mode contacts as specified in the QSO Relay Options dialog; Write an updated version of the JTAlertX ADIF Log File from the contacts in the HRD Logbook so that a ‘Scan Log and Update…’ in JTAlertX can be run to update its Wanted Alert requirements.
During the synchronisation process a pop-up notification will be displayed above the tray notification area:
After the database synchronisation has completed, a summary report will be written to the Documents/QSORelay folder using the following filename format:
Sync Report yyyyMMddhhMMss.txt
where yyyyMMdd is the date, and ddhhMMss is the local time the synchronisation was performed.
The time taken to synchronise the databases will vary depending upon the software and hardware performance of the computer(s) involved, as well as the number of database rows being processed, but will typically take less than a minute.
Delete a Contact
If a JT-mode contact relayed to HRD Logbook from QSO Relay was made by mistake, it can be simply deleted from HRD logbook. The next time the databases are synchronised, the same contact will be deleted from the QSO Relay database automatically, or it can be manually deleted. To manually delete the same contact from the QSO Relay database, click on the tray icon and select the Delete a Contact… item from the menu:
This will display the Delete Contact dialog in which the row to be deleted is selected by using the up and down arrow keys, or by clicking in the left most column to highlight the row:
The text on the caption bar indicates the number of rows in the QSO Relay database which should equal the number of rows in the HRD Logbook after a database synchronisation has been completed, and as contacts are logged in both databases.
NOTE: If there are many contacts (10’s of thousands), it may take some time for the Delete Contact dialog to appear for the first time while the grid is being populated. However, when the Delete Contact dialog is subsequently re-opened, it will update quicker.
To assist in locating a row in the grid, a search can be made by selecting either the QsoDate radio button to search for contacts by QSO Date, or by selecting the Call radio button to search for contacts by Call. As characters are typed into the text box, the grid will begin to filter the rows displayed to those that partially match the text being entered.
For example, to locate contacts made in September of 2015, enter 201509. To locate a contact by Call, select the Call radio button and type the callsign of the station worked.
After selecting the row, click on Delete pushbutton and you will be given a chance to confirm the deletion before proceeding:
Click on the Yes pushbutton to have the row deleted from the QSO Relay database, or click on the No pushbutton to cancel the deletion.
Click on the Close button in the Delete Contact dialog to close the dialog.
Check for Updates
To determine if a new release of QSO Relay is available for download, click on the tray icon and select the Check for Updates… item from the menu to launch the QSO Relay Updater as a separate application.
The QSO Relay Updater will determine if a later release version is available, and if so, details like the following will be displayed:
Click on the No pushbutton to cancel the update. Click on the Yes pushbutton to proceed with the download. A progress bar will display as the installation file is downloaded:
The QSO Relay application needs to be closed before it can be updated, so after the download completes the following message will be displayed:
Close the QSO Relay application by clicking on the tray icon and select the Exit… item from the menu:
Then click on the Yes pushbutton in the Proceed with Update message dialog to proceed with the installation. Refer to the Installing QSO Relay topic for further details on the installation process.
About QSO Relay
To display details of the version of QSO Relay that is currently running, click on the trayicon and select the About QSO Relay menu item:
The version number is displayed in the About QSO Relay dialog:
Close the About QSO Relay dialog by clicking the OK pushbutton.
Closing QSO Relay
To close the QSO Relay application, click on the tray icon and select the Exit menu item:
QSO Relay will then terminate and the trayicon will be removed from the system tray.
Reporting Issues
If you encounter a problem, before reporting the issue via our support forum, please read the following information. You will then be able to provide us with technical information that will help to diagnose and resolve any coding issues more quickly.
Unless you already have, you should join the QSO Relay support forum at:
http://groups.io/g/vk2byi-qsorelay
You then can search the message topics posted by other forum members, and many times a solution to your problem may be found there.
Otherwise, follow this procedure when reporting an issue:
- If an application error occurs, an exception log file will be automatically created using the following name format:
- Exception yyyy-MM-dd.log
- where yyyy-MM-dd is the current local date.
- If you can repeat the process that causes an error, refer to the Session Tracing section earlier in this document on how to create a session log file. Then repeat the process with session tracing enabled, and be sure to uncheck the Enable tracing checkbox and click the Close button in the QSO Relay Options dialog when done. This will ensure that the full session tracing information is written and the file closed.
- The exception and session tracing log files are written to the following folder:
C:\Users\
- Zip up all log files (*.log) from this folder, and send an email to chris@vk2byi.com.au explaining the issue you are encountering and be sure to attach the log files.
- If the attachment is too big to be sent via email, you can post it to the files section in our support forum instead.
Release Notes
Version 1.7.6472.36182 (2017-09-20)
- Fixed error with cached contacts file not being parsed correctly.
Version 1.6.6396.27909 (2017-09-18)
- Added FT8 and JT4 to the set of modes that will be extracted from HRD Logbook during a synchronise database operation when filtered by the ‘JT Mode contacts only’ selection in the Logbook Extract drop-down listbox in the Options dialog;
- Added support for embedded carriage return/line feed characters in the Address field in the UDP datagram sent by JTAlertX.
Version 1.5.6371.29224 (2017-06-11):
- Added a new feature whereby the scope of rows to be extracted from HRD Logbook during a synchronise database operation can be filtered to all mode contacts, only JT mode contacts or only digital mode contacts;
- Corrected the contents of the County field when a new QSO is being added to HRD Logbook, to include the County value only, and not the State and County values for US contacts.
Version 1.4.6357.26174 (2017-05-28):
- Handles ‘empty’ values in the Latitude, Longitude, My Latitude and My Longitude columns during ADIF logging file extract;
- Rounds non-integer values in RX Power and TX Power columns during ADIF logging file extract;
- Added RX Power column to ADIF logging file extract.
Version 1.3.6343.31566 (2017-05-16):
- Modified to work with JTAlertX 2.9.7 onwards using its Standard ADIF File and Last QSO API logging features;
- Added HRD Logbook duplicate checking and reporting during Database Synchronisation;
- Added more support for globalization of digit grouping and decimal symbols.
Version 1.2.6338.24212 (2017-05-12):
- Improved Database Synchronisation performance;
- Added Database Synchronisation reports to users “Documents\QSORelay” folder;
- Added caching of contacts that could not be relayed to HRD Logbook, to allow relay during a subsequent database synchronisation;
- Improved message description on unique constraint violation exceptions;
- Floating point values in float columns that should only contain integer values;
- Added row count to Delete Contact dialog caption bar;
- Added QsoDate and Call search feature to Delete Contact dialog;
- Added multiple attempts to check contact has been successfully logged in HRD Logbook;
- Added support for different decimal place characters for different cultures;
- Added support to convert invalid floating-point values to integers values;
- Added diagnostic tracing statements that can be captured to a session log file.
Version 1.1.6323.38334 (2017-04-24):
- Fixed contact verification to prevent duplicates;
- Fixed Access query error;
- Changed default folder for SQLite files to application data folder.
- Initial beta release.
