CrystalControl2 (CC2)
Programming GUIDE

By Jim Clark, a.k.a. jc634

Overview

In the absence of a screen editor, I thought it might be handy to have a basic/general programming guide for writing CrystalControl2 (CC2) screens. Most of this information can be found in the sample files that are included with CC2. The latest version of CC2 is at http://www.crystalfontz.com/forum/forumdisplay.php?s=&forumid=20.

CC2 programming syntax consists of writing information in various sections. This information provides CC2 commands to modify what you want to display on your LCD. This guide does not describe how to install CC2, use the configuration screen, etc. Please read the CC2 manual, which can be downloaded at http://www.crystalfontz.com/forum/showthread.php?s=&threadid=3251 for this information.

Enjoy your LCD module. They are quite fun, and can provide an almost endless amount of information about your computer, local weather, and just about anything else you can imagine.

If you write a screen you like, please upload it to the User Screens forum located here: http://www.crystalfontz.com/forum/forumdisplay.php?s=&forumid=24.I have taken many screens that other users have written and learned something from them. I added the unmodified screen to my LCD or modified it to incorporate my “personal” touch.

Once Crystalfontz releases the CC2 GUI Screen Editor, this guide might make a nice reference but most of the information should not be required.

Disclaimers

· This guide is not written by Crystalfontz employees. Please do not berate CF if you find errors.

· If you find errors, omissions, or have additional useful information, please post in the forums or PM me.

· Please note that this is a just a “GUIDE”; it is not a definitive programming manual.

For More Information

For more information on Crystalfontz displays, please go to http://www.crystalfontz.com/.


CONTENTS

Basic Screen File Syntax 3

screen file naming convention 7

CC2 PLUG-INS 8

CUSTOM DISPLAY PLUG-INS 10

SYSTEM AND PROGRAM INFORMATION PLUG-INS 16

CC2 SYSTEM PLUG-IN 16

RIVATUNER PLUG-IN 16

FRAPS PLUG-IN 17

SPEEDFAN PLUG-IN 17

TIMEDATE PLUG-IN 18

MOTHERBOARDMONITOR PLUG-IN 18

WINAMP PLUG-IN 19

FOOBAR2000 PLUG-IN 20

EMAIL PLUG-IN 21

GAMES PLUG-IN 22

PERFORM PLUG-IN 23

PROCESS PLUG-IN 23

TEXTFILE2 PLUG-IN 23

THE SCAB MODULE 25

ADVANCED TOPICS 29

LCD BUTTON PROGRAMMING 29

KEYBOARD PROGRAMMING 33

CFA-635 LED PROGRAMMING 34

CMAP CHARACTERS 35

USER WRITTEN PLUG-INS AND SAMPLE SCREENS 37

USER WRITTEN PLUG-INS 37

SAMPLE SCREENS 37

cc2_cchar Sample Screens 37

Speedfan Sample Screens 37

cc2_ bigchars Sample Screens 37

cc2_hbar Sample Screens 37

cc2_histogram Sample Screens 38

cc2_showgif Sample Screens 38

CC2_System Plug-In 38

Rivatuner Plug-In 38

Fraps Plug-In 38

Timedate Plug-IN 38

Motherboardmonitor Plug-In 38

Winamp Plug-In 39

Foobar2000 Plug-In 39

Email Plug-In 39

Games Plug-In 39

Perfmon Plug-In 39

Textfile2 Plug-In 39

SCAB Module 39

Basic Screen File Syntax

CC2 screen files are divided into various sections. CC2 interprets the information in these sections to write information to the LCD display. This is the VERY basic programming syntax required to communicate information to be displayed on a Crystalfontz display from CC2.

The basic sections are as follows:

[pre]

The information under this section tells CC2 your LCD type.

Example:

4 row, 20 column display

Appropriate values:

rows = 4 (634, 635) rows = 2 (631, 632, 633)

cols = 20 (631, 634, 635) cols = 16 (632, 633)

[screen]

General screen information is contained under this section.

Example:

screen_name is the information displayed in the CC2 Configuration screen.

options = 0 is to set the default justification. Default justification will be left justified, unless otherwise specified in row options or item options (see below).

alt_delay is to set how long this screen will display before going to the next screen when CC2 is set to scroll thru the screens.

[r00]

Row header. This designates the beginning of a row. General row syntax is contained under this section. The first row is r00, second row is r01, and so on. Note: they must contain both characters (00, for example).


Example:

options = 10 Right Scrolling will be used for this line.

scroll_speed = 2000 The speed at which the line will scroll.

CC2 line (and [screen]) justification options are:

Row Right Justify 01

Row Center 02

Row Scroll Center 04

Row Scroll Left 08

Row Scroll Right 10

The Scroll options may be used with the scroll_speed option.

