Developer Information: Submitting QSOs to LoTW
TQSL is an open source C++ application built using TrustedQSL that enables a user to
- manage Callsign Certificates
- manage Station Locations
- detect QSOs that have already been uploaded to LotW and haven’t subsequently changed
- digitally sign ADIF and Cabrillo files
- upload digitally signed files to LoTW via the internet.
TQSL’s functionality is also accessible via a command line interface.
If you’d like to participate in the development of TrustedQSL and its applications, join the Trusted QSL Development Group via TrustedQSLDevel@yahoogroups.com
A logging application that aspires to manage Callsign Certificates and Station Locations on behalf of its user would do so by invoking functions provided in TrustedQSL. A logging application that only intends to automate the uploading of logged QSOs to LoTW can do so by invoking TrustedQSL functions, or by invoking TQSL via its command line interface.
A logging application that employs TrustedQSL to upload logged QSOs to LoTW is responsible for ensuring that QSOs already submitted to LoTW are not resubmitted unless they've subsequently been modified. Uploading all of a log's QSOs should not be routine. As described below, TQSL detects such duplicate QSOs and prevents them from being routinely uploaded.
When digitally signing an ADIF or Cabrillo file, TQSL processes these ADIF fields or their Cabrillo equivalent:
|CALL||Callsign of the station worked|
|FREQ||Frequency on which you transmitted||optional|
|BAND||Band on which you transmitted|
|FREQ_RX||Frequency on which you received||optional|
|BAND_RX||Band on which you received||optional|
|MODE||mode or mode group|
|QSO_DATE||UTC date on which the QSO started|
|TIME_ON||UTC time at which a valid, two-way QSO is established|
|PROP_MODE||propagation mode||set to
|SAT_NAME||satellite name||if and only if PROP_MODE is
A valid callsign
- contains only the letters A through Z, the digits 0 through 9, and the slash character
- contains at least one number and one letter
- is at least three characters in length
- does not begin or end with a slash character
- does not begin with 0
- does not begin with 1 unless it begins with 1A, 1M, or 1S
TQSL can employ each QSO record's STATION_CALLSIGN field to select the correct Callsign Certificate to be used for digitally signing that QSO record. Even if not used to select the Callsign Certificate, TQSL does check for consistency between each QSO record's STATION_CALLSIGN field and the Callsign Certificate that is being used to digitally sign that QSO record.
A recommended minimum set of fields for log data was initially described in ADIF 1 (1996). This set (CALL, QSO_DATE, TIME_ON, BAND, and MODE) has since become the de facto standard for the minimum data required to constitute a valid QSO record and (not coincidentally) it comprises the set of fields which Logbook requires.
Among the minimum data required, TIME_ON is the time field which must be present for there to be a valid QSO record; TIME_OFF need not be present in a QSO record for the record to be valid. Since only a single time value need be present for a ADIF QSO record to be valid (records having only a single time value are seen with great frequency), this time value (TIME_ON) must report when 2-way contact was established and a valid QSO started in order for it and the other data in the QSO record to be of value to an award credit system such as Logbook. This is consistent with other instances — on QSL cards, in contest reporting, etc. — where just a single time value is used to describe a QSO.
The time at which contact is established is also typically the time at which the QSO gets logged. This is certainly true for DX-peditions and contest-style operations but it is also true for sequenced weak-signal and scatter protocols as well. In all such cases, the contact ends and is logged as soon as a 2-way contact has been established making TIME_OFF identically equal to TIME_ON. In such cases, TIME_OFF is therefore redundant as well as optional providing additional justification (if needed) for omitting TIME_OFF.
A QSO that continues on past the point at which the minimum requirements for establishing 2-way contact are satisfied represents the intended circumstance for employing the optional TIME_OFF field. Logbook ignores TIME_OFF as that field does not provide any information pertinent to Logbook's purpose of matching QSOs in order to confer award credit. The presence of TIME_ON in the record indicates both: (a) the station is reporting that a 2-way contact took place; and (b) the time at which the station believes 2-way contact was established. That is sufficient — if all the info matches with the QSO partner — to confer award credit. How long the QSO may have continued once 2-way contact was established is simply not a consideration for granting award credit.
TIME_ON does not extend backwards to include any of the preceding time that was needed to establish a valid contact. Any time spent first in calling and then in exchanging and acknowledging both callsigns and at least one specific piece of information beyond the callsigns (those being the minimum requirements for having a valid, QSO1,2) represents effort that was expended before 2-way contact was established, before a valid QSO started, and before TIME_ON. Before 2-way contact is established there may be something — it may be a "proto-QSO" — but whatever it is, it doesn't become a valid QSO eligible for award credit until 2-way contact is established at TIME_ON.
There are no ADIF fields defined for recording the time spent calling or exchanging calls and information prior to a 2-way contact being established. That may well represent a systemic deficiency in ADIF. However, the meaning of TIME_ON and TIME_OFF are not mutable, For example, there would be no way for an importing application to distinguish
established contact at TIME_ON and then continued conversing for 45 minutes until TIME_OFF
started calling at TIME_ON and finally established contact by 45 minutes later at TIME _OFF
if TIME_ON were to be employed in a non-standard manner to arbitrarily indicate "started calling at" rather than "established contact at". At least one additional field is necessary to reliably report the times for three distinct QSO events: "began calling at", "established contact at", and "contact ended at" without introducing indecipherable confusion.
The 'I' in ADIF means Interchange. To have successful interchange requires mutual agreement between programs and programmers on what certain things have to mean. In this case, TIME_ON must consistently mean "established contact at" in all cases . Adopting any other approach is an invitation to total chaos.
Logging programs (or their users) that employ alternative definitions for the times recorded in their log will need to adjust the ADIF output that is supplied to Logbook as appropriate in order to behave consistently with other loggers. "Appropriately adjust" means to ensure the value of TIME_ON emitted is a time that one would be satisfied with had it been written (printed) on a QSL card. Not doing so may result in the failure to obtain confirmation matches because the times (meaning TIME_ON) for the two sides of the QSO do not fall within the +/- 30 minute window Logbook allows for a match.
1 Ed Tilton, W1HDQ, "What is a contact?..." (The World Above 50 Mc), QST, March 1957 p. 55
2 Gene Zimmerman, W3ZZ, "What is a Contact?" (The World Above 50 MHz), QST, March 2006 p.79
When processing a QSO that specifies a mode but not a submode, for example
If such an entry is found, TQSL will submit the QSO to LoTW with the mode specified in the ADIFMAP entry. If no such entry is found, TQSL will reject the QSO as specifying an unrecognized mode.
When processing a QSO that specifies both a mode and a submode, for example
If such an entry is found, TQSL will submit the QSO to LoTW with the mode specified in the ADIFMAP entry.
and does not specify
adif-submode. If such an entry is found, TQSL will submit the QSO to LoTW with the mode specified in the ADIFMAP entry. If no such entry is found, TQSL will reject the QSO as specifying an unrecognized mode.
TrustedQSL provides facilities for detecting duplicate QSOs, which are defined as QSOs
- that have already been submitted to LoTW from the computer on which TrustedQSL is hosted, and
- whose CALL, BAND, MODE, PROP_MODE, and SAT_NAME fields have not been subsequently modified, and
- were submitted with a Station Location whose fields have not been subsequently modified
When directed to digitally sign a log file, switch options in TQSL’s command line interface enable the invoking logging application to specify whether the presence of one or more duplicate QSOs in that log file should abort the signing operation, only sign QSOs that aren’t duplicates, or sign all QSOs including duplicates. To prevent the LoTW Server from having to process duplicate QSOs, developers of logging applications are encouraged to exploit the duplicate QSO detection and removal facilities provided in TrustedQSL and by TQSL’s command line interface. Duplicate QSOs should only be re-submitted if the user concludes those QSOs never reached LotW when originally submitted, or were subsequently lost. Note that any digitally-signed log file generated by TrustedQSL that contains one or more duplicate QSOs will recognized by the LoTW Server as containing duplicate QSOs.
QSO Upload Web Service
LoTW provides a web service at https://lotw.arrl.org/lotw/upload that will accept a digitally-signed log file using the RFC1867 protocol. This service returns HTML containing two comments that describe the results of an upload operation:
<!-- .UPL. result -->
where result will be either accepted or rejected.
<!-- .UPLMESSAGE. text -->
where text is a possibly multiline text message that can be displayed to the user if desired.
Note that being logged in to an LoTW User Account is not a prerequisite to using this web service.