4. Software

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

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

4.1 Dynamic C 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 specific to the Intellicom.

• ICOM--libraries associated with features specific to the Intellicom unit.

• TCPIP--libraries specific to using TCP/IP functions on the Intellicom board.

Other 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 ICOM directory contains libraries required to operate the Intellicom unit.

• ICOM.LIB--This library supports OP6600 and OP6700 Intellicom boards only. 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. Additional TCP/IP libraries are added on an ongoing basis.

4.2 Intellicom Function APIs

4.2.1 Board Initialization

void brdInit (void);

Initializes port registers for the operation of the board. Call this function at the beginning of the application.

Return Value

None

See Also

dispInit, keyInit

4.2.2 Digital I/O

void digOut (int channel, int value);

Sets the state of a digital output.

Parameters

channel is the output channel number (0, 1, 2, or 3).

value is the output value (0 or 1).

Return Value

None.

See Also

digIn

int digIn (int channel);

Reads the state of a digital input.

Parameters

channel is the input channel number (0, 1, 2, or 3).

Return Value

The state of the input (0 or 1).

See Also

digOut

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

int serMode (int mode);

User interface to set up up serial communication lines for the Intellicom board. Call this function after serXOpen().

Parameters

mode is the defined serial port configuration of the devices installed.

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

Return Value

0 if correct mode, 1 if not.

See Also

serB485Tx, serB485Rx

void serB485Tx();

Sets pin 3 (DE) high to disable Rx and enable Tx.

See Also

serMode, serB485Rx

void serB485Rx();

Resets pin 3 (DE) low to enable Rx and disable Tx.

See Also

serMode, serB485Tx

4.2.4 Keypad Controls

void keyProcess (void);

Scans and processes keypad data (up to 8 × 8 matrix) for key assignment, debouncing, press and release, and repeat. Provides debouncing, user-definable key code, separate press and release code (both optional), two- and three-speed auto repeat.

Return Value

None.

See Also

keyConfig, keyGet, keypadDef

void keyConfig (char cRaw, char cPress, char cRelease, char cCntHold, char cSpdLo, char cCntLo, char cSpdHi );

Assigns user-defined keys to keypad positions. Defines ticks for key debouncing and speed.

Parameters

cRaw is the Raw Key Code Index, a 2 × 6 keypad matrix with the following raw keycode index assignments.

	Col 5	Col 4	Col 3	Col 2	Col 1	Col 0
Row 1	5	4	3	2	1	0
Row 0	13	12	11	10	9	8

cPress is the Key Press Code, an 8-bit value returned when a key is pressed (0 = Unused). See keypadDef for default press codes.

cRelease is the Key Release Code, an 8-bit value to be returned when a key is released (0 = Unused).

cCntHold is Hold Ticks, how long to hold before repeating (0 = No Repeat).

cSpdLo is Low-Speed Repeat Ticks, how many times to repeat (0 = None).

cCntLo is Low-Speed Hold Ticks, how long to hold before going to high-speed repeat (0 = Slow Only).

cSpdHi isHigh-Speed Repeat Ticks, how many times to repeat after low-speed repeat (0 = None).

Return Value

None.

See Also

keyProcess, keyGet, keypadDef

char keyGet (void);

Gets next keypress.

Return Value

The next keypress, or 0 if none.

See Also

keyConfig, keyProcess, keypadDef

void keyInit (void);

Initializes keypad process.

Return Value

None.

See Also

brdInit

void keypadDef();

Configures keypad to default layout:

[ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ . ]

[ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 0 ] [Enter]

Return Value

	 None.

See Also

keyConfig, keyGet, keyProcess

4.2.5 Display Controls

void dispContrast (char vcontrast);

Sets display contrast.

Parameters

Suggested values are 40-128 for high to low contrast, although 4-252 can be used. Contrast adjustment not supported on VFDs.

Return Value

None.

See Also

dispOnoff, dispBacklight

void dispCursor (unsigned int wStyle);

Sets cursor type: on, off, or blinking.

Parameters

wStyle is one of the following cursor macros:

DISP_CUROFF      for cursor off
DISP_CURON       for cursor on
DISP_CURBLINK     for cursor blink

Return Value

None.

See Also

dispClear, dispGoto

void dispGoto (unsigned wX, unsigned wY);

Positions the cursor.

Parameters

wX is the column position, 0 to 19.

wY is the row position, 0 to 3.

Return Value

None.

See Also

dispClear, dispCursor

void dispClear (void);

Clears the display and homes cursor.

Return Value

None.

See Also

dispGoto, dispCursor

void dispPutc (char cByte);

Puts a character on the display.

Parameter

cByte is the character to display.

Return Value

None.

See Also

dispPrintf

void dispPrintf (char *pcFormat, ...);

Prints formatted string to the display, similar to printf call.

