Wildcat (BL2000) User's Manual

> ## 4. Software

> Dynamic C Premier is an integrated development system for writing embedded software. It runs on an IBM-compatible PC and is designed for use with Z-World single-board computers and other devices based on the Rabbit microprocessor.

> Chapter 4 provides the libraries, function calls, and sample programs related to the BL2000.

> ### 4.1 BL2000 Libraries

> With Dynamic C running, click File > Open, and select Lib. The following list of Dynamic C libraries and library directories will be displayed.

> Two library directories are used to develop applications for the BL2000.

> - BL2000—libraries associated with features specific to the BL2000.
> - TCPIP—libraries specific to using TCP/IP functions on the BL2000.

> Other generic functions applicable to all devices based on the Rabbit 2000 microprocessor are described in the Dynamic C Premier User's Manual.

> #### 4.1.1 Library Directories

> The BL2000 directory contains the libraries required to operate the BL2000.

> - BL20xx.LIB—This library supports all BL2000 series boards. The functions in this library are described in this chapter.

> The TCPIP directory contains libraries with generic TCP/IP functions.

> - ARP.LIB—address resolution protocol functions.
> - BOOTP.LIB—bootstrap protocol functions.
> - BSDNAME.LIB—BSD-style socket routines.
> - DCRTCP.LIB—TCP/IP functions.
> - DNS.LIB—handles host name resolution.
> - FTP_CLIENT.LIB—FTP client functions.
> - FTP_SERVER.LIB—FTP server functions.
> - HTTP.LIB—HTTP handler.
> - ICMP.LIB—ICMP handler.
> - IP.LIB—handles the network layer (just above the link layer and the device driver).
> - MD5.LIB—implements the MD5 algorithm defined in TCP/IP RFC 1321.
> - NET.LIB—general networking API. This is the "top-level" library for the networking library suite. It includes the packet-driver interface.
> - PKTDRV.LIB—packet driver functions.
> - POP3.LIB—POP3 functions.
> - REALTEK.LIB—packet driver functions for the RealTek RTL8019AS.
> - SMTP.LIB—SMTP handler.
> - TCP.LIB—transmission control protocol.
> - UDP.LIB—user datagram protocol.
> - VSERIAL.lib—virtual Telnet functions.
> - ZSERVER.lib—miscellaneous TCP/IP server data structures and routines.

> The functions in these libraries are described in the Dynamic C TCP/IP User's Manual included in the manual set with the Dynamic C Premier User's Manual.

> ### 4.2 BL2000 Function APIs

> #### 4.2.1 Board Initialization

> ##

> void brdInit (void);

> Call this function at the beginning of your program. This function initializes the system I/O ports and loads all the A/D and DAC calibration constants from flash memory into SRAM for use by your program.
> The ports are initialized as follows:

> Port | I/O | Function | Output Function State
> PA0 | Output | OUT0/RELAY/LED_DS4 | High-Current Driver Off
> PA1 | Output | OUT1/LED_DS5 | High-Current Driver Off
> PA2 | Output | OUT2/LED_DS6 | High-Current Driver Off
> PA3 | Output | OUT3/LED_DS7 | High-Current Driver Off
> PA4 | Output | OUT4 | High-Current Driver Off
> PA5 | Output | OUT5 | High-Current Driver Off
> PA6 | Output | OUT6 | High-Current Driver Off
> PA7 | Output | OUT7 | High-Current Driver Off
> PB0 | Input | IN6 | N/A
> PB1 | Input | CLKA | N/A
> PB2 | Input | IN7 | N/A
> PB3 | Input | IN8 | N/A
> PB4 | Input | IN9 | N/A
> PB5 | Input | IN10 | N/A
> PB6 | Output | RS485_EN | Off
> PB7 | Output | UPGOOD | Bad Indicator Off
> PC0 | Output | TXD RS-485 | Inactive high
> PC1 | Input | RXD RS-485 | N/A
> PC2 | Output | RTS/TXC RS-232 | Inactive high
> PC3 | Input | CTS/RXC RS-232 | N/A
> PC4 | Output | TXB RS-232 | Inactive high
> PC5 | Input | RXB RS-232 | N/A
> PC6 | Output | TXA Programming Port | Inactive high
> PC7 | Input | RXA Programming Port | N/A
> PD0 | Output | DAC-ADC_SK | On
> PD1 | Output | DAC-ADC_SDI | On
> PD2 | Input | RTL-ADC_SDO | N/A
> PD3 | Input | RTL_SK | N/A1
> PD4 | Output | RTL_SDI | On
> PD5 | Output | DAC0_CS | Inactive high
> PD6 | Output | DAC1_CS | Inactive high
> PD7 | Output | ADC_CS | Inactive high
> PE0 | Output | OUT8 | High-Current Driver Off
> PE1 | Output | OUT9 | High-Current Driver Off
> PE2 | Input | IN0 | N/A
> PE3 | Input | IN1 | N/A
> PE4 | Input | IN2 | N/A
> PE5 | Input | IN3 | N/A
> PE6 | Input | IN4 | N/A
> PE7 | Input | IN5 | N/A

> 1 PD3 is an output (and is on) for the BL2020 and the BL2030.

> SEE ALSO

>     digOut, digIn, serMode

> #### 4.2.2 Digital I/O

> ##

> int digIn(int channel);

> Reads the state of an input channel:
>   IN0-IN10—standard digital inputs, ± 36 V DC
>   IN11-IN14—pseudo digital inputs using A/D converter inputs ADC0-ADC3, ± 10 V DC
>   IN15-IN19—pseudo digital inputs using A/D converter inputs ADC4-ADC8, 0 V to 48 V DC
>   IN20-IN21—pseudo digital inputs using A/D converter inputs DAC0-DAC1, 0 V to 48 V DC
>   (BL2010 and BL2030)
> The threshold is fixed at 2.40 V for channels IN0-IN10. Anything below 2.40 V is a logic 0, and anything higher than or equal to 2.40 V is a logic 1.
> The default threshold for channels IN11-IN21 is also set to 2.40 V. The threshold for these channels may be changed by adding the following two lines to your program.

>     #undef   THRESHOLD
>     #define  THRESHOLD xx.xx

> where xx.xx is the desired threshold voltage. Anything below the threshold value is a logic 0, and anything higher than or equal to the threshold value is a logic 1.
> PARAMETER
> channel is the input channel number (0-21)
> RETURN VALUE
> The state of the input (0 or 1).
> SEE ALSO

>     brdInit, digOut

> ##

> void digOut(int channel, int value);

> Sets the state of a digital output (OUT0-OUT9).
> The default setting for the function is for current-sinking outputs. To change from sinking to sourcing outputs, add the following two lines at the beginning of your program.

>     #undef   OUTPUT_DRIVE
>     	 	 	 	 	 #define  OUTPUT_DRIVE  SOURCING

> The relay is driven by PA0, which is the same Rabbit 2000 parallel port that drives OUT0 and LED DS4. OUT0 therefore works in parallel with the relay output. Z-World therefore recommends that you do not use OUT0 for a digital output when you are using the relay.
> PARAMETERS
> channel is the output channel number (0-9).
> value is the output value (0 or 1).
> SEE ALSO

>     brdInit, digIn

> #### 4.2.3 Serial Communication

> Library files included with Dynamic C provide a full range of serial communications support. The RS232.LIB library provides a set of circular-buffer-based serial functions. The PACKET.LIB library provides packet-based serial functions where packets can be delimited by the 9th bit, by transmission gaps, or with user-defined special characters. Both libraries provide blocking functions, which do not return until they are finished transmitting or receiving, and nonblocking functions, which must be called repeatedly until they are finished. For more information, see the Dynamic C Premier User's Manual and Technical Note 213, Rabbit 2000 Serial Port Software.

