QCard C User Guide

Chapter 3

« Previous | Next »

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;

Selectively execute any program function using the QCard Controller's on-board debugging environment (called QED-Forth);

Use the QCard Controller's built-in operating system to access extended memory;

Use the terminal to interact with a running multitasking application; and,

See how easy it is to set up a multitasking application.

Installing the Mosaic IDE and Control-C Compiler

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.

You are now ready to talk with your QCard Controller!

Turning on Your QCard Controller

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:

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".

If you still are having trouble, email or give us a call.

Using the Mosaic IDE

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. 

« Previous | Next »