4. Sample Programs

To help familiarize you with the RabbitCore RCM2100 modules, several sample Dynamic C programs have been included. Loading, executing and studying these programs will give you a solid hands-on overview of the RabbitCore's capabilities, as well as a quick start with Dynamic C as an application development tool.

4.1 Sample Program Overview

Dynamic C comes with a large number of sample programs that illustrate many of its features. These programs are intended to serve as tutorials, but then can also be used as starting points or building blocks for your own applications.

NOTE	It is assumed in this section that you have at least an elementary grasp of ANSI C. If you do not, see the introductory pages of the Dynamic C Premier User's Manual for a suggested reading list.

We have selected five of these sample programs to take you through a complete tour of the capabilities of the RCM2100 modules. They form a learning arc from basic I/O control to advanced TCP/IP issues, including Web serving:

• FlashLED.c
• ToggleLED.c
• FlashLEDs.c
• PingLED.c
• EthCore1.c

Once you have loaded and executed these five programs and have an understanding of how Dynamic C and the RCM2100 modules interact, you can move on and try the other sample programs, or begin building your own.

4.2 Loading and Compiling Programs in Dynamic C

This section gives you a short summary of how to connect the target system, start Dynamic C, and load a sample program. For more details on these topics, refer to Sections 2 and 3 of this manual, and the Dynamic C Premier User's Manual.

4.2.1 Connect Prototyping Board

Section 2.3 provides detailed instructions for setting up the RCM2100 Prototyping Board and making its hardware connections. In summary:

• Install the RCM2100 module on the Prototyping Board;
• Connect the PROG connector of the programming cable to J5 of the RCM2100, and the other end of this cable to your PC's COM port;
• Connect an Ethernet cable to the module's RJ-45 jack, and to a LAN or micro-LAN hub;
• Connect the power supply to the Prototyping Board.

The PWR LED should light up. If it does not, see Section 2.3.

4.2.2 Start Dynamic C

Section 3.4 of this manual provides detailed instructions for installing and starting up Dynamic C.

• Double-click on the Dynamic C icon.

Dynamic C should start and compile the BIOS, completing with a message that reads "BIOS successfully compiled and loaded." If it does not, see Section 3.4.

4.2.3 Load Program

In Dynamic C, use the File | Open menu item to open the file explorer, and double-click on the Samples folder. In that folder, double-click on the RCM2100 folder. In that folder, double-click on the file FlashLED.c.

4.2.4 Compile & Run Program

With FlashLED.c open in a Dynamic C window, press F9 or click on the Run | Run menu item. Dynamic C should compile the program, and when it finishes, LED DS3 on the Prototyping Board should begin to flash.

Congratulations! You've just compiled and run your first Dynamic C program on the RCM2100 module!

NOTE	For a quick tutorial on using Dynamic C's editing, compiling and debugging features, see Section 3 in the Dynamic C Premier User's Manual.

4.3 Sample Program: FlashLED.c

If you did not load and compile FlashLED.c in the prior section, refer to Sections 4.2.3 and 4.2.4.

Program Description

This program is about as simple as a Dynamic C application can get--the equivalent of the traditional "Hello, world!" program found in most basic programming tutorials. If you are familiar with ANSI C, you should have no trouble reading through the source code and understanding it.

The only new element in this sample application should be Dynamic C's handling of the Rabbit microprocessor's parallel ports. The program:

1. Initializes the pins of Port A as outputs.
2. Sets all of the pins of Port A high, turning off the attached LEDs.
3. Starts an endless loop with a for(;;) expression, and within that loop:

· Writes a bit to turn bit 1 off, lighting LED DS3;

· Waits through a delay loop;

· Writes a bit to turn bit 1 on, turning off the LED;

· Waits through a second delay loop;

These steps repeat as long as the program is allowed to run.

You can change the flash rate of the LED by adjusting the loop values in the two for expressions. The first loop controls the LED's "off" time; the second loop controls its "on" time.

