RabbitLink Software

RabbitLink
User's Manual

3. RabbitLink Software

All the firmware necessary to operate the RabbitLink with a Rabbit-based target system is already loaded--all you have to do is open a terminal emulator to interact with the serial console on the RabbitLink board, configure the board, and you are ready to go. Although no further application development is needed for the RabbitLink, the application running on the target system will have to be written to take into account the availability of the RabbitLink.

Chapter 3 describes the RabbitLink firmware and the Dynamic C features that enable the target system to be used with the RabbitLink.

3.1 RabbitLink Firmware

When Dynamic C first opens, the following list of Dynamic C root directories will be displayed.

NOTE If you plan to install the RabbitLink firmware from the companion CD, you will be given the choice of a destination folder. You may wish to install the firmware as shown above in your Dynamic C directory.

The RABBITLINK directory is specific to the RabbitLink, and contains the source code and binary images associated with features specific to the RabbitLink.

The STDIO.LIB library in the Lib directory contains functions used by target boards to access the RabbitLink serial console. Other functions applicable to all devices based on the Rabbit 2000 microprocessor are described in the Dynamic C Premier User's Manual.

All the firmware necessary to operate the RabbitLink with a Rabbit-based target system is already loaded at the factory. In case it becomes necessary to reload the firmware, the RABBITLINK directory contains the source code and the binary image to download.

CLEAR_PARAM.BIN--Binary image to reset the network configuration parameters of the RabbitLink board (stored on the second flash) to default values. This binary file is used to reset the serial port if its operation has become undefined.
CLEAR_PARAM.C--Source code to reset the network configuration parameters of the RabbitLink board (stored on the second flash) to default values.
DOWNLOAD.C--RabbitLink firmware source code.
DOWNLOAD.BIN--RabbitLink firmware binary image.

NOTE Refer to Appendix C.1, "Download Firmware," for complete instructions on how to load a firmware upgrade or reload the firmware.

3.2 Downloading and Debugging through the RabbitLink

3.2.1 Getting Started

Before attempting to do any downloading or debugging through the RabbitLink, you will need either the Rabbit Field Utility (version 2.0) or Dynamic C (version 7.03 or later) installed on your PC.

If you plan to use the Rabbit Field Utility, version 2.0 is available on the companion CD. Select the Rabbit Field Utility on your PC desktop after installing the software on the companion CD. Complete instructions for using the Rabbit Field Utility are included in the Help menu for the Rabbit Field Utility.

NOTE Note that pre-2.0 versions of the Rabbit Field Utility are unable to handle Ethernet transfers by the RabbitLink.

3.2.2 Downloading and Debugging

Regardless of whether you use the Rabbit Field Utility or Dynamic C, downloading across an Ethernet connection is essentially the same as across a serial connection.

Dynamic C can also be used for debugging across an Ethernet or an Internet connection. Once a program is successfully downloaded to the controller attached to the RabbitLink, Dynamic C can be used to debug the program in exactly the same way as it would be used via a serial link.

NOTE Refer to the Dynamic C Premier User's Manual for more detailed information on downloading and debugging.

3.2.2.1 RabbitLink Configuration Commands

Configure the following RabbitLink network parameters before using the RabbitLink.

set ip <IP address>
set gateway <address>
set netmask <address>
set port <TCP port number>
set hostname <name>
set passphrase <passphrase>

NOTE The configuration commands and procedures are described in detail in Section 2.2, "Configuring RabbitLink Network Parameters from Your PC."

3.2.2.2 Connections

Connect the RabbitLink board as shown in Figure 9 with the PROG connector on the program download cable connected to the programming header of the Rabbit-based target system and the unmarked connector connected to the PROG OUT header of the RabbitLink board. The RabbitLink board is also connected to the Ethernet and should have been configured with its IP address, netmask, and gateway information.

Figure 9. RabbitLink Connections for Download/Debug

Enter the information in the Dynamic C Options > Communications dialog box for the RabbitLink you are connecting to:

The Network Address field should contain the IP address of the RabbitLink.
The Control Port field should be set to the TCP port number that the RabbitLink uses to accept control commands from Dynamic C--the default value is 4244. If the RabbitLink is behind a firewall, the Control Port field should be set to the port on the firewall that is being forwarded to the RabbitLink.

If a RabbitLink or multiple RabbitLinks are attached to a local network, press the Discover button in the Options > Communications dialog box to have Dynamic C send a broadcast message to each RabbitLink attached to the network. The default port for discovery is 4242. Each RabbitLink will respond with its IP address, name, control port, current status, and MAC address. Selecting any line in the Discover window will cause the information for that RabbitLink to be placed into the appropriate fields in the Options > Communications dialog box.

3.2.3 Troubleshooting Tips

If Dynamic C is unable to establish communication with the RabbitLink, make sure that the RabbitLink is powered on, and make sure that the Ethernet cable is firmly connected to the RabbitLink and that the USER and ACTIVE LEDs are on.
If Dynamic C is still unable to establish communication with the RabbitLink, make sure that Dynamic C has the correct IP address and control port information.
If Dynamic C is able to establish communication with the RabbitLink, but midway through the download process displays the error message "Error receiving Flash ID from target," check to make sure that the program download cable is plugged in correctly from the RabbitLink to the controller being programmed, and that the controller is powered on.

3.3 Accessing the RabbitLink Serial Console

The RabbitLink serial console provides the commands to set network parameters, to create and delete Web pages, and to send E-mail. The serial console can be accessed via the serial port using the PROG IN connector on the RabbitLink, as was done in Chapter 2 to configure the RabbitLink. This method can also be used by a non-Rabbit board with a RabbitLink to provide Web and E-mail access.

If a Rabbit 2000-based target board is connected to the PROG OUT port of the RabbitLink, then the target board can communicate with the RabbitLink console via the program download cable by using the following Dynamic C functions.

int PrintToConsole(char flag);

This function controls whether STDIO commands such as printf go to the RabbitLink serial console in addition to the Dynamic C STDIO window.

Parameter

flag 0-printf and related commands work as normal,
1-printf and related commands go to the RabbitLink serial console as well.

Return Value

0 if successful, -1 if not.

Library
STDIO.LIB
See also
getchar, SendToConsole, ConsoleFinish


   
int SendToConsole(char *data, int length);
This function writes a binary buffer of a specified length to the serial console on a RabbitLink. Any data are acceptable since the data will not show up in the Dynamic C STDIO window.

Parameters

data is a pointer to the data to be sent.
length is the length of the buffer passed in data.

Return Value

The actual number of bytes written to the console.

Library
STDIO.LIB
See also
getchar, PrintToConsole, ConsoleFinish

int ConsoleFinish(long timeout);

This function finishes receiving data from the RabbitLink serial console by blocking for an optional amount of time to do it. If the timeout is set to 0, the function will not receive any data, but will poll to determine whether there are more data to receive.

Parameters

timeout is the length of time to time out, in milliseconds, and is 0 for ConsoleFinish to determine whether there are more data to receive.

Return Value

0 if there are more data on the serial console, non-zero if all the data have been received.

Library
STDIO.LIB
See also
getchar, PrintToConsole, SendToConsole
Example
main() {
  // first method
  SendToConsole("set ip 10.10.2.102\n", 19);

  // second method
  PrintToConsole(1);
  printf("set gateway 10.10.2.1\n");
  PrintToConsole(0);
}
NOTE Additional examples are provided in the Samples/RabbitLink folder. Refer to Section 3.7, "Sample Programs." for more information.
3.4 Web Serving

The Web server built into the RabbitLink firmware can be controlled via the RabbitLink console. HTML pages, images, and other files can be added and deleted from the file system on the second flash, and can be loaded by a browser elsewhere on the network at any time. See Appendix F., "Serial Console Commands," for detailed descriptions of the console commands.

