YFKlog v0.3.5 Manual

Preliminary version (11-Mar-2008). Always under construction.

Copyright (c) 2008 Fabian Kurz, DJ1YFK <mail@fkurz.net>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".


YFKlog is a general purpose ham radio logbook program designed to run on *nix systems. This manual tries to give a detailed description of all features and functions of YFKlog.

The main website of YFKlog is located at: http://fkurz.net/ham/yfklog.html


Contents

  1. Installation
    1. SQLite
    2. MySQL
  2. Setup
    1. Mandatory settings
    2. Optional settings
  3. Main Menu
  4. Logging QSOs
  5. Searching and editing QSOs
  6. Handling QSL-cards
    1. Incoming cards
    2. Outgoing cards
  7. ADIF import and export
  8. Online log
  9. Select Logbook, create new Logbook
  10. Awards/Statistics
    1. Standings for awards
    2. Statistics, Xplanet markers
  11. Name/QTH database
  12. LOTW functions
    1. LOTW export
    2. LOTW import
  13. Transceiver control, hamlib
  14. Remote logging (for fldigi)
  15. Appendix
  16. GNU Free Documentation License

1. Installation

Download the latest version of YFKlog and unpack the tarball to a directory of your choice, then run make install.

$ wget http://fkurz.net/ham/yfklog/yfklog-0.3.5.tar.gz
$ tar zxfv yfklog-0.3.5.tar.gz
$ cd yfklog-0.3.5 
$ su
# make install

By default, YFKlog will be installed to /usr, but you can specify another directory by adding the option DESTDIR=/your/favorite/directory. If you have no root privileges on the machine, a path within your home-directory would be suitable.

Now you are ready to run YFKlog, the executable is simply called yfk and should be in your PATH.

On your first run, YFKlog will create a directory, ~/.yfklog/, where it stores your configuration and (in case of SQLite) your logbook. A setup screen appears, where you can edit the most important settings (see Setup below). You can chose between two databases, SQLite or MySQL.

SQLite is a lightweight, self-contained, zero-configuration SQL database engine and probably the right choice for most users of YFKlog. It's very easy to set up (for example in Debian, just install libdbd-sqlite3-perl and libclass-dbi-sqlite-perl and you're set!) and surprisingly fast.

MySQL is pretty much the opposite. Don't use it, unless you know why you'd want to.

1.1 SQLite

There is nothing really to set up, this is the default setting. SQLite will autmatically create a SQLite database file of the name as set in dbname=.... This single file contains the whole database. It's trivial to back up and (if needed) accessible via the sqlite3 command line utility just like a MySQL database.

1.2 MySQL

