YAAC Command-Line Options

There are several options that can be specified on the Java command line when launching YAAC to modify its operation, in addition to standard JVM options. The YAAC-specific options appear on the command line after the -jar YAAC.jar part of the command.

java [-JVM_options] -jar YAAC.jar [-YAAC_options]

The most obvious JVM options relevant to YAAC are the -Xmx and -D options. The former specifies the maximum amount of heap memory Java is allowed to use. For YAAC, this typically should be at least 256m (256 megabytes), and at least 1024 megabytes when importing/compiling the whole-planet OpenStreetMap file, but not exceeding half the available RAM on your computer; thrashing in swap space will impair the performance not only of YAAC but of your entire computer. Smaller heap sizes can be used for tiny systems like the Raspberry Pi if the amount of incoming data (and/or persistence time thereof) is limited.

There are a few YAAC-specific JVM system properties that can be defined with the -D option to override certain defaults (primarily in the OpenStreetMap importer logic), using the -Dpropertyname=value syntax.

property name	value meaning
`user.language`	sets the locale for language rendering and related changes in the YAAC user interface, overriding the operating system default. This can be used if there is a problem in the rendering being done in the default language locale, so you can switch to another. Note that display text strings are only provided in YAAC in English, German (Deutsch), and incompletely in Russian. All other locales default the text to English, but other aspects of the display (such as number formatting) will still be done in the current locale.
`alt.tile.dir`	Specifies the path to a directory where scratch index files for OpenStreetMap data importing are stored. By default, such files are stored in the configured tile directory; this option should be used when another physical disk is available for the scratch files, so that importing will not be slowed by excessive disk head seeks. There is no benefit in specifying this if the system has only one physical disk drive, and potential additional performance impairment if specifying a different partition on the same physical disk drive.
`dated.tile.dir`	Specify when using the File->OpenStreetMap->Download PreImported Tiles command that a different subdirectory on the YAAC author's website should be used to download tiles. By default, the author makes pre-imported tile files available in the `tiledir` subdirectory at the `https://www.ka2ddo.org/ka2ddo/` URL. If, for some reason, the current download is defective, a previous download directory can be used; the naming convention is tiledir_yyyymmdd, where yyyymmdd is the date of the OpenStreetMap download file used to create the tile directory.
`dont.purge.temp`	If the value is "true", don't delete the temporary files when the import is completed. By default, the several gigabytes (potentially) of scratch files are deleted when the import completes. These files are not of use to anyone who is not developing changes to the importer code.
`generate.named.bbox.file`	If the value is "true", generate an additional debugging file during OSM XML import which logs all map bounding boxes at various geopolitical levels. Not functional for PBF imports.
`keep.unrenderable.osm.attributes`	If the value is "true", don't discard certain OpenStreetMap attributes that are helpful in analyzing the OSM data but are not actually used in rendering the map. This will cause generated tile files to be somewhat larger, due to preserving the additional attributes, and will therefore negatively impact OSM rendering times.
`skip.osm.xml.parse`	If the value is "true", go directly to the sorting of imported tiles, skipping the XML or PBF parsing step. This is useful to preserve work if YAAC is shut down after parsing is complete but before the generated tiles are sorted and moved in place of previous versions of the operational `.ways` and `.nodes` files.
`use.multi.osm.thread`	If defined (regardless of what value is specified for the property) and your system has at least 4 CPU cores available to the Java runtime, YAAC will use an alternate version of the OpenStreetMap renderer that uses parallel threads to read the .ways and .nodes files from disk and compute the rendering. Note that this is only useful if you have a slow disk drive and slow multi-core processor, such that YAAC can render while it is reading, rather than alternately reading the map tile files and rendering them in a single rendering thread. This is experimental, and not guaranteed to improve map rendering performance relative to the single-thread renderer.

The command-line options specific to YAAC are:

option name meaning

-profile profilename Run YAAC with the named alternate named configuration profile. By default, YAAC will use the configuration stored in the nameless profile. The name is arbitrary, and can consist of letters, numbers, underscores, hyphens, and a few other punctuation characters; if spaces are used in the name, the name may need to be quoted to prevent the shell from ignoring the part of the name after the first space.

-clear Erase all of the YAAC configuration data for this profile; if for the nameless profile, erase everything (including named profiles). YAAC will behave as if it was newly installed on a clean system, offering the option of running the configuration wizard to initially configure YAAC.