3.4.1 RabbitLink Configuration Commands

The following RabbitLink parameters must be configured before the RabbitLink is used.

set ip <IP address>
set gateway <address>
set netmask <address>

NOTE The configuration commands and procedures are described in detail in Section 2.2, "Configuring RabbitLink Network Parameters from Your PC."

3.4.1.1 Connections

Connect the RabbitLink board as shown in Figure 10 with the PROG connector on the program download cable connected to the programming header of the Rabbit-based target system and the unmarked connector connected to the PROG OUT header of the RabbitLink board.

Figure 10. RabbitLink Connections for Web Serving
(Rabbit-based embedded system)
NOTE Refer to Section 3.6, "Web Serving and E-mail With Non-Rabbit Boards." for informatiom on connecting a non-Rabbit embedded system.

3.4.2 Creating Web Pages

The RabbitLink serial console contains commands for writing, reading, and deleting files from the flash file system.

3.4.2.1 ASCII Files

The target embedded system may place ASCII files (for example, an HTML file) on the RabbitLink. Use the put command shown below.

put <filename>, where <filename> is the file name (timeout 60 seconds)

Use a <Ctrl-d> or a <Ctrl-z> to end the command since Enter() will be interpreted by the RabbitLink serial console as a carriage return (\r) or as a carriage return + line feed (\r \n) in the text or the file name being entered.

A timeout is built in to the put command so that data transfer will begin no later than after the timeout. The timeout countdown process does not begin until the RabbitLink senses there is no activity.

The following example shows how to create and update a simple Web interface.

First, create the HTTP file.
put status.html
<H2>Status:</H2>
Temperature: OK
<P>Humidity: OK
<P>See <A HREF="data.txt">data</A>
<Ctrl-d>
Note that the final line represents actually entering a <Ctrl-d> to end the file, not typing that text.

The RabbitLink responds OK.

Next, create the data file.
put data.txt
TIME  TEMP  HUM
0000  21    67
0600  25    75
1200  27    78
<CTRL-d>
The RabbitLink responds OK.

The files currently in the file system can be listed by the list files command.
list files
The RabbitLink responds
      86  status.html
      61  data.txt
OK
Use the get command to view a file at any time. For example, type
get status.html
The RabbitLink responds
<H2>Status:</H2>
Temperature: OK
<P>Humidity: OK
<P>See <A HREF="data.txt">data</A>
OK
NOTE Type get <filename> 0 to see the size, in bytes, of <filename>.

3.4.2.2 Binary Files and Images

Use the binary version of the put command to send a binary file (for example, GIF or JPG).

put <filename> <size>, where <filename> is the file name and <size> is the size, in bytes, of the file (timeout 10 seconds)

Specifying the number of bytes to be sent alerts the RabbitLink console that this file is not an ASCII file, and the RabbitLink will accept all the characters sent as raw data bytes, ignoring the special meaning of characters such as <CTRL-d> (04h) that would otherwise signify the end of an ASCII file.

A timeout is built in to the put command so that data transfer will begin no later than after the timeout even though the file size is less than the maximum or the specified size. The timeout countdown process does not begin until the RabbitLink senses there is no activity.

The following example shows how to create and update a simple Web interface.

First, create the HTTP file.
put data.bin 2034
[2034 bytes of raw data follow]
The RabbitLink responds OK.

The files currently in the file system can be listed by the list files command.
list files
The RabbitLink responds
      86  status.html
      76  data.txt
     203  data.bin
OK
NOTE It is faster and more efficient to transfer all files, including ASCII files, as binary files.

Images (GIF or JPG files) are often very large binary files. It is easier to transfer these files from the PC directly to the RabbitLink, especially when the images will not change. This can be accomplished by connecting the RabbitLink directly to your PC, as was done to configure the RabbitLink (see Section 2.2, "Configuring RabbitLink Network Parameters from Your PC."). Connect the DIAG end of the programming cable to the PROG IN port of the RabbitLink, and the other end to your PC's serial port as shown in Figure 11.