NOTE	Since the variable j is defined as type int, the range for j must be between 0 and 32768. To permit larger values and thus longer delays, change the declaration of j to unsigned int or long.

More Information

See the section on primitive data types, and the entries for the library functions WrPortI( ) and BitWrPortI( ) in the Dynamic C Premier User's Manual.

4.4 Sample Program: ToggleLED.c

One of Dynamic C's unique and powerful aspects is its ability to efficiently multitask using cofunctions and costatements. This simple application demonstrates how these program elements work.

Compile & Run Program

Open the source file ToggleLED.c, located in the Samples\RCM2100 folder. Press F9 to compile and run the program.

The LED DS3 on the Prototyping Board will begin blinking. Press switch S2 to toggle LED DS2 on and off.

Program Description

This program uses two costatements to set up and manage the two tasks. Costatements must be contained in a loop that will "tap" each of them at regular intervals. This program:

1. Initializes the pins of Port A as outputs.
2. Sets all the pins of Port A high, turning off the attached LEDs.
3. Sets the toggled LED status variable vswitch to 0 (LED off).
4. Starts an endless loop using a while(1) expression, and within that loop:

· Executes a costatement that flashes LED DS3;

· Executes a costatement that checks the state of switch S2 and toggles the state of vswitch if it is pressed;

· Turns LED DS2 on or off, according to the state of vswitch.

These steps repeat as long as the program is allowed to run.

The first costatement is a compressed version of FlashLED.c, with slightly different flash timing. It also uses the library function DelayMs() to deliver more accurate timing than the simple delay loops of the previous program.

The second costatement does more than check the status of S2. Switch contacts often "bounce" open and closed several times when the switch is actuated, and each bounce can be interpreted by fast digital logic as an independent press. To clean up this input, the code in the second costatement "debounces" the switch signal by waiting 50 milliseconds and checking the state of the switch again. If it is detected as being closed both times, the program considers it a valid switch press and toggles vswitch.

Unlike most C statements, the two costatements are not executed in their entirety on each iteration of the while(1) loop. Instead, the list of statements within each costatement is initiated on the first loop, and then executed one "slice" at a time on each successive interation. This mode of operation is known as a state machine, a powerful concept that permits a single processor to efficiently handle a number of independent tasks.

The ability of Dynamic C to manage state machine programs enables you to create very powerful and efficient embedded systems with much greater ease than other programming methods.

More Information

See the entries for the DelayMs() function, as well as Section 5, "Multitasking with Dynamic C," in the Dynamic C Premier User's Manual.

4.5 Sample Program: FlashLEDs.c

In addition to Dynamic C's implementation of C-language programming for embedded systems, it supports assembly-language programming for very effiicient processor-level control of the module hardware and program flow. This application is similar to FlashLED.c and ToggleLEDs.c, but uses assembly language for the low-level port control within cofunctions, another powerful multitasking tool.

Compile & Run Program

Open the source file FlashLEDs.c, located in the Samples\RCM2100 folder. Press F9 to compile and run the program.

All the LEDs on the Prototyping Board (including DS4 and DS5, if you have installed them) will light. DS2 and DS3 will begin flashing at different rates, and will continue doing so until the program is interrupted.

Program Description

Dynamic C permits the use of assembly language statements within C code. This program creates three functions using assembly language statements, then creates a C cofunction to call two of them. That cofunction is then called within main().

Within each of the C-like functions, the #asm and #endasm directives are used to indicate the beginning and end of the assembly language statements.

In the function initialize_ports( ), port A is initialized to be all outputs while bit 0 of port E is initialized to be an output.

In the function ledon( ), a 0 is written to the port A bit corresponding to the desired LED (0, which equals DS3, or 1 which equals DS4), turning that LED on. The ledoff( ) function works exactly the same way except that a 1 is written to the bit, turning the selected LED off.

Finally, in the cofunction flashled( ), the LED to be flashed, the on time in milliseconds, and the off time in milliseconds are passed as arguments. This function uses an endless for(;;) loop to call the ledon( ) and ledoff( ) functions, separated by calls to the wait function DelayMs( ). This sequence will make the indicated LED flash on and off.

