merccc

merccc requires a configuration file to operate. This configuration file specifies the scoring formula and its variables, the competing teams, and other parameters to tailor merccc to the competition. The configuration file specifications can be viewed by running merccc with the --about (shown below) or --format options, or from this website: configuration specs (pretty print)

1.1 File Encoding

merccc configuration files must be encoded in UTF-8. This encoding is backwards compatible with ASCII, so if the configuration file doesn't use any non-basic-Latin characters (i.e. everything is non-accented Latin alphabet), ASCII or Windows ANSI encoding will work. If the user does need to support non-basic-Latin characters, then the configuration file must be explicitly saved as UTF-8 (without BOM). UTF-8 is typically not a problem in Linux systems with proper locale setup.

Windows users will need to use an editor such as Notepad++ to properly edit UTF-8 files. Although the built-in Notepad has an option to save text files as UTF-8, it does so in a way that may cause problems when used with merccc. If Notepad++ is used, the encoding can be changed using the Encoding menu:

The default bitmap text font also does not support non-basic-Latin characters. Refer to §7.2 Fonts on how to use different fonts for the display.

1.2 Example

Below is a very simple example of a merccc configuration file to score a competition with the following formula:

(A-B) * Scaler

This example is going to be used throughout the manual, copy and paste to your favorite text editor and save the file to start playing with the program. Note that the scoring formula has to be converted into postfix format:

[system]
resourcedir=./resources

[formula]
postfix=A B - Scaler *

[fields]
A=Variable A, 0, 3, 30:15:0
B=Variable B, 0, 1
Scaler=Scaling Variable, 1, 0

[tournament]
setup=300 # in seconds
window=600 # in seconds
maxattempts=3

[teams]
5=BGP3 Perseus' Pride, B-G Robotics, 0-badge.jpg
15=A Little Debug Never Hurts, Accredited University, 1-badge.jpg

▸ Not all characters are valid for each configuration entry: identifiers and right hand side values may not contain the following characters: # (hash mark) and , (comma). Additionally, identifiers may not have = (equal sign). Hash marks (#) are used to write comments. Anything after the hash mark will be ignored by the program. Commas are used to separate right-hand side parameters for entries that require multiple values.

1.3 Graphics and Sounds Resources

The resourcedir option specifies where merccc should look for media files associated with the competition. The user must place the following files inside the directory along with any team badges specified in the [teams] section:

logo.png - competition logo
setup-start.wav - sound file to play when the setup period has started
window-start.wav - sound file to play when scoring window has started
window-end.wav - sound file to play when the team runs out of time

▸ A missing resources directory is not fatal to the program: merccc will use the default blue Mercury logo if logo.png is not found. If the sound files are missing, the program will still perform its functions, but no sound will be played. If a team badge image file is missing, the program will not display the image for the team.

The specified resource directory is relative to where the configuration file is located. The directory tree should look like the following:

config.merccc
resources/logo.png
resources/setup-start.wav
resources/window-start.wav
resources/window-end.wav
resources/0-badge.jpg
resources/1-badge.jpg

The configuration file and its resource directory can also be compressed into a ZIP file to simplify distribution and archival of the file. merccc can load the ZIP file directly.

1.4 Scoring

The [formula] section specifies the scoring formula with the postfix option. The formula has to be in postfix notation. The formula can have floating number literals. merccc supports the following operators to calculate a score: + - * / ^ and SQRT.

The variables are defined in the [fields] section. All the variables used in the postfix formula must be specified in this section. The format for a variable entry is as follows:

NAME=DESCRIPTION, DEFAULT_VALUE, TYPE, [POSSIBLE_VALUES]

NAME must correspond with the variable name used in the formula. merccc will use the DEFAULT_VALUE to fill in the value for the variable during scoring when the operator has not entered any other value.

TYPE specifies the kind of variable:

TYPE of 0 is a floating point variable that can take any value. The program will bring up an input dialog for the operator to specify a value for the variable in a scoring session.
TYPE of 1 is a discrete positive integer with minimum value of 0. The program will have +1 and UNDO buttons to modify this variable.
TYPE of 2 or greater means that the variable has this many possible values. For example, a TYPE of 3 will need 3 possible values, delimited by colons, specified in the POSSIBLE_VALUES field. POSSIBLE_VALUES is not required for TYPE of 0 or 1.