Figure 11. RabbitLink Connections for Transferring
Files Directly to RabbitLink Flash from PC
NOTE Since there is no flow control supported on the PROG IN port of the RabbitLink, it is advisable to reduce the baud rate from 57,600 bps to a lower value while transferring large binary files to ensure that no bytes are missed as the file is written to the flash file system. Alternatively, some terminal programs (such as TeraTerm) can add a delay to a binary file transfer.

3.4.3 Viewing Web Pages on the RabbitLink

The RabbitLink should be connected to the target system and the Ethernet as shown in Figure 10. In a Web browser connected to the same network that the RabbitLink is on, go to the address
http://<IP address>/<filename>
where <IP address> is the IP address of the RabbitLink, and <filename> is the name of the Web page you wish to view.

To continue the example, enter the address
http://<IP address>/status.html
into a Web browser with network access to the RabbitLink board, replacing <IP address> with the address of your RabbitLink board. The page should appear something like this.

Status:

Temperature: OK

Humidity: OK

See data.

Click on the link to bring up the data file.

TIME TEMP HUM
0000 21 67
0600 25 75
1200 27 78

The files in the RabbitLink file system cannot be appended to, so the file must first be deleted and then rewritten in order to add a new line of data.

Type
delete data.txt
The RabbitLink responds OK.

The files currently in the file system can be listed by the list files command.
list files
The RabbitLink responds
      86  status.html
OK
Rewrite the new data.
put data.txt
TIME  TEMP  HUM
0000  21    67
0600  25    75
1200  27    78
1800  28    75
<Ctrl-d>
The RabbitLink responds OK.

Reloading the page of data should now show

TIME TEMP HUM
0000 21 67
0600 25 75
1200 27 78
1800 28 75

3.4.4 Serial Console Commands for Variables

The RabbitLink serial console also has the ability to handle SSI (Server Side Includes) variables. These variables are stored in an xmem buffer. This means that the memory will lose the variables when power is cycled, although the references to the variables will still exist.

NOTE Any HTML file that includes SSI tags must have the file extension .shtml.

The RabbitLink boots up whenever the power cycles, and then displays the message
RabbitLink Serial Console Version ...
This section lists the serial configuration commands associated with variables.

createv <varname> <vartype> <format> <value> [strlen]

This command creates a variable called <varname>. The variable can be referenced within Web files (for example, ).
<vartype> is the type of the variable (int8, int16, int32, float32, or string)
<format> is the printf-style format specifier (such as %d) for outputting the variable
<value> is the value to assign to the variable.
[strlen] is only used if the variable is of type string. [strlen] is used to give the maximum length of the string.
Examples
createv var1 float32 "%.2f" 3.14

createv var2 string "%s" "This is only a test." 50
The RabbitLink will respond OK after each command.

getv <varname>

This command gets the value of the variable called <varname>. The value is printed using the format specifier given in the createv command.
Example
getv var2
The RabbitLink responds.
This is only a test.
OK
putv <varname> <value>

This command assigns the given <value> to the given variable <varname>.
Example
putv var1 3.14

	 OK

getv var1

3.14
OK
list variables

This command lists all the variables.
Example
list variables
The RabbitLink responds.
var1 float32
var2 string50
OK
reset variables

This command deletes all the variables.
Example
reset variables
The RabbitLink responds OK.

NOTE Additional examples are provided in the sample program EG2100Vars.C found in the Samples/RabbitLink folder. Refer to Section 3.7, "Sample Programs." for more information.

3.5 Send E-mail

The SMTP client built into the RabbitLink firmware is able to send simple E-mail messages to a SMTP server via the RabbitLink console.

3.5.1 RabbitLink Configuration Commands

The following RabbitLink parameters must be configured before the RabbitLink is used.

set ip <IP address>
set gateway <address>
set netmask <address>
set mail from <username@domain.ca>
set mail server <IP address>