> The following function calls are specific to the BL2000.

> ##

> int serMode(int mode);

> User interface to set up BL2000 serial communication lines. Call this function after serXOpen().
> If Mode 1 is selected, CTS/RTS flow control is exercised using the serCflowcontrolOn and serCflowcontrolOff functions from the RS232.LIB library.
> PARAMETER
> mode is the defined serial port configuration.

> Mode | Serial Port
> B | C | D
> 0 | RS-232, 3-wire | RS-232, 3-wire | RS-485
> 1 | RS-232, 5-wire | CTS/RTS | RS-485

> RETURN VALUE
> 0 if valid mode, 1 if not.
> SEE ALSO

>     ser485Tx, ser485Rx

> ##

> void ser485Tx(void);

> Sets (high) pin 3 (DE) to enable Tx.
> SEE ALSO

>     serMode, ser485Rx

> ##

> void ser485Rx(void);

> Resets (low) pin 3 (DE) to disable Tx.
> SEE ALSO

>     serMode, ser485Tx, serCflowcontrolOn, serCflowcontrolOff

> #### 4.2.4 Relay and LED Outputs

> ##

> void relayOut(int relay, int value);

> Sets the state of a relay.
> The relay is driven by PA0, which is the same Rabbit 2000 parallel port that drives OUT0 and LED DS4. OUT0 therefore works in parallel with the relay output. Z-World therefore recommends that you do not use OUT0 for a digital output when you are using the relay.
> PARAMETERS
> relay is the relay to control, 0 = Relay 0.
> value is the value used to connect the relay common contact to one of the following contacts:
>   0 = relay common connected to relay normally closed contact
>   1 = relay common connected to relay normally open contact
> SEE ALSO

>     brdInit

> ##

> void ledOut(int led, int value);

> LED ON/OFF control.
> The relay is driven by PA0, which is the same Rabbit 2000 parallel port that drives OUT0 and LED0. OUT0 therefore works in parallel with the relay output. Z-World therefore recommends that you do not use OUT0 for a digital output when you are using the relay. The relay and OUT0 are also turned on when LED0 is turned on.
> PARAMETERS
> led is the LED to control:
> 0 = OUT0 LED
> 1 = OUT1 LED
> 2 = OUT2 LED
> 3 = OUT3 LED
> 4 = BAD indicator
> value is the value used to control the LED:
> 0 = OFF
> 1 = ON
> SEE ALSO

>     brdInit

> #### 4.2.5 A/D Converter Inputs

> ##

> void anaInCalib(int channel, int value1, float volts1, int value2, float volts2);

> Calibrates the response of the A/D converter channel as a linear function using the two conversion points provided. Gain and offset constants are calculated and placed into global table _adcInCalib.
> PARAMETERS
> channel is the A/D converter input channel (0-10).
> value1 is the first A/D converter channel value.
> volts1 is the voltage corresponding to the first A/D converter channel value.
> value2 is the second A/D converter channel value.
> volts2 is the voltage corresponding to the second A/D converter channel value.
> RETURN VALUE
> 0 if successful.
> -1 if not able to make calibration constants.
> SEE ALSO

>     anaIn, anaInVolts, brdInit

> ##

> int _anaIn(unsigned char cmd, char len);

