Your First Program

This Chapter will get you started using the Control-CForth
language to program your QCard Controller. It will guide you through the
installation of the Mosaic IDE, an integrated editor,
compiler, and terminal, and you'll start up and talk with your
controller. You'll also:

Compile and download your first program using an example multitasking program that performs calculations using floating point
math, stores data in arrays in the QCard Controller's extended memory space,
and prints the results to the terminal;

The Mosaic IDE, which includes the
Control-C Compiler, a full-featured editor and communications terminal,
is provided on an installation CD-ROM. To install it onto your PC, first
insert the Installation CD-ROM into your CD Drive. If the installer does not
launch automatically, browse to your computer's CD drive using the 'My
Computer' icon and double click on 'Setup.exe' to manually launch the
installer.

We recommend that you use the default installation
directory ("C:\Mosaic\") and choose 'Typical Setup' when asked. If you wish to
install into a different directory, you may type in any pathname provided that
it does not contain any spaces. The 'Custom' setup option can be used if
another version of either TextPad (the editor used within the Mosaic
IDE), the Mosaic Terminal (previously called QED-Term), or an
earlier version of the Mosaic IDE has already been installed. However, the
Mosaic IDE requires all of its components to work properly.
Please contact us if you have any questions.

When the installation is complete, you will need to
restart your computer unless you are installing onto a Windows 2000 machine.
Be sure to choose 'Yes' when asked to restart - if you don't, the installation
may not complete properly. If you choose 'No' and restart later we recommend
that to assure a full restart you fully shutdown your computer and then turn it
back on; lesser restarts don't always restart fully.

Familiarize yourself with the locations of the power and
serial connectors as shown in Chapters 1 and 2. After finding them follow
these steps to turn on your system and establish communications with it:

1. Connect the female end of the 9-Pin serial
communications cable to your computer terminal's RS-232 serial communications
port and the male end to the primary serial port on the PowerDock. If you are
not using a PowerDock, but instead are directly connecting to the QCard
Controller, you'll need a 10-pin to dual DB-9F cable (Mosaic Part No.
QED-COM-CABLE-9). You can use any of your PC's COM ports. COM2 is usually
available, but some PCs only have COM1 available. If your computer does not
have an RS-232 serial port, low cost USB-to-RS-232 serial cables are available;
contact Mosaic Industries for details.

2. Power up your PC computer or terminal.

3. You should check the
configuration of your Windows communications drivers:

1. On your PC go to the device manager dialog
box by double clicking "System" in the "Control Panel", clicking the "Hardware"
tab, and clicking the "Device Manager" button.

2. In the list of devices open up the list of
"Ports" and double click on "Communications Port (COM2)". (If COM2 is tied up
with another service, such as a fax/modem, you may want to use COM1 instead.)

3. You'll now have a dialog box called
"Communications Port (COM2) Properties". Click the general tab and make sure
you have these settings:

Property

Value

Baud Rate

19200

Data Bits

8

Parity

None

Stop Bits

1

Flow Control

Xon/Xoff

4. We recommend that you use Mosaic Terminal,
the terminal program that comes with the Mosaic IDE. You can start the
terminal by double clicking the Mosaic IDE executable (the primary application
of the Mosaic IDE) and choosing the terminal toolbar button which looks like
this:

(The appearance of this and other toolbar icons may
change in subsequent versions of the Mosaic IDE.) You can also start the
terminal by double clicking the application "MosaicTerminal.exe".

The terminal starts using COM2 by default at a speed of
19200 baud, no parity, and 1 stop bit. Xon/Xoff flow control is enabled, and
the file transfer options are set so that the terminal waits for a linefeed (^J)
character before sending each line (this is very important). You can use any
other terminal program, but it must be configured with these same settings. If
you use another terminal program, you must specify that it use the linefeed
character as its prompt character. It might be denoted as LF, ^J, ascii
decimal 10, or ascii hex A.

If your PC is set up to use a COM port other than COM2
Mosaic Terminal will respond with a warning box saying "Invalid port number".
If so, just go to the Mosaic Terminal menu item "Settings→
Comm→Port" and choose the COM port you chose when configuring Windows in step 3. above.

5. Verify the baud rate of the Mosaic Terminal by
going to "Settings→Comm→Baud Rate" and making sure that 19200 is
selected. This is the baud rate used to communicate with the QCard
Controller. If the baud rate is incorrect, garbled characters may appear in
the terminal when you try to communicate with the controller.

6. Plug the QCard Controller's power supply into a 110
VAC outlet. European users will need a power transformer for changing European
220 VAC to 110 VAC. Insert the power supply output plug into the power jack on
the PowerDock and turn the power switch ON by moving the power switch towards
the power jack.

1. You should now see the following response:

Coldstart
QED-Forth V4.4x

2. If you hit the enter key while the cursor
is in your terminal window you should see the QCard Controller respond with,

ok

The serial communications responses indicate that your
QCard Controller is now working!

If Something Doesn't Work

If no message appears on your terminal there's something
wrong, so:

1. Verify that power is being properly applied to the
controller.

2. Verify that the serial cable is properly connected.

