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, <!--#echo var="var1"-->).
> <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