The scoring system also supports optional "flags" for each participants that must be met to be classified or designated as the winner. The following is an example that requires the champion to pass "LOS Test Passed" and "Track Finished" flags, and the participants must pass "Track Finished" to be classified:

champion_criteria=LOS Test Passed, Track Finished
classification_criteria=Track Finished

These options must be specified in the [formula] section and can be omitted entirely. The flags can be applied to each team in the classification control tab during the competition.

1.5 Team Definitions

The teams are defined in the [teams] section. Each entry has the following format:

ID=NAME, INSTITUTION, BADGE_FILE

ID is the numeric ID for each team. Each team must have a unique ID number. NAME and INSTITUTION are for human-readability purposes. BADGE_FILE specifies the image file to display for the team. This file must be placed inside the resources directory as specified by the resourcedir entry in the [system] section.

If no badge file is needed, the user can insert a dummy file name for the team.

2. Running merccc ▲

merccc can be run by directly executing the JAR file using the Java Virtual Machine java program:

java -jar <merccc-jar-file> [options]

If the installer was used in Windows, the program can be launched from the Start Menu. The program will bring up a file open dialog that the user can use to choose a configuration file to load.

If the deb package was used in Linux systems, an executable is installed as /usr/bin/merccc. Assuming that /usr/bin is in the user's PATH environment variable, the following command can be used to run and load a configuration file in a typical Linux system:

merccc -c config.merccc

merccc can open the configuration file directly with the -c command line option or by using the file open dialog and opening a file with .merccc extension.

The program can also open a ZIP file containing a configuration file and its associated resources directory with the -z command line option or by using the file open dialog and opening a file with .zip or .merccz extension. The file open dialog will be provided if neither -c nor -z options were provided.

2.1 Command Line Options

Running merccc with the --help option will bring up a list of command line options:

Configuration loading:

‑c	‑‑config FILE	load FILE to configure merccc
‑z	‑‑zip ZIPFILE	load ZIPFILE containing a merccc configuration

If neither option is specified, merccc will present a file open dialog. If no configuration file or a zip file containing a configuration is specified, merccc will not start.

Additional options:

‑f	‑‑format	print configuration file format to console and quit
‑l	‑‑load FILE	load saved .csv data from a previous scoring session
	‑‑help	display help message
	‑‑about	display information about the software
	‑‑localization	display information about text localization
	‑‑font FONT	use the specified FONT instead of the built‑in font
	‑‑ask‑font	list system fonts to use with font selection dialog
‑p	‑‑port PORT	open tcp server socket interface
	‑‑localport PORT	open loopback only tcp server socket interface
‑m	‑‑nosound	disable all audio playback
‑t	‑‑notheme	ignore user's theme defined in the configuration
‑d	‑‑debug LEVEL	set program verbosity for debugging
‑r	‑‑refreshrate TIME	set display refresh rate in milliseconds
	‑‑rendertime	display the time it took to render a frame
	‑‑client	information on using the client mode
‑g	‑‑client-gui	GUI to setup client mode connection
‑x	HOST:PORT	run merccc in client mode

2.2 Keyboard Shortcuts

CTRL+[1‑4]	select active control tab
F1	set output mode to logo and time
F3	set output mode to run status
F4	set output mode to classification
F5	show/hide preview window
CTRL+S	save recorded data set
CTRL+L	load previously saved data set
CTRL+A	add a score without running a scoring session
CTRL+M	toggle sound playback
CTRL+F	change display window font

3. Display Window Controls ▲

After merccc successfully loads the configuration file, the Control Window, shown below, will be brought up. The Control Window is used by the program's operator to control the state of the program, enter scores, manipulate scoring data, save and load scoring data, generate competition report, and control what the Display Window is displaying.

The Display Window should be placed on an external display connected to the host computer. The external display can be an HDTV monitor or a projector to be shown to the audience of the competition.

The bottom of the Control Window has the controls for the Display Window. Click the "Detect" button to enumerate all active displays connected to the computer. The output list will contain all the detected displays and their resolution. When an output display is selected, the program will show the Display Window to the appropriate screen. Choose the "Hide" option to hide the Display Window.

The "Mode" option has three entries: "Logo and Time", "Run Status", and "Classification". The "Logo and Time" will make the Display Window show the competition's logo (logo.png from the resources directory) and the current time in a stylish fashion. The "Run Status" mode will display the current status of the competition. The "Classification" mode will display the current standings of all teams in the competition.

Below is an example output of "Logo and Time" and "Classification" output modes:

4. Scoring Controls ▲

There are four scoring states for the program: IDLE, SETUP, RUN, and POST-RUN. When the program is idle, i.e. no team is active, the "SCORING" tab allows the operator to choose the next team to score and set the number attempts, setup time, and run window time. If the Display Window is currently in "Run Status" mode during the IDLE state, it will display the competition logo, the clock, and a notice of which team is running next (the currently selected team in the Control Window):

4.1 Setup State

When the operator clicks on the "START SCORING SESSION" button, the program will play the setup-start.wav file and start the SETUP state:

If the Display Window is in "Run Status" output mode, the following will be displayed (setup time left and the team badge):

The setup phase can be skipped or paused. The operator can also add or deduct time (in seconds) for the setup if a correction is needed. The add/deduct function can also be done while the timer is paused. When the time is up (or the setup phase is skipped), the program will play window-start.wav and go into RUN state:

4.2 Run State

The operator can score the current performance of the team in this state. The scoring control fields will have the default value for each field. The operator can change this value by clicking the input buttons on the right side of these fields. Once the run is concluded, the operator can click "COMMIT" to have the score recorded by the program. If the team elects to discard the current run and try again for their next run, the operator must click "DISCARD" to nullify the current attempt and start scoring the next one.

When the team runs out of time or attempts, the program will play window-end.wav and go into POST-RUN state. IF the time runs out before the operator can commit the score of the last completed attempt, the operator can do so in the POST-RUN state. The Display Window will show the current best score in "Run Status" mode while in RUN state and POST-RUN states.

5. Data Manipulation and Export/Import ▲

The "DATA" tab displays all recorded scores. The operator can save the data as a .csv file, or load previously recorded data from a .csv file (useful for backing up the data). The operator can also make corrections with the "EDIT" and "DELETE" functions. Making frequent saves is recommended. Just in case. All the data functions can be done during any phase of the program.

The operator can also "ADD" a new data entry from this control tab without having to run a scoring session:

6. Classification Control ▲

The final tab "CLASSIFICATION" shows the current standings in the competition and allows the operator to generate a report text file with final rankings of the teams, scoring data, and the configuration file that was used for the session. The operator can also set a tiebreaker for teams that did not complete a run in the competition (higher tiebreaker value will be placed higher, and the default is the minimum for all teams).

The operator can also set flags (if defined in the configuration) for each team.

The teams must meet the criteria for classification to be ranked, otherwise they will marked with a DNF. DNF teams are ranked by the highest committed score (if any) or the tiebreaker value if no score was committed for a team. Classified teams that did not meet the criteria to be a champion will be noted with an asterisk.

Finally, the operator can control the ranks that are displayed in the Display Window in "Classification" output mode.

7. Customization ▲

Some aspects of merccc can be customized to tailor the program to the competition better. This section only covers some customization options. Refer to the configuration file specifications for the full extent of what is possible.

7.1 Options Menu

The Control Window has an options menu that can be used to change how the program behaves:

Unchecking the "Play sounds" menu item will mute all audio playback by the program. The "Preview window" is a window that has a thumbnailed view of the output Display Window. The preview window can be useful to the operator if he or she can not actually see the output display while operating the program and still wanting to be aware of what the program is displaying.

7.2 Fonts

By default, merccc will use the built-in bitmap fonts. The bitmap fonts do not support non-basic-Latin characters, and if such support is required, a font provided by the Operating System must be used. Fonts can be specified in the [theme] section of the configuration file with the systemfont option. It can also be specified from the command line by using the --font <font_name> or the --ask-font options. The font of the output display can also be changed by using the "Select font..." option from the options menu that will bring up the following font chooser dialog:

Fonts can be changed at anytime.

7.3 Score Field Number Format

The format of the score fields in "Run Status" mode during a scoring run can be customized in the [display] section of the configuration file. For example, the following configuration will individually format a variable:

[display]
A=2,0
B=2,0 # two digits and no decimal digits
Scaler=1,1 # one digit and a decimal digit

The configuration above will result in the following "Run Status" display:

7.4 Font Scaling

The following options in the [theme] section will scale the text and digits in the Display Window (default values shown, values are in proportion to the screen height):

digitsheight=0.10
smalldigitsheight=0.07
textheight=0.06

The following screenshot shows what elements get scaled by each option:

7.5 Logo Positioning and Scaling

