4. DeviceMate Sample Programs

4.1 Ethernet Network Cables

Before proceeding you will need to have the following items.

• If you don't have Ethernet access, you will need at least a 10Base-T Ethernet card (available from your favorite computer supplier) installed in a PC.
• Two RJ-45 straight through Ethernet cables and a hub, or an RJ-45 crossover Ethernet cable.

The Ethernet cables and Ethernet hub are available from Z-World in a TCP/IP tool kit. More information is available at www.zworld.com.

4.1.1 Ethernet Connections

• If you do not have access to an Ethernet network, use a crossover Ethernet cable to connect the hardware platform to a PC with at least a 10Base-T Ethernet card.
• If you have Ethernet access, use a straight Ethernet cable to establish an Ethernet connection to the hardware platform from an Ethernet hub.

The PC running Dynamic C through the serial port on the hardware platform does not need to be the PC with the Ethernet card.

Figure 8 shows the two connections described above.

Figure 8. Ethernet Connections

4.1.2 Ethernet Networks

The DeviceMate hardware platform uses a 10Base-T type of Ethernet connection, which is the most common scheme. The RJ-45 connectors are similar to U.S. style telephone connectors, except they are larger and have 8 contacts.

An alternative to the direct connection using a crossover cable is a direct connection using a hub. The hub relays packets received on any port to all of the ports on the hub. Hubs are low in cost and are readily available. The hardware platform uses 10 Mbps Ethernet, so the hub or Ethernet adapter must be either a 10 Mbps unit or a 10/100 unit that adapts to either 10 or 100 Mbps.

In a corporate setting where the Internet is brought in via a high-speed line, there are typically machines between the outside Internet and the internal network. These machines include a combination of proxy servers and firewalls that filter and multiplex Internet traffic. In the configuration below, the hardware platform could be given a fixed address so any of the computers on the local network would be able to contact it. It may be possible to configure the firewall or proxy server to allow hosts on the Internet to directly contact the controller, but it would probably be easier to place the controller directly on the external network outside of the firewall. This avoids some of the configuration complications by sacrificing some security.

Figure 9. Typical Corporate Network

If your system administrator can give you an Ethernet cable along with its IP address, the netmask and the gateway address, then you may be able to run the sample programs without having to setup a direct connection between your computer and the hardware platform. You will also need the IP address of the nameserver, the name or IP address of your mail server, and your domain name for some of the sample programs.

4.2 Running TCP/IP Sample Programs

We have provided a number of sample programs demonstrating various DeviceMate uses. These programs require connecting the PC and the hardware platform together on the same network. This network can be a local private network (preferred for initial experimentation and debugging), or a connection via the Internet.

Obtaining IP addresses to interact over an existing operating network can involve a number of complications, and must usually be done with the cooperation of your ISP and/or network systems administrator (if your company has one). For this reason, we recommend that your first efforts be done via a direct connection between a PC and the hardware platform using an Ethernet crossover cable or a simple arrangement with a hub. (A crossover cable should not be confused with regular straight through cables.)

In order to set up this direct connection, use a virgin PC (right out of the box), or disconnect a PC from the corporate network, or as yet another approach install a second Ethernet adapter and set up a separate private network attached to the second Ethernet adapter. Disconnecting your PC from the corporate network may be easy or nearly impossible, depending on how it is set up. Mobile PCs, such as laptops, are designed to be connected and disconnected, and will present the least problem. If your PC boots from the network or is dependent on the network for some or all of its disks, then it probably should not be disconnected. If a second Ethernet adapter is used, be aware that Windows TCP/IP will send messages to one adapter or the other, depending on the IP address and the binding order in Microsoft products. Thus you should have different ranges of IP addresses on your private network from those used on the corporate network. If both networks service the same IP address, then Windows may send a packet intended for your private network to the corporate network. A similar situation will take place if you use a dial-up line to send a packet to the Internet. Windows may try to send it via the local Ethernet network if it is also valid for that network.

The following IP addresses are set aside for local networks and are not allowed on the Internet: 10.0.0.0 to 10.255.255.255, 172.16.0.0 to 172.31.255.255, and 192.168.0.0 to 192.168.255.255.

4.2.1 How to Set IP Addresses in the Sample Programs