[r00-i00]

Item header. This designates an item (character or graphics) to be displayed by CC2. In the above, this is the first item to be displayed on the first row. Again, both designator characters are required (00, for example).

Example:

[r00-i00] First item in the first row. Again, both characters (00, etc.) are required.

options = 10 Display this item (text) scrolling right within its allotted space.

length = 7 This item (text) will be displayed within a spacing of 7 characters.

scroll_speed = 1000 Speed at which this text will scroll.

string = "CPU"Actual text to be displayed for this item. Using these options, the text would be displayed and scrolled in the indicated string length as follows:

"CPU” (without the quotes).

The length function is handy when you wish to fill/format a section of the display.

Example:

JIM, PLEASE CHECK THIS

This will fill a section of your display with 10 spaces.

CC2 item justification options are:

Item Right Justify 01

Item Center 02

Item Scroll Left 08

Item Scroll Right 10

As noted above, these options may be used with the scroll_speed and length options.

To display additional information on the first line, use the following:

r00 designates the first row, i01 designates the second item on this row.

A VERY basic screen file using hard-coded text:

[pre]

rows=4

cols=20

[screen]

screen_name="jc_CPU"

options=0

alt_delay=5000

[r00]

options=0

[r00-i00]

string="Powered by"

[r01]

options=0

[r01-i00]

string="Intel"

[r02]

options=0

[r02-i00]

string="Pentium 4"

[r03]

options=10

[r03-i00]

string=”3300”

[r03-i01]

string=" MHz"

This is how the screen file would look on your LCD display:

screen file naming convention

You can be as descriptive as you want when naming screen files. To help organize my screen files, I normally preface files I have written or modified by adding “jc_” to their name. Also, I try to name my screen file the same as the screen_name variable.

CC2 has several rules for screen file extensions. Here is a list of these extensions and a description of when to use them:

· .1602
Designates a screen file for a 16 x 2 LCD display. This includes the CFA-632 and CFA-633.

· .2002
Designates a screen file for a 20 x 2 LCD display. This includes the CFA-631.

· .2004
Designates a screen file for a 20 x 4 LCD display. This includes the CFA-634 and CFA-635.

· .cfaxxx
Designates a screen file a specific LCD display. For example, .cfa635 would be the extension to use specific to the CFA-635. These extensions are used when you include information specific to that LCD. On a CFA-635, this might represent code you included for button commands or SCAB information.

CC2 PLUG-INS

CC2 includes several modules (plug-ins) to provide additional display formats, display graphics, and to obtain data from various programs and system variables. Information to be obtained from plug-ins is written into [fromxx] statements, where xx starts with 00.

In this example, RED highlights a static ID and BLUE highlights a dynamic ID where they are defined and used:

CC2 uses id numbers (instead of hard-coded text) to designate information to be displayed. Program plug-ins (i.e., Speedfan) typically have static id numbers. Display plug-ins use user generated ids. In the above example, opt01="temp02=2143662286”. This is a static id number.

opt02="id=@01" is an example of a user generated id number. A screen file may have several user generated id numbers. Id=@xx starts with 01 and each id=xx must be unique to a particular screen file.

Use the id=xx in lieu of the string function to display variables text.

Using the above code, here is an example of display information:


The id=@01 would display the custom character generated by the cc2_cchar plug-in. In this case, it would look like a degree symbol.

To display the speedfan temp, the item information would be:

CUSTOM DISPLAY PLUG-INS

Custom display plug-ins can display up to eight 6 x 8 special/custom characters. This is a limitation of the hardware/firmware in Crystalfontz displays.

The following CC2 plug-ins are provided to allow additional display options/formats and graphical information.

cc2_bigchars provides the ability to display characters of an item in BIG character format over two lines using four custom characters on the top line and four custom characters on the bottom line. The example displays CPU usage in Big Character format.

Example:

To display this information, the code would be written as follows:


cc2_cchar provides the ability to program/display custom characters.

Example:

This code will produce a degree symbol. The –‘s produce a blank space and the 8’s produce a filled space.

The following example can be used to display multiple custom characters. This data came from a “Running Man” screen written by daks001:

Up to 8 special characters may be defined using this plug-in.


cc2_hbar provides the ability the display horizontal bar graphs.

Example:

Normally, you only need to change 2 of the above lines. In the opt01 line, the id=@01 may change, depending on how many id #’s you are using in a screen file. Change opt03 line to the length you want for the bar. On 16 column displays (CFA-632 and CFA-633), the maximum length of the bar graph would be 16.

Using the characters defined in the opt10 to opt27 lines, the output would look like this:

cc2_histogram provides the ability the display horizontal histograms.

Example:

Normally, you only need to change 2 of the above lines. In the opt01 line, the id=@01 references the information you want to display as a histogram. Change the opt03 line to the length you want for the histogram bar. The maximum length would be 16 or 20, depending up on the type of display.

