Wonderware SATELLITE I/O Server User`s Guide

Wonderware SATELLITE I/O Server User`s Guide
Wonderware Rapidkit I/O Server
User’s Guide
Revision A
March 2001
Wonderware Corporation
All rights reserved. No part of this documentation shall be reproduced, stored in a
retrieval system, or transmitted by any means, electronic, mechanical, photocopying,
recording, or otherwise, without the prior written permission of the Wonderware
Corporation. No copyright or patent liability is assumed with respect to the use of
the information contained herein. Although every precaution has been taken in the
preparation of this documentation, the publisher and author assume no responsibility
for errors or omissions. Neither is any liability assumed for damages resulting from
the use of the information contained herein.
The information in this documentation is subject to change without notice and does
not represent a commitment on the part of Wonderware Corporation. The software
described in this documentation is furnished under a license or nondisclosure
agreement. This software may be used or copied only in accordance with the terms
of these agreements.
Wonderware Rapidkit I/O Server User’s Guide
 2001 Wonderware Corporation. All Rights Reserved.
100 Technology Drive
Irvine, CA 92618
U.S.A.
(949) 727-3200
http://www.wonderware.com
Trademarks
All terms mentioned in this book that are known to be trademarks or service marks
have been appropriately capitalized. Wonderware Corporation cannot attest to the
accuracy of this information. Use of a term in this book should not be regarded as
affecting the validity of any trademark or service mark.
Wonderware and InTouch are registered trademarks of Wonderware Corporation.
Wonderware FactorySuite, WindowMaker, WindowViewer, SQL Access Manager,
Recipe Manager, SPC Pro, DBDump, DBLoad, HDMerge, HistData, Wonderware
Logger, InControl, InTrack, InBatch, IndustrialSQL, FactoryOffice, Scout,
SuiteLink and NetDDE are trademarks of Wonderware Corporation.
Contents
INTRODUCTION .................................................................................................. 1
COMMUNICATION PROTOCOLS .......................................................................... 1
ACCESSING REMOTE ITEMS VIA THE I/O SERVER .............................................. 2
RAPIDKIT MAIN WINDOW.............................................................................. 3
USING THE FILE MENU ...................................................................................... 3
CONFIGURING THE I/O SERVER ................................................................... 5
RENAMING THE SERVER ................................................................................ 6
SERVER NAME ................................................................................................... 6
CONFIGURING THE RAPIDKIT PORTS........................................................ 7
DELETING A PROTOCOL ..................................................................................... 7
MODIFYING A PROTOCOL NAME......................................................................... 7
CONFIGURING A COM PORT ......................................................................... 9
ADVANCED COM SETTINGS......................................................................... 13
CONFIGURING A TCP/IP (SOCKETS) PORT.............................................. 17
ADDING A PORT ............................................................................................... 21
DELETING A PORT .......................................................................................... 22
VIEWING THE ITEM SYNTAX ...................................................................... 23
CONFIGURING A TOPIC DEFINITION........................................................ 26
ADDING A NEW RAPIDKIT TOPIC CONFIGURATION........................... 27
CONFIGURING THE I/O SERVER SETTINGS ............................................ 29
CONFIGURING THE LOGGER MODE ......................................................... 31
SETTING SECURITY ........................................................................................ 32
USING THE DATA MENU................................................................................ 33
MONITORING DATA ....................................................................................... 34
CREATING AN ASCII TEXT FILE FROM THE DATA MONITOR
WINDOW............................................................................................................. 38
CREATING AN ASCII TEXT FILE FROM ALL ACTIVE DATA .............. 39
CREATING A CSV FILE................................................................................... 40
DESIGNING AN I/O SERVER PROTOCOL .................................................. 41
UNDERSTANDING PROTOCOL OBJECTS ............................................................ 41
OBJECT DEFINITIONS ....................................................................................... 41
RAPIDKIT STRING SYNTAX ............................................................................... 42
USING THE PROTOCOL MODELER TO CONFIGURE PROTOCOLS .. 44
Table of Contents
ADDING A NEW PROTOCOL......................................................................... 46
EDITING A PROTOCOL .................................................................................. 47
CONFIGURING A SERIAL PROTOCOL (COM PORT) ............................. 49
CREATING ADVANCED COM SETTINGS................................................... 52
CONFIGURING A TCP/IP PROTOCOL (SOCKETS) .................................. 56
DEFINING A MESSAGE................................................................................... 60
DEFINING PARAMETERS .............................................................................. 64
DEFINING CHECKSUM PARAMETERS ............................................................... 64
DEFINE DATA PARAMETER ............................................................................. 67
DEFINE CONSTANT PARAMETER ..................................................................... 68
DEFINE ITEM PARAMETER............................................................................... 69
DEFINE TOPIC PARAMETER ............................................................................. 70
DEFINE ERROR CODE PARAMETER.................................................................. 72
DEFINE ERROR CODE VALUE .......................................................................... 74
DEFINE USER FUNCTION PARAMETER ............................................................. 75
DEFINE ITEM .................................................................................................... 77
I/O SERVER HELP MENU ............................................................................... 80
CONTENTS ....................................................................................................... 80
HOW TO USE HELP .......................................................................................... 80
ABOUT RAPIDKIT ......................................................................................... 80
DEFINING ITEM NAMES ................................................................................ 81
PREDEFINED ITEM/POINT NAMES .................................................................... 81
MONITORING THE STATUS OF COMMUNICATIONS WITH A DEVICE
............................................................................................................................... 84
USING THE STATUS ITEM IN MICROSOFT EXCEL.............................................. 84
MONITORING THE STATUS OF AN I/O CONVERSATION..................... 85
USING DDESTATUS AND IOSTATUS IN MICROSOFT EXCEL ............................ 85
READING VALUES FROM THE I/O SERVER INTO MICROSOFT
EXCEL ................................................................................................................. 86
WRITING VALUES TO THE I/O SERVER FROM MICROSOFT EXCEL
............................................................................................................................... 87
TROUBLESHOOTING I/O SERVER COMMUNICATION PROBLEMS . 88
DEBUGGING COMMUNICATION BETWEEN INTOUCH AND AN I/O SERVER....... 88
DEBUGGING COMMUNICATION BETWEEN SUITELINK AND AN I/O SERVER..... 90
DEBUGGING COMMUNICATION BETWEEN AN I/O SERVER AND A PLC ........... 91
SPECIAL WONDERWARE LOGGER MESSAGES ..................................... 99
LOCAL COM PORT ERRORS ............................................................................ 99
COM PORT ERRORS ........................................................................................ 99
LOCAL TCP/IP PORT ERRORS.......................................................................... 99
TCP/IP PORT RUN-TIME ERRORS ................................................................... 100
DATA CONVERSION ERRORS .......................................................................... 100
COMMUNICATION ERRORS ............................................................................ 101
Table of Contents
CHECKSUM ERRORS ...................................................................................... 101
RUN-TIME ERRORS ........................................................................................ 101
GLOBAL ERRORS (NON-SERVER SPECIFIC) ..................................................... 102
Rapidkit Main Window
Wonderware Rapidkit I/O Server
Introduction
The Wonderware Rapid Protocol Modeler Kit (Rapidkit) I/O Server (referred to
as the server through the remainder of this user’s guide) is a Microsoft Windows
application program that acts as a communication protocol server. It allows other
Windows application programs access to data from devices via configurable
protocols. While the Rapidkit run-time allows loading and executing multiple
protocols simultaneously, the integrated protocol modeler gives you the ability to
create new protocols for your specific bus systems. Available communication
types are:
• Serial communication via COM port
• TCP/IP via windows sockets (WinSock)
While the server is primarily intended for use with Wonderware InTouch (version
3.01 and later), any Microsoft Windows program capable of acting as a DDE,
FastDDE, or SuiteLink™ client may use it.
Communication Protocols
Dynamic Data Exchange (DDE) is a communication protocol developed by
Microsoft to allow applications in the Windows environment to send/receive data
and instructions to/from each other. It implements a client-server relationship
between two concurrently running applications. The server application provides
the data and accepts requests from any other application interested in its data.
Requesting applications are called clients. Some applications such as InTouch and
Microsoft Excel can simultaneously be both a client and a server.
FastDDE provides a means of packing many proprietary Wonderware DDE
messages into a single Microsoft DDE message. This packing improves efficiency
and performance by reducing the total number of DDE transactions required
between a client and a server. Although Wonderware's FastDDE has extended the
usefulness of DDE for our industry, this extension is being pushed to its
performance constraints in distributed environments.
NetDDE extends the standard Windows DDE functionality to include
communication over local area networks and through serial ports. Network
extensions are available to allow DDE links between applications running on
different computers connected via networks or modems. For example, NetDDE
supports DDE between applications running on IBM compatible computers
connected via LAN or modem and DDE-aware applications running on non-PC
based platforms under operating environments such as VMS and UNIX.
SuiteLink uses a TCP/IP based protocol and is designed specifically to meet
industrial needs such as data integrity, high-throughput, and easier diagnostics.
This protocol standard is only supported on Microsoft Windows NT 4.0 or higher.
1
2
Wonderware Rapidkit I/O Server
SuiteLink is not a replacement for DDE, FastDDE, or NetDDE. The protocol used
between a client and a server depends on your network connections and
configurations. SuiteLink was designed to be the industrial data network
distribution standard and provides the following features:
• Value Time Quality (VTQ) places a time stamp and quality indicator on all
data values delivered to VTQ-aware clients.
• Extensive diagnostics of the data throughput, server loading, computer
resource consumption, and network transport are made accessible through the
Microsoft Windows NT operating system performance monitor. This feature
is critical for the scheme and maintenance of distributed industrial networks.
• Consistent high data volumes can be maintained between applications
regardless if the applications are on a single node or distributed over a large
node count.
• The network transport protocol is TCP/IP using Microsoft’s standard WinSock
interface.
Accessing Remote Items via the I/O Server
The communication protocol addresses an element of data in a conversation that
uses a three-part naming convention that includes the application name, topic name
and item name. The following briefly describes each portion of this naming
convention:
application name
The name of the Windows program (server) that
accesses the data element. In the case of data coming
from or going to equipment via this server, the
application portion of the address is Rapidkit. This
name can be re-configured. Please see Renaming the
Server on page 6 for detailed information on
configuring the server name.
topic name
Meaningful names are configured in the server to
identify specific devices. These names are then used as
the topic name in all conversations to that device. For
example, S115.
Note You can define multiple topic names for the same
device to poll different points at different rates.
item name
A specific data element within the specified topic. For
example, when using this server, an item can be a relay,
timer, counter, register, etc., in the PLC.
Note The item/point names are predefined by the
server. The term "point" is used interchangeably with
the term "item" in this user's guide.
For more information on item/point names, see the "Item Names" section
later in this user's guide.
Rapidkit Main Window
Rapidkit Main Window
To start Rapidkit, double-click the Rapidkit icon.
Rapidkit starts and the main window displays.
The current configuration file and its full path display in the main window title bar.
If a topic is active, it displays in the client area of the main window, called the
topic monitor list.
Using the File Menu
Use the options on the File menu to load and save the internal topic configuration
database.
New
Use the New option to clear the internal topic database for a new topic
configuration. This option is disabled when the Rapidkit server is active (a client
is connected).
3
4
Wonderware Rapidkit I/O Server
Open
Use the Open option to replace the internal topic database with the information
contained in the new topic configuration file. This file is automatically loaded the
next time the server is started. This menu is disabled when the Rapidkit server is
active (a client is connected).
Save As
Use the Save As option to save the internal topic database under a new name. This
command is only needed if you want to save the configuration under a different
name. If you edit the internal topic database, the data is stored automatically in the
current configuration file. This menu is disabled when the Rapidkit server is active
(a client is connected).
Exit
Select Exit to terminate the Rapidkit server.
Configuring the I/O Server
5
Configuring the I/O Server
Once the server has been installed, some configuration is required. Configuring the
server automatically saves the data in a configuration file. If no configuration file
is selected, you are prompted to select a filename.
Use the options on the Configure menu to access the windows used to configure
the server.
Option
Description
Server Name…
Register the server under a different name.
Selecting this option accesses the Server Name
window. See Server name on page 6.
Ports…
Use this option to view and modify port
definitions. Selecting this option accesses the
Select Port window. See Configuring the Rapidkit
Ports on 7
Topic Definition…
Use this option to create, modify or delete a topic
definition. Selecting this option accesses the Topic
Definition window. See Configuring a Topic
Definition on page 26.
Server Settings…
Use this option to change protocol timer, to change
the default configuration file path, or to enable the
server to start automatically as Windows NT.
Selecting this option accesses the Server Settings
window. See Configuring the I/O Server Settings
on page 29.
Logger…
Use this option to set the logger mode for the
server. Selecting this option accesses the Set
Logger Mode window. See Configuring the
Logger Mode on page 31.
Security…
Use this option to set the server security. Selecting
this option accesses the Security window. See
Setting Security on page 32.
6
Wonderware Rapidkit I/O Server
Renaming the Server
Use the Server Name window to register the server under a different name, other
than “Rapidkit”. To access the Server Name window, select Server Name from
the Configure menu or click the Configure Server Name icon on the Rapidkit main
window toolbar.
The Server Name window displays.
Enter the new name for the server, then click OK.
Server name
The following cases require renaming the server:
• The DDE/SuiteLink I/O server name (application name) should reflect the
protocol name.
• Running several instances of Rapidkit (each with its own configuration file).
The server name is stored in the working directory of the server in the following
file:
ServerName.ini
Note You do not need to rename the server if you want Rapidkit to communicate
on several ports with different protocols. One instance of Rapidkit can load and
operate multiple protocols simultaneously.
SuiteLink requires the registered I/O server name and the EXE name to be
identical. If you configure a new server name (i.e. “BarCode”) you need to rename
the Rapidkit.exe file to reflect the new name in the executable file name. To do
this, copy the file “Rapidkit.exe” to “BarCode.exe”. This may also require creating
the corresponding windows shortcuts to manually start BarCode.exe.
To run several instances of Rapidkit simultaneously:
• Copy the Rapidkit.exe file into different directories
• Rename the I/O server name, so that each copy accesses its own
ServerName.ini file
It is not possible to run Rapidkit as a service if the .exe name is not Rapidkit.exe.
If a different I/O server name is used (configured under Server Name) when
running as a service, only DDE communication is possible.
Note The main window title bar always displays the name Rapidkit.
Configuring the Rapidkit Ports
Configuring the Rapidkit Ports
Use the Select Port window to view or modify port definitions.
To access the Select Port window, select the Port option from the Configure
menu, or click the Port icon. The Select Port window displays.
The Select Port window displays the following information for configured ports:
• Protocol name assigned to the port
• Server port location
• Filename
Deleting a protocol
1.
Select the protocol name in the Protocol column.
2.
Click Delete. A message displays, where you confirm the delete by clicking
OK.
3.
Click Done to save the changes and close the Select Port window.
Modifying a protocol name
1.
Double-click the protocol name in the Protocol column.
2.
Make appropriate changes on the COM port window. See Configuring a
COM Port on page 9 for detailed instructions.
3.
Click Done to save the changes and close the Select Port window.
Note If this is the first configuration performed for the server, the Save
Configuration window displays prompting you to save the configuration file.
7
8
Wonderware Rapidkit I/O Server
Buttons on this window
Click Done to close the Select Port window and accept any new modifications,
additions, or deletions.
Click Configure to specify the port settings for the selected port. The port window
for the selected port displays. You can also access the port window by doubleclicking the name in the Protocol column on the Select Port window.
See Configuring a COM Port on page 9.
See Configuring a TCP/IP Protocol (Sockets) on Page 56
Click Add to add a new protocol. The Load Protocol window displays.
See Adding a Port on page 21.
Click Delete to delete the selected protocol.
Click Syntax to view the item syntax of the selected protocol. The Item Syntax
window displays.
See Viewing the Item Syntax on page 23.
Click Help to access the Rapidkit online help system.
Configuring a COM Port
9
Configuring a COM Port
Use the COMxx port window to configure the settings for a port.
To access the COMxx port window:
1.
Select the Port option from the Configure menu.
2.
Select the appropriate COM port protocol from those listed in the Select Port
window.
3.
Click Configure.
The COM port window for the selected protocol displays.
Use the Baud rate field to specify the baud rate (bits per second) at which the serial
port communications device operates.
Available baud rates are:
110
300
600
1200
2400
4800
9600
14400
19200
38400
56000
57600
115200
128000
256000
Use the Data bits field to specify the number of bits in the bytes transmitted and
received. This member can be one of the following values:
4, 5, 6, 7, 8
Use the Stop bits field to specify the number of stop bits to be used. This member
can be one of the following values:
1, 1.5, 2
Note When configuring the 8250, the following restrictions apply to the values
specified for the Data Bits and Stop Bits members:
!
!
The number of data bits must be 5 to 8 bits.
The use of 5 data bits with 2 stop bits is an invalid combination, as is 6, 7,
or 8 data bits with 1.5 stop bits.
10
Wonderware Rapidkit I/O Server
Use the Parity field to specify the parity scheme to be used. This member can be
one of the following values:
None, Odd, Even, Mark, Space
Use the Response timeout field to specify the response timeout in seconds when
waiting for a response to a sent read or write message from the device. Set this
timeout to a value that safely guarantees responses within this time under normal
conditions.
• Setting the timeout too short results in reporting errors, bad status, and
discarding of response messages.
• Setting this timeout too long results in detecting an error condition late.
Select or deselect this field to enable or disable the protocol simulation mode on a
port.
• If not checked the protocol operates normally on the COM port.
• If checked the COM port is not opened or accessed in any way.
All messages sent and received are simulated and can be viewed in the logger when
setting the logger mode to log protocol. Simulated responses consist of a correct
response message as defined in the protocol. Variable data sections in responses
are initialized to zero. It is possible to modify these values and even to create
complete user defined responses by modifying a file called SIMULATE.TXT in
the server’s directory. Refer to the protocol definition and the protocol specific
documentation supplied by the protocol vendor for the syntax of this simulation
data file.
Use this mode to test a client application without a physical device connected. As
a protocol designer you may want to use this mode to test your protocol generated
messages, data conversion routines and error handling against the protocol
specification.
Note Only request/response or poke/response messages are automatically
simulated in simulation mode. Unsolicited messages or user defined non-zero data
sections require the file simulate.txt to be edited according to the protocol syntax.
Syntax of Simulate.txt:
Simulate.txt is expected to be in the windows profile format containing sections
and entries.
Simulating data values:
[<protocol name>]
data=<value>
Whenever Rapidkit evaluates data values, it checks if they can be retrieved from
Simulate.txt. Values are scanned as ASCII data for ASCII protocols or as hexascii
data for binary protocols. The data does not need to fit the exact data parameter
size. It is expanded with zeros if too short or truncated if too long. Escape
Configuring a COM Port
sequences can be used to enter binary values in ASCII data or ASCII values in
binary data. The syntax is identical to the format in the protocol designer.
Note: If the same data parameter is used in different messages all parameter values
will be affected.
Simulating poll/poke responses:
[<port name>]
<message name>=<message data>
Whenever Rapidkit generates simulated protocol request/write responses, it checks
if they can be retrieved from Simulate.txt. Messages are scanned as ASCII data for
ASCII protocols or as hexascii data for binary protocols. The message format must
match the exact message specification as defined in the protocol designer. Escape
sequences can be used, too.
The port name must match the port/protocol name reference as displayed in the
port combo box of the topic configuration dialog.
Note: Use this simulation to simulate all test cases of valid and invalid response
messages to test the error handling of the protocol.
Simulating unsolicited messages:
[<port name>]
<non RPM message name>=<message data>
receive=<non RPM message name>
Whenever Rapidkit scans the port for data, it checks if there is a receive entry
under the port name section in Simulate.txt. If this entry exists and a message is
configured it uses this data as received data. It then resets the receive entry to an
empty string. This is necessary to avoid continuos reception of data. Messages are
scanned as ASCII data for ASCII protocols or as hexascii data for binary protocols.
The port name must match the port/protocol name reference as displayed in the
port combo box of the topic configuration dialog.
Note: Response message simulation has precedence over unsolicited message
simulation.
Example of a Simulate.txt file:
;data simulation
[ASCII test protocol]
data=BAFC
;poll response simulation
[COM1 ASCII test protocol]
readdata=\02S0155BAFCDD\03
;unsolicited message simulation
[COM1 ASCII test protocol]
msg1=\02U0155BAFCDD\03
receive=msg1
Buttons on this window
11
12
Wonderware Rapidkit I/O Server
Click OK to accept settings as the set of COM default parameters for the port
configuration.
Click Cancel to discard changes.
Click Default to assign standard COM parameters to the complete COM default
configuration (basic and advanced)
Click Advanced to open the Advanced COM Settings window. See Advanced
COM settings on page 13.
Click Help to access the Rapidkit online Help system.
Advanced COM settings
Advanced COM settings
Use the Advanced COM Settings window to set all advanced COM port
parameters available DCB (device control block).
To configure a COM port protocol:
1.
Select the Port option from the Configure menu.
2.
Select the appropriate COM port protocol from those listed in the Select
Port window.
3.
Click Configure to access the COM Port window.
4.
Click Advanced.
The Advanced COM Settings window for the selected protocol displays.
Transmit section
Use the CTS output flow control field to specify whether the CTS (clear-to-send)
signal is monitored for output flow control.
If this member is selected and CTS is turned off, output is suspended until CTS is
sent again.
Use the DSR output flow control field to specify whether the DSR (data-setready) signal is monitored for output flow control.
If this member is selected and DSR is turned off, output is suspended until DSR is
sent again.
13
14
Wonderware Rapidkit I/O Server
Use the XON/XOFF field to specify whether XON/XOFF flow control is used
during transmission.
If this member is selected, transmission stops when the XoffChar character is
received and starts again when the XonChar character is received.
Use the continue on XOFF sent field to specify whether transmission stops when
the input buffer is full and the driver has transmitted the XoffChar character.
• If this member is selected, transmission continues after the input buffer has
come within XoffLimit bytes of being full and the driver has transmitted the
XoffChar character to stop receiving bytes.
• If this member is not set, transmission does not continue until the input buffer
is within XonLimit bytes of being empty and the driver has transmitted the
XonChar character to resume reception.
RTS (Request to send) control section
Use the RTS control section to specify the RTS (request-to-send) flow control.
This member can be one of the following values:
Value
Meaning
Disable
Disables the RTS line when the device is opened and leaves it
disabled.
Enable
Enables the RTS line when the device is opened and leaves it on.
Handshake
Enables RTS handshaking. The driver raises the RTS line when the
"type-ahead" (input) buffer is less than one-half full and lowers the
RTS line when the buffer is more than three-quarters full.
Toggle
Specifies that the RTS line will be high if bytes are available for
transmission. After all buffered bytes have been sent, the RTS line
will be low.
Receive section
Use the options in the Receive section to set your specifications for receiving data.
Use the DSR sensitivity field to specify whether the communications driver is
sensitive to the state of the DSR signal.
Advanced COM settings
15
If this member is selected, the driver ignores any bytes received, unless the DSR
modem input line is high.
Use the XON/XOFF field to specify whether XON/XOFF flow control is used
during reception.
If this member is set, the XoffChar character is sent when the input buffer comes
within XoffLimit bytes of being full, and the XonChar character is sent when the
input buffer comes within XonLimit bytes of being empty.
Use the Enable error replacement field to specify whether bytes received with
parity errors are replaced with the character specified by the Error char member.
If this member is set and the Parity member is set, replacement occurs.
Use the Discard NULL bytes field to specify whether null bytes are discarded.
If this member is TRUE, null bytes are discarded when received.
Use the options in the DTR control box to specify the DTR (data-terminal-ready)
flow control.
The available settings in this box are defined as follows:
Value
Meaning
Disable
Disables the DTR line when the device is opened and leaves
it disabled.
Enable
Enables the DTR line when the device is opened and leaves it
on.
Handshake
Enables DTR handshaking.
Use the XON limit field to specify the minimum number of bytes allowed in the
input buffer before flow control is activated to inhibit the sender. Note that the
sender may transmit characters after the flow control signal has been activated, so
this value should never be zero. This assumes that either XON/XOFF, RTS, or
DTR input flow control is specified.
16
Wonderware Rapidkit I/O Server
Use the XOFF limit field to specify the maximum number of bytes allowed in the
input buffer before the sender activates flow control to allow transmission. This
assumes that either XON/XOFF, RTS, or DTR input flow control is specified. The
maximum number of bytes allowed is calculated by subtracting this value from the
size, in bytes, of the input buffer.
Use the Error char field to specify the value of the character used to replace bytes
received with a parity error.
Global section
The Global section provides options for the global settings.
Use the XON char field to specify the value of the XON character for both
transmission and reception (in hex notation).
Use the XOFF char field to specify the value of the XOFF character for both
transmission and reception (in hex notation).
Use the EOF char field to specify the value of the character used to signal the end
of data (in hex notation).
Use the Event char field to specify the value of the character used to signal an
event (in hex notation).
Configuring a TCP/IP (Sockets) port
Configuring a TCP/IP (Sockets) port
Use the Configure TCP/IP Parameters window to configure a TCP/IP port
displayed in the Select Port window.
To access the Configure TCP/IP Parameters window:
1.
Select the Port option from the Configure menu.
2.
Select the appropriate TCP/IP protocol from those listed in the Select Port
window.
3.
Click Configure.
The Configure TCP/IP Parameters window displays.
Enter a logical name for this port in the Port name field.
Local Parameters Port
Enter a short integer, representing the port, or select the Default option.
• For a server socket (passive connection - see below), you must specify a port.
• For a client socket (active connection - see below), you typically accept the
default value for this parameter, allowing Windows Sockets to select a port.
17
18
Wonderware Rapidkit I/O Server
• If the protocol on this port allows setting the local port in the topic or if you
checked Default, this field is disabled.
Local Parameters Address
Enter a socket address, such as ftp.microsoft.com, 128.56.22.8, or the name of the
computer in the network.
This is your Internet Protocol (IP) address on the network. You will probably rely
on the default value for this parameter.
If the protocol on this port allows setting the local address in the topic or if you
checked Default, this field is disabled.
Remote Parameters Port
Enter a short integer representing the remote port number.
If the protocol on this port allows setting the local port in the topic, this field is
disabled.
Remote Parameters Address
Enter the network address of the socket to which this object is connected.
Examples of appropriate entries in this field are:
• A machine name, such as ftp.microsoft.com
• A dotted number, such as “128.56.22.8”.
If the protocol on this port allows setting the local address in the topic, this field is
disabled.
• Select Active to establish a client connection actively to a server.
• Select Passive to connect in TCP/IP server mode. Wait for a client connection
(listening mode).
Use this field to specify the response timeout in seconds. This refers to the time
elapsing when waiting for a response to a sent read or write message from the
device.
Set this timeout to a value that safely guarantees responses within this time under
normal conditions.
• Setting the timeout too short results in reporting errors, bad status, and
discarding of response messages.
• Setting this timeout too long results in detecting an error condition late.
Configuring a TCP/IP (Sockets) port
Use the Simulate messages field to enable or disable the protocol simulation mode
on a port.
• If not checked the protocol operates normally on the TCP/IP port.
• If checked the TCP/IP port is not opened or accessed in any way. All
messages sent and received are simulated and can be viewed in the logger
when setting the logger mode to log protocol.
Simulated responses consist of a correct response message as defined in the
protocol. Variable data sections in responses are initialized to zero. You can
modify these values and create complete user defined responses by modifying the
SIMULATE.TXT file, located in the server’s directory. Refer to the protocol
definition and the protocol specific documentation supplied by the protocol vendor
for the syntax of this simulation data file.
Use this mode to test a client application without a physical device connected. As
a protocol designer you might want to use this mode to test your protocol generated
messages, data conversion routines, and error handling against the protocol
specification.
Note Only the request/response or poke/response messages are automatically
simulated in simulation mode. Unsolicited messages, or user defined non-zero data
sections, require the file SIMULATE.TXT to be edited according to the protocol
syntax.
Syntax of Simulate.txt:
Simulate.txt is expected to be in the windows profile format containing sections
and entries.
Simulating data values:
[<protocol name>]
data=<value>
Whenever Rapidkit evaluates data values, it checks if they can be retrieved from
Simulate.txt. Values are scanned as ASCII data for ASCII protocols or as hexascii
data for binary protocols. The data does not need to fit the exact data parameter
size. It is expanded with zeros if too short or truncated if too long. Escape
sequences can be used to enter binary values in ASCII data or ASCII values in
binary data. The syntax is identical to the format in the protocol designer.
Note: If the same data parameter is used in different messages all parameter values
will be affected.
Simulating poll/poke responses:
[<port name>]
<message name>=<message data>
Whenever Rapidkit generates simulated protocol request/write responses, it checks
if they can be retrieved from Simulate.txt. Messages are scanned as ASCII data for
ASCII protocols or as hexascii data for binary protocols. The message format must
match the exact message specification as defined in the protocol designer. Escape
sequences can be used, too.
19
20
Wonderware Rapidkit I/O Server
The port name must match the port/protocol name reference as displayed in the
port combo box of the topic configuration dialog.
Note: Use this simulation to simulate all test cases of valid and invalid response
messages to test the error handling of the protocol.
Simulating unsolicited messages:
[<port name>]
<non RPM message name>=<message data>
receive=<non RPM message name>
Whenever Rapidkit scans the port for data, it checks if there is a receive entry
under the port name section in Simulate.txt. If this entry exists and a message is
configured it uses this data as received data. It then resets the receive entry to an
empty string. This is necessary to avoid continuos reception of data. Messages are
scanned as ASCII data for ASCII protocols or as hexascii data for binary protocols.
The port name must match the port/protocol name reference as displayed in the
port combo box of the topic configuration dialog.
Note: Response message simulation has precedence over unsolicited message
simulation.
Example of a Simulate.txt file:
;data simulation
[ASCII test protocol]
data=BAFC
;poll response simulation
[COM1 ASCII test protocol]
readdata=\02S0155BAFCDD\03
;unsolicited message simulation
[COM1 ASCII test protocol]
msg1=\02U0155BAFCDD\03
receive=msg1
Adding a Port
Adding a Port
Use the Load Protocol window to add a new port to the system.
To access the Load Protocol window and add a port:
1.
Select the Port option from the Configure menu.
2.
Click Add on the Select Port window.
The Load protocol window displays.
Select the appropriate protocol from the Load protocol window, then click Open.
If the protocol is a serial protocol, the Set Protocol State window displays.
Select a COM port or all COM ports on which the selected protocol will be active.
Each port/protocol combination displays a line in the Select Port window.
Note If you selected a non-serial protocol, it is loaded without prompt.
21
22
Wonderware Rapidkit I/O Server
Deleting a Port
Use the Select Port window to delete a port.
To access the Select Port window and delete a port:
1.
Select the Port option from the Configure menu.
2.
Select the appropriate protocol from those listed in the Select Port window.
3.
Click Delete.
Ports can only be deleted if the selected port is not referenced in the topic
configuration. Selecting Delete when a referenced port is selected, brings up the
following warning:
If the selected port is not referenced the following warning displays:
Viewing the Item Syntax
Viewing the Item Syntax
Use the Protocol Item Syntax window to view the syntax for a port.
To access the Protocol Item Syntax window:
1.
Select the Port option from the Configure menu.
2.
Select the appropriate protocol from those listed in the Select Port window.
3.
Click Syntax.
The Protocol Item Syntax window for the specified port displays.
Use this window to get information about qualified item names supported by the
corresponding protocol. Item syntax varies from protocol to protocol.
Available item names section
This section displays a list of available item names as defined in the corresponding
protocol. Use these names to create valid item names for client operations. The
same item name may appear several times in this list box, depending on available
access modes and/or valid ranges of item parameters.
• Item names can be constants, such as - Temperature
• Item names can contain variable sections indicated by brackets, such as –
DT<address>
• If the address is an item name parameter of type integer with a size of 5, an
example of a fully qualified item name is - DT00008
To display the item properties, select an item name from the Available item names
section
23
24
Wonderware Rapidkit I/O Server
Note An item name may contain more than one variable section (item name
parameter).
The Type field displays the data type of the selected item. It can be one of the
following:
DISCRETE, INTEGER, REAL, STRING, STRING (Hexascii)
Define your client or InTouch tag correspondingly.
The Access field displays the access mode of the selected item. It can be one of
the following:
• READ (poll) - the item can be read (via poll messages)
• READ(unsolicited) - the item can be read (via unsolicited messages)
• WRITE - the item can be written
The Comment section displays descriptive text and detailed information about the
item (as defined in the protocol).
The Item name parameters section displays a list of variable item name
parameters. Select a parameter in the list to display its properties.
The Type field displays the data type of the selected item name parameter. The
data type controls valid characters in the item name. Valid characters for the
specified type are:
• OCTAL - digits: 0...7
• DECIMAL - all digits 0...9
• HEXADECIMAL - all digits 0...9 and a...f, A...F
• STRING - any string
Viewing the Item Syntax
The Size field displays the number of characters (digits) required for the item name
parameter.
The Comment section displays descriptive text and detailed information about the
parameter as defined in the protocol.
25
26
Wonderware Rapidkit I/O Server
Configuring a Topic Definition
One or more topic definitions must exist for each device (e.g. programmable logic
controller - PLC) that the Rapidkit server communicates with. Each topic
definition must contain a unique name. Use the Topic Definition window to create
new, modify, or delete topic definitions.
To access the Topic Definition window:
1.
Open the Configure menu on the main window.
2.
Select Topic Definition from the Configure menu.
When this option is selected, the Topic Definition window displays.
Once topics have been defined, their names appear in the Topics section of the
Topic Definition window.
Buttons on this window
Click Done to close the window and accept any new definitions, modifications, or
deletions.
Click New to add a new topic definition, using the Topic Configuration window.
See Adding a new Rapidkit Topic Configuration on page 27.
Note The actual layout and number of available parameters depends on the selected
port and protocol.
Highlight a name from the listing then click Modify to modify or view its existing
topic definition. The Rapidkit Topic Configuration window displays with the
selected topic definition.
Highlight a name from the listing then click Delete to delete its topic definition. A
message box displays prompting you to confirm the deletion.
Adding a new Rapidkit Topic Configuration
Adding a new Rapidkit Topic Configuration
Use the Topic Configuration window to add a new topic definition.
To access the Topic Configuration window and create a new topic:
1.
Open the Configure menu on the main window.
2.
Select Topic Definition from the Configure menu.
3.
Click New.
The Rapidkit Topic Configuration window displays:
Enter a unique name for the device (PLC) in the Topic Name field.
Note When communicating with InTouch, this name is used as the topic name in
the Access Name definition.
Enter the frequency (in milliseconds) that the server will acquire data for the
items/points associated with this topic in the Update Interval field. If you enter
zero, Rapidkit will not actively gather data from the PLC.
Note Different items/points can be polled at different rates by defining multiple
topic names for the same PLC and setting different update rates for each topic.
Select the Enable access to update interval box to enable client access to the
update interval.
• If this box is checked, a client can read and write the update interval on this
topic through the I/O item name ‘updateinterval’.
• If this box is not checked, the client can only read the update interval.
Note The actual update interval for the slowest item on this topic can be read
through the I/O item name MAXINTERVAL. This gives you an indication of the
performance of your configuration during operation.
27
28
Wonderware Rapidkit I/O Server
Select Suppress item configuration errors if you have items defined as ‘read
only’ or ‘write only’ and you cannot prevent your client from poking to or
activating these items. This option instructs Rapidkit to not log the resulting
errors:
• ERROR:
no poke message found for item: ...
• WARNING:
no poll message defined for item:...
• ERROR:
no poll or unsolicited message defined for item:...
Select the Poke mode for this topic from the drop down menu:
Control mode - Preserves poke order and poke values. All client poke values
are poked in exactly the same order to the device. Use this mode for control
clients like InBatch, InControl etc.
Transition mode - Preserves poke order but allows the server to fold poke
values to the same item by poking only the first, second and last value to an
item in one timeslice. This mode ‘thins out’ multiple poke values generated by
moving a slider to the important transition values (no slider stuttering).
Optimization mode - No preservation of poke order and complete folding of
pokes to transmit the last value of an item only. Use this mode when
performance is critical and poke values of items are independent of each other,
such as recipe downloads.
Note: If the protocol support optimized writes (multiple items per write message)
the poke modes "Transition Mode" and "Control Mode" impose certain
requirements on the client poke order. Since Rapidkit cannot change the poke order
in these modes, non-grouped client poking of items can produce an error. An
optimized write message can be sent only, if all of the item values are available. If
a poke using a different message occurs during pokes to the write optimized
message this message can never be completed without violating the poke order.
Refer to the protocol documentation about optimized write implementations on the
specific protocol.
Select the appropriate port and protocol from the Port drop-down list. Only
currently loaded protocols are available in the port list box.
Additional parameters may appear depending on the configured protocol for the
port.
Example:
This additional parameter, PLC address field, is defined in the protocol. See
Define Topic Parameter, on page 70 for a detailed description.
Configuring the I/O Server Settings
Configuring the I/O Server Settings
To change the protocol timer, network using Wonderware NetDDE, change the
default configuration file path, or to enable the server to start automatically as a
Windows NT server, use the Server Settings option.
To access the Server Settings window:
1.
Open the Configure menu on the main window.
2.
Select Server Settings from the Configure menu.
When this option is selected, the Server Settings window displays.
Note When configuring the server on Windows NT, the user must be logged on
with system administrator privileges. This ensures that updates to the system
registry are performed.
Enter the frequency (in milliseconds) the server is to check for data to process in
the Protocol Timer Tick field. This should be approximately two to four times
faster than the fastest rate desired to update data from the equipment.
Select NetDDE being used if you are networking using Wonderware NetDDE.
To create a new default configuration file, enter the complete path for the directory
in which the file is to be saved in the Configuration File Directory field. This
new path is automatically written to the WIN.INI file and the server uses this path
to load its configuration file the next time it is started.
Notes There is no limit to the number of configuration files created. When using
the server with InTouch, it is recommended that you save the configuration file in
your application directory. For more information on the Configuration File, see
"Saving the Configuration File" in this user's guide.
Loading and saving configuration files is faster from the File menu of the Rapidkit
server.
29
30
Wonderware Rapidkit I/O Server
Select Start automatically as Windows NT Service to start the server as a
Windows NT Service.
Windows NT offers the capability of running applications even when a user is not
logged on to the system. This is valuable when systems must operate in an
unattended mode. Enabling this option and rebooting the system causes the server
to run as a Windows NT service. However, to view configuration information or
to reconfigure the server, the user must log on to the system.
Any server related problems that may arise, such as missing adapter cards,
licensing failures, or device drivers not loading, will not be visible to the user until
a log on is performed.
Disabling this option and rebooting the system causes the server to run as a
Windows NT application program once again.
Note It is recommended to have the server configured and communicating
successfully prior to running it as a Windows NT service.
Click Cancel to close the window without saving changes.
Click OK to accept the server settings. The following message box displays:
Click OK to close the window.
Note You must restart the server for the changes to take effect.
Configuring the Logger Mode
Configuring the Logger Mode
Use the Set Logger Mode window to set the Logger mode of the server.
To access the Set Logger Mode window:
1.
Open the Configure menu on the main window.
2.
Select Logger from the Configure menu.
The Set Logger Mode window displays.
• Select OFF to disable all message logging.
• Select Errors for normal operation logging to the Wonderware Logger.
• Select TRACE to log errors and all activation/deactivation activities including
calls to Rapidkit.
• Select ALL to cause the server to log all activities including single item value
updates.
• Select Show protocol to log message data.
Note When logging activity increases, the server’s performance degrades. The
logger mode defaults to “Errors” whenever Rapidkit is started.
31
32
Wonderware Rapidkit I/O Server
Setting Security
Use the Security window to set security for the server.
To access the Security window:
1.
Open the Configure menu on the main window.
2.
Select Security from the Configure menu.
The Security window displays.
This window is used to lock the server’s configuration against changes during
runtime.
The Security window example shown above is the default selection, where the
checkbox is not selected. All topics are locked against changes while the server is
active (a client is connected); however, you can still view the topic configurations.
If you select Allow configuration while topics are active you can:
• Access some elements of the topic configuration while the topics are active.
• Change the update interval.
• Enable access to update interval.
• Suppress item configuration errors.
• Change the poke mode.
You CANNOT add, delete, rename or change other properties of a topic when this
option is selected.
Click OK to accept these settings and close the Security window.
Click Cancel to close the Security window without saving the changes.
Using the Data Menu
Using the Data Menu
The Data menu contains two commands used for diagnostic purposes during
runtime:
• Data Monitor – Accesses the Data Monitor window where you view the data
received from the devices. See Monitoring data on page34.
• Dump Active Data – Accesses the Dump Active Data window, used to create
an ASCII file of all active data. See Creating an ASCII Text File from all
Active Data on page 39.
The remaining command, DB Dump, is used to transfer the internal topic database
to InTouch. See Creating a CSV File on page 40.
33
34
Wonderware Rapidkit I/O Server
Monitoring data
Use the Data Monitor window to view the data received from the devices.
To access the Data Monitor window:
1.
Open the Data menu on the main window.
2.
Select Data Monitor from the Data menu.
The Data Monitor window displays.
The data monitor window displays information of the selected topic with active
items or errors. The data is updated as it changes. It is a useful tool for tracking
down errors, for determining performance and to validate item values.
Use the Topic drop down box to select any of the active topics. A preceding ‘*’
indicates that at least one item in this topic has an error while a preceding ‘#’
indicates bad status.
The Update Interval field displays the current configured update interval of the
topic. This value changes whenever the value is poked via I/O.
The Longest Interval field displays the current update interval of the slowest item
of the topic. This value is measured for each poll cycle and each received cyclic
service indication. If this value drastically differs from the desired update interval
the communication media is not fast enough to satisfy the load.
Note Both values, update interval and longest interval, are accessible via I/O. You
can create an InTouch performance meter by displaying these values graphically
for each topic. If I/O access is enabled, you can even tune the bus performance
conveniently from InTouch.
Monitoring data
The Items field displays the number of active items and the number of items with
errors (in parenthesis). If you select this option, only items with errors display in
the item data section of this window.
Item data section
The data section adapts to the size of the window. The server saves the size and
position.
This section of the Data Monitor window displays information about the following
nine properties:
ErrPoll: Protocol specific poll error as defined in the error code parameter of
the corresponding poll message. If no error code parameter is defined this
column is left blank.
ErrUns: Protocol specific poll error as defined in the error code parameter of
the corresponding unsolicited message. If no error code parameter is defined
this column is left blank.
Pmsg: Unique identifier for the poll message of the item. Data of items with
the same Pmsg number is acquired via the same poll message. Use this
column to verify the optimization/message grouping mechanism of the
protocol.
Umsg: Unique identifier for the unsolicited message of the item. Data of
items with the same Umsg number is acquired via the same unsolicited
message. Use this column to verify the optimization/message grouping
mechanism of the protocol.
Quality: OPC compatible data quality of the item. This reflects the status of
the item’s acquired data.
Time: Time of the last update of the item. This time stamp reflects the last
protocol update of the item. This may not be identical to the client update of
the item depending on the change of value.
Raw: Raw value as scanned from the message prior to conversion. The
format is ASCII for ASCII protocols and HEXASCII for binary protocols.
Value: Current value of the item after conversion.
Name: Item name.
35
36
Wonderware Rapidkit I/O Server
An item can have six basic data quality states as described in the following table:
State
Data quality good:
Clamp hi
Clamp lo
Cannot convert
Description
00C0
Data communications are good.
Data is good.
The register was read or written without any problems
converting the data.
0056
Data communications are good.
Data is not good.
The data is clamped at high limit.
The register was read or written ok but it was necessary
to clamp its value to a limit.
The value is larger than the maximum allowed.
A string is truncated.
Example: A floating point value is clamped to
FLT_MAX
0055
Data communications are good.
Data is not good.
The data is clamped at low limit.
The register was read or written ok but it was necessary
to clamp its value to a limit.
The value is smaller than the minimum allowed.
0040
Data communications are good.
Data is not good.
The data could not be converted.
The server may return either a constant in place of the
data or return quality information alone.
The data is not useable, it is not known whether the
value is too large or too small.
Incorrect data type.
Floating point not-a-number.
Example: 0x000a in a PLC BCD register.
Monitoring data
State
No access
No communication
37
Description
0x0004
Bad, Configuration Error
Data communications are good.
Data cannot be sent and/or received.
Cannot access the item.
The item does not exist.
The item is not available.
The server is able to communicate with the PLC but is
not able to access the register.
The server determined the point is not valid.
The PLC responds that the register does not exist,
cannot be read, or cannot be written.
Cannot access a fenced, write-protected, or read-only
item.
The PLC is in a mode that does not permit access to this
item.
Incorrect number of data bytes (but the message is
otherwise good).
Invalid command or invalid op code (but the message is
otherwise good).
The PLC is busy. The server gave up retrying.
0018
Data communications are down.
Cannot access the PLC due to a communications error.
The topic is in slow poll (or equivalent) mode.
The PLC does not exist and/or is not responding.
There is no link-validating message.
Lack or resources in the server. A TSR (or driver)
cannot allocate memory.
Lack of resources in the communications link.
The communications link is off-line.
All communications channels are in use.
The network is unable to route the message to the PLC.
Select an item on the Data Monitor window to view the item properties in the I/O
DATA MONITOR window. Click OK to close the monitor.
38
Wonderware Rapidkit I/O Server
Creating an ASCII text file from the Data Monitor
Window
Use the Dump button on the Data Monitor window to create an ASCII text file
from the topics displayed in the Data Monitor window:
1.
Open the Data menu on the main window.
2.
Select Monitor from the Data menu. The Data Monitor window displays.
3.
Select the Topic from the drop down list.
4.
Click Dump.
A copy of the contents of the monitor window is sent to an ASCII text file. The
resulting file can be loaded into Microsoft Excel or any standard text editor. Tabs
separate all columns.
After the dump is complete, a message box containing the newly created ASCII
text file displays. The server automatically generates the ASCII text file name and
sets the file location using the following pattern:
<current working directory>\datmonXX.txt
where XX is a two digit number between 00 and 99. Rapidkit increments the
number each time a file is dumped.
Note Existing files with the same name are erased.
Creating an ASCII Text File from all Active Data
Creating an ASCII Text File from all Active Data
Use the Dump Active Data window to create an ASCII file containing all the active
data.
To access the Dump Active Data window and copy all active data into an ASCII
file:
1.
Open the Data menu on the main window.
2.
Select Dump Active Data. The Dump Active Data window displays.
3.
Click OK to start the process of copying all active data into an ASCII file.
Select the Errors only option to dump only those topics with errors. The resulting
file can be loaded into Microsoft Excel or any standard text editor where all
columns are separated by tabs.
After the dump is complete, a message box containing the newly created ASCII
text file name displays.
The server automatically generates the ASCII text file name and sets the files
location using the following pattern:
<current working directory>\datdmpXX.txt
where XX is a two digit number between 00 and 99. Rapidkit increments the
number each time a file is dumped.
Note Existing files with the same name are erased.
39
40
Wonderware Rapidkit I/O Server
Creating a CSV File
Use the CSV File to Dump To: window to dump the internal topic database into a
CSV file
To access the CSV File to Dump To: window and create the CSV file:
1.
Open the Data menu on the main window.
2.
Select DB Dump from the Data menu. The CSV Dump window displays.
3.
Select the Save in: location and enter a name for the file.
4.
Click Save.
The resulting file can be loaded into InTouch using Wonderware’s DBLoad utility
to automatically generate InTouch access names.
Designing an I/O Server Protocol
Designing an I/O Server Protocol
Use the Protocol option on the Design menu to locate and edit protocol elements.
Understanding Protocol objects
This section provides information to help you understand how to use the protocol
designer, followed by detailed instructions on locating and editing protocol
elements. By selecting the Protocol option from the Design menu, you can create,
view, and edit protocol objects.
A protocol object can be one of the following:
•
An entire protocol
•
A message definition (template)
•
An item definition (template)
•
A parameter
Object definitions
Word
Definition
Protocol
A protocol is a complete description of messages sent and
received to acquire data for items.
Message
Rapidkit support three types of messages:
• Poll messages (read request with data response)
• Poke message (write request with write confirmation
response)
• Unsolicited messages (spontaneous incoming
message and its response)
Messages are necessary to define read and write activities
on the protocol. Messages in the protocol designer may
41
42
Wonderware Rapidkit I/O Server
Word
Definition
contain several variable parts. This allows creation of
message templates that create multiple messages at runtime from one message definition.
Item
Items define the relationship between the address space of
objects available to the client of the I/O server and the
corresponding protocol activities. Items also may contain
variable parts so that it is possible to create item templates
that allow creation of multiple items at run-time from one
item definition.
Parameter
Parameters are a placeholder for variable parts in protocol
definitions, messages, items and topics. A parameter
configuration defines where a parameter value is obtained
and how it is converted and inserted. Parameters are
categorized according to their value origin. Using
parameters reduces the amount of message/item definitions
needed to generate a protocol. Parameters allow creation of
protocol object templates that can create multiple protocol
object instances at run-time.
Rapidkit string syntax
String
Rapidkit ASCII string
Syntax
Any printable character string.
Example:‘This is a Rapidkit ASCII string’
Rapidkit formula:
An expression of the form:
[<parameter name>][*,/][integer1][+,-][integer2]
where parameter name is a valid parameter name,
integer1 and integer2 are valid decimal numbers.
Examples:
<address>*2+100
<address>-10
<address>/4
<address>
50
Note Rapidkit formulas contain not more than one
parameter and not more than one of each of the
operations multiplication./division and
addition/subtraction.
Rapidkit parameter value
string
Any Rapidkit ASCII string or a string containing a
formula or a single parameter:
Examples:
‘Test’
<address>
Designing an I/O Server Protocol
String
Syntax
<address>/4-100
Rapidkit parameterized
ASCII string
Any printable character string where the following
characters have special meanings:
‘\’ escape character followed by a two digit
hex number representing a byte
‘<’ escape character followed by a parameter
name
‘>’ escape character terminating a parameter
name
‘{‘ escape character followed by a formula
‘}‘ escape character terminating a formula
If you want to use these character in the string
enter them as escape sequences:
Rapidkit parameterized
binary data string
‘\’ "
‘\5C’
‘<’ "
‘\3C’
‘>’ "
‘\3E’
‘{’ "
‘\7B’
‘}’ "
‘\7D’
Any character pairs consisting of :
‘0’..’9’, ‘a’..’f’, ‘A’..’F’ plus the following
special characters:
‘\’ escape character followed by a printable
character
‘<’ escape character followed by a parameter
name
‘>’ escape character terminating a parameter
name
‘{‘ escape character followed by a formula
‘}‘escape character terminating a formula
Rapidkit protocol data
string
A Rapidkit parameterized ASCII string or Rapidkit
parameterized binary data string depending on the
protocol type (ASCII or binary).
43
44
Wonderware Rapidkit I/O Server
Using the Protocol Modeler to Configure Protocols
Use the Protocol Modeler window to view protocol elements in a hierarchical tree
view and to configure new and existing protocols. Using this window, you can edit
several protocols simultaneously. Protocols are listed in the root of the tree view,
while the corresponding child elements appear as branches and leaves.
To access the Protocol Modeler window:
1.
Open the Design menu on the main window.
2.
Select Protocol.
The Protocol Modeler window displays.
Use the pop-up menu to manipulate the protocol objects:
1.
Right-click the object to access the pop-up menu.
2.
Select the appropriate function from the pop-up menu.
Option
Cut
Copy
Function
Copies a protocol object into a temporary buffer
while deleting it at the original location.
Copies a protocol object into a temporary buffer.
Using the Protocol Modeler to Configure Protocols
Option
Paste ‘<object name>’
Edit
New Protocol
NewMessage
New Parameter
New Item
Delete
Function
Pastes a protocol object into a protocol location.
• If the object is a protocol, it is pasted into the
root (independent of the selection).
• If the object is a message or parameter, it is
pasted into the selected protocol.
• If the object is an item, it is copied into the
message the selected object belongs to. The
item or message must be selected.
Opens the editor for the selected object.
Creates a new protocol.
Creates a new message on the selected protocol.
Creates a new parameter on the selected protocol.
Creates a new item on the selected message. This
menu is enabled only if a message is selected.
Deletes the selected object.
Buttons on this window
Click Done to close the window and leave the protocol designer.
Click New to access the New Protocol Object window where you can create a new
object. See Adding a new Protocol on page 46.
Click Modify to access the Define Protocol window where you can edit the
selected protocol element. See Editing a protocol on page 47.
Click Delete to delete the selected protocol element.
Click Load to load a protocol, using the Load Protocol window. See Adding a
Port on page 21.
Click Save as to save the selected protocol under a new filename. Use this
command only if you want to save a protocol under a filename other than the
current one. Modifications as configuration results in the protocol designer are
automatically updated to the loaded file.
Click Set State to set the state (active/inactive/port) of the selected protocol.
Click Help to activate Rapidkit online Help.
45
46
Wonderware Rapidkit I/O Server
Adding a new Protocol
Use the New Protocol Object window to add a new protocol.
To access the New Protocol Object window:
1.
Open the Design menu on the main window.
2.
Select Protocol to access the Protocol Modeler window.
3.
Click New.
The New Protocol Object window displays.
Use the options on this window as described in the following table.
Option
New Protocol
New Message
New Item
New Parameter
Description
Creates a new protocol.
See Editing a protocol on page 47.
Creates a new message on the selected protocol. See
Defining a Message on page 60.
Creates a new item on the selected message. This menu
is enabled only if a message is selected in the protocol
designer. See Define Item Parameter on page 69.
Creates a new parameter on the selected protocol. See
Defining Parameters on page 64.
Editing a protocol
Editing a protocol
Use the Define Protocol window to set the basic properties of a protocol.
To access the Define Protocol window and edit a protocol element:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Highlight the appropriate protocol from the list on the Protocol Modeler
window.
4.
Click Modify.
The Define Protocol window displays.
Use the Protocol name field to set the name of the protocol (Rapidkit ASCII
string).
Each protocol object has a Comment section. Use the Comment section to enter
descriptive text for later references and documentation (Rapidkit ASCII string).
47
48
Wonderware Rapidkit I/O Server
Use the Communication section to select the protocol (communication) type:
1. COM port (serial protocol accessing the Windows COM API)
2. TCP/IP sockets (message oriented protocol accessing the Window socket API)
Use the Max. message size field to define the maximum message size. This is the
size of memory allocated for the message buffers on a port. This size needs to be
larger or equal to the largest message sent or received on the protocol.
Use the Data section to specify the data type, either ASCII or Binary:
Data Type
ASCII
(messages contain ASCII
data)
Description
Protocol data is entered as ASCII text.
Non-printable characters can be entered with the
escape character “\” followed by a two digit hex
number representing the ASCII code.
Example1: message request: \02ST
Example2: <STX> constant parameter with the
value of “\02”
Refer to “Definitions” in the Protocol Modeler
section.
Binary (messages contain
binary data)
Protocol data is entered as hexadecimal bytes (2
digits per byte). ASCII data can be entered with
the escape character: “\”
Example1: message request: 10\A\B0103 is
identical to 1041420103
Refer to “Definitions” in the Protocol Modeler
section.
The Messages section displays all message templates configured for the protocol.
• Click Add to add a message
• Click Modify to edit a selected message (or double click message
selection)
• Click Delete to delete a selected message
Configuring a Serial Protocol (COM Port)
Configuring a Serial Protocol (COM Port)
Rapidkit allows you to define the COM parameters in the port configuration.
However, you can define a set of default values in the Protocol Modeler that are
most common for devices on the specific protocol.
These values are used to initialize the COM settings in the port configuration, and
they appear if you click Default in the Port Configuration window to reset the
values to the default.
Use the Set COM Default Parameters window to configure a protocol element.
To access the Set COM Default Parameters window:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Highlight the appropriate COM port protocol from the list on the Protocol
Modeler window.
4.
Click Modify.
5.
Click Configure.
The Default Parameters window displays.
Note Setting the COM default parameters does not force these values on the COM
port when the port is opened. Your can override these values in the port
configuration of the server.
Use the Baud rate field to specify the baud rate (bits per second) at which the
serial port communications device operates.
Available baud rates are:
110
300
600
1200
2400
4800
9600
14400
19200
38400
56000
57600
115200
128000
256000
49
50
Wonderware Rapidkit I/O Server
Use the Data bits field to specify the number of bits in the bytes transmitted and
received. This member can be one of the following values:
4, 5, 6, 7, 8
Use the Stop bits field to specify the number of stop bits to be used. This member
can be one of the following values:
1, 1.5, 2
Note When configuring the 8250, the following restrictions apply to the values
specified for the Data Bits and Stop Bits members:
!
!
The number of data bits must be 5 to 8 bits.
The use of 5 data bits with 2 stop bits is an invalid combination, as is 6, 7,
or 8 data bits with 1.5 stop bits.
Use the Parity field to specify the parity scheme to be used. This member can be
one of the following values:
None, Odd, Even, Mark, Space
Use the Response timeout field to specify the response timeout in seconds when
waiting for a response to a sent read or write message from the device. Set this
timeout to a value that safely guarantees responses within this time under normal
conditions.
• Setting the timeout too short results in reporting errors, bad status, and
discarding of response messages.
• Setting this timeout too long results in detecting an error condition late
Buttons on this window
Click OK to accept settings as the set of COM default parameters for the port
configuration.
Click Cancel to discard changes.
Click Default to assign standard COM parameters to the complete COM default
configuration (basic and advanced).
Configuring a Serial Protocol (COM Port)
Click Advanced to open the Advanced COM Settings window, used to set all
advanced COM port parameters available DCB (device control block). See
Creating Advanced COM Settings on page 52.
Click Help to access the Rapidkit online Help system.
51
52
Wonderware Rapidkit I/O Server
Creating Advanced COM Settings
Use the Advanced COM Settings window to set all advanced COM port
parameters available DCB (device control block).
To access the Advanced COM Settings window:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Highlight the appropriate COM port protocol from the list on the Protocol
Modeler window.
4.
Click Modify.
5.
Click Configure.
6.
Click Advanced.
The Advanced COM Settings window displays.
Transmit section
Use the CTS output flow control field to specify whether the CTS (clear-to-send)
signal is monitored for output flow control.
If this member is selected and CTS is turned off, output is suspended until CTS is
sent again.
Use the DSR output flow control field to specify whether the DSR (data-setready) signal is monitored for output flow control.
If this member is selected and DSR is turned off, output is suspended until DSR is
sent again.
Creating Advanced COM Settings
53
Use the XON/XOFF field to specify whether XON/XOFF flow control is used
during transmission.
If this member is selected, transmission stops when the XoffChar character is
received and starts again when the XonChar character is received.
Use the continue on XOFF sent field to specify whether transmission stops when
the input buffer is full and the driver has transmitted the XoffChar character.
• If this member is selected, transmission continues after the input buffer has
come within XoffLimit bytes of being full and the driver has transmitted the
XoffChar character to stop receiving bytes.
• If this member is not set, transmission does not continue until the input buffer
is within XonLimit bytes of being empty and the driver has transmitted the
XonChar character to resume reception.
RTS control section
Use the RTS control section to specify the RTS (request-to-send) flow control.
The member can be one of the following values:
Value
Description
Disable
Disables the RTS line when the device is opened
and leaves it disabled.
Enable
Enables the RTS line when the device is opened
and leaves it on.
Handshake
Enables RTS handshaking. The driver raises the
RTS line when the "type-ahead" (input) buffer is
less than one-half full and lowers the RTS line
when the buffer is more than three-quarters full.
Toggle
Specifies that the RTS line will be high if bytes are
available for transmission. After all buffered bytes
have been sent, the RTS line will be low.
54
Wonderware Rapidkit I/O Server
Receive section
Use the DSR sensitivity field to specify whether the communications driver is
sensitive to the state of the DSR signal.
If this member is selected, the driver ignores any bytes received, unless the DSR
modem input line is high.
Use the XON/XOFF field to specify whether XON/XOFF flow control is used
during reception.
If this member is set, the XoffChar character is sent when the input buffer comes
within XoffLimit bytes of being full, and the XonChar character is sent when the
input buffer comes within XonLimit bytes of being empty
Use the Enable error replacement field to specify whether bytes received with
parity errors are replaced with the character specified by the Error char member.
If this member is set and the Parity member is set, replacement occurs.
Use the Discard NULL bytes field to specify whether null bytes are discarded.
If this member is TRUE, null bytes are discarded when received.
DTR control section
Use the DTR control box to specify the DTR (data-terminal-ready) flow control.
The available settings in this box are defined as follows:
Value
Meaning
Disable
Disables the DTR line when the device is opened
and leaves it disabled.
Enable
Enables the DTR line when the device is opened and
leaves it on.
Handshake
Enables DTR handshaking.
Use the XON limit field to specify the minimum number of bytes allowed in the
input buffer before flow control is activated to inhibit the sender. Note that the
sender may transmit characters after the flow control signal has been activated, so
this value should never be zero. This assumes that either XON/XOFF, RTS, or
DTR input flow control is specified.
Creating Advanced COM Settings
Use the XOFF limit field to specify the maximum number of bytes allowed in the
input buffer before the sender activates flow control to allow transmission. This
assumes that either XON/XOFF, RTS, or DTR input flow control is specified. The
maximum number of bytes allowed is calculated by subtracting this value from the
size, in bytes, of the input buffer.
Use the Error char field to specify the value of the character used to replace bytes
received with a parity error.
Global section
Use the XON char field to specify the value of the XON character for both
transmission and reception (in hex notation).
Use the XOFF char field to specify the value of the XOFF character for both
transmission and reception (in hex notation).
Use the EOF char field to specify the value of the character used to signal the end
of data (in hex notation).
Use the Event char field to specify the value of the character used to signal an
event (in hex notation).
55
56
Wonderware Rapidkit I/O Server
Configuring a TCP/IP Protocol (Sockets)
Use the TCP/IP Parameters window to define the initial settings of the port
configuration of the server and the location of the user input of these settings.
To access the Configure TCP/IP Parameters window:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Highlight the appropriate TCP/IP protocol from the list on the Protocol
Modeler window.
4.
Click Modify to access the Define Protocol window.
5.
Click Configure.
The TCP/IP Parameters window displays.
Local Parameters Port
Use the Port field to enter a well-known port to be used with the socket, or select
‘Default’ if you want Windows Sockets to select a port (disables the edit field).
You can also enter a parameter to supply the value for the local port.
Valid input:
Rapidkit parameter value string with the following restrictions:
•
Expression must equate to a decimal number
•
Single parameter (numeric value) of constant or topic type only
•
No formulas
Entering parameters in this field has the following effect:
Configuring a TCP/IP Protocol (Sockets)
Constant parameter:
The socket port number is fixed to the value of the constant parameter and
cannot be edited by the end user. The edit field of the local socket port in
the server’s port configuration is disabled. It displays the value of the
constant parameter.
Topic Parameter:
The value of the socket port number is edited in the topic configuration if
the port of the topic is set to this protocol. The edit field of the local socket
port in the server’s port configuration is disabled displaying ‘set in topic
configuration’.
Local Parameters Address
Enter the network address of the connected socket, a dotted number such as
"128.56.22.8" or the network name of the host. Select ‘Default’ if you want
Windows Sockets to select the local address. You can also enter a parameter to
supply the value for the local port.
Valid input:
Rapidkit parameter value string with the following restrictions:
•
Expression must equate to a string
•
Single parameter (string value) of constant or topic type only
•
No formulas
Entering parameters in this field has the following effect:
Constant parameter:
The local socket address is fixed to the value of the constant parameter and
cannot be edited by the end user. The edit field of the local socket address in
the server’s port configuration is disabled. It displays the value of the
constant parameter.
Topic Parameter:
The value of the local socket address is edited in the topic configuration if
the port of the topic is set to this protocol. The edit field of the local socket
address in the server’s port configuration is disabled displaying ‘set in topic
configuration’.
Remote Parameters Port
Use the Port field to enter the port identifying the socket application. You can
also enter a parameter to supply the value for the remote port. Valid input includes
a Rapidkit parameter value string with the following restrictions:
•
Expression must equate to a decimal number
•
Single parameter (numeric value) of constant or topic type only
•
No formulas
Entering parameters in this field has the following effect:
57
58
Wonderware Rapidkit I/O Server
Constant parameter:
The remote socket port number is fixed to the value of the constant
parameter and cannot be edited by the end user. The edit field of the remote
socket port in the server’s port configuration is disabled. It displays the
value of the constant parameter.
Topic Parameter:
The value of the remote socket port number is edited in the topic
configuration if the port of the topic is set to this protocol. The edit field of
the remote socket port in the server’s port configuration is disabled
displaying ‘set in topic configuration’.
Remote Parameters Address
Enter the network address of the connected socket, a dotted number such as
"128.56.22.8" or the name of the remote network node. You can also enter a
parameter to supply the value for the local port. Valid input includes:
Rapidkit parameter value string with the following restrictions:
•
Expression must equate to a string
•
Single parameter (string value) of constant or topic type only
•
No formulas
Entering parameters in this field has the following effect:
Constant parameter:
The local socket address is fixed to the value of the constant parameter and
cannot be edited by the end user. The edit field of the remote socket address
in the server’s port configuration is disabled. It displays the value of the
constant parameter.
Topic Parameter:
The value of the local socket address is edited in the topic configuration if
the port of the topic is set to this protocol. The edit field of the remote
socket address in the server’s port configuration is disabled displaying ‘set
in topic configuration’.
Connect section
Select the connection mode (client/Server) as follows:
•
Select Active - Rapidkit connects to the remote host (client)
•
Select Passive - Rapidkit waits for a connection by the remote host
(server)
Use the Response timeout field to specify the response timeout in seconds when
waiting for a response to a sent read or write message from the device. Set this
Configuring a TCP/IP Protocol (Sockets)
timeout to a value that safely guarantees responses within this time under normal
conditions.
• Setting the timeout too short results in reporting errors, bad status and
discarding of response messages.
• Setting this timeout too long results in detecting an error condition late.
Buttons on this window
Click OK to keep all changes.
Click Cancel to discard all changes.
59
60
Wonderware Rapidkit I/O Server
Defining a Message
Rapidkit provides you the ability to define both outgoing and incoming messages,
using the Define Message window.
To access the Define Message window:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Highlight the appropriate protocol from the list on the Protocol Modeler
window.
4.
Click Modify to access the Define Protocol window.
5.
Click Add in the Messages section.
The Define Message window displays.
When you define a message, you are actually defining two messages:
• An outgoing message: Request, poke or unsolicited response
• An incoming message: Response to a request/poke or unsolicited
message
Depending on the number of variable sections (parameters) in the message, a
message definition can define a message template. A single message template can
result in several message instances at runtime if some variable sections of the
message contain different values.
The simplest case of a message is a request message with a fixed request buffer and
a response buffer containing at least one variable part: the item data. Instead of
requesting a fixed data area in the target device some parts of the request can be set
at runtime. This could be a bus address, the starting address of the data area, etc.
In Rapidkit, these variable parts of a message are declared as parameters
(placeholders) that provide their values at runtime.
Not only message data can be parameterized. Most properties of protocol objects
in Rapidkit can have variable values.
Defining a Message
A special message type is a communication error response message generated by
Rapidkit when receiving unidentified data. To enable this feature define an
unsolicited message with the pre-defined parameter: <UNIDENTIFIED DATA> in
the unsolicited field and the appropriate Rapidkit response in the response field.
Whenever Rapidkit receives out-of-frame data (logged as "discarding xx bytes" in
the WW logger) it sends this response.
Note: Only one message of this type can be defined per protocol.
Use the Message name field to enter the message name, used to reference the
message template.
Valid input: Any unique text defining a message name
Use the Comment field to enter descriptive text about the message template.
Valid input: Rapidkit ASCII string defining a message comment.
Use the Type section to select the message type. Options are:
• Request
(message template is a poll request/response pair)
• Poke
(message template is a write/write confirmation pair)
• Unsolicited
(message is a spontaneous device message/Rapidkit
response pair)
The area below the Type section reflects the request or poke buffer sent by
Rapidkit to request data from the device, or write data to the device in the case of
61
62
Wonderware Rapidkit I/O Server
Request or Poke message type. In the case of Unsolicited message type it is the
unsolicited message received from the device.
Valid input:
Rapidkit protocol data string with the following restrictions:
•
•
Valid parameter types
Checksum parameter, data parameter (poke and unsolicited messages
only), constant parameter, item parameter, topic parameter, error code
parameter (unsolicited messages only), user function parameter
String cannot be empty
Use the Response field to enter the response or write confirmation from the device
expected after sending the request or poke buffer in the case of Request or Poke
message type.
In the case of Unsolicited message type it is the response of Rapidkit to an
unsolicited message.
Leave the field empty in the case of unconfirmed pokes or in the case of
unconfirmed unsolicited messages.
Valid input:
Rapidkit protocol data string with the following restrictions:
•
Valid parameter types
Checksum parameter, data parameter (poll messages only), constant
parameter, item parameter, topic parameter, error code parameter, user
function parameter
•
String can be empty
The Items section displays a list of items that scan data from the corresponding
data parameters of the message poll response or unsolicited message or that insert
data in the corresponding data parameters of the poke buffer.
Select the item, then click the appropriate button:
• Add
Adds an item to a message
•
Modify
Edits selected item
•
Delete
Deletes selected item
Defining a Message
Click Cancel to discard all changes and close the Define Messages window.
Click OK to save all changes to the configuration file. If any new parameter was
entered you are prompted to define the parameter. Selecting Yes accesses the
Select Parameter Type selection window.
63
64
Wonderware Rapidkit I/O Server
Defining Parameters
Use the Select Parameter Type window to access the appropriate window used to
define parameters for each type listed.
To access the Select Parameter Type window:
1.
Open the Design menu on the main window.
2.
Select Protocol from the Design menu to access the Protocol Modeler
window.
3.
Click New to access the New Protocol Object window.
4.
Click New Parameter.
The Select Parameter Type window displays.
Select the type of parameter to be defined. Depending on the parameter context,
some parameter types may be disabled. Depending on the parameter type, the
parameter type specific window displays to set the parameter properties.
Defining Checksum Parameters
The Define Checksum Parameter window displays when you select the Checksum
option in the Select Parameter Type window.
Defining Parameters
Use the Parameter name field to enter the name of parameter used to reference
this parameter.
Valid input: Rapidkit ASCII string.
Use the Comment section to enter descriptive text for documentation.
Valid input: Rapidkit ASCII string defining a message comment.
Use the Checksum type field to enter the checksum algorithm for calculating the
checksum.
Available checksum types:
•
XOR (LRC) - Longitudinal Redundancy Checksum is calculated by
XORing all values starting at offset up to the checksum position (some
protocols refer to this as BCC)
•
CRC16 of message data starting at offset up to the checksum position in
the message
•
SUM (BCC) - Block checksum is calculated by adding message data
starting at offset up to the checksum position in the message (some
protocols refer to this a as LRC)
•
user DLL
Allows the user to specify a proprietary function supplied in a separate
DLL. This function may implement any checksum algorithm using the
following syntax:
65
66
Wonderware Rapidkit I/O Server
BOOL <function name>(BYTE* buf, LONG bufsize, BYTE* target,
LONG targetsize)
where
BOOL
return type to the function (TRUE/FALSE)
function name
any valid function name
buf
message data starting at checksum offset
bufsize
size of buf in bytes
target
target buffer for checksum result
targetsize
size of checksum target buffer. This buffer may be
significantly larger than the needed value size due
to internal allocation strategies, but is at least one
byte larger than the checksum value size. This
allows the user function to use string operations to
fill the target buffer with an appended terminating
zero character without overwriting invalid memory
locations.
Note The user defined checksum function copies the calculated checksum to a
target buffer. It should not insert it into the message itself since it also may be
called on received message comparisons where the original message needs to be
unmodified.
Use the Offset field to enter the offset in message to start checksum calculation.
Valid input: Rapidkit ASCII string equating to a numerical decimal
expression
Use the Initial value field to enter the start value for checksum calculation.
Valid input: Rapidkit ASCII string equating to a numerical hexadecimal
expression in the range of 0..FFFF.
Use the Mask field to enter the checksum mask (required for certain checksum
algorithms only).
Valid input: Rapidkit ASCII string equating to a numerical hexadecimal
expression in the range of 0..FFFF.
Use the Data size field to enter the size of the parameter value in bytes.
Select Convert endian if the byte order of the result is to be changed if inserted
into protocol message data.
Use the DLL name field to enter the name of the DLL.
If the DLL is in the system path of NT the filename is sufficient.
Defining Parameters
If not the full path/filename needs to be specified.
Use the Function name field to enter the name of the function. Rapidkit uses
dynamic DLL loading. If the DLL or function is not found this parameter is not
available. In this case Rapidkit is still able to process the remaining sections of the
protocol that do not depend on this parameter.
Define Data Parameter
The Define Data Parameter window displays when you select the Data option in
the Select Parameter Type window.
Data parameters contain the response or poke data in messages.
Use the Parameter name field to enter the name of the parameter used for
references.
Use the Comment field to enter the descriptive text for documentation.
Use the Data size field to enter the size of data in bytes (binary protocol) or
characters (ASCII protocol).
67
68
Wonderware Rapidkit I/O Server
Data Field: This option is the default setting for using this section of the message
as a data source for scanning item values at certain offsets specified in the
corresponding item definitions.
Integer:
Select this setting if you need to process the numerical value of this
data parameter as an input value in your response. (i.e. the protocol needs to return
the value or modified value in the response message. You can modify the
parameter value in the response via a formula). The insert size is identical to the
scan size.
If ‘Integer’ was selected as the ‘Scan as’ option you can specify the conversion
rule. The available options depend on the protocol type:
ASCII:
BINARY:
CHAR (8 bits signed)
single character only (size=1)
CHAR (8 bits unsigned) single character only (size=1)
OCTAL (signed)
OCTAL (unsigned)
DECIMAL
HEXADECIMAL (signed)
HEXADECIMAL (unsigned)
CHAR (8 bits signed)
single character only (size=1)
CHAR (8 bits unsigned) single character only (size=1)
SHORT (16 bits signed)
WORD (16 bits unsigned)
LONG (32 bits signed)
DWORD (32 bits unsigned)
Note Specifying signed or unsigned on ASCII scanning invokes implicit sign
expansion. I.e. scanning ‘FF’ as ‘HEXADECIMAL (signed)’ on a 2-byte data size
gives an integer value of –1.
Scanning it unsigned results in a value of 256. Scanning 00FF as a 4 byte signed
or unsigned ‘HEXADECIMAL’ value gives 256 in both cases. Use CHAR to get
the signed or unsigned value of the ASCII code of the character. This is useful for
character conversions in responses via a formula (i.e., upper to lower case etc.)
Define Constant Parameter
The Define Constant Parameter window displays when you select the Constant
option in the Select Parameter Type window.
Defining Parameters
Constant parameters represent a constant value independent of messages or items.
Use constant parameters to standardize protocol specific values.
Use the Parameter name field to enter the name of the parameter used for
references.
Use the Comment field to enter the descriptive text for documentation.
Use the Value field to enter the constant value inserted for the parameter.
Note You can use constant parameters to create symbols or Mnemonics for oftenused values.
Define Item Parameter
The Define Item Parameter window displays when you select the Item option in
the Select Parameter Type window.
Item parameters scan their values from a specific position in the item name. This
enables generic construction of item templates.
69
70
Wonderware Rapidkit I/O Server
Use the Parameter name field to enter the name of a parameter used for
references.
Use the Comment field to enter the descriptive text for documentation.
Use the Size field to specify the size of parameter value in the item name in
characters.
Use the Scan as box to set the internal type into which the item parameter value is
scanned.
Use the Convert box to select the conversion mode. The conversion mode
determines how the scanned item name section is interpreted and if the byte order
should be changed (Convert endian).
Use the Insert as box to set the insertion mode. The insertion mode determines
how the item parameter value is inserted and sets the insertion size of the
parameter.
Define Topic Parameter
The Define Topic Parameter window displays when you select the Topic option in
the Select Parameter Type window.
Topic parameters scan their values from the topic configuration. Creating a topic
parameter automatically generates a new edit field in the topic configuration if a
port with this protocol is referenced.
Defining Parameters
Use the Parameter name field to enter the name of the parameter used for
references.
Use the Comment field to enter the descriptive text for the logical meaning of this
topic parameter. The text displays in the help window (“?” button) for this topic
parameter when configuring a topic.
Use the Header field to enter the string appearing in front of the edit field in the
topic configuration window.
Use the Units field to enter the string appearing behind the edit field in the topic
configuration window.
Use the Save Key field to enter the key used for saving data in the configuration
file.
Use the Position field to select the position relative to other topic parameters in the
topic configuration.
71
72
Wonderware Rapidkit I/O Server
Use the Size field to enter the size of parameter value in the item name in
characters.
Use the Scan as box to set the internal type into which the item parameter value is
scanned.
Use the Convert box to set the conversion mode. The conversion mode
determines how the scanned item name section is interpreted and if the byte order
should be changed (Convert endian).
Use the Insert as box to set the insertion mode. The insertion mode determines
how the item parameter value is inserted and sets the insertion size of the
parameter.
Select the Hot topic configuration field to configure this topic parameter even
when the server is active, if security is set to “Allow configuration while topics are
active”. If this box is not checked, the parameter is disabled when the server is
active (clients being connected).
Define Error Code Parameter
The Define Error Code Parameter window displays when you select the Error
Code option in the Select Parameter Type window.
Defining Parameters
Error code parameters scan their values from a specific position in the response
buffer of a message. This value is displayed in the error code section of the
monitor window. Each error value can be assigned to an error text that is displayed
in the item state window of the monitor window.
Use the Parameter name field to enter the name of a parameter used for
references.
Use the Comment field to enter the descriptive text for this error code parameter.
Use the Data size field to enter the size of a parameter value in the response
message in bytes. This value can only be changed if the error code value list is
empty.
Use the Radio buttons in the Show values section to determine what type of
error codes are listed:
Errors only displays only error code values with bad quality
OK only
displays only error code values with good quality
All
displays all error code values
73
74
Wonderware Rapidkit I/O Server
Buttons on this window
Click Add to Access the Define Error Code Value window where you add error
code values.
Click Modify to edit the error code value.
Click Delete to delete the error code value.
Define Error Code Value
Clicking Add from the Define Error Code Parameter window accesses the Define
Error Code Value window.
Use the Error value field to enter the error value as it is returned in the message
Use the Error text field to enter the descriptive text for the error code value. This
text is used by WWLogger and monitor window.
Use the OPC quality field to specify the corresponding OPC quality for the error
code value. Manually enter a HEX value or select a description from the drop
down list.
Defining Parameters
Define User Function Parameter
The Define User Function Parameter window displays when you select the User
Function option in the Select Parameter Type window.
User function parameters provide an external interface to insert parameter values
that cannot be generated with the built in features of Rapidkit. This could be a
proprietary message parameter calculation/algorithm, accessing user defined lists,
etc.
The syntax of the function call is:
•
BOOL <function name>(BYTE* buf, LONG bufsize, BYTE*
target, LONG targetsize)
where:
BOOL
return type to the function
(TRUE/FALSE)
function name
any valid function name
buf
message data preceding parameter
bufsize
size of message data in bytes
target
target buffer for user parameter value
targetsize
size of user parameter value target buffer.
The target size may be significantly larger than the needed value
size due to internal allocation strategies, but is at least one byte
larger than the parameter value size. This allows the user
function to use string operations to fill the target buffer with an
appended terminating zero character without overwriting invalid
memory locations.
Note The user defined function copies the calculated parameter value to a target
buffer. It should not insert the value into the message itself since it also may be
called on received message comparisons where the original message needs to be
unmodified.
Use the Parameter name field to enter the name of parameter used for references.
75
76
Wonderware Rapidkit I/O Server
Use the Comment field to enter the descriptive text for documentation.
Use the DLL name field to enter the name of the DLL to be loaded.
The DLL name may have the following syntax:
a. Full name path (e.g. "C:\Program Files\VendorX\VendorLib.DLL")
This string needs to be modified when copying the protocol file to a different
PC.
b. Relative path (e.g. ".\VendorLib.DLL")
Rapidkit will search the DLL in the current server directory.
c. Single name (e.g. "VendorLib.DLL")
Rapidkit will search the file in the system paths.
Use the Function name field to enter the name of the function to be called.
Use the Data size field to enter the number of bytes to be inserted into the
protocol.
Define Item
Define Item
Items are defined on the message level. Item names can be parameterized to create
item templates.
Rapidkit uses this name to validate items names at run-time. The following
algorithm is used on client item creation:
• Rapidkit scans all messages for item definitions. Each item definition name or
template is compared with the requested client item name synactically. The
fixed item name part is compared case insensitively. The parameter section is
tested for format and contents.
Example: Reg0002 would be a valid item name if address is a 4 digit decimal
item parameter
• Rapidkit tests if the item value position is in the scannable range of the
corresponding message data.
If both criteria are met, the item is valid.
Note: The item definition names must be unique within a message only. They
do not need to be unique across the protocol. In fact it is very common to have
the same item definition (e.g. Reg<address>) in many different messages:
several read messages accessing different memory areas in the PLC, write
messages etc. Rapidkit will pick the message with the matching item where
the item value can be scanned from (or written to in the case of poking). I.e. if
a second read message access a different memory area in the PLC the offset
for the same item in this new message could be defined as: <address>*4-400,
assuming the new memory area starts at word address 100 (corresponding to
400 data value bytes).
Enter descriptive text for documentation into the Comment field..
77
78
Wonderware Rapidkit I/O Server
Select the type that the item value will be converted to internally from the IO
server type selection box.. It should match the InTouch tag type definition.
Select the data parameter of all available data or error code parameters in the
message the item is created in. Click the Edit button to view or modify the selected
parameter in the corresponding editor.
Valid input is a Rapidkit parameterized ASCII string with the following
restrictions:
• Contains a parameter only
• Valid parameter types:
data parameter, error code parameter
• String cannot be empty
Enter the offset for item data value scanning within the parameter. In this example
the item register address is multiplied by 4, because the register address was
specified in words and each word is represented by 4 ASCII bytes in the data
parameter values.
Valid input:
Rapidkit parameter value string.
Enter the data size in bytes to be scanned at the offset within the data parameter
values.
Enter the scanning mode in the Scan as field. The available modes depend on the
protocol type:
ASCII:
BINARY:
CHAR (8 bits signed)
single character only (size=1)
CHAR (8 bits unsigned) single character only (size=1)
OCTAL (signed)
OCTAL (unsigned)
DECIMAL
HEXADECIMAL (signed)
HEXADECIMAL (unsigned)
CHAR (8 bits signed)
single character only (size=1)
CHAR (8 bits unsigned) single character only (size=1)
SHORT (16 bits signed)
WORD (16 bits unsigned)
Define Item
LONG (32 bits signed)
DWORD (32 bits unsigned)
Note: Specifying signed or unsigned on ASCII scanning invokes implicit sign
expansion. I.e. scanning ‘FF’ as ‘HEXADECIMAL (signed)’ on a 2 byte data size
gives an integer value of –1. Scanning it unsigned results in a value of 256.
Scanning 00FF as a 4 byte signed or unsigned ‘HEXADECIMAL’ value gives 256
in both cases. Use CHAR to get the signed or unsigned value of the ASCII code of
the character. This is useful for character conversions in responses via a formula
(i.e. upper to lower case etc.)
Check the Convert endian box if the byte order should be changed. Available for
binary protocols only.
Check this box if the binary value should be converted as a BCD representation.
Available for binary protocols only.
Click Mask to define and enable a mask on the scanned value in order to evaluate
selected bits only. The mask is entered in hexadecimal notation.
79
80
Wonderware Rapidkit I/O Server
I/O Server Help Menu
The online Help menu is available to help you use Rapidkit. This section describes
how to use Rapidkit online Help.
You can access Rapidkit online Help by selecting Help on the main window or by
selecting the Help button on any of the windows in Rapidkit.
Contents
Use this option to display the Table of Contents for the Rapidkit Help file.
How to Use Help
Use this option to access a list of basic instructions for using the Help file.
About RAPIDKIT
Use this option to access miscellaneous information regarding the server, such as
the software version you are running, the copyright information, license
information, etc.
Your FactorySuite system license information can be viewed through the license
viewing utility that is launched from the About window.
# For more information on the license viewing utility, see your FactorySuite
System Administrator’s Guide.
Defining Item Names
Defining Item Names
The item names depend upon the protocol used to access the item. The port
selected in the topic configuration determines the protocol.
View the item name syntax of a specific port by selecting the syntax button on the
Select Port window opened by the Configure Ports menu option.
Predefined Item/Point Names
All Rapidkit topics have predefined item/point names to monitor and control
communication properties. System defined item/point names are:
UPDATEINTERVAL Item
The UPDATEINTERVAL item is used to access the currently set update interval.
It is the same value displayed in the monitor window of the Rapidkit server. It
indicates the currently requested update interval in milliseconds. If the
corresponding topic is configured for Enable I/O access to update interval, a client
can poke new values into this item. In any case the value can always be read
through I/O. The range of valid values differs with respect to the topic settings.
The value of zero indicates that no items on that topic are updated.
I/O Type:
ACCESS:
RANGE:
INTEGER
READ, WRITE (if configured)
1.. 2147483647
0
(topic inactive, no items are updated)
Note By poking a value of zero into the update interval item, a client can
conveniently stop all update activities on the corresponding topic without having to
deactivate the items.
MAXINTERVAL Item
The MAXINTERVAL item is used to access the measured maximum update
interval in milliseconds of all items of the corresponding topic for the last
completed poll cycle. It is the same value displayed in the monitor window of the
Rapidkit server under Longest Interval. This item is read only.
I/O Type: INTEGER
ACCESS: READ
RANGE:
0..2147483647
Note Use the UPDATEINTERVAL and MAXINTERVAL items to conveniently
tune the performance of the communication via I/O.
STORESETTINGS Item
The STORESETTINGS item is used to make the temporary update interval
changes via I/O permanent. If the client pokes a value of 1 into the
STORESETTINGS item the currently set update interval is written to the servers
configuration file. If the update interval has been changed via I/O and
STORESETTINGS is not poked to 1, the server uses the original update interval
for that topic the next time it is started. Reading the item will always give 0.
I/O Type: DISCRETE
81
82
Wonderware Rapidkit I/O Server
ACCESS:
RANGE:
READ, WRITE
0, 1
Note Use this item to conveniently store your optimized configuration via I/O.
ITEMCOUNT Item
The ITEMCOUNT item is used to access the number of active items in the
corresponding topic. It is the same value displayed in the monitor window of the
Rapidkit server under Items. This item is read only.
I/O Type: INTEGER
ACCESS: READ
RANGE:
0..2147483647
Note Use the ITEMCOUNT item to monitor the number of currently active items.
ERRORCOUNT Item
The ERRORCOUNT item is used to access the number of active items that have
errors in the corresponding topic. It is the same value displayed in the monitor
window of the Rapidkit server under errors ( ) only. If the communication status of
a topic is bad all items have errors (item count equals error count). This item is
read only.
I/O Type: INTEGER
ACCESS: READ
RANGE:
0..2147483647
Note Use the ERRORCOUNT item to monitor if there are any badly configured
items or invalid item values. This is the case if the topic status is 1 and
ERRORCOUNT is not zero.
WRITECOMPLETE Item
The WRITECOMPLETE item is used to access the state of pending write activities
on the corresponding topic. If the topic is opened the value of the
WRITECOMPLETE item is initially 1 indicating all write activities are complete no pokes are pending. If values are poked into any items of the topic the value of
the WRITECOMPLETE item changes to 0 indicating write activity is currently in
progress. If the server has completed all write activities the value of the
WRITECOMPLETE item changes to 1 if all pokes were successful or to -1 if at
least one poke has failed. If the value of the WRITECOMPLETE item is not zero
the client can poke 1 or -1 to it ( poke a 1 to clear errors or a -1 to test a client
reaction on write errors).
I/O Type: INTEGER
ACCESS: READ/WRITE
RANGE:
-1,0,1
Note Use the WRITECOMPLETE item to serialize a sequence of poke values into
a single item or to monitor success or failure of poking into one or more items.
READCOMPLETE Item
The READCOMPLETE item is used to access the state of initial reads on all items
in the corresponding topic. If the topic is opened and no item is advised, the value
of the READCOMPLETE item is 0. After all activated items have been read once,
Defining Item Names
the READCOMPLETE item changes to 1. If at least one item could not be read
the READCOMPLETE item alters to –1 indicating there have been read errors.
If at least one new item is advised now READCOMPLETE changes to 0 and after
this/these item(s) has/have been read it changes to 1 or –1 again.
Poking a 0 to this item resets the internal read states of all items in this topic. This
resets the READCOMPLETE item to 0. If all items are read again after this poke,
the READCOMPLETE item changes back to 1 or –1.
I/O Type:
INTEGER
ACCESS:
READ/WRITE
RANGE:
-1,0,1
POLLNOW Item
Poking a 1 to the predefined POLLNOW item forces all items within this topic to
be read immediately. This is useful if you want to get the newest values from the
device, regardless of its updateinterval. You can use this if you want to trigger the
reads within a topic by your own.
I/O Type:
DISCRETE
ACCESS:
READ/WRITE
RANGE:
0,1
Note Use POLLNOW and READCOMPLETE for measuring of the longest
interval. Create a topic with updateinterval 0. Poke READCOMPLETE to 0 and
POLLNOW to 1 and store the actual time. Then wait until READCOMPLETE
changes back to 1. The difference between the current time and the stored time
equals the updateinterval.
83
84
Wonderware Rapidkit I/O Server
Monitoring the Status of Communications with a
Device
For each topic name (device, e.g. PLC), there is a built-in discrete item that can be
used to monitor the status of communications with the PLC.
The discrete item, Status, is set to 0 when communication with the device fails and
is set to 1 when communication is successful.
Using the Status Item in Microsoft Excel
The status of PLC communications can be read into Microsoft Excel by entering
the following DDE reference formula in a cell on a spreadsheet:
=Rapidkit|S115!Status
In the above formula:
Rapidkit Is the name of the server application.
S115
Is the exact topic name defined in the server for the device.
Status
Is the built in discrete item used to monitor the status of
communications with the device.
Monitoring the Status of an I/O Conversation
Monitoring the Status of an I/O Conversation
WindowViewer supports built-in topic names called DDEStatus and IOStatus
that can be used to monitor the status of specific I/O conversations.
For example, let's assume that WindowViewer (VIEW) is communicating with the
Rapidkit I/O Server to a PLC that has been defined in the server with S115 for its
topic name. The discrete items, DDEStatus and IOStatus, are set to 0 when this
I/O conversation has failed and set to 1 when this I/O conversation is successful.
Using DDEStatus and IOStatus in Microsoft
Excel
The status of communication between the PLC and InTouch can be read into
Microsoft Excel by entering the following DDE reference formula in a cell on a
spreadsheet:
=view|DDEStatus!S115
Or
=view|IOStatus!S115
In the above formulas:
view
Is the name of the InTouch application.
[DDE][IO] Status
Built-in topic name used to monitor the status of
communications between the server and InTouch.
S115
The exact access name defined in InTouch for this
topic.
85
86
Wonderware Rapidkit I/O Server
Reading Values from the I/O Server into Microsoft
Excel
Values may be read directly into Microsoft Excel spreadsheets from the server by
entering a DDE formula into a cell using the following format:
=applicationname|topicname!itemname
Example formula:
=Rapidkit|S115!EW4
In the above formula:
Rapidkit Is the name of the server application name.
S115
Is the exact topic name defined in the server for the PLC.
EW4
Is the actual location in the PLC that contains the data value. This
is the item name.
In this example, each time the value of EW4 changes in the PLC, the server
automatically sends the new value to the cell containing the formula in Microsoft
Excel.
Note Refer to the Microsoft Excel manual for complete details on entering Remote
Reference formulas for cells.
Writing Values to the I/O Server from Microsoft Excel
Writing Values to the I/O Server from Microsoft Excel
Values may be written to the server from Microsoft Excel by creating an Excel
macro that uses the POKE command. The proper command is entered in
Microsoft Excel as follows:
channel=INITIATE("applicationname","topicname")
=POKE(channel,"itemname", Data_Reference)
=TERMINATE (channel)
=RETURN()
The following describes each of the above POKE macro statements:
•
channel=INITIATE("applicationname","topicname")
Opens a channel to a specific topic name (defined in the server) in a
particular application name (the executable name less the .EXE) and
assigns the number of that opened channel to channel.
Note By using the channel=INITIATE statement, the word channel
must be used in the =POKE statement instead of the actual cell
reference. The "application name" and "topic name" portions of the
formula must be enclosed in quotation marks.
•
=POKE(channel,"itemname", Data_Reference)
POKE is the value contained in the Data_Reference to the specified item
name (actual location in the PLC) via the channel number returned by the
previously executed INITIATE function. Data_Reference is the
row/column ID of the cell containing the data value.
•
=TERMINATE(channel)
Closes the channel at the end of the macro. Some applications have a
limited number of channels therefore; they should be closed when
finished. Channel is the channel number returned by the previously
executed INITIATE function.
•
=RETURN()
Marks the end of the macro.
Note Refer to the .XLM sample Excel poke macro provided on the server program
disk. Also refer to the Microsoft Excel manual for complete details on entering
Remote Reference formulas for cells.
87
88
Wonderware Rapidkit I/O Server
Troubleshooting I/O Server Communication Problems
This section provides you with some simple steps that can be taken to ascertain and
correct communication problems. The problems described here represent the most
probable causes of communication failure.
Note This is a general troubleshooting guide and for the sake of brevity we cannot
cover every possible source of communication problems.
Debugging Communication Between InTouch
and an I/O Server
This section explains the most common error situations that can occur when
attempting to establish communication between InTouch and a server.
About servers
Servers are Window applications that communicate with I/O, PLCs, and/or other
data sources. If a server supports either the Microsoft Dynamic Data Exchange
(DDE) or the Wonderware SuiteLink protocol, it is capable of communicating with
the Wonderware InTouch program.
Note All Wonderware Version 7.0 or later servers support both DDE and
SuiteLink. However, the SuiteLink protocol is only supported on the Windows NT
(Version 4.0 or later) operating system.
Servers respond to data requests made by other applications. Requesting
applications are called clients. When WindowViewer acts as a client and requires
the value of an item, it contacts the server and requests the item’s value. The
server reports the value and updates WindowViewer only if a change occurs. All
WindowViewer data requests provide information relating an item to a register,
coil number, or I/O data point understood by the server. The server uses the
information to automatically handle all messages to and from I/O, hardware
devices (PLC), and/or other data sources.
Note We highly recommend starting all the servers required by the InTouch
application before starting WindowViewer. InTouch (versions prior to 7.0)
displays the Initiating DDE Conversation message box for each uninitiated
conversation.
For example:
If you start up WindowViewer and cannot successfully establish a
conversation with a server, the following Initiating DDE Conversation window
displays:
Troubleshooting I/O Server Communication Problems
The information in the second line indicates that you have at least one I/O type
tagname defined in your Tagname Dictionary that is associated with an Access
Name that defines OMRONFO as the Application Name, and HLPLC as the
Topic Name. Make note of exactly how the application and topic names are
spelled.
$ This example only applies when using a version of InTouch prior to
InTouch 7.0.
Troubleshooting
To troubleshoot communication problems between WindowViewer and the server,
perform the following steps as listed below.
%
%
Verify the I/O Server is running.
1.
Start the server program.
2.
Verify the server is running by checking to see if it is in the Windows Task
List.
•
On Windows NT, right-click on the Windows Taskbar and select Task
Manager from the menu. Click the Applications tab to view all currently
running applications. Or, press the CTRL+SHIFT+ESC keys.
•
On Windows 95, press the ALT+TAB keys while holding down the ALT
key.
•
On Windows 3.1 or Windows for Workgroups, press the CTRL+ESC
keys.
If the I/O Server is running, verify the I/O Server's program name is correct
in all WindowMaker Access Name definitions.
1.
Switch to (or start) WindowMaker.
2.
Select Access Names from the Special Menu. The Access Name Definitions
window displays listing all Access Names defined in the WindowMaker.
3.
In the Access Names list, select the access name referencing the server and
click Modify. The Modify Access Name window displays.
4.
Verify the server's program name in the Application Name box is correct. If it
is wrong, correct it and click OK. If it is correct, click Cancel.
•
The server's exact "executable name" MUST be typed in the Application
Name box in all Access Name definitions. The ".exe" extension is not
used.
•
If you are debugging a remote tagname reference, also verify that the node
name for the remote computer in the Node Name box is correct.
89
90
Wonderware Rapidkit I/O Server
5.
%
Repeat steps 3 & 4 and verify the server program name is correct in all access
names that use it.
If you still cannot establish a conversation, verify the exact topic name used in
the WindowMaker Access Name definitions is defined in the I/O Server
program.
•
1.
Close WindowViewer if it is running. (The server cannot be configured if
WindowViewer is running.)
2.
Start the server program.
3.
From the server’s Configure menu, select Topic Definition. The Topic
Definition window displays listing all topic names defined in the server.
4.
Verify that the topic name exists and is spelled exactly the same (including
spaces) as the topic name referenced in the WindowMaker Access Name
definition.
•
Blank spaces cannot follow the topic name in either the server's Topic
Definition or the Access Name definition.
5.
If the topic name is different, either correct it in the server or switch to
WindowMaker and correct it in the Access Name definition.
6.
Once you performed the above procedure, restart WindowViewer and switch
to the server program. Data should now appear in the server’s program
window to indicate that WindowViewer and the server are communicating.
•
7.
The data in the server’s program window indicates the read and write
messages that the server is sending to and receiving from the PLC. These
are not error messages; only status messages are written to the server’s
program window.
If no data displays in the server’s program window, switch to the Wonderware
Logger to check for error messages. For example, a common error message is:
•
"Error for DDE: OMRONFO|HLPLC!<null>("item") Advise failed"
This message displays when the item defined in one or more tagnames is
invalid for the server.
%
•
InTouch tagnames use specific naming conventions when accessing data
from a server. The valid item names for all Wonderware servers are
documented in their respective User's Guides. Typically, the item naming
conventions used by each server are consistent with the names used by the
equipment manufacturer.
•
For more information on the Wonderware Logger, see your online
FactorySuite System Administrator's Guide.
If you are still experiencing problems, see the Debugging Communication
Between Suiteink and an I/O Server troubleshooting section.
Debugging Communication Between SuiteLink
and an I/O Server
Troubleshooting I/O Server Communication Problems
If you have successfully applied the debug techniques listed in the previous section
and are still experiencing communication problems to a server that is attempting to
communicate using the SuiteLink protocol, perform the following steps as listed
below:
%
Verify the I/O Server supports the Wonderware SuiteLink protocol, that is,
the I/O Server is version 7.0 or above.
%
Try communicating to the I/O Server using the DDE protocol, using the
following steps. If this is not possible, proceed to the next troubleshooting
section.
1.
Verify Microsoft's TCP/IP stack is installed and configured properly.
•
SuiteLink uses the Microsoft TCP/IP stack for its communications even if
the client application and the server reside on the same node.
2.
If you do not have an Ethernet card to bind to the TCP/IP stack, install the
Microsoft Loop Back Adapter.
3.
Install the Microsoft TCP/IP stack.
Debugging Communication Between an I/O
Server and a PLC
This section provides you with simple steps to diagnose and correct server to PLC
communication problems. The debug techniques listed below address both serial
and board servers. Disregard any information that is not applicable to the server
type that you are using.
When attempting to establish communication between a server and a PLC, if no
data displays in the server's program window and the data items are not updating in
WindowViewer, switch to the Wonderware Logger and check for error messages.
# For more information on the Wonderware Logger, see your online
FactorySuite System Administrator's Guide.
For example, some of the most common errors that may appear in the Wonderware
Logger for serial servers are:
Response Timeout
WCRET =-2
WakeUp=-2
Receive Overrun
Framing Errors
Note Unless specified otherwise, most serial communication based servers are full
duplex. If you require a server for half duplex (one that monitors the CTS and
RTS lines) or if you are not sure whether the PLC's protocol is full or half duplex,
call your PLC supplier.
Also, during in-house server testing, we have found that the communication cards
that use the National 16450 and 16550 UARTs seem to be less susceptible to level
and timing problems. Cards based on other chips may work, but we recommend
using the National cards. Some of the highly integrated UART chips (most
notably, Winbond and UMC) have a tendency for their transmitters to hang,
requiring re-initialization of the UART. If this occurs, you may have to restart the
91
92
Wonderware Rapidkit I/O Server
server or execute the Reinitialize I/O command from the Special menu in
WindowViewer.
%
Check your cabling to the PLC.
Is it wired correctly? Check for shorts, loose wires, broken wires, crossed wires,
and so on.
$ A continuity tester can be helpful here.
%
Verify the I/O Server’s serial configuration settings (Parity, Stop Bits, Baud
Rate, Handshaking and so on) against the settings in the hardware device.
%
Verify the communication port is working properly in Windows.
1.
Close the server program.
•
If you are using a server that requires a TSR, you cannot verify that the
port is functioning properly while the TSR is running. Stop all TSRs then
continue with this procedure. If you confirm that the port functions
properly without the TSR running, change your software interrupt (IRQ)
to another number. For example, change 60 to 62.
•
Also, if you are using an AT type computer, two devices cannot share
interrupts. Verify that the communication port you are using has a unique
interrupt setting.
2.
On Windows 3.1 or Windows for Workgroups, start the Terminal program.
On Windows 95 or Windows NT, start the HyperTerminal program.
3.
Configure the Terminal (or HyperTerminal) program to use the same
communication port with the same settings (baud rate, parity, stop bits and so
on) as the hardware device.
4.
Connect a null modem cable to a second computer's port.
5.
On the second computer, start and configure the Terminal (or HyperTerminal)
program with the same settings as the first computer.
6.
Verify that you can send data between the two computers.
•
If you do not have two computers and the computer you are using has
another port, start two instances of the Terminal (or HyperTerminal)
program with each configured to their own port, then try communicating
between them.
•
If you have an external modem, connect the modem to the communication
port that you are testing and see if you can dial out.
7.
If the communication port does not appear to be functioning properly, check
your environment files (AUTOEXEC.BAT, CONFIG.SYS, SYSTEM.INI, and WIN.INI).
Look for suspicious programs or drivers that might be taking control of the
port or its interrupt before the server is loaded. Always try to keep your
environment files as clean as possible. If you are in doubt about an entry,
comment it out.
8.
If the previous step was unsuccessful, try another communications port or
another computer.
Note A common misconception is that if you can connect to a PLC with a DOS
program, that the same communication port works in Windows - this is not the
case! Windows is an entirely different environment than DOS.
Troubleshooting I/O Server Communication Problems
%
What type of UART is on the COM port?
• If it is not a 16550, then you must lower your baud rate to 9600 or slower.
Only the 16550 UART can sustain continuous, error free communications at
speeds higher than 9600 baud. Other UARTs may work at speeds faster than
9600 baud, but errors may be written to the Wonderware Logger. For
example, "Receive Overruns." To determine which UART you have, enter
MSD at a DOS prompt, then choose COM Ports from the MSD menu.
%
If you are running Windows for Workgroups, verify the following:
1.
Verify the following lines are added to the [386 enh] section of your system.ini
file that is located in your \Windows directory:
• EMMEXCLUDE=A000-EFFF
COMxFIFO=0
Where x specifies the COM port number. You need to add a separate
COMxFIFO line for each serial port using a 16550 UART chip.
2.
3.
%
If you are running Windows for Workgroups (Version 3.1 or later), you need
to download SERIAL.386 (this file fixes a Microsoft bug) from the Wonderware
Bulletin Board System (949-727-0726) or from the Wonderware WEB site at:
http://wondertech.wonderware.com.
•
The file is 10620 bytes and has a date of 2/17/94. It is contained in a selfextracting zip file called wg1001.exe. The file is located in the "PatchFix
Library" on the Wonderware BBS in the File Transfers / Patchfix area.
•
The Wonderware Web site requires that you register before you are given
access.
If (1. and 2.) above do not work, verify the value of the ComBoostTime
parameter in your SYSTEM.INI file. This parameter represents the number of
milliseconds that a virtual machine can process a COM interrupt. (The default
value is 2.) We do not recommend that you normally change this setting
however, if you are receiving errors such as "Receive Overruns" or "WCRE=2", try increasing the value to 20.
Verify the parameters for WWCOMTSR.
• Do not specify a receive and/or transmit buffer size of 8!
For example:
Correct:
COM1:0 COM2:1,2048,2048
COM1:0 COM2:1
Incorrect:
COM1:0 COM2:1,8,8
%
Does your computer crash when you try to communicate through the COM
port?
• If so, verify that each TSR has a unique software interrupt.
•
%
There is a utility, ShowSoft, available on the Knowledge Base CD that
can assist you in determining the software interrupts that are available.
Does your computer lock up?
93
94
Wonderware Rapidkit I/O Server
• Verify the COM port's IRQs do not conflict with each other or with any other
communication boards in the computer.
%
If the PLC or field device has more than one COM port, verify that you are
connected to the correct port.
• The COM port on your computer uses the RS-232 hardware communication
standard. Meaning, you must connect the cable from the COM port to an RS232 compliant device.
Note A common mistake is to connect to an RS-422 or RS485 port on the PLC.
To do this, you need an RS232 to RS422/485 conversion device.
If possible, use an external converter instead of a board-based converter that plugs
into a slot in the computer. A board-based converter is typically more difficult to
get working for inexperienced users. If a board-based converter is not set up
properly, it can conflict with other communication boards in the computer such as,
internal modems.
%
If you are using the Windows 95 operating system, verify the following:
1.
Click Start on the Windows Taskbar. Point to Settings, then select Control
Panel in the menu. The Control Panel window displays.
2.
Double-click the System icon. The System Properties window displays.
3.
Click the Device Manager tab and select the COM port that you are using for
the server.
4.
Click Properties. The Properties window displays.
5.
Click the Port Settings tab.
Troubleshooting I/O Server Communication Problems
%
6.
Click Advanced. The Advanced Port Settings window displays.
7.
Lower the default Receive Buffer and Transmit Buffer settings to their
minimum. Lowering these settings may solve I/O communication problems
for portable computers (notebook, or laptops) and framing errors for standard
computers.
8.
If you are using a 16550 UART chip, select the Use FIFO buffers (requires
16550 compatible UART) option. If you are not using a UART chip, make
sure this option is not selected.
If you are using the Windows NT operating system, verify the following:
•
1.
Click Start on the Windows task bar. Point to Settings, then select Control
Panel in the menu. The Control Panel window displays.
2.
Double-click the Ports icon. The Ports window displays.
3.
Select a port and click Settings. The Settings for COMx window displays.
95
96
Wonderware Rapidkit I/O Server
%
4.
Click Advanced. The Advanced Settings for COMx window displays.
5.
Set the Interrupt Request Line (IRQ) value to the minimum. Lowering this
setting may solve I/O communication problems for portable computers
(notebook, or laptops) and framing errors for standard computers.
6.
If you are using a 16550 UART chip, select the FIFO Enabled option. If you
are not using a UART chip, make sure this option is not selected.
How long is your RS-232 cable?
Fifteen meters (Fifty feet) is the maximum practical length for the RS-232
standard.
%
Try using a different COM port for the I/O Server.
%
If you are installing an I/O Server or configuring a board based I/O Server on
a computer that is running the Windows NT operating system, verify that you
are logged on with Administrator privileges.
$ Without Administrator privileges, the server and Server Install program cannot
make the necessary edits to the Windows NT Registry during installation or
board configuration of the server.
1.
Click Start on the Windows Taskbar. Point to Programs, then point to
Administrative Tools (Common), and select User Manager in the menu.
The User Manager window displays.
Troubleshooting I/O Server Communication Problems
%
2.
Double-click the username you typed in during log on.
3.
If the User Properties window does not appear, you do not have Administrator
privileges.
4.
If the User Properties window does appear, click the Groups button and verify
“Administrators” is in the “Member of:” list.
If you experience occasional or random communication errors in the
Wonderware Logger, for example, "Response Timeouts," check for noise.
• Do the physical cables run past any known noise sources such as photocopiers,
fluorescent lamps, fans, pumps, motors or generators?
• Are your cables properly shielded from its environment? With radio modems
and Rapidkit link ups, occasional communications errors in the Wonderware
Logger are normal and to be expected as long as they do not adversely impact
the flow of data.
%
Increase the Reply Timeout setting in the I/O Server to a value between 5 and
10 seconds.
• Some communications errors result from not allowing the PLC or field device
enough time to respond to the server's request for data.
%
Verify the PLC is properly configured and the cable is good by using the
programming software for the PLC.
• When testing, run the programming software and communicate with the server
at the same time.
•
%
The ability to perform this test depends upon the type of PLC that you are
using.
Reinstall the I/O Server and verify that you are using the latest version.
• We continually improve our servers and using the latest version guarantees the
best results.
97
98
Wonderware Rapidkit I/O Server
New versions of the Wonderware I/O Servers are released regularly on the
Knowledge Base CD and they are also available to Comprehensive Support
customers on the Wonderware Bulletin Board System (949-727-0726) or from the
Wonderware WEB site at: http://wondertech.wonderware.com.
%
Move the I/O Server’s configuration file to another location on the
computer’s hard drive. This will clear all configuration for the I/O Server,
then reconfigure the I/O Server.
Wonderware server configuration files are typically named exactly the same as the
server’s executable name but with the .CFG extension, e.g. OMRONFO.CFG.
Refer to the Configuration File section of the server user’s guide for the exact name
of the configuration file.
%
If possible, reinstall the Windows operating system.
• Some of the files that are installed on your computer or the NT registry may
have been corrupted or accidentally modified.
%
%
If these troubleshooting suggestions do not solve your problem, there may be
a problem with your computer. There are many subtle differences between
the various computer hardware brands. Try using a computer that is a
different brand and select one that meets the following criteria:
1.
A different PC manufacturer. If this is not possible, try a different PC model
from the same manufacturer.
2.
The computer does not use an OEM (Original Equipment Manufacturer)
version of Microsoft Windows. When you start up Windows, only the
Microsoft Windows logo should display, not a logo from a hardware
manufacturer. We highly recommend you use only a Microsoft Windows
product. Contact your vendor to determine if installing an off-the-shelf copy
of Microsoft Windows will cause any problems.
If you feel you have tested all possible situations that may be causing your
failed I/O communications, contact your local Wonderware distributor for
technical support.
For more information on obtaining technical support, see your online FactorySuite
System Administrator’s Guide.
Special Wonderware Logger Messages
Special Wonderware Logger Messages
Local COM Port Errors
The following logger messages can occur in error situations if log errors (default)
is selected in the logger settings.
<COM port> OpenComm ERROR: The device identifier is invalid or unsupported!
<COM port> OpenComm ERROR: The device's baud rate is unsupported!
<COM port> OpenComm ERROR: The specified byte size is invalid!
<COM port> OpenComm ERROR: The default parameters are in error!
<COM port> OpenComm ERROR: The hardware is not available (is locked by
another device)!
<COM port> OpenComm ERROR: The function cannot allocate the queues!
ERROR: SetCommState != 0 -> Closing: <COM port>!
COM port errors
These errors refer to a local error when opening a COM port on your node. The
COM port is not available or cannot be initialized to the configured communication
parameters.
ERROR: sending <number of bytes> bytes to <COM port> (msgid: <message id>)
A local error occured sending a message to a COM port.
ERROR: reading <COM port>
A local error occured reading data from a COM port.
Local TCP/IP port errors
ERROR: Creating listening socket on port: <port name>
ERROR: Creating socket on port: <port name>
The windows socket API was not able to create the requested socket.
ERROR: Listening on port: <port name>
ERROR: Connecting socket on port <port name>
ERROR: Accepting connection on port <port name>
The windows socket API returned an error on the requested socket service..
99
100
Wonderware Rapidkit I/O Server
TCP/IP port run-time errors
ERROR: sending <number of bytes> bytes to <port name> (msgid: <message id>)
ERROR: reading <port name>
The windows socket API returned an error on the requested socket
service.
ERROR: Network subsystem failed on port <port name>
ERROR: The connection was reset by the remote side on port <port name>
ERROR: The connection was aborted on port <port name>
ERROR: Connection lost on port <port name>
Communication was lost due an external condition. All corresponding
items will go to bad. The server tries to reestablish the communication.
Data conversion errors
CONVERSION ERROR: invalid char: <invalid character>\<invalid char in hex
notation> in item value: <item data> for item <item name>(<topic name>)
CONVERSION ERROR: item value: <item data> for item <item name>(<topic
name>) is not a HEX number
The received buffer for item value scanning contained at least one invalid
character.
ERROR: invalid poke string length (<actual length> valid length: <valid length>)
for item: <item name> on <topic name>
ERROR: string value: <string value> more than 1 char for item: <item
name>(<topic name>)
The poke string for a string item does not have the correct size. It is not
transferred to the device.
POKE ERROR: invalid value, cannot convert for item: <item name> on <topic
name>
The poke value cannot be converted. Data is not transferred to the PLC.
ERROR: value: <value> clamped high at 255 for item: <item name>(<topic
name>)
ERROR: value: <value> clamped low at -127 for item: <item name>(<topic
name>)
ERROR: value: <value> clamped low at 0 for item: <item name>(<topic name>)
An invalid value has been specified for poking data. Value is clamped and
transferred to the device.
ERROR: cannot get numeric value from data parameter: <parameter name>
(configured as Data field)
A data parameter was configured as a data field but used an integer value.
ERROR: Topic parameter: <parameter name> (<value>) has invalid length:
<actual length> (should be: <required length>) in topic: <topic name>
A topic parameter does not have the correct length.
Special Wonderware Logger Messages
ERROR: poke value <value> does not fit in protocol data of size <size>
Poke data has incorrect size.
Communication errors
ERROR in response: <error code> (<error text>)
A user defined error code associated with a bad quality was received. All
items of the corresponding message are set to this quality.
ERROR in response: <error code> (unknown error)
A user defined error code with non-configured value was received. All
items of the corresponding message are set to bad quality (no access).
Checksum errors
ERROR: invalid checksum: <actual checksum> - should be: <expected
checksum> in message: <message name>
An invalid checksum was received. Item qualities in the corresponding
message are set to bad (no communication).
ERROR: checksum user function (<function name> in DLL: <DLL name>) returns
FALSE
The user checksum function was not able to calculate the checksum.
Run-time errors
ERROR: user function (<function name> in DLL: <DLL name>) returns FALSE
A user function was not able to calculate the value of a parameter.
Received data is discarded; generating poke data generates an error.
ERROR: no poke message found for item: <item name>(<topic name>)
An attempt was made to poke an item that does not have a corresponding
poke message defined.
RESPONSE TIMEOUT(<time out in milliseconds>ms) on Port: <port name>
A response to a request/poke message was not received in the defined port
timeout.
ERROR: Blocked poke data timeout for message: <message name> (id: <message
id>) - not all data values were poked by client!
One or more items belonging to a single poke message were poked. But
the data sections in this message were never completed by poking all
necessary items within the timeout period. All corresponding pokes fail.
ERROR: cannot generate protocol data from parameter: <parameter name>
ERROR: cannot generate unsolicited protocol data from parameter: <parameter
name>
101
102
Wonderware Rapidkit I/O Server
ERROR: cannot generate numeric value from parameter: <parameter name>
ERROR: cannot generate protocol poll request value from parameter: <parameter
name>
ERROR: cannot generate protocol poll response value from parameter: <parameter
name>
ERROR: cannot generate protocol poke request value from parameter: <parameter
name>
ERROR: cannot generate protocol poke response value from parameter:
<parameter name>
ERROR: cannot generate protocol simulation poll response value from parameter:
<parameter name>
ERROR: cannot generate protocol simulation poke response value from parameter:
<parameter name>
ERROR: cannot generate unsolicited protocol receive value from parameter:
<parameter name>
ERROR: cannot generate unsolicited protocol response value from parameter:
<parameter name>
An error occurred generating a value from a parameter. Check the
parameter definition.
Global errors (non-server specific)
ERROR: invalid topic name: <topic name>
An invalid topic name was specified to establish a client connection.
New status (<topic name>): <status> (<OK/ERROR>)
The communication status of a topic (to the device) has changed.
ERROR poking write complete item - writes are pending
Cannot poke to the write complete item while writes are pending.
ERROR poking write complete item - invalid value: <value>
Invalid value poked to write complete item.
ERROR poking read complete item - invalid value: <value>
Invalid value poked to write complete item.
ERROR: cannot read item: <item name> on: <item name>
Cannot read item defined as non-read.
ERROR: poking item <item name> on <topic name> (writing not allowed)
Cannot poke item defined as non-write.
write complete (ERROR) - item: <item name> on: <topic name>
An error occurred poking an item.
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising