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."