Most of the sample programs use macros to define the IP address assigned to the hardware platform and the IP address of the gateway, if there is a gateway.

#define MY_IP_ADDRESS "216.112.116.155"

#define MY_NETMASK "255.255.255.248"

#define MY_GATEWAY "216.112.116.153"

In order to do a direct connection, the following IP addresses can be used for the hardware platform:

#define MY_IP_ADDRESS "10.1.1.2"

#define MY_NETMASK "255.255.255.248"

// #define MY_GATEWAY "216.112.116.153"

In this case, the gateway is not used and is commented out. The IP address of the board is defined to be 10.1.1.2. The IP address of you PC can be defined as 10.1.1.1.

4.2.2 How to Set Up your Computer's IP Address for Direct Connect

When your computer is connected directly to the hardware platform via an Ethernet connection, you need to assign an IP address to your computer. To assign the PC the address 10.1.1.1 with the subnetmask 255.255.255.248 under Windows 98, do the following.

Click on Start > Settings > Control Panel to bring up the Control Panel, and then double-click the Network icon. In the window find the line of the form TCP/IP > Ethernet adapter name. Double-click on this line to bring up the TCP/IP properties dialog box. You can edit the IP address directly and the subnet mask. (Disable "obtain an IP address automatically.") You may want to write down the existing values in case you have to restore them later. It is not necessary to edit the gateway address since the gateway is not used with direct connect.

The method of setting the IP address may differ for different versions of Windows, such as 95, NT, or 2000.

Figure 10. Direct Connection PC to DeviceMate Hardware Platform

4.2.3 Run the PINGME.C Demo

Find the PINGME.C program in the Dynamic C SAMPLES\TCPIP\ICMP folder.

1. Edit the IP address and netmask in to 10.1.1.2 and the netmask of your PC (available under the "IP Address" tab in "TCP/IP Properties" under "Network Settings").
2. Compile the program by pressing F5 or using the Compile menu.
3. Connect an Ethernet crossover cable from your computer's Ethernet jack to the RCM2200's RJ-45 Ethernet connector. (Refer to Section 4.1, "Ethernet Network Cables," if you need more information on Ethernet network cables.)
4. Start the program running (press F9 select Run in the Run menu). The green LNK light on the RCM2200 should be on to indicate an Ethernet connection is made. (Note: If the LNK light does not light, you may not have a crossover cable, or if you are using a hub perhaps the power is off on the hub.)
5. Ping the board from your PC. This can be done by bringing up the MS-DOS window and running the ping program:

ping 10.1.1.2

or by Start > Run
and typing the command

ping 10.1.1.2

Notice that the yellow ACT light flashes on the RCM2200 while the ping is taking place, and indicates the transfer of data. The ping routine will ping the board four times and write a summary message on the screen describing the operation.

4.3 DeviceMate Dynamic C Libraries and Sample Programs

Once you start looking at developing your own DeviceMate applications, the DevMate directory contains the Dynamic C libraries you will need. The libraries and the function calls are described in complete detail in the DeviceMate Software User's Manual.

Two directories contain sample programs to illustrate the DeviceMate features of the hardware platform.

• The DMUNIT directory contains sample programs for a hardware platform interface with another Rabbit-based single-board computer or another single-board computer running Dynamic C.
• The DMTARGET directory contains libraries or sample programs for a hardware platform interface with Rabbit-based targets. The DMTARGET\Arch directory contains sample programs for use with nonRabbit-based targets.

4.3.1 Serving Web Pages

1. With the Rabbit programming cable connected to the RCM2200, open the program DEVMATE.C in the SAMPLES\DMUNIT directory, set the IP address, gateway, and netmask network parameters as you did in Section 4.2.1, then compile and run the program by pressing F9.
2. Move the Rabbit programming cable to the RCM2300 as shown in Figure 7, open the sample program VAR.C in the SAMPLES\DMTARGET directory, set the IP address, gateway, and netmask network parameters as you did in Section 4.2.1, then compile and run the program by pressing F9.
3. Remove the programming cable from the RCM2300 and set the programming cable aside.