> Reads the voltage of an analog input channel by serially clocking out an 8-bit command to the A/D converter device of the following formats:
> TLC2543 commands
> D7-D4
>   Channel 0 - 10
>   Channel 11 = (Vref+ - Vref-)/2
>   Channel 12 = Vref-
>   Channel 13 = Vref+
>   Channel 14 = software powerdown
> D3-D2
>   Output data length:
>   01—8 bits
>   00—12 bits (normally used as default)
>   11—16 bits (not supported by driver)
> D1
>   Output data format
>   0—MSB first
>   1—LSB first (not supported by driver)
> D0
>   Mode of operation
>   0—Unipolar (normally used as default)
>   1—Bipolar
> TLC1543 commands (the TLC1543 is a 10-bit A/D converter)
> D7-D4
>   Channel 0 - 10
>   Channel 11 = (Vref+ - Vref-)/2
>   Channel 12 = Vref-
>   Channel 13 = Vref+
>   (No software power-down mode available)
> D3-D0
>   No specific values assigned.
> PARAMETERS
> cmd is the A/D converter input channel (0-10) to read.
> len is the output data length:
> 0 = 12-bit mode (BL2000/BL2020 only)
> 1 = 8-bit mode (BL2000/BL2020 only)
> 2 = 10-bit mode (BL2010/BL2030 only)
> RETURN VALUE
> A value corresponding to the voltage on the A/D converter input channel, which will be:
> 0-4095 for 12-bit A/D conversions
> 0-1023 for 10-bit A/D conversions
> 0-255 for 8-bit A/D conversions
> SEE ALSO

>     anaIn, anaInVolts, brdInit, samples/bl2000/adc/AD3.C

> ##

> int anaIn(unsigned int channel);

> Reads the state of an A/D converter input channel.
> PARAMETER
> channel is the A/D converter input channel (0-10) to read.
> RETURN VALUE
> A value corresponding to the voltage on the analog input channel, which will be:
> 0-4095 for 12-bit A/D conversions (BL2000,BL2020)
> 0-1023 for 10-bit A/D conversions (BL2010,BL2030).
> SEE ALSO

>     anaInVolts, anaInCalib, _anaIn, brdInit

> ##

> float anaInVolts(unsigned int channel);

> Reads the state of an A/D converter input channel and uses the previously set calibration constants to convert it to volts.
> PARAMETER
> channel is the A/D converter input channel (0-10).
> RETURN VALUE
> A voltage value corresponding to the voltage on the analog input channel.
> SEE ALSO

>     anaIn, anaInCalib, brdInit

> ##

> int anaInEERd(unsigned int channel);

> Reads the calibration constants, gain, and offset from the simulated EEPROM in flash memory.
> PARAMETER
> channel is the A/D converter input channel (0-10).
> RETURN VALUE
> 0 if successful.
> -1 if address or range is invalid.
> SEE ALSO

>     anaInEEWr, brdInit

> ##

> int anaInEEWr(unsigned int channel);

> Writes the calibration constants, gain, and offset to the simulated EEPROM in flash memory.
> PARAMETER
> channel is the A/D converter input channel (0-10).
> RETURN VALUE
> 0 if successful.
> -1 if address or range is invalid.
> SEE ALSO

>     anaInEERd,  brdInit

> #### 4.2.6 D/A Converter Outputs

> The functions in this section apply only to the BL2000 and the BL2020 models.

> ##

> int anaOutCalib(int channel, int value1, float volts1, int value2, float volts2);

> Calibrates the response of the D/A converter channel desired as a linear function using the two conversion points provided. Gain and offset constants are calculated and placed into global table _dacCalib.
> PARAMETERS
> channel is the D/A converter output channel (0 or 1).
> value1 is the first D/A converter value.
> volts1 is the voltage corresponding to the first D/A converter value.
> value2 is the second D/A converter value.
> volts2 is the voltage corresponding to the second D/A converter value.
> RETURN VALUE
> 0 if sucessful.
> -1 if not able to make calibration constants.
> SEE ALSO

>     anaOut, anaOutVolts, brdInit

> ##

> void anaOut(unsigned int channel, unsigned int modecount);

> Sets the voltage of a D/A converter output channel by serially clocking in 16 bits to a D/A converter using the following format:
> D15-D14
>   Doesn't matter.
> D13-D12
>   Mode of operation
>   00—Normal Operation
>   01—Software Powerdown, 1 kW to GND
>   10—Software Powerdown, 100 kW to GND
>   11—Software Powerdown, three-state
> D11-D0
>   Data bits, MSB-LSB (0-4095)
> PARAMETERS
> channel is the D/A converter output channel to write (0 or 1).
> modecount is a value corresponding to the voltage on the D/A converter output and/or setting the mode of operation:

> Operation Mode | Description | modecount Value
> 0 | Normal Mode | 0-4095
> 1 | Software Powerdown, 1 kW to GND | 0x1000
> 2 | Software Powerdown, 100 kW to GND | 0x2000
> 3 | Software Powerdown, three-state | 0x3000

> RETURN VALUE
> None
> SEE ALSO

>     anaOutVolts, anaOutCalib, brdInit

> ##

> void anaOutVolts(unsigned int channel, float voltage);

> Sets the voltage of a D/A converter output channel by using the previously set calibration constants to calculate the correct data values.
> PARAMETERS
> channel is the D/A converter output channel (0 or 1).
> voltage is the voltage desired on the output channel.
> SEE ALSO

>     anaOut, anaOutCalib, brdInit

> ##

> int anaOutEERd(unsigned int channel);

> Reads the calibration constants, gain, and offset from the simulated EEPROM in flash memory.
> PARAMETER
> channel is the D/A converter output channel (0 or 1).

> RETURN VALUE
> 0 if successful.
> -1 if address or range is invalid.
> SEE ALSO

>     anaOutEEWr, brdInit

> ##

> int anaOutEEWr(unsigned int channel);

> Writes the calibration constants, gain, and offset to the simulated EEPROM in flash memory.
> PARAMETER
> channel is the D/A converter output channel (0 or 1).
> RETURN VALUE
> 0 if successful.
> -1 if address or range is invalid.
> SEE ALSO

>     anaOutEERd, brdInit

> ### 4.3 Sample Programs

> Sample programs are provided in the Dynamic C Samples folder, which is shown below.

> The various folders contain specific sample programs that illustrate the use of the corresponding Dynamic C libraries. For example, the sample program PONG.C demonstrates the output to the STDIO window.

> The BL2000 folder provides sample programs specific to the BL2000, and the TCPIP folder provides sample programs to illustrate the TCP/IP aspects of programming the BL2000. Each sample program has comments that describe the purpose and function of the program. Follow the instructions at the beginning of the sample program.

> Let's take a look at the BL2000 folder.

> - BOARD_ID.C—This program is used to identify the model of BL2000 being used, and display that information in the STDIO window.
> - COUNTLEDS.C—This program will count from 0 to 31 in binary, using the four general-purpose LEDs, DS4-DS7, and the Processor Bad LED, DS8. The LEDs are used in reverse logical order to minimize the cycling of the relay, which is slaved to the same output as DS4.
> - LEDS_4.C—This program creates four "devices" (lights), and four buttons to toggle them. Users can view the devices with their Web browser, and change the status of the lights. If the Demonstration Board is connected to the BL2000, the lights on the Demonstration Board will match the ones on the Web page. See Appendix D for hookup instructions for the Demonstration Board.

> #### 4.3.1 Digital I/O

> The following sample programs are found in the IO subdirectory in SAMPLES/BL2000.

> - ANADIGIN.C—Demonstrates using the A/D converter channels as digital inputs. You will be able to see an input channel toggle HIGH and LOW when pressing the pushbuttons on the Demonstration Board. See Appendix D for hookup instructions for the Demonstration Board.
> - DIGIN.C—Demonstrates the use of the digital inputs. Using the Demonstration Board, you can see an input channel toggle from HIGH to LOW when pressing a pushbutton on the Demonstration Board. See Appendix D for hookup instructions for the Demonstration Board.
> - DIGOUT.C—Demonstrates the use of the high-current outputs. Using the Demonstration Board, you can see an LED toggle on/off via a high-current output. See Appendix D for hookup instructions for the Demonstration Board.
> - LED.C—Demonstrates how to toggle the output LEDs on the BL2000 on/off.
> - PWM.C—Demonstrates the use of Timer B to generate a PWM signal on digital output OUT8. The program generates a 42 Hz PWM signal with the duty cycle adjustable from 1 to 99%.
> - RELAY.C—Demonstrates how to control the relay on the BL2000.