-clearBulletins Erase all persisted bulletin messages originated by this copy of YAAC in this profile.

-clearObjects Erase all persisted object definitions originated by this copy of YAAC in this profile.

-clearPorts Erase all of the interface port definitions (TNCs, GPSs, weather stations, APRS-IS connections, etc.) in this profile. YAAC will ask if you want to run the configuration wizard to define new ports.

-clearWindows Erase all of the memorized positions and sizes of different window types in YAAC in this profile, and let the operating system window manager and YAAC use default placements and sizes.

-debug Turn on all extra tracing messages in the YAAC error log. May impair YAAC's performance due to the extra logging.

-debug:debugcategory[,debugcategory...]

Turn on selected extra tracing messages in the YAAC error log, rather than enabling all debug messages. Categories are specified as a comma-separated list of case-sensitive category names. May impair YAAC's performance due to the extra logging. Some debug categories include:

all - same as specifying just the -debug option without a category list
AGWPE - log state change and keep-alive events in the AGWPE port driver (note this category name is uppercase)
aprs - log APRS protocol events
ax25 - log AX.25 protocol events
awt - log Java Abstract Widget Toolkit (AWT) user interface events
awtmouse - same as "awt", except add mouse events to the logged categories
filter - log filter changes caused by user actions
gps - log GPS debugging events
gui - log YAAC GUI events other than low-level AWT events
nws - log weather alert processing errors
osm - log OpenStreetMap map rendering milestones (used to measure rendering performance)
thread - log process threading events (useful to detect startup race conditions during code development)

Plugins can define additional tracing categories; check their documentation for details.

-gui Force YAAC to try to use a GUI display. By default, YAAC will attempt to open the graphical windows if a graphical environment is available (on Microsoft Windows and Macintosh OS X, or on Linux and Unix systems where an X server is available).

-gui:firstWindowType

Force YAAC to try to use a GUI display (as with the plain -gui option), but starting with the specified type of window. By default, the first YAAC UI window will be the geographical map with the map controls above the actual map and text message sending controls below the map. The available first window types are:

Name	Meaning
map	display the default geographical map window
stationlist	display the Station/Object tabular display window
help	list all the available choices for first windows, then terminate YAAC

Note that some YAAC plugins may provide additional views that are candidates for being first windows, so check their documentation and/or the output from -gui:help to see what choices are available.

-nogui Force YAAC to run without a GUI. Not all functionality will be available. Useful when using YAAC as a stand-alone digipeater or I-gate where a screen is not available or needed, but YAAC must be configured in -gui mode prior to running in -nogui mode.

-storepass password Specify the password for opening the keystore. Necessary when running in -nogui mode when using the SSL APRS-IS port driver, where the authentication credentials must be extracted from the keystore. Note that this can be a security risk, as the password can displayed by system utilities that report the command lines of currently executing commands. If possible, use the -promptpass option instead.

-promptpass Specify that YAAC should prompt for the keystore password at the console used to invoke YAAC. Necessary when running in -nogui mode when using the SSL APRS-IS port driver, where the authentication credentials must be extracted from the keystore. This does nothing if the YAAC startup environment does not have a standard input file to prompt on and read the password from; as such, YAAC will try to prompt in the GUI when the password is required, which will fail if in -nogui mode.

-tempTileDir tiledir_path Specify a non-configured path to the directory tree where pre-imported OpenStreetMap tile files and USGS SRTM terrain files are stored. Typically used only on DVD-ROM or USB memory stick distributions of YAAC, so that sample map data can be provided on the distribution medium.

-version Print out the version of the YAAC program (not counting for any installed plugins) and terminate YAAC.

-version:all Print out the versions of YAAC and every installed and activated plugin, and terminate YAAC. The output is printed as multiple lines; each line is the name of the plugin (first being the core YAAC program), followed by a TAB character ('\\t' or 0x09) and the version string for that plugin.

-callsign Specify the default callsign-SSID for YAAC, in case there wasn't an already-configured port specifying a callsign-SSID. Primarily useful when using the -createportoption.

-createport port_description

check the current configuration, and, if it does not contain a port definition matching the specified port_description string, it will create one, taking the port-specific defaults for any description that is not complete.