The from address will be included in the From line of all E-mail messages sent from the RabbitLink. This address should be an actual E-mail address that you have access to since any error responses from the SMTP server will be sent to this address.

NOTE Ask your network administrator for assistance with the mail server IP address.
NOTE The configuration commands and procedures are described in detail in Section 2.2, "Configuring RabbitLink Network Parameters from Your PC."

3.5.1.1 Connections

Connect the RabbitLink as shown in Figure 12 with the PROG connector on the program download cable connected to the programming header of the Rabbit-based target system and the unmarked connector connected to the PROG OUT header of the RabbitLink.

Figure 12. RabbitLink Connections for E-mail
(Rabbit-based embedded system)

3.5.2 Sending a Message

To send an E-mail message, use the console mail command. The following example shows how an E-mail message is sent.

First, set the RabbitLink parameters. These parameters will be stored in flash so they only need to be set once. The RabbitLink responses are shown in a grey box.
set mail from status@rabbitcompany.com

OK

set mail server 10.10.4.212

OK
NOTE Note that you must specify the IP address of the mail server.

Next, send an E-mail message with the mail command. The first line typed after the mail command will be the subject line, and the rest will form the body of the message.
mail engineer@rabbitcompany.com
Error -- South wall
The system on the south wall has reported an error.  
Please check it.
<Ctrl-d>

OK
Use a <CTRL-d> (04h) or a <CTRL-z> (1Ah) to send the message since Enter() will be interpreted by the RabbitLink serial console as a carrier return (\r) or as a carrier return + line feed (\r \n).

The E-mail is sent immediately.

The E-mail account engineer@rabbitcompany.com will receive the following E-mail message.
Return-Path: <status@rabbitcompany.com>
From: <status@rabbitcompany.com>
To: <engineer@rabbitcompany.com>
Subject: Error -- South wall

The system on the south wall has reported an error.  
Please check it.
There may be additional headers as well, depending on your SMTP server and E-mail client.

3.6 Web Serving and E-mail With Non-Rabbit Boards

Connect the RabbitLink board as shown in Figure 13 with the DE9 connector on the programming cable connected to a serial connector on the non-Rabbit target system and the unmarked connector connected to the PROG IN header of the RabbitLink board. The level converter on the programming cable converts the RS-232 levels from the target system to the CMOS-level signals used by the RabbitLink.

Figure 13. RabbitLink Connections for Web Serving
(non-Rabbit embedded system)

The put, get, and mail commands (and the associated commands for use with variables) are used in the same way as in a Rabbit-based embedded system, but use the serial port on the non-Rabbit target system.

NOTE See the Samples/RabbitLink folder for examples of sending console commands over the serial port. Refer to Section 3.7, "Sample Programs." for more information.

3.7 Sample Programs

Dynamic C Premier contains sample programs for the target systems connected to the Ethernet via the RabbitLink. The sample programs are located in Samples/RabbitLink.

Let's take a look at the Samples/RabbitLink folder.

EG2100_MAIL.C--Sample program for Rabbit-based embedded system to generate an E-mail message to be sent by the RabbitLink.
EG2100_SERIAL.C--Sample program to illustrate serial communication with any embedded system connected to the RabbitLink.
EG2100_VAR.C--Sample program for Rabbit-based embedded system using variables on Web pages to be sent by the RabbitLink.
EG2100_WED.C--Sample program for Rabbit-based embedded system to generate Web pages to be served by the RabbitLink.

Z-World
http://www.zworld.com
Voice: (530) 757-3737
FAX: (530) 753-5141
sales@zworld.com
Rabbit Semiconductor
http://www.rabbitsemiconductor.com
Voice: (530) 757-8400
FAX: (530) 757-8402
sales@rabbitsemiconductor.com

NOTE	Ask your network administrator for assistance with the mail server IP address.
NOTE	The configuration commands and procedures are described in detail in Section 2.2, "Configuring RabbitLink Network Parameters from Your PC."