> #### 4.3.2 Serial Communication

> The following sample programs are found in the RS232 subdirectory in SAMPLES/BL2000.

> - PUTS.C—Transmits and then receives an ASCII string on Serial Ports B and C. It also displays the serial data received from both ports in the STDIO window.
> - RELAYCHR.C—This program echoes characters over Serial Port B to Serial Port C. It must be run with a serial utility such as Hyperterminal.

> The following sample programs are found in the RS485 subdirectory in SAMPLES/BL2000.

> - MASTER.C—This program demonstrates a simple RS-485 transmission of lower case letters to a slave BL2000. The slave will send back converted upper case letters back to the master BL2000 and display them in the STDIO window. Use SLAVE.C to program the slave BL2000.
> - SLAVE.C—This program demonstrates a simple RS-485 transmission of lower case letters to a slave BL2000. The slave will send back converted upper case letters back to the master BL2000 and display them in the STDIO window. Use MASTER.C to program the master BL2000.

> #### 4.3.3 A/D Converter Inputs

> The following sample programs are found in the ADC subdirectory in SAMPLES/BL2000.

> - AD_CALIB.C—Demonstrates how to recalibrate an A/D converter channel using two known voltages to generate two coefficients, gain and offset, which are rewritten into the user block data area. The voltage that is being monitored is displayed continuously. Note that this sample program will overwrite the calibration constants set at the factory.
> - AD1.C—Demonstrates how to access the A/D internal test voltages in both the TLC2543 and TLC1543 A/D converter chips. The program reads the A/D internal voltages and then uses the STDIO window to display the RAW data.
> - AD2.C—Demonstrates how to access the A/D channels using the anaInVolt function. The program uses the STDIO window to display the voltage that is being monitored.
> - AD3.C—Demonstrates how to access the A/D converter channels with the low- level A/D driver. The program uses the STDIO window to display the voltage that is being monitored on all the A/D channels using the low-level A/D driver.
> - AD4.C—Demonstrates how how to use the A/D converter channels with the low- level A/D driver. The program uses the STDIO window to display the voltage (average of 10 samples) that is being monitored on all the A/D converter channels using the low-level A/D driver.

> #### 4.3.4 D/A Converter Outputs

> The following sample programs are found in the DAC subdirectory in SAMPLES/BL2000.

> - DACAL.C—This program demonstrates how to recalibrate an D/A converter channel using two known voltages, and defines the two coefficients, gain and offset, that will be rewritten into the D/A converter's EEPROM simulated in flash memory. Note that this sample program will overwrite the calibration constants set at the factory.
> - DAOUT1.C—This program outputs a voltage that can be read with a voltmeter. The output voltage is computed using the calibration constants that are read from the EEPROM simulated in flash memory.
> - DAOUT2.C—This program demonstrates the use of both the D/A and the A/D converters. The user selects both the D/A converter and A/D channel to be used, then sets the D/A converter output voltage to be read by the A/D channel. All activity will be displayed in the STDIO window.

> #### 4.3.5 TCP/IP Sample Programs

> TCP/IP sample programs are described in Chapter 5.

> ### 4.4 Using Dynamic C

> To run a sample program, open it with the File menu (if it is not still open), compile it using the Compile menu, and then run it by selecting Run in the Run menu. The BL2000 must be in Program mode (see Section 3.1, "Switching Between Program Mode and Run Mode,") and must be connected to a PC using the programming cable as described in Section 2.1, "BL2000 Connections.".

> More complete information on Dynamic C is provided in the Dynamic C Premier User's Manual. TCP/IP specific functions are described in the Dynamic C TCP/IP User's Manual. Information on using the TCP/IP features and sample programs is provided in Section 5, "Using the TCP/IP Features."

Z-World http://www.zworld.com Voice: (530) 753-3737 FAX: (530) 753-5141 sales@zworld.com