The port description string consists of multiple expressions without embedded whitespace (unless mentioned specifically below) separated by semicolon ";" characters. All the semicolons are required even if a particular expression is empty. The first expression (required) will have the following format:

portType,deviceName,baudRateOrPortNumber,callsign,passcode,transmitEnabled[,digipeatAlias[,...]]

where portType is the case-sensitive name of the port driver, such as Serial_TNC, APRS-IS, etc., deviceName and passcode are escaped to be legitimate text in an XML tag body and their meaning is specific to the port type, transmitEnabled is either "true" or "false", and there can be any number of digipeat aliases in the syntax of display-format AX.25 callsign-SSID values.

The second expression is a APRS-IS filter expression. This expression can (and must) have spaces between multiple filters; note that such port_descriptions must be quoted to prevent the operating system shell from breaking the port_description at the space.

The third expression is "true" or "false" for whether this port is enabled for operation, defaulting to "true" if not specified.

The fourth expression is "true" or "false" for whether flow control (or something overloading the meaning of this field) should be enabled or not.

The fifth expression is a decimal number of the value of the acceptableProtocolsMask bitmask. The interpretation is port-type-specific, and should be left at zero for port types that don't use it.

The sixth expression is two decimal numbers separated by a slash "/" character representing the timeslot offset (relative to the top of the cycle) in seconds and the length of the timeslot cycle in seconds. Negative cycle length indicates that timeslotting is not used, but the values are preserved in case the user wants to turn timeslotting back on. An optional third number can be specified to specify the duration of a single timeslot in seconds.

The seventh expression is a decimal number of the value of the flags bitmask, defaulting to zero. Bit meanings are port-type-specific, but generically include the following values:

value	meaning
1	this port is communicating over HF radio bands (and therefore has a more restricted baud rate)
2	for External Message Source port types, indicates that the port is using UDP rather than TCP. For GPS ports, it indicates that remote GPS's should be transmitted as APRS Objects, not just displayed locally.
4	for GPS ports, indicates this is not a local GPS, but a remote one for another location, typically when sending GPS over a non-APRS link to monitor another object, such as an amateur rocket or balloon. For External Message Source ports, indicates that incoming messages should be processed by the local station (as if received) as well as transmitted to other APRS stations.
8	for hardware serial port types, the port should not raise the DTR (Data Terminal Ready) or RTS (Request To Send) modem control signals.
16	for APRS-IS and SSL-APRS-IS ports, retry indefinitely if a network connection fails or was not able to be established in the first place; normally, the reconnection attempts will only be made for a limited number of retries. Useful for deployments where the Internet service may be disrupted for extended periods (such as mobile operation).
32	use port-specific workaround feature. For example, the KISS-over-TCP port and Serial_TNC port types use this to request a certain extra KISS escaping technique to prevent Kenwood TM-D710 radios from interpreting a legitimate character sequence as a frequency change command to the radio.
64	-- not presently used --
128	when using timeslotting, don't coalesce duplicate dynamically-generated packets (such as position beacons and status messages) into a single packet if more that one of the same message type has been queued before the timeslot comes around.
4096	for AGWPE and KISS-over-TCP port types, indicate that the host name/address field is instead a service instance name under DNS-SD Service Discovery (Internet RFC 6763; the Apple implementation is trademarked as Bonjour) and should be looked up to find the destination IP address and port number, rather than being used directly as a domain name of the host.

The eighth expression is a pipe "|" separated list of names of beacon definitions that should be transmitted through this port. Only meaningful for ports capable of transmitting APRS or OpenTRAC packets.

For further details of the exact syntax of the port expression, consult the YAAC source code for the org.ka2ddo.yaac.io.PortConfig class, or the specific subclass of org.ka2ddo.yaac.io.PortConnector for the port type of interest.

Note that the -createport option can be specified multiple times if multiple ports are to be created. Also, some characters (such as the pipe "|" symbol, or whitespace in compound APRS-IS filter expressions) may need to be quoted to prevent shell processing of those characters.

-exit Overrides any default or explicit specification of the -gui option, and shuts down YAAC after evaluating all other command-line parameters. This is primarily useful for installation scripts so that basic YAAC configuration settings that cannot be inferred by YAAC as a default can be configured without leaving the installation script hung where it started YAAC. The -callsign and -createport options are the most useful with this option.