3. Check the terminal configurations of the Mosaic
Terminal (using the menu item "Settings→Comm"), and recheck the
communications properties of the Windows communications port.

4. Perform a "special cleanup".

Doing a
"Special Cleanup"

If you ever need
to return your QCard Controller to its factory-new condition, just do a Special
Cleanup: With the power on, install jumper J1, press the reset button,
then remove the jumper. This procedure will remove any application programs
and reinitialize all operating system parameters to their factory-new condition.

Using the Editor and
Compiler

The Mosaic IDE has two main components, the TextPad editor, which includes the Control-C compiler, and the
Mosaic Terminal serial terminal program, both of which you'll find in the
default directory "C:\Mosaic\":

TextPad is a fully featured and highly
configurable text and program editor. You'll use it to write and compile your code. All
of the functions of the C compiler tools are available through the controls in
TextPad. You can launch TextPad from the 'Mosaic IDE' group in the 'Programs'
section of your Windows 'Start' menu. For convenience, you may want to place a
shortcut to it on your desktop or on your Windows Taskbar.

Mosaic Terminal is a serial communications
terminal that allows you to interactively control your controller over its
RS-232 interface. You'll also use it to download your
compiled C programs Forth source
code for compilation into the memory of the QCard Controller. Mosaic
Terminal may be launched from the 'Mosaic IDE' group within 'Start→Programs',
but it is also available from within TextPad, either from the 'Tools' dropdown menu or
by clicking the terminal icon on TextPad's toolbar.

You can type characters directly into the terminal
window, and they will be accepted by the QCard Controller's line editor and
interpreter. This mode of interaction is convenient when debugging or typing
short code fragments. If you are sending source code to the QCard Controller,
it is best to create a file first. The file can be saved to disk to provide a
record of your work, and the terminal program can be used to download the file
to the QCard Controller. You can also use the terminal to record your
debugging sessions and save them as a file on disk.

The TextPad Tool Bar

Along with the standard tools you expect in a text editor
you'll find some custom tools available in the toolbar that you'll use to
compile and download your programs. Each of these tools is also accessible in
the 'Tools' dropdown menu of TextPad. For C programmers the Debug icon
calls the C compiler and assembler only, the Single-Page Compile icon
performs a standard build of your program, and the Multi-Page Compile
icon performs a multi-page memory model build of your program. Forth
programmers won't need to use these tools. Both C and Forth programmers will
find the Terminal icon useful; it launches the Mosaic Terminal
program. Each of these tools is described in more detail below.

The 'Debug Tool' Finds Syntax Errors in C Programs

The Debug Tool, designated by the "Magnifying Glass" icon,
invokes the Control-C compiler — Forth programmers do not need to use it
because Forth programs are compiled by the QCard Controller's resident
operating system as they are downloaded. The
Debug Tool, designated by the "Magnifying Glass" icon, invokes the compiler and
assembler only — it does not produce downloadable code. Use it to quickly
check the syntax of a program and find compilation errors without performing
the full build which would be needed to download the program into the microcontroller.

The 'Single-Page Compile Tool' Compiles and Makes a
Downloadable Single-Page C Program

The Single-Page Compile Tool, designated by the "Single-Page"
icon is also for C programmers. It controls how C programs are linked and
stored in memory. Forth programmers do not need to use it. The Single-Page Compile Tool, designated by the
"Single-Page" icon, performs a standard, single-page memory model build of your
program. If you are compiling a program whose compiled size does not exceed 32
Kbytes of memory you should use this mode for fastest execution. Although this
program size is sufficient for many applications, you may need to use the
multi-page build if your application grows beyond 32 K. If you see the
following warning printed in the compiler output, then you must switch to the
multi-page memory model build (using the Multi-Page Make icon):

WARNING: Input section
".doubleword" from 'progname.o11' is not used !

The 'Multi-Page Compile Tool' Compiles and Makes a
Downloadable Long C Program

Forth programmers will also not need the Multi-Page Compile Tool,
designated by the "Multi-Page" icon, which assists in compiling long C
programs. The Multi-Page Compile Tool,
designated by the "Multi-Page" icon, invokes the C compiler's multi-page build
mode. Programs compiled in this mode may be many pages in length limited only
by the amount of FLASH installed in the QCard Controller. It is always a good
programming practice to break large projects into multiple smaller source code
files for organization, and the multi-page build also uses this organization
for distributing the compiled program across multiple 32 Kbyte pages. Thus, no
source code file may contain more than 32 Kbytes worth of compiled source code
or the above warning will be issued and the program will not run. A more
detailed description of this behavior is available in Chapter 4.

You may wonder why there are
both "Single-Page" and "Multi-Page" compile modes. The reason is that C
function calls between pages take just a little longer to execute (calls to
functions on a different page take 49 microseconds while those on the same page
or to common memory take only 11.5 or 13.75 microseconds, respectively).
Because most function calls are to functions on the same page or to common
memory, page changes are rare; the average execution speed of multi-page C applications
is still quite fast.

'Mosaic Terminal' Communicates with Your Product

The Terminal icon launches
the communications program, Mosaic Terminal. When you launch Mosaic Terminal
for the first time, check the communications settings (Settings→Comm) to
verify that the serial port is set correctly for your computer.