As is proper in C program design, the contents of main( ) are almost trivial. The program first calls initialize_ports(), then begins an endless for(;;) loop. Within this loop, the program:

1. Calls the library function hitwd(), which resets the microprocessor's watchdog timer. (If the watchdog timer is not reset every so often, it will force a hard reset of the system. The purpose is to keep an intermittent program or hardware fault from locking up the system. Normally, this function is taken care of by the Virtual Driver, but it is called explicitly here).
2. Sets up a costatement which calls two instances of the flashled() function, one for each LED. Note that one LED is flashed one second on, one-half second (500 ms) off, while the other is flashed in the reverse pattern.

Note also the wfd keyword in the costatement. This keyword (an abbreviation for waitfordone, which can also be used) must be used when calling cofunctions. For a complete explanation, see Section 5 and 6 in the Dynamic C User's Manual.

More Information

See the entries for the hitwd() and DelayMs() functions in the Dynamic C Premier User's Manual, as well as those for the directives #asm and #endasm. For a complete explanation of how Dynamic C handles multitasking with costatements and cofunctions, see Chapter 5, "Multitasking with Dynamic C," and Chapter 6, "The Virtual Driver," in the Dynamic C Premier User's Manual.

4.6 Sample Program: PingLED.c

One of the RCM2100 series's most important features is the availability of the built-in Ethernet port. This program makes the simplest possible use of the network port by "pinging" a remote system and using LEDs to report the status of the ping attempt and its return.

Compile & Run Program

Open the source file PingLED.c, located in the Samples\RCM2100 folder. Edit the six #define values near the beginning of the file to represent valid network addresses for your setup.

Press F9 to compile and run the program.

NOTE	The RCM2100 must be connected to a network as described in Section 2.3.3, "Connect Ethernet Network Cable," in order for this program to work.

Each time the program sends a ping to the remote address, LED DS2 on the Prototyping Board will flash. Each time a successful return from a ping attempt is received, LED DS3 will flash.

If the ping return is unsuccessful (i.e., the remote system does not exist or does not acknowledge the ping within the timeout period), DS3 will not flash.

With short ping times, as will be encountered in most micro-LAN and LAN settings, the two LEDs should flash almost in parallel as pings are sent and returned.

Program Description

For operation, network addresses must be correctly defined at the start of this program. The most important address to set correctly is MY_IP_ADDRESS, which is the address of the RCM2100 module. (The MY_NETMASK address must be correct as well, but the default of 255.255.255.0 is almost universally used.)

If you wish to ping systems outside the local network, you will have to correctly define the MY_GATEWAY address as well. If you wish to ping systems using domain names instead of IP addresses, a valid DNS server address must be defined for MY_NAMESERVER.

The IP address to be pinged is defined by PING_WHO. You will have to change this address and recompile the program to ping different addresses. (In most real-world applications, there should be some mechanism by which to dynamically define or select addresses.) This address may be defined as a numeric IP address. If a gateway to the Internet and a valid DNS server are specified, this definition may also be a fully-qualified domain name (such as "www.zworld.com").

The program first defines three functions to control the LEDs—one to initialize them, and then one each to drive the "ping out" and "ping in" LEDs.

The program begins by calling the LED initialization function pingleds_setup( ). More importantly, it then calls sock_init( ), which initializes the packet driver and the TCP manager using the compiler defaults. This function must always be called before any other TCP/IP functions.

The program then resolves the address to be pinged into a numeric value. using the library function resolve(). If the defined address is numeric, it converts the define string into truly numeric form. If the address is a domain name, the function queries the indicated DNS server to obtain the numeric address. (If the function is unable to resolve the address—if, for example, the numeric address is incomplete or badly formed, or the DNS server is unable to identify the domain name—the program will print a message to the screen and terminate.)

The program then begins an endless loop using for(;;). Within this loop, the program executes the following steps:

1. Calls tcp_tick( ) to perform the basic housekeeping functions for the socket;
2. As a costatement, waits for the duration of PING_DELAY (defined by default as 500 mS or one-half second), issues a ping to the resolved address using the _ping() function, and flashes LED DS2;
3. As a second costatement, checks for a ping return using the _chk_ping() function. If the ping is successful, the costatement flashes LED DS3.

If you uncomment the #VERBOSE define near the beginning of the program, the ping return costatement will also print a message to the screen indicating each successful ping.

More Information

Refer to the Dynamic C TCP/IP Software User's Manual for complete details on the Dynamic C implementation of TCP/IP protocols.

4.7 Sample Program: EthCore1.c

The RCM2100 modules with Ethernet ports can act as micro Web page servers, with dynamic interaction between the controller and the web pages. This sample program demonstrates how a web page can be used to both monitor and control an RCM2100 module.

Compile & Run Program

Open the source file EthCore1.c, located in the Samples\RCM2100 folder. Edit the three #define values near the beginning of the file to represent valid network addresses for your setup.

Press F9 to compile and run the program.

NOTE	The RCM2100 must be connected to a network as described in Section 2.3.3, "Connect Ethernet Network Cable," in order for this program to work.
NOTE	This program will be more interesting to observe if LEDs DS4 and DS5 are installed in the Prototyping Board.

When the program starts, LEDs DS2, DS3 and DS5 will be lit, and DS4 will be dark. Open a web browser and enter the IP address you defined for the RCM2100 module in the program in the address window. A page like that shown in Figure 8 should appear.

Figure 8. Browser Screen for Sample Program EthCore1.c

Clicking on each of the button images in the browser window will toggle the state of the associated LED image, and will toggle the state of the corresponding LED on the Prototyping Board. Since the web page is generated by the RabbitCore module (using Dynamic HTML), the LED image and the corresponding LED's real state will always be in step.

Program Description

This program begins to show the range of applications for an Ethernet-enabled embedded system controller, so let's look closely at its operation.

As with PingLED.c, several network addresses must be defined before this application can work. The most important is again MY_IP_ADDRESS, which defines the RCM2100 system's IP address. The netmask value should be set if the default of 255.255.255.0 is not correct.

If you are using the system on a local network and will not be trying to access it from outside that network, the MY_GATEWAY value does not matter. If you want to be able to reach the system from outside the local network, you must specify a valid gateway address.

Generally, the other defined values may be left at their default settings. If you are operating the system behind a firewall or proxy and need to specify a host port for redirection, you should comment out the line reading:

#define REDIRECTHOST MY_IP_ADDRESS

Then uncomment the next line, which defines a specific redirection host and port:

#define REDIRECTHOST "my host.com:8080"

Be sure to enter the host port where indicated by "my host.com:8080".

This application creates dynamic HTML web pages on the fly. For simplicity, all of the web page components—shell HTML, image GIFs, etc.—are imported into flash memory using the -#ximport statements. It is also possible to read these files from other locations, including the onboard flash file system, but this application keeps things simple by loading all the components into working memory.

The program then defines four instances of an LED toggling function, which are basic CGI functions that swap the values "ledon.gif" and "ledoff.gif" as the contents of the ledn strings, and then force a reload of the web page to change the associated LED image. The physical LEDs on the Prototyping Board are turned on or off to match the ledn strings displayed on the web page.

More Information

Refer to the Dynamic C TCP/IP Software User's Manual for complete details on the Dynamic C implementation of TCP/IP protocols.

4.8 Where Do I Go From Here?

The Dynamic C \Samples folders contain dozens of sample programs. Some of them are intended for other hardware with somewhat different characteristics, but most can be run on the RabbitCore RCM2100 series modules, either as-is or with some modification.

(All programs in the \Samples\RCM2100 folder will run without changes on the RCM2100 series.)

We suggest that you continue exploring the sample programs, loading, running and modifying them to gain further insight into how to develop embedded system applications using these modules.