Create a database (in this example it's called YFKlog, the user is dj1yfk and the password is notmypassword) and grant the user the neccessary permissions:

$ mysqladmin -u root -p create YFKlog
$ mysql -u root -p
mysql> GRANT ALL ON YFKlog.* TO dj1yfk@localhost IDENTIFIED BY 'notmypassword';
mysql> FLUSH PRIVILEGES;
mysql> quit

Now start YFKlog and change at least the mandatory settings (see below) according to your database setup. If YFKlog can properly connect the database, it will automatically create its database tables after the first start. When updating from an older version, all upgrades of the database structure are performed automatically as of version 0.2.3.


2. Setup

Most of the permanent settings of YFKlog are stored in a file, called ~/.yfklog/config. This file will automatically be created on your first run of YFKlog, and can be changed either from YFKlog itself (accessible from the main menu) or edited manually with your favourite text editor.

Have a careful look at the possible settings!

If you're editing the file manually, note that the file-format allows an arbitrary placement of the variables in the file. If a variable is set more than once, the last occurance is used. The format name=value must be used, no spaces/tabs between name= and value are allowed.

Some settings in this file are mandatory. YFKlog won't run properly without setting these. Other settings are optional, which doesn't mean they are not important.

2.1 Mandatory Settings

2.2 Optional Settings


3. Main Menu

All functions of YFKlog are accessible through the main menu, shown on the right. The single menu points will be described in greater detail in the following sections; some are self explanatory. A quick overview:


4. Logging QSOs

In the Logging Mode, as shown in the picture, the screen is split up into 4 main windows. A QSO can be saved with F2, cleared with F3, pressing F5 queries band and more via hamlib. F6 performs a callsign lookup for the current call with a browser as set in the config. F7 enables remote logging mode for fldigi/gmFSK.

You can switch between the Windows 1, 3 and 4 by pressing F8, F9 and F10 respectively.

  1. This is the main entry window. It contains all important fields to enter the QSO data during the QSO. Tab, cursor down or enter gets you to the next field, cursor up or Shift-Tab one field back. The tab order of the fields can be freely configured, see Setup.
    Additional to the fields which are shown here, you can save additional information to the according database fields via the Remarks field:
  2. This window shows information about the callsign entered, derived from the country file cty.dat. The last line also shows - if available - known club memberships, if the DXCC was worked before, and if so on which bands, and if the callsign appears in any other log, as specified by checklogs in the config file. This is an example where all these information are shown.
  3. The last few QSOs in the log are shown in Window 3. You can jump here by pressing F9 and select any QSO to edit it. The fields shown are: Callsign, Band, Mode, Time, Date, Name, QTH, RST-sent, RST-received, QSL-sent, QSL-received, LOTW-status. Sort order can be changed by "logsort" (see above).
  4. Window 4 shows the last QSOs with the station you are currently working. You can go to this window by pressing F10 and select a QSO to edit it. Sort order can be changed by "prevsort" (see above).

5. Searching and Editing QSOs

Logged QSOs can be searched and edited under the menu point Search and Edit. The interface is similar to the normal logging screen, but the entry form now has some additional fields. Actually, all database fields can be directly seen and edited here.

First, enter any search criteria into the given fields. For example, when you are looking for all contacts with Brazil on 40m, go to the field 'Band' and enter 40, then go to the 'DXCC' field and enter 'PY'. Pressing F5 will start the search, and you can chose any of the matching QSOs to edit, as seen in the screen shot.

Any matching QSO can now be selected and after pressing enter, the QSO details appear in the fields and can be edited. F2 saves the changes made, F3 cancels the changes, F4 permanently deletes the selected QSO.

In some cases, you may want to change a group of QSOs at once, which would be a lot of work via this Search and Edit mode one by one. For such occasions, it is advantageous to know some basic SQL commands to do the changes directly on the mysql command line. The Appendix II contains examples for several common scenarios (like toggling the QSL-sent flag for a number of QSOs, deleting QSOs from a date-range etc.) which can easily be adopted, even without knowledge of SQL.


6. Handling QSL cards

Effective handling of QSL cards, both incoming and outgoing, is easily done with YFKlog. This section describes how.

6.1 Incoming QSL cards

The menu point QSL enter mode allows you to record received QSLs very effectively. After entering 3 or more letters of the callsign, all QSOs with matching callsigns from the current log are shown. The user can select a QSO, press space bar and the QSL-received status of this QSO toggles between 'N' to 'Y'. Pressing 's' on the same QSO toggles the QSL-sent status between 'N', 'Y' and 'Q', which makes it very easy to answer incoming QSL cards by putting them into the QSL queue and later process them.

Any changes made to can be saved by pressing F2 or cancelled by pressing F3. The screenshot shows an example screen, for the string 'UA9'.

6.2 Outgoing QSL cards, QSL queue

Outgoing QSL cards are saved in a QSL queue before they are processed. This happens either by logging a QSO with the QSL-S field set to 'Q', by importing a log with the qslsi option set to 'Q', or by changing the QSL-sent flag of a QSO to 'Q' in the QSL-enter mode as described above.

The queue can be emptied in different ways, by printing or writing the cards:

6.2.1 Print cards/labels

The queued QSLs can be printed into a PDF file by selecting the QSL print mode. Different label definition files (*.lab) are available, and Appendix III gives a short tutorial how to write your own. The conversion to PDF is done with LaTeX. To work properly, pdflatex, with the geometry package must be installed on the system.

Depending on the label definition file, an arbitrary number of QSOs may fit on one label. If the first label for one station is full, a new one is created. The output is alphanumerically sorted by the callsign.

After generating the PDF-File with the QSL-labels, YFKlog asks the user to review the file, and if he's is happy to remove the printed cards from the QSL-queue and set their status to 'Y'. Note that this cannot be undone! When in doubt, select 'No'. You can always flush the queue later if needed.

6.2.2 Writing cards

To write cards by hand, YFKlog has the "QSL write mode". When selected from the main menu, all queued QSL cards with their details are shown, sorted by callsigns.

When a QSL card for a highlighted QSO has been written, pressing space bar will change it's QSL status from "Q" (queued) to "Y" (yes, sent), and you can continue with the next card.

If you finished writing your cards, pressing F2 will save all changed QSL-flags, F3 cancels all changes and returns to the main menu.


7. ADIF import and export

The ADIF (Amateur Data Interchange Format) is now the de facto standard format to exchange logbook data. YFKlog can import and export this format, using a good subset of the available defined fields.

See Appendix X for a detailled description of the database design of YFKlog and differences to ADIF.

7.1 ADIF export

Almost all fields in the log table in YFKlog's database can directly be mapped to an ADIF field. This means, that (almost) no data is lost when exporting to ADIF from YFKlog. There are two exceptions:

  1. YFKlog has a separate log field for handling LOTW confirmations. This field has no ADIF equivalent and is not used when exporting to ADIF.
  2. Exported logs from YFKlog currently don't include any DXCC information. This will be fixed in foreseable future.

To export the current logbook to an ADIF file, chose "ADIF export" in the main menu. You'll be asked to enter a filename (or accept the default, yourcall.adi) and specify a date-range for the log to be exported (or export the whole log). The ADIF file will then be written and saved in the current directory. If a file with the same name already exists, it will be overwritten.

7.2 ADIF import

As mentioned above, most of the possible (and all of the commonly used!) ADIF fields have an equivalent entry in the database used by YFKlog. To import an ADIF file, move it to the directory YFKlog resides in, and chose "ADIF import" from the main menu.

You'll be given a list of ADIF files in the current directory and asked to chose one to import into the current logbook.

The actual import procedure consists of three steps: First the ADIF file is parsed, that means, the ADIF data structure (<call:6>DJ1YFK ...) is read. In the next step, each QSO is checked for sanity, the DXCC, prefix, ITU/CQ zones are determined (if not included in the file) and finally in the last step the log is added to the database.

Note that currently the DXCC country information from an ADIF file is ignored. YFKlog always tries to determine the DXCC of each call itself. If the contact doesn't contain some information like power, or QSL-sent flags, the default value as set in the config file is used.

The speed of the ADIF import is approximately 10 000 QSOs per minute on the author's PC (1.8GHz, 256MB RAM).


8. Update Onlinelog

to be written...


9. Select Logbook

Keeping several logs in one database is not a problem with YFKlog. Under the menu point "Select Logbook", you can change the current logbook or add a new logbook to the database.

It makes sense to name them after the callsign used, but you could chose any name. Note that, if the callsign contains a slash (/), it's automatically replaced with an underscore (_) for the internal logbook name (i.e. PA/DJ1YFK/P will be pa_dj1yfk_p internally) to avoid several problems. When printing QSL labels however, or exporting the log, it's changed back to a slash.


10. Awards and Statistics

10.1 Standings for awards

The standings for several popular awards, namely DXCC, WPX (PFX), WAZ (CQZ), IOTA and WAS (STATE) and VUCC (GRID) can be calculated by YFKlog. It considers both paper QSL and LOTW confirmations for this, and lists them once combined and once separately. Custom awards are possible with some limitations.

The screenshot shows the author's DXCC score. You can see five columns: Band, number of worked entities, number of confirmed entities (either LOTW or paper), number of entities confirmed by paper QSO, number of entities confirmed by LOTW.

The used date range (if any) and the bands to be included in these standings can be chosen/changed at runtime if wanted. The default bands are set in the config file as awardbands.

Additionally to the overview as seen on the screenshot, a detailled list of each DXCC/Prefix/State/etc versus the bands is written to a file, as stated. Examples: DXCC, WPX, CQ-Zones, etc.

Additional to the default awards, you can generate statistics for custom awards. The database structure is fixed, and adding additional fields for all kinds of awards is not the intention of the author, instead the "Remarks" field can be used for this purpose, in the format "$award:$value". For example to save a DOK for a QSO, an entry like "DOK:S07", "DOK:N16" has to be saved in the remarks field. Accordingly, RDAs would be entered as "RDA:MO-01", "RDA:VO-12" etc. In the award mode "Custom", you can generate statistics of those items (DOK, RDA, whatever), by specifying the name of the item. All QSOs are then searched for matching comments and statistics like for the other awards are generated.

10.2 Statistics, Xplanet markers

Several statistics, such as QSOs per Band, Continent or Mode, can be retrieved in the same sub menu. Finally, it's possible to generate a marker file for Xplanet which shows all DXCC entities in different colours: Red for needed, yellow for worked, and green for confirmed DXCCs. This can make a beautiful desktop background, which includes a realtime grayline map!


11. Name / QTH database

YFKlog maintains a database of names/QTHs for callsigns. If you enter a QSO with a known call, the name- and QTH-fields are automatically filled.

It's possible to edit or delete entries in this database by chosing "Edit Name/QTH DB" from the main menu.


12. LOTW functions

YFKlog makes it easy to keep track with the LOTW status of your QSOs, but still is far away from full LOTW integration.

For each QSO, YFKlog saves a value (called QSLrL, QSL-received-LOTW), which can be:

12.1 LOTW export

Selecting "Export to LOTW" from the main menu will cause YFKlog to export all QSOs from the current log with the QSLrL-flag N to an ADIF file, and changes these QSOs to R (requested). The ADIF file can then be signed with tQSL and uploaded to LOTW.

12.2 LOTW import

Received QSL records from LOTW can be downloaded via the LOTW web-interface, under "Your QSOs" -> "Download report". A file called lotwreport.adi is generated, which contains all confirmations, by default since the last download of this file.

This file may contain QSL records for one or several of your callsigns, and can be imported to YFKlog via "Import from LOTW" in the main menu.

YFKlog will update the QSLrL flag of each confirmed contact accordingly. If the file contains confirmations for several callsigns, YFKlog automatically selects the proper logbook to update, and produces a warning if a QSO (or even a logbook) cannot be found.

The lotwreport.adi file might contain additional information, like the CQ zone or IOTA reference of the station. By default, this information is not considered by YFKlog, but by setting lotwdetails=1 in the config file they will be added to your logbook.

Note that repeatedly importing the same lotwreport file doesn't cause any problems. In case you lost track of when you last imported a lotwreport, you can savely import a complete report of all your confirmations again.


13. Transceiver control via Hamlib.pm

YFKlog supports very basic functions to retrieve the frequency and mode from a connected transceiver by means of the HamLib Perl bindings.

13.1 Hamlib setup

The config file contains two parameters for hamlib: rigmodel and rigpath. The first is the number of the transceiver to be used, as shown in rigctl --list. The second is the path to the device to which the transceiver is connected, e.g. /dev/ttyS0.

$ ./rigctl --list 2> /dev/null | grep K2
221     Elecraft        K2                      0.5     Beta

13.2 Usage

Querying the frequency and mode from hamlib can be either automatically or on request. In the main logging window, pressing F5 will query the frequency and mode and then write them into the fields of the logging form.

Alternatively, it's possible to automatically retrieve frequency and mode with every new QSO, when setting autoqueryrig=1 in the configuration.


14. Remote logging (for fldigi/gmfsk)

As of Version 0.3.5 (January 2008), YFKlog can receive QSO data from another application my means of IPC. When in the main logging mode, press F7 to enable the remote mode. YFKlog then waits for new QSOs from another application (tested with fldigi and gmfsk) and adds them to the log. Pressing F7 again leaves the remote mode and normal logging can continue.

The current program design of YFKlog does not allow this to listen for remote QSOs in the background, but a logged QSO (by fldigi/gmfsk) will survive in the message queue and be fetched as soon as YFKlog enters the remote mode.


Appendix (very much UNDER CONSTRUCTION)

Using Putty

When using YFKlog via ssh with Putty, the F-keys may not work in the default configuration. In the putty configuration (Terminal -> Keyboard), set "The Function keys and keypad:" to Xterm R6.

Database backup

Regular backups of your logbook data are highly recommended. With SQLite and MySQL you can easily produce a so-called SQL dump of the database, from which you'll be able to completely restore your database in case of data loss.

For SQLite, use the following command-line:

sqlite3 ~/.yfklog/YFKlog '.dump' | gzip -c > dump.sql.gz

This will produce a compressed file dump.sql.gz which contains the whole database in human readable SQL format. Replace ~/.yfklog/YFKlog with the location of the SQLite database file, in case you don't use the default location.

For MySQL, use the command line utility mysqldump:

mysqldump -p YFKlog | gzip -c > dump.sql.gz
Where YFKlog is the name of the database. You will be prompted to enter your password; alternatively you may directly include it in the command line (for example when invoked from cron): mysqldump -pMYPASSWORD ....

1. Database performance (only MySQL)

It's highly recommended to activate MySQL's query cache, since YFKlog does many repeated equal database queries, for example when scrolling through a list of QSOs. Enabling the cahce will significantly speed up scrolling.

2. SQL examples: Mass-editing, deletion, etc.

YFKlog offers the possibility to edit or delete QSOs, one by one. In some cases however, you might want to delete or modify a large number of QSOs. In this case, a few SQL commands can safe you a lot of time. Following are some real world examples which you might adopt for your own purposes.

Example 1: Mass editing

After importing my CQWW-CW QSOs, I noticed that I imported all QSOs with the default power (100W) instead of 750W, which was actually used. Solution:


[dj1yfk@dl0tud dj1yfk]$ mysql -p
Enter password:

mysql> use DJ1YFK
Database changed
mysql> update log_dj1yfk set pwr=750 where date='2006-11-25' or date='2006-11-26';
Query OK, 3158 rows affected (1.73 sec)
Rows matched: 3158  Changed: 3158  Warnings: 0

mysql>

Database Backup

A backup of the complete database can be easily done by sqldump. In this example the database name is YFKlog.

MySQL

mysqldump -p YFKlog | gzip - - > dump.sql.gz

mysqldump will promt you for the password to access the database. If you invoke mysqldump from a script, you may add the password in the command line (mysqldump -pPASSWORD) but be advised that this is not very secure. Everyone doing a ps a during the backup can see your password. You may want to consider using for example expect if this is an issue.

SQLite3

sqlite3 ~/.yfklog/YFKlog .dump YFKlog | gzip - - > dump.sql.gz

Alternatively, just back up the database file itself, ~/.yfklog/YFKlog, but makre sure there is not currently any process writing to it.

GNU Free Documentation License

http://www.gnu.org/licenses/fdl.txt