Introduction

The RS232TdvCmdProtocol3 is a component which sends and receives command strings through RS232. The component gives events when it receives commands and values.

There is a companion ActiveX component called IMTdvCmdProtocol with the same interface working over TCP/IP using the Internet Messenger ActiveX component as its transport protocol.

This RS232TdvCmdProtocol3 is a part of the TORDIVEL SOFTWARE SOLUTIONS.

RS232TdvCmdProtocol3 is copyright of TORDIVEL AS 2002.

23 May 2002, Oslo, Norway.

Help Index

•	The Package

•	Properties

•	Methods

•	Events

•	Protocol

•	Using the ActiveX component

•	Using the test program


The Package

The package consists of

•	RS232TdvCmdProtocol3.ocx (the component)

•	ReadMe.txt (read me file)

•	RS232TdvCmdProtocol3.hlp (help file)

•	RS232TdvCmdProtocol3Test.exe (test program)


Properties

Name	Type	RW	Description
ConfigXML	WideString	RW	The complete configuration in SPB-XML format
Timeout	Integer	RW	The time the component waits before the data is deemed lost. Default: 20 s
Checksum	WordBool	RW	Determines whether checksum is added to the data. Default: FALSE
Separator	Byte	RW	The character that separates multiple commands in one data string. Default: ‘;’
Mode	Integer	RW	Three values are valid: 0: Normal 1: Simulator 2: Disable
PortOpen	WordBool	R	Indicates whether the port is open


Methods

Name	Parameters	Return Value	Description
Send	Command: WideString		Sends Command
SetPortNo	PortNo: integer		Sets the COM port number for the communication
GetPortNo		Integer	Gets the COM port number
SetPortParametres	Parametres; WideString		Sets baud rate, data bits, parity and stop bits. The parametres must be separated by the character defined in the Separator property
GetPortParametres		WideString	Gets values of baud rate, data bits, parity and stop bits.
AboutBox			Shows the About box


Events

Name	Parameters	Description
OnCommand	Command: WideString	Occurs when a command is received
OnValue	Name, Value; WideString	Occurs when a value is received
OnError	Id: Integer; Error: WideString	An error has occurred: Id = 0: COM port error Id = 1: Port already open Id = 2: Port not open Id = 3: Invalid port number Id = 4: No port selected Id = 5: No configuration file is defined Id = 6: Parametres error Id = 7: Timeout Id = 8: Checksum error
OnConfigureChange		Occurs when the configuration changes
OnPacketStart		Occurs when the start control character(s) is received
OnPacketEnd		Occurs when the end control character is received


Protocol

The TDVCmdProtocol is a simple text-format where commands and values are separated with the ‘;’-character. A command is defined as a string and a value is defined by a tag and a value separated with an ‘=’ character.

A typical message consists of a command and a couple of values:

Example: watch;program=scorpion;value=on

Using a text protocol where values are identified with tags and commands are commands means that application protocols can be defined and extended without having the receiving parser to fail even if command or values not known are received.

The RS232TDVCmdProtocol3 defines the following transport layer to securely transmit the messages over RS-232. The protocol is kept very simple to make it easy to implement it on any device or controller.

•	<stx> is used to start the packet. By default <stx> has ASCII value 02h.

•	<etx> is used to end a packet. <etx> has ASCII value 03h.

An optional <checksum> is two bytes wide and is inserted before <etx>

The data sent over the wire without checksum is:

Example: <stx>watch;program=scorpion;value=on<etx>

with checksum:

example: <stx>watch;program=scorpion;value=on;<checksum><etx>

The checksum is represented by a 2-character ASCII hexadecimal format and is transmitted along with the data string. The checksum equals the modulo-256 (100h) sum of all the ASCII values in the data string.

In the above example the checksum is:

77h (w) + 61h (a) + 74h (t) + 63h (c) + 68h (h) + 3Bh (;) +

70h (p) + 72h (r) + 6Fh (o) + 67h (g) + 72h (r) + 61h (a) + 6Dh (m) + 3Dh (=) +

73h (s) + 63h (c) + 6Fh (o) + 72h (r) + 70h (p) + 69h (i) + 6Fh (o) + 6Eh (n) + 3Bh (;) +