Change the opt08 line value if the histogram is too slow or fast. Change the opt09 and opt10 lines if the information to be displayed has a value range different than 0 to 100.

A histogram would look like this:

cc2_showgif provides the ability the display GIF files.

The ability to display GIF files is based upon the eight 6 x 8 pixel limitation. A GIF file may be any the following sizes:

48 pixels wide x 8 pixels high (1 row x 8 chars)

24 pixels wide x 16 pixels high (2 rows x 4 chars)

18 pixels wide x 24 pixels high (3 rows x 2 chars)

12 pixels wide x 32 pixels high (4 rows x 2 chars)

GIF files I have created or used have been 24 x 16.

Here is an example of how to program a [fromxx] statement for a GIF file:

Depending on the size of the GIF file (# of row and columns), change the idRowx code as well as the width and height statements.

Opt 07, 08, and 09 lines requires a little more explanation. If you have a static (non-animated) GIF, 1 is the start and 1 is the end. Delay is meaningless. If you have an animated GIF, change the values accordingly. Start is the first frame you want to display. End is the last frame you want to display from the GIF file. Delay is the time between GIF frames.

Note: To determine the End value, you must know your GIF! Do not make this value larger than the number of frames in the GIF file. In order to determine how many frames an animated GIF file has, right-click on the file, click on Properties, click on Summary, and note the Frame Count value. The End cannot be higher than this value. Normally, I use the default Start and Delay values.

The opt10 tells CC2 the name of your GIF file and where you stored it. Please note the double \\’s. CC2 uses the \ as an escape character to define special characters. For example, \128 can be used in lieu of the cc2_cchar in the example above to display a degree symbol. In order to tell CC2 you want to use a \, you must type in a \\ to designate a \.

SYSTEM AND PROGRAM INFORMATION PLUG-INS

CC2 provides the ability to display various system variables and other program information through several plug-ins. These plug-ins contain static id numbers to use in your screen files. These plug-ins are listed below.

CC2 SYSTEM PLUG-IN

CC2 has several built-in system information variables included in the CC2_sysinfo plug-in. These variables are:

3206762360 = CPU Speed (updated every second)

1976281390 = Physical Memory Total (mbytes)

3933404336 = Physical Memory Remaining (mbytes)

427577619 = Physical Memory Used (mbytes)

1405082188 = Physical Memory Used (percent)

583466298 = Page File Total (mbytes)

3114568835 = Page File Remaining (mbytes)

3426372789 = Page File Used (mbytes)

719852342 = Page File Used (percent)

3695144023 = Virtual Memory Total (mbytes)

2586301874 = Virtual Memory Used (mbytes)

1733937101 = Virtual Memory Remaining (mbytes)

1718984274 = Virtual Memory Used (percent)

Simply use the above id numbers in a screen file to display the desired information.

For example, to display CPU Speed on a LCD line, include the following in a screen file:

In this example, CPU speed would be the first item displayed on the second line.

RIVATUNER PLUG-IN

CC2 has several built-in information variables included in the CC2_rivatuner plug-in. In order to use this data, you must have Rivatuner installed and running. These variables are:

455143046 = Core (GPU) Clock Speed

3219935972 = Memory Clock Speed

2701541562 = Core Temperature

587540593 = Ambient (Case or PCB) Temperature

1701432209 = Fan Duty Cycle

3317019095 = Core Voltage

2571469204 = CPU Temperature (limited support)

Use these static id numbers as desired, similar to the example in the System Variables section above.

You may obtain the latest version of Rivatuner at http://www.guru3d.com/rivatuner/.

FRAPS PLUG-IN

CC2 has several built-in information variables included in the CC2_fraps plug-in. In order to use this data, you must have Fraps installed and running. These variables are:

1245223672 = Current FPS Rate

188611884 = Game Name

281064427 = Total Fram Count

Use these static id numbers as desired, similar to the example in the System Variables section above.

You may obtain the latest version of Fraps at http://www.fraps.com/.

SPEEDFAN PLUG-IN

CC2 has several built-in information variables included in the CC2_speedfan plug-in. In order to use this data, you must have Speedfan installed and running. These variables are:

temperature sensors (up to temp32)

temp01 = 1121532333

temp02 = 2143662286

temp03 = 2175758444

temp04 = 170285134

fan rpm readings (up to fan32)

fan01 = 962694859

fan02 = 3520374012

fan03 = 2869593465

fan04 = 2061411185

voltage readings (up to volts32)

volts01 = 249415841

volts02 = 2891227368

volts03 = 4160193155

volts04 = 1279566055

The above are examples of information obtained from Speedfan by CC2 and stored in the cc2_speedfan.ini file.