Logbook of The World
Logbook of The World



Yaesu -- Choice of the World's top DX'ers -- Ad

Yaesu | LoTW® Principal Sponsor

Developer Information: Submitting QSOs to LoTW

TQSL is an open source C++ application built using TrustedQSL that enables a user to

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:

ADIF Field Field Contents Presence
CALL Callsign of the station worked required
FREQ Frequency on which you transmitted one of BAND or FREQ must be present.
BAND Band on which you transmitted one of BAND or FREQ must be present. A value for BAND will be derived from the value of FREQ if BAND is absent from record
FREQ_RX Frequency on which you received optional
BAND_RX Band on which you received optional
MODE mode or mode group required
SUBMODE submode optional
QSO_DATE UTC date on which a valid, two-way QSO was established required
TIME_ON UTC time at which a valid, two-way QSO was established required
PROP_MODE propagation mode requred and set to SAT for Satellite QSOs; otherwise, optional
SAT_NAME satellite name required if PROP_MODE is SAT; othewise, omit
STATION_CALLSIGN The callsign that you used over the air optional
OPERATOR The callsign that you used over the air if STATION_CALLSIGN is absent from record (per ADIF standard since v2.1.5 [2004]) optional
MY_DXCC Your DXCC entity code optional
MY_STATE Your Primary Administrative Subdivision (of enumerated type per ADIF standard since v2.1.4 [2003]) optional
MY_CNTY Your Secondary Administrative Subdivision (of enumerated type per ADIF standard since v2.1.4 [2003]) optional
MY_GRIDSQUARE Your grid square (or grid subsquare) optional
MY_VUCC_GRIDS A comma separated list of 2 or 4 grid squares for operations which take place from a grid boundary or 4-way intersection per the VUCC rules. optional
MY_CQ_ZONE Your CQ zone optional
MY_ITU_ZONE Your ITU zone optional

Callsigns

TQSL and Logbook consider a valid callsign to be one that:

  • 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
  • has a maximum length of 20 characters

Station Callsign

TQSL can employ each QSO record's STATION_CALLSIGN field — which reports the callsign that was used over the air to make the QSO — 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 will by default 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.This helps to ensure the integrity of the data uploaded to Logbook.

With regard to OPERATOR, per the ADIF standard (since ADIF 2.1.5 [2004]):

if STATION_CALLSIGN is absent OPERATOR shall be treated as both the logging station's callsign [the callsign used over the air] and the logging operator's callsign.

The above is specified as a "shall" meaning that it is mandatory for all ADIF-conforming applications, both importing and exporting, to treat the OPERATOR field in this manner. Thus, an application which emits OPERATOR while omitting STATION_CALLSIGN is reporting to TQSL (and every other ADIF-conforming application) that the operator's callsign and the callsign that was used over the the air to make the QSO are one and the same.

If that is not the interpretation which the exporting application desires to convey, an ADIF-conforming application must either emit the STATION_CALLSIGN field in addition to OPERATOR or omit OPERATOR entirely if the STATION_CALLSIGN field is absent from the record and the value of OPERATOR does not reflect the callsign that was used over the air.

The ADIF standard further specifies that the values of both the STATION_CALLSIGN and OPERATOR fields are to be callsigns. The logging operator's name properly goes into the MY_NAME field, not into the OPERATOR field. The appearance of a non-callsign value in the OPERATOR field, such as a name, represents another non-conformance with the ADIF standard.

Applications which allow non-conforming ADIF to be emitted are non-conforming applications.TQSL cannot guarantee correct and error-free interoperation with non-conforming applications.

Station Location Fields

TQSL can employ the value of each QSO record's station location fields to override the corresponding value given in the station location that is selected in TQSL on a QSO-by-QSO basis. A highy useful feature for mobile, rover and portable operations. The ADIF station location fields recognized by TQSL are:

  • MY_DXCC
  • MY_STATE
  • MY_CNTY
  • MY_CQ_ZONE
  • MY_ITU_ZONE
  • MY_GRIDSQUARE
  • MY_VUCC_GRIDS

Even if not used to override the values specified in the station location, TQSL will by default check for consistency between each QSO record's station location fields and the corresponding values specified in the station location selected in TQSL. This helps to ensure the integrity of the data uploaded to Logbook.

MY_STATE

The MY_STATE field has been defined in the ADIF standard as being enumerated type since ADIF v2.1.4 [2003]; MY_STATE is not a string type field that may contain free text. This means that any value appearing in the MY_STATE field which is not the code value of an element specfied in the ADIF primary administrative subdivision (PAS) enumeration is a non-conformance with that standard.

Applications that allow non-conforming ADIF to be emitted are non-conforming applications. Specifically, any application that allows uncontrolled user inputs to pass through and be emitted as the value of the MY_STATE field, e.g. permitting a user-suupplied value of California to be emitted as the value of MY_STATE rather than the code value of CA, represents a non-conforming application.

ADIF is a standard which is relevant to application developers, not to end-users who need not be concerned with its complexity and arcana. The responsibility for ensuring an application's conformance with the ADIF standard should never be pushed down and made dependent upon  actions taken at the user level. Rather, it is your responsibility as the application's developer to ensure that user actions do not result in your application generating non-conforming ADIF output.

Allowing non-conforming values to appear in what users are told is an "ADIF file" is unfair to users and makes your application not fit for purpose. Emitting non-conforming values is being uncooperative with the developers of other ADIF-comforming applications.

Non-conformance with the ADIF standard breaks the data portability and cross-application interoperability that describing a file as ADIF was supposed to signify. TQSL cannot guarantee correct and error-free interoperation with non-conforming applications.

QSO_DATE & TIME_ON

A QSO's date and time must be within the date range of the Callsign Certificate used to digitally sign the QSO record. The Callsign Certificate must not have expired.

A recommended minimum set of fields for log data was initially described in ADIF 1 (1996). That set — CALL, QSO_DATE, TIME_ON, BAND, MODE — has since become the de facto standard for the minimum data required to constitute a valid QSO record and (not coincidentally) also comprises the minimum 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 is optional and need not be present in a QSO record for that record to be valid. Since only a single time value need be present for a ADIF QSO record to be considered a valid representation of a QSO (records having a single time value are seen with great frequency), this time value (TIME_ON) must be reporting when 2-way contact was established and a valid QSO resulted 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 is logged. This is certainly the case for DX-peditions and contest-style operations but it is also true for sequenced weak-signal and scatter protocols as well. In all these 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 such were needed) for the common practice of 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 is taken to indicate both: (a) the station is reporting that a 2-way contact took place; and (b) the time at which the logging station believes 2-way contact was established. That is sufficient — if all other 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 in 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" or a QSO in the process of being made — 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 reporting on the time spent calling or exchanging calls and information prior to a 2-way contact being established. That may well represent a systemic deficiency of the ADIF standard. However, the meanings of TIME_ON and TIME_OFF are not mutable and may not be arbitrarily re-purposed in order to compensate for perceived deficiencies in the standard. 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

from

started calling at TIME_ON and finally established contact by 45 minutes later at TIME _OFF

if TIME_ON were in some cases to be unilateraly employed to indicate "started calling at" rather than "established contact at". At least one additional field is necessary to reliably report on the times for three distinct QSO events: "began calling at", "established contact at", and "contact ended at" without introducing indecipherable chaos and confusion.

The 'DI' in ADIF means Data Interchange. To have successful interchange of data requires mutual agreement between programs and programmers on what the data mean. In this case, TIME_ON must consistently be treated as meaning "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.

TQSL cannot guarantee correct and error-free interoperation with non-conforming applications.

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

Mode

When processing a QSO that specifies a mode but not a submode, for example

<MODE:1>M

TQSL will seek an ADIFMAP entry in the current Configuration Data that specifies

adif-mode='M'

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.

Submode

When processing a QSO that specifies both a mode and a submode, for example

<MODE:1>M<SUBMODE:1>S

TQSL will seek an ADIFMAP entry in the current Configuration Data that specifies

adif-mode='M' adif-submode='S'

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 seek an ADIFMAP entry in the current Configuration Data that specifies

adif-mode='M'

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.

Duplicate QSOs

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 be 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 for using this web service because the .tq5 or .tq8 payload being uploaded is self-authenticating, i.e. signed.