The following options in the [theme] section will position and scale the logo Display Window in "Logo and Time" display mode (default values shown, values are in proportion to the screen height):

logoheight=0.40
logoposition=0.40

The program supports displaying a banner in the Display Window. The banner can be a sponsorship image or any miscellaneous art. The banner will be displayed when the program is idle and during setup period:

The banner is specified by the banner option in the [theme] section of the configuration file. The image file must then be placed in the resources directory. The banner will be scaled by the program accordingly.

The banner can be hidden at anytime using the Options menu in the Control Window

7.7 Colors

The colors used in the program can be changed using the [theme] section of the configuration file. The color configuration entry takes comma-separated RGB values in decimal (e.g. 127,0,255). The following table lists the colors used, the configuration entries, and the default colors:

Color	Configuration Entry	Default
Foreground Primary	primarycolor	32,187,255
Foreground Secondary	secondarycolor	255,126,48
Foreground Alternate	altcolor	255,255,255
Background	bgcolor	0,0,0
Table Light Background	tablebgcolor	5,32,80

The foreground colors will also colorize the bitmap digits and text fonts. Table Light Background color is the color used to alternate row colors in Classification output mode table.

7.8 Background Image

merccc supports displaying a background image by using the following configuration entries in the [theme] section:

bgimage=file.jpg
bgalignment={0 to 6}
bgscaling={0 to 2}

The image file must be placed inside the resources directory. The alignment option value corresponds to the following positions:

The scaling value of 0 means no scaling, 1 is fit the width of the image to the screen, 2 is fit the height of the image to the screen.

8. Localization ▲

The text in the Display Window is written in English by default. The configuration file can override the text with the [localization] section. Run the program with --about option and select "Localization Information" for details or run the program with --localization to print this information to the console.

9. TCP Server Socket Interface ▲

merccc has a TCP socket interface that can be used to gather information about the program remotely. The interface also has a monitor mode where the remote client can listen to changes on the control software as it happens. Refer to the TCP Socket Interface Documentation for details on the communications protocol.

The server is invoked by using the -p <port_number> option for a publicly accessible connection, or --localport <port_number> for loopback only port.

9.1 Display Client Mode

The TCP socket interface can be used by merccc itself to display information from a remote merccc instance running the TCP server socket interface. This is accomplished by using the -x command line option on the local machine:

java -jar <merccc-jar-file> -x <host>:<port_number>

<host>:<port_number> is the address and port where the server instance is running (with the -p or --localport options). The client will then try to attempt to connect and fetch the configuration from the server and ask the user to select which active display should be used for the output. The active displays and their resolutions will be listed:

Resources will not be transferred by default! If connection is successful, the client instance will create a Display Window on the selected local display or screen and reflect everything the server instance (that is controlled by the operator) is doing.

The client instance can load its configuration and resources locally, but the configurations between the local and remote instances must match! The client will perform a hash on its local configuration and request a hash of the server's configuration and make a test. If the hashes do not match, the client will refuse to run. The -c or -z options can be used to load a local configuration, e.g. with the server running -p 19000:

java -jar <merccc-jar-file> -c config.merccc -x 192.168.1.177:19000

or:

java -jar <merccc-jar-file> -z config-archive.zip -x 192.168.1.177:19000

To enable transferring of resources, the --copyresources option must be used on both the server and client. If both ends use this option, the client will ask the user where to put the copied resources and load the resources after they are download.

The client display can also be locked into a specific display mode. While locked, the operator controlling the server instance can change the output display modes and the client will not change its own mode. The locking is accomplished using the --lockmode <mode> option where mode is 0 for "Logo and Time", 1 for "Run Status", and 2 for "Classification".

Caveat: the client can only connect to the server while the server is in IDLE state to prevent incoherent local state. The client will refuse to connect if the server is not in IDLE state.

10. Building from Source

The source to merccc can be obtained from github:

git clone https://github.com/wheerdam/merccc

To build the program using ant:

cd merccc
ant package-for-store

The built jar package will be located in store/MercControl.jar.

The package build scripts require bash. To build the deb package (fakeroot is required to build the package):

cd distrib
./build-deb.sh

To build the Windows installer (requires launch4j and makensis from NSIS):

# edit build-win.sh so $LAUNCH4J points to the directory that contains launch4j

./build-win.sh

To clean source directory of build files:

./clean.sh

◄ Go Back ▲ Back to Top