Parameter

pcFormat is the formatted string.

Return Value

None.

See Also

dispPutc

void dispOnoff (int onOff);

Turns the display on or off.

Parameters

Set or write 1 to turn the display on. Clear or write 0 to turn the display off.

Return Value

None.

See Also

dispContrast, dispBacklight

void dispBacklight (int onOff);

Sets the backlight on or off. Not supported on VFDs.

Parameters

Set or write 1 to turn the backlight on. Clear or write 0 to turn the backlight off.

Return Value

None.

See Also

dispContrast, dispOnoff

void dispInit();

Initializes the display. Specifically, the function reinitializes the display controller, clears the display, and puts a nonblinking underline cursor in the top left position.

Return Value

None.

See Also

brdInit

4.2.6 Speaker Controls

void spkrOut (unsigned int wFreq, unsigned int wAmp );

Outputs speaker frequency and volume with various frequency and voltage values.

Parameters

wFreq--suggested frequency values are from 575 Hz to 3,000 Hz: for example, enter 1000 for 1 kHz. Values less than 575 (575 Hz) will be ignored.

wAmp--voltage amplitude (volume) values are 0, 1, 2, and 3: 0 = off, and 3 = loudest volume.

Return Value

None.

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 ICOM and TCPIP folders provide sample programs specific to the Intellicom board. 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 ICOM folder.

• COFTERMA.C--Demonstrates cofunctions, the cofunction serial library, and using a serial ANSI terminal such as Hyperterminal from an available PC COM port connection.

• DEMOBRD1.C--Flashes LEDs on Demonstration Board included in Development Kit. See Appendix D for hookup instructions for the Demonstration Board.

• DEMOBRD2.C--Flashes LEDs on Demonstration Board included in Development Kit and illustrates the Dynamic C runwatch function. See Appendix D for hookup instructions for the Demonstration Board.

• DEMOBRD3.C--Flashes LEDs on Demonstration Board included in Development Kit and demonstrates the use of costatements. See Appendix D for hookup instructions for the Demonstration Board.

• HTTPDEMO.C--Allows a Web browser to view and change the state of the Intellicom board. See Appendix D for hookup instructions for the Demonstration Board.

• ICOM232.C--Demonstrates a simple RS-232 loopback.

• ICOM485.C--Demonstrates a simple RS-485 transmission from master to slave.

• ICOM5WIRE.C--Demonstrates a 5-wire RS-232 loopback in an Intellicom set up for 5-wire RS-232.

• ICOMDEMO.C--Demonstration program to illustrate Intellicom features. This demonstration program comes up when the Intellicom is first powered up before new programs are compiled and run.

• ICOMIO.C--Demonstrates how to turn the digital I/O on and off.

• KEYLCD.C--Demonstrates use of LCD and keypad.

• MBOXDEMO.C--Implements a Web server that allows e-mail messages to be entered and then shown on the LCD display. See Appendix D for hookup instructions for the Demonstration Board.

• MUSIC.C--Speaker demonstration: plays one line of "Bicycle Built For Two" (with lyrics).

• MUSIC2.C--Speaker demonstration: plays one line of "Für Elise" as background music while other processing is going on.

• REMOTE1.C--Demonstrates simple serial data communication using a remote ANSI terminal such as Hyperterminal from an available PC COM port connection.

• SMTPDEMO.C--Uses the TCPIP\SMTP.LIB library to send an e-mail when a key on the keypad or a switch on the Demonstration Board is pressed. See Appendix D for hookup instructions for the Demonstration Board.

• SPEAKER.C--Demonstrates how to adjust the speaker frequency and volume.

• TCP_RESPOND.C--Shows how to receive messages and respond.

• TCP_SEND.C--Shows how to send message to specific addresses and ports.

The programs TCP_SEND.C and TCP_RESPOND.C are meant to be executed on two different Intellicom boards so that the two boards communicate with each other. In the absence of a second board, PCSEND.EXE (used with TCP_SEND.C) and PCRESPOND.EXE (used with TCP_RESPOND.C) in the SAMPLES\ICOM\WINDOWS directory can be used on the PC console side at the command prompt. Both the executables and the C source code are located in the WINDOWS directory.

Using PCSEND

PCSEND.C is the source code for PCSEND.EXE used on the PC console side to communicate with an Intellicom board. The executable PCSEND.EXE is similar to TCP_SEND.C, but is run at the command prompt to communicate with an Intellicom board running TCP_RESPOND.C.

Using PCRESPOND

PCRESPOND.C is the source code for PCRESPOND.EXE used on the PC console side to communicate with an Intellicom board. The executable PCRESPOND.EXE is similar to TCP_RESPOND.C, but is run at the command prompt to communicate with an Intellicom board running TCP_SEND.C.

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 Intellicom 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 4, "Programming Cable 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.