RabbitLink User's Manual

3. RabbitLink Software

This chapter describes the software functionality available when using a RabbitLink.

3.1 Downloading and Debugging via the RabbitLink

Downloading a program to an embedded target via the RabbitLink is done using Dynamic C or the Rabbit Field Utility (RFU). The rows in the following table show which versions of Dynamic C and the RFU are compatible with which versions of the RabbitLink firmware. The firmware version is the same as its serial console; the version number is displayed in the console's startup message.

Table 2. Compatibility Between Dynamic C and the RabbitLink Firmware

RabbitLink Firmware	Dynamic C	Rabbit Field Utility
Version 1.00	Versions 7.03 thru 7.06	Version 2.0
Version 2.00	Versions 7.20 and later	Version 2.20

Before a program can be downloaded to a Rabbit-based target, the RabbitLink must be visible on the network. It must also be visible to Dynamic C or the Rabbit Field Utility (RFU). This is accomplished by setting the network parameters on the RabbitLink board and giving this information to Dynamic C or the RFU.

3.1.1 RabbitLink Network Parameters

Follow the steps in Section 2.2, "Configuring RabbitLink Network Parameters from Your PC," on page 8 if you have not already done so. The RabbitLink requires an IP address, a gateway address, a netmask and a port number to communicate across an network.

3.1.2 More RabbitLink Network Parameters

From Dynamic C, enter the RabbitLink addresses from the Communications dialog box found on the Options menu. From the RFU, the Communications dialog box is accessed from the Setup menu.

• 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 Communications dialog box to have Dynamic C or the RFU send a broadcast message to each RabbitLink attached to the network. The default UDP 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 Communications dialog box.

3.1.3 Password Protect the Embedded Target

Though not required, it is highly recommended that the passphrase security feature be activated before the RabbitLink is deployed. This gives some protection to the embedded target system from unauthorized communication. The passphrase may be up to 256 characters long. The serial console command "set passphrase" will prompt twice for a passphrase and will store the hashed value of it on the RabbitLink. When a session starts, the RabbitLink will ask for the passphrase, allowing access to the embedded system only after receiving the correct value. If no passphrase is set, just press <ENTER> when asked for it. If you forget the passphrase, the only way to recover is to use the RabbitLink serial console to set a new passphrase. This will require the hardware connections shown in Figure 4 on page 6 and the software setup described in Statically Assigned Network Parameters.

3.1.4 Using Dynamic C or the RFU to Download

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

The RFU downloads bin files that were previously created using Dynamic C. Dynamic C starts with a source code file and compiles it down to the target.

3.1.5 Remote Debugging with Dynamic C

Once a program is successfully downloaded to the target controller attached to the RabbitLink, Dynamic C may be used to debug the program precisely as if the PC running Dynamic C was directly connected to the target. Refer to the Dynamic C User's Manual for detailed information on downloading and debugging.

3.1.6 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. Look in the Communications dialog box accessed from the Options menu.
  
  
• If Dynamic C is able to establish communication with the RabbitLink, but midway through the download process displays either "Error receiving Flash ID from target"or "Target Communication Error," 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.2 RabbitLink Firmware

The firmware necessary to operate the RabbitLink with a Rabbit-based target system is loaded at the factory. This means that after the hardware connections have been made and the network parameters configured, the RabbitLink may be used immediately to download a program to the local or remote Rabbit-based system.

In case it is necessary to reload or replace the firmware, the following bin files are available for download from the RabbitLink directory that was created when Dynamic C installed. The corresponding source code files are in the same directory.

• 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.
  
  
• DOWNLOAD.BIN--RabbitLink firmware binary image.
  
  

The RabbitLink firmware version must be compatible with the version of Dynamic C that is used to download applications to the target that is connected to the RabbitLink (see Table 2). The companion CD in the RabbitLink Tool Kit contains versions 1.00 and 2.00 of the firmware.

3.2.1 Downloading Firmware to the RabbitLink

Follow these steps to reload the firmware or to reset the RabbitLink serial port.

1. Connect the RabbitLink board to your PC as shown in Figure 8 with the PROG connector on the programming cable connected to the PROG IN header of the RabbitLink board.
   
   

Figure 8. RabbitLink Connections for Downloading Firmware

2. Use the Rabbit Field Utility version 2.0 or later to load the DOWNLOAD.BIN firmware or the CLEAR_PARAM.BIN binary image onto the RabbitLink board.
   
   
3. Disconnect the programming cable.
   
   
4. Unplug the power supply, then plug the power supply back in. This resets the RabbitLink from Program Mode to Run Mode.
   
   

3.2.2 Firmware Upgrades

Follow the above steps to install a firmware upgrade. Just substitute the name of the firmware upgrade for the firmware binary image file (DOWNLOAD.BIN ). Firmware upgrades will be available at

 www.rabbitsemiconductor.com 

or at

 www.zworld.com

3.3 Serving Web Pages and Sending E-Mail

The RabbitLink is primarily intended for downloading and debugging across an Ethernet-based network with a Rabbit-based target.

3.3.1 Using DeviceMate Features

Z-World offers DeviceMate as a better-fit solution for those who wish to use Internet services. The DeviceMate feature set has more options, such as watchdogs and message logging, and also an interface that is easier to use than what is available on the RabbitLink. For more information about DeviceMate, please refer to the DeviceMate Software User's Manual available at:

http://www.zworld.com

The DeviceMate software may be downloaded to the RabbitLink to replace the RabbitLink firmware.

3.3.2 Using RabbitLink Features

RabbitLink console commands may be used to send e-mail and serve web pages. A complete list of the available commands are in Appendix E, "Serial Console Commands."

Prior to Dynamic C 7.20, a console API existed for target applications to send console commands to the RabbitLink. Please see Appendix E.6, starting on page 38 for API function descriptions.

Starting with Dynamic C 7.20, the console commands are sent to the RabbitLink through the serial port interface.