Overview
Aether includes the built in ability to track several awards. It is also possible to create custom award definitions to allow tracking additional awards. This page describes how to create these custom awards definition files. Note that this feature is intended for advanced users of Aether. This feature was introduced in version 1.6.3 of Aether and is not supported in earlier versions.
File Format
Aether awards definition files are plain text files whose contents are JSON data. The top level item in the JSON file must be a dictionary whose contents describe the award being defined. The order of fields in the dictionary is not important. An awards definition file may only contain the definition of a single award. For example, for a DXCC award definition, the contents of the file would be:
{
"awardName" : "DX Century Club",
"awardShortName" : "DXCC",
"awardSponsor" : "ARRL",
"awardWebsite" : "http:\/\/www.arrl.org\/dxcc",
"numberOfQSOsRequired" : 100,
"mainQualifierKeyPathInQSO" : "callbookInfo.dxcc",
"additionalRelevantKeys" : [
"callbookInfo.country"
]
}
A detailed description of the available fields, their purpose, and example values are given in the Award Definition Fields section of this page.
A JSON linter like jsonlint.com can be used to verify that your file is correctly formatted according to the JSON standard. Note that this does not verify that e.g. the field names Aether expects are correct, merely that the file is structurally correct.
Files must be saved with the extension .awardsdef to be recognized by Aether. See the Loading Into Aether section below for details on installing a custom award definition file in Aether.
I've posted the awards definition files that Aether ships with on GitHub: https://github.com/armadsen/AetherAwards . They can be used as reference examples when creating your own custom award definition files. You can also modify these files and load them to customize tracking for the built in awards.
Award Definition Fields
Awards definitions in Aether include several fields. The table below lists these fields, including a description of the field's purpose, and whether or not it is optional. The descriptions use the example of the ARRL's Worked All States award to illustrate how they work.
| Field Name | Description | Optional |
|---|---|---|
| awardName | Full name of the award (e.g. "Worked All States") | NO |
| awardShortName | Abbreviated name of the award (e.g. "WAS") | NO |
| awardSponsor | Name of the award's sponsor (e.g. "ARRL") | YES |
| awardWebsite | URL for the award's website (e.g. "http://www.arrl.org/was") | YES |
| mainQualifierKeyPathInQSO | QSO key path for main qualifier value (e.g. "callbookInfo.state") | NO |
| numberOfQSOsRequired | Number of QSOs required to receive the award (e.g. 50) | YES |
| achievementLevels | List of number of QSO thresholds for additional achievements | YES |
| possibleMainKeyValues | Possible values for the main qualifier value (e.g. List of the 50 states) | YES |
| additionalRelevantKeys | Key paths for values to show as additional columns in the awards window | YES |
| uniquingKeys | Key paths for values that cause QSOs to be treated as unique | YES |
| requiredFixedKeysAndValues | Key paths and corresponding values that must be set for a QSO to count | YES |
| startDate | First date for QSOs to be considered to count for the award. YYYY-MM-DD | YES |
| endDate | Last date for QSOs to be considered to count for the award. YYYY-MM-DD | YES |
Some of these fields, like awardName are fairly self explanatory. For those that are not, see the detailed descriptions below.
mainQualifierKeyPathInQSO
This field is a key paths for the main qualifier value for the award. The main qualifier value for an award is the value that must be unique for each QSO in the award. For example, for Worked All States, it's the contacted station's U.S. state. For DXCC, it's the DXCC entity number. For Worked All Zones, it's the CQ zone.
This field is the most important one in an awards definition file and is required.
achievementLevels
This field is an array (a list) of additional achievement levels for the award. For example, the RSGB IOTA program offers awards for confirmed QSOs with 100 islands, 200 islands, 300 islands, and so on. Using the achievementLevels field, a single award definition can be used to continually track progress toward the next achievement level you're working on.
This field is optional. When the achievementLevels field is present, the awards tracking window will show your progress to the next level beyond that you've already achieved (based on confirmed QSOs in your log).
possibleMainKeyValues
In some cases, it is desirable to make the awards tracking system only accept QSOs whose main qualifier value is one of a predefined list of valid values. For example, for Worked All States, this is a list of all 50 states. For IOTA, it could be a list of all registered IOTA designators, etc. This field is optional, and if it is not included, any (non-empty) value for the main qualifier key path will be considered valid.
additionalRelevantKeys
The additionalRelevantKeys field is a list of key paths for values that are interesting or relevant but which are not used for the actual awards tracking calculations. Aether will display columns for these key paths in the QSO table in the awards tracking window. Aether uses this field for the USA Counties award to also show each QSO's state.
uniquingKeys
For some awards, multiple QSOs with the same main qualifier value should be counted towards an award. For example, for the 5 Band DXCC award, up to five QSOs with the same DXCC entity may be counted as long as they're on separate bands.
The uniquingKeys field is an optional list of key paths. If any of the values for these key paths differ between two QSOs being considered for awards tracking, both QSOs will be considered unique and valid contributions to the award.
To illustrate, consider an award where this list includes "band", and the mainQualifierKeyPathInQSO is callbookInfo.dxcc. In this case, two QSOs with a DXCC number of 291, where the first has a band of "20m", and the other is "40m" will both be counted toward the award.
requiredFixedKeysAndValues
For some awards, it can be useful to require one or more key paths to have one of a predefined list of valid values, even though these key paths are not used directly in the awards tracking calculations.
The requiredFixedKeysAndValues field is a dictionary whose keys are key paths, and whose values are arrays/lists of allowable values for the corresponding key path.
For example, for Worked All States, this field is used to specify that QSO's must have a country value of "United States", "USA", "US", etc. to be considered valid. That way, QSOs with other countries will not be considered valid for the award, even if they happen to have an otherwise valid two letter state abbreviation filled in for their state.
startDate and endDate
If you'd only like to consider QSOs made in a specific date range, you can specify the startDate and/or endDate. Both take a string of the format YYYY-MM-DD. For start date, any QSO made after 00:00 UTC (ie midnight) on that date are considered valid. For end date, any QSO made before 23:59 UTC on that date are considered valid. You can omit either date to specify an open ended range, and you can omit both to avoid restricting QSOs to a certain date range. Note: This feature is only available in Aether 1.6.11 or later.
Key Paths
Several of the fields in an award definition have a value that is a key path for a QSO. The table below lists the key path for several common values. If one you'd like to use isn't listed here, please contact Aether support for assistance.
| Value | Key path | Type | Example Value |
|---|---|---|---|
| Callsign | callsign | String | "AC7CF" |
| Operating Mode | mode | String | "CW" |
| Frequency (in MHz) | frequency | Number | 14.060 |
| Band | band | String | "20m" |
| State | callbookInfo.state | String | "UT" |
| County | callbookInfo.county | String | "Salt Lake" |
| Country | callbookInfo.country | String | "United States of America" |
| Grid Square | callbookInfo.gridSquare | String | DN40br |
| DXCC Number | callbookInfo.dxcc | Number | 291 |
| CQ Zone | callbookInfo.ituZone | Number | 6 |
| CQ Zone | callbookInfo.cqZone | Number | 5 |
| IOTA island | callbookInfo.iota | String | "NA-065" |
Loading Into Aether
To load an awards definition file into Aether, drag it onto Aether's icon in the Dock. You'll be asked if you'd like to install it. Click Install, and Aether will install it for you. You can also manually install awards definition files by copying them into ~/Library/Containers/com.openreelsoftware.aether/Data/Library/Application Support/Aether.
Note that currently, if an awards tracking window is already open, it will not show a newly installed award. To workaround this, you should quit and restart Aether after installing a new awards definition file. This is a limitation that will be fixed in a future release of Aether.