The sample program VAR.C runs a Web server (http://10.1.1.2/var.shtml), and will accept variable updates from a target processor. These variables are included in .shtml pages that the DeviceMate hardware platform serves. Hence, these variables allow a simple means of having dynamic content in Web pages. The .shtml file var.shtml shows how these variables are included in a Web page.

4.3.2 FileSystem Access

1. With the Rabbit programming cable connected to the RCM2200, open the program DEVMATE_FS.C in the SAMPLES\DMUNIT directory, set the IP address, gateway, and netmask network parameters as you did in Section 4.2.1, then compile and run the program by pressing F9.
2. This program requires a small change to RABBITBIOS.C in the Dynamic C BIOS directory. The filesystem used in this example is a RAM filesystem (any FS2 filesystem may be used), and so room in RAM must be reserved. You will find the line:

 	 	 #define XMEM_RESERVE_SIZE (0*0000L)

at the top of the BIOS. Change it such that room is allocated in main system memory. For example, to allocate 16K, change the line to

 	 	 #define XMEM_RESERVE_SIZE (4*0000L)

but the exact amount is not as important.
3. Move the Rabbit programming cable to the RCM2300 as shown in Figure 7, open the sample program FS_TINY.C in the SAMPLES\DMTARGET directory, then compile and run the program by pressing F9.
4. Remove the programming cable from the RCM2300 and set the programming cable aside.

The sample program FS_TINY.C provides filesystem access to a target processor connected to the RCM2200. The target processor may make requests that will be serviced by the DM_FS.LIB library, such as uploading, removing (deleting), or renaming files.

Once a file is uploaded from the target, it will be available in the local filesystem for other applications to use, such as the Web (HTTP) or FTP servers. As this sample program makes use of the Web (HTTP) server, make sure the network information below is correct! After files are uploaded, you should be able to browse to:

http://[MY_IP_ADDRESS]/index.html

and be able to find your file there.

For more examples of using the ZSERVER.LIB library, there are several Web examples that use it, such as samples\tcpip\http\static2.c.

4.3.3 Running Your Own Set-Up

1. With the Rabbit programming cable connected to the RCM2200, open the program DEVMATE.C in SAMPLES\DMUNIT, set the IP address, gateway, and netmask network parameters as you did in Section 4.2.1, then compile and run the program with F9.
2. Move the Rabbit programming cable to the programming port of the target single-board computer, open the target program, then compile and the target board's program by pressing F9.
3. Remove the programming cable from the programming port and set it aside.

You are now ready to use the RCM2200 as a DeviceMate hardware platform to develop your own application.

Appendix B provides connection information on interfacing to a nonRabbit-based target board.

4.3.4 Reference Info

Table 1 lists the libraries used by Rabbit-based and nonRabbit-based target devices.

Table 1. Dynamic C Libraries for Rabbit and nonRabbit Targets

On Rabbit-Based Targets	Required by	On nonRabbit-Based Targets
DM_SMTP.LIB	E-Mail	DM_SMTP.C and DM_SMTP.H
DM_FS.LIB	File System	DM_FS.C and DM_FS.H
DM_LOG.LIB	Message Logging	DM_LOG.C and DM_LOG.H
DM_TCP.LIB	TCP/IP	DM_TCP.C and DM_TCP.H
DM_WD.LIB	Watchdogs	DM_WD.C and DM_WD.H
DM_VAR.LIB	Web Page Variables	DM_VAR.C and DM_VAR.H

These libraries or other files are not called directly when you develop your own application. Instead you will invoke one of the following.

#use TC_CONF.LIB (Rabbit-based target device)

or

#include TC_CONF.H (nonRabbit-based target device)

USE_TC_* macros need to be defined before the #use statement as explained in the DeviceMate Software User's Manual.

4.4 Where Do I Go From Here?

If there are any problems at this point,

• Check the Z-World Technical Bulletin Board at http://www.zworld.com/support/bb/index.html.
• E-mail your questions to support@zworld.com.
• Call Z-World Technical Support at (530)757-3737.

If the sample programs ran fine, you are now ready to go on.

Refer to the DeviceMate Software User's Manual and the Dynamic C TCP/IP User's Manual to develop your own applications. An Introduction to TCP/IP provides background information on TCP/IP, and is available on the CD and on Z-World's Web site.