76h (v) + 61h (a) + 6Ch (l) + 75h (u) + 65h (e) + 3Dh (=) + 6Fh (o) + 6Eh (n)

= C66h mod 100h = 66h

The complete ASCII table


Using the test program

The purpose of this program is to test and demonstrate the RS232TdvCmdProtocol3 component.

The program consists of the following tabs:

•	RS232TdvCmdProtocol3

•	SimpleScheduler3

•	About


RS232TdvCmdProtocol3

On this page you can configure the component and test the main features.

Commands and values which are received are listed in the log, along with any warnings and error messages. You can configure the log to show what you want to see and how you want to see it.

The messages are listed according to the table below:

Message	Level	In\out	Normal	Raw data
STX	2	In	‘Packet start’	Start character(s)
ETX	2	In	‘Packet end’	End character
Command	1	In\out	Command	Command
Value	1	In\out	Value	Value

If then Raw data check box is checked all messages are shown with STX and ETX characters, and the checksum( if enabled ).


Log configuration

By right clicking in the log you get a menu as shown below. Here you can set which levels you want to display, you can set the log’s size, empty it, delete it, and by choosing Configuration you can set more advanced options.


Advanced Log Configuration

In this dialog you can customize the log’s layout, - e.g. set the columns’ captions, fonts and colors.

You can also set the format to display date/time information, where

H: hour

N: minute

S: second

Z: ms

D: day

M: month

Y: year

Example:

hh:nn:ss.zz DD/MMM/YYYY yields 16:34:52.22 30/JAN/2001


SimpleScheduler3

On this page you can enable automatic sending of strings.


About


Using the ActiveX component

The RS232TdvCmdProtocol3 component consists of the form shown below, along with an About Box.

If the Checksum is enabled a checksum is added to the data. The checksum is represented by a 2-character ASCII hexadecimal format and is transmitted along with the data string. The checksum equals the modulo-256 (100h) sum of all the ASCII values in the data string.

You can choose between three different protocols:

1.	<STX><Data><ETX>

•	Start control character: #2

•	End control character: #3

•	Checksum disabled

2.	<STX><Data><Checksum><ETX>

•	Start control character: #2

•	End control character: #3

•	Checksum enabled

3.	<SOH><STX><Data><ETX>

•	Start control character: #1#2

•	End control character: #3

•	Checksum disabled

You can choose between three different modes:

1.	Normal

•	The port is open.

•	Messages are sent and received, events are generated and messages are shown in the log according to the Show in / out messages checkboxes.

2.	Simulator

•	The port is open

•	Received messages are shown in the log, but no events are generated

•	Sent messages are shown in the log, but are not physically sent.

3.	Disable

•	The port is closed.

•	No messages are sent or received, and nothing is shown in the log.

From the panel which appears when ticking the Show simulator checkbox you can simulate sending and receiving messages.


Normal mode

In normal mode the strings are actually sent when pressing the Send button and the From application checkbox is ticked.


Simulator mode


Disable mode


The Complete ASCII table


TORDIVEL SOFTWARE SOLUTIONS

TORDIVEL AS Software House is developing a portfolio of Windows NT/2000 software components and solutions with the following properties:

•	Simple and easy to use

•	Very high quality

•	Requirements from real use cases

•	Easy to deploy

•	"Simply working"

•	Network applications building blocks

Important keywords are: HTTP, TCP/IP, XML, and stateless servers.

These components and solutions are divided into two categories:

•	Professional Software Components

•	Freeware Components Library

We distribute the components and solutions to promote the skills of the experienced developers working at TORDIVEL and want to establish links to developers and companies all over the world.

If you have comments/suggestions your feedback is more than appreciated. Please contact us.

Storgata 20 N-0184 OSLO NORWAY
Telefax +47 2315 8701 Telephone +47 2315 8700
E-mail: office@tordivel.com Web: http://www.tordivel.com


Copyright Notice

(c) 2001, 2002 RS232TdvCmdProtocol3 is copyright of

Storgata 20 N-0184 OSLO NORWAY
Telefax +47 2315 8701 Telephone +47 2315 8700
E-mail: office@tordivel.com Web: http://www.tordivel.com