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:
|Callsign of the station worked
|Frequency on which you transmitted
FREQ must be present.
|Band on which you transmitted
FREQ must be present. A value for
BAND will be derived from the value of
BAND is absent from record
|Frequency on which you received
|Band on which you received
|mode or mode group
|UTC date on which a valid, two-way QSO was established
|UTC time at which a valid, two-way QSO was established
|requred and set to
SAT for Satellite QSOs; otherwise, optional
SAT; othewise, omit
|The callsign that you used over the air
|The callsign that you used over the air if
STATION_CALLSIGN is absent from record (per ADIF standard since v2.1.5 )
|Your DXCC entity code
|Your Primary Administrative Subdivision (of enumerated type per ADIF standard since v2.1.4 )
|Your Secondary Administrative Subdivision (of enumerated type per ADIF standard since v2.1.4 )
|Your grid square (or grid subsquare)
|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.
|Your CQ zone
|Your ITU zone
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
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 ):
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
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:
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 field has been defined in the ADIF standard as being enumerated type since ADIF v2.1.4 ;
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 recommended minimum set of fields for log data was initially described in ADIF 1 (1996). That set —
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
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
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_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
started calling at
TIME_ON and finally established contact by 45 minutes later at
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
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 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
.tq8 payload being uploaded is self-authenticating, i.e. signed.