Professional Documents
Culture Documents
Version 1.4.2
Document Revision A
How to Contact Us
Phone (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax (510) 357-8136
E-mail techsupport@osisoft.com
World Wide Web http://www.osisoft.com
Mail OSIsoft OSI Software, Ltd
P.O. Box 727 P O Box 8256
San Leandro, CA 94577-0427 Symonds Street
USA Auckland 1035 New Zealand
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and
Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a
registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and
DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_ssimaticnet.doc
Introduction.................................................................................................................... 1
Reference Manuals......................................................................................................2
Supported Features......................................................................................................3
Diagram of Hardware Connection................................................................................6
Principles of Operation..................................................................................................7
Installation Checklist......................................................................................................9
Pre-installation Procedures.........................................................................................11
Install Siemens Library Software................................................................................11
Configuration Files......................................................................................................11
The Windows NT Control Panel.................................................................................12
The COML1413 Setup Program.................................................................................12
S5 vs. TI-505 Connections.........................................................................................13
Interface Installation....................................................................................................15
Naming Conventions and Requirements....................................................................15
Microsoft DLLs............................................................................................................ 16
Interface Directories...................................................................................................16
Interface Installation Procedure..................................................................................17
Installing the Interface as an NT Service....................................................................17
Digital States................................................................................................................21
PointSource..................................................................................................................23
PI Point Configuration..................................................................................................25
Point Attributes...........................................................................................................25
Output Points.............................................................................................................. 34
Performance................................................................................................................. 41
Interface Performance................................................................................................41
Multiple Copies of the Interface..................................................................................41
Performance Point Configuration...............................................................................42
Security......................................................................................................................... 63
Buffering....................................................................................................................... 67
Configuring Buffering with PI-ICU (NT-Intel)...............................................................67
Configuring Buffering Manually..................................................................................70
Example piclient.ini File..............................................................................................71
Note: The current version of the interface went through limited tests of data types for
the S5 Series PLC. See section "PI Point Configuration" later in this manual for
supported data types. A customer who requires additional data type support must be
prepared for onsite tests.
Reference Manuals
OSIsoft
UniInt End User Document
PI Data Archive Manual
PI-API Installation Instructions
Siemens
These manual describe the protocols in detail:
SINEC CP 143 mit COM 143 Bestell-Nr. 6GK1970-1AB43-0AA0
SIMATIC NET SEND/RECEIVE-Programmierschnittstelle
Supported Features
Feature Support
Part Number PI-IN-SI-SIMAT-NTI
Platforms NTI
PI Point Types Int16, Int32, float16, float32, string,
digital
Sub-Second Timestamps No
Sub-Second Scan Classes No
Automatically Incorporates PI Point Yes
Attribute Changes
Source of Timestamps
The source of timestamps is configurable by setting the /time command-line parameter
in the .bat file /time=SERVER (recommended) or the API node local time
/time=LOCAL.
Outputs
Outputs are not tested for S5 yet and not implemented for Siemens S5 floating-point
numbers. Please contact OSI SOFTWARE GmbH for further information.
UniInt-Based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an
OSIsoft-developed template used by our developers, and is integrated into many
interfaces, such as the SIEMENS SIMATIC NET TI-505 interface. The purpose of
UniInt is to keep a consistent feature set and behavior across as many of our interfaces
as possible. It also allows for the very rapid development of new interfaces. In any
UniInt-based interface, the interface uses some of the UniInt-supplied configuration
4
While the CP-1413 was being phased out and before the CP-1613 was released, OSI
was recommending that the SOFTNET-S7 (basic or extended) software be installed on
the interface node in conjunction with a standard Windows NT-compatible Ethernet
card. Although the difference in speed is not as great as between the CP-1413 and CP-
1613, the CP-1613 processor is faster than the SOFTNET-S7/Ethernet Card
combination. This is because the CP-1613 card, unlike the Ethernet card, has a built-in
processor that can be used to process incoming transactions. With SOFTNET-S7, the
CPU of the personal computer must process the incoming transactions.
Using a CP-1413 or CP-1613 is referred to as using “Hardnet.” Using SOFTNET-S7
in conjunction with a standard Windows NT-compatible Ethernet card is referred to as
using “Softnet.”
PI Server
OpenVMS, NT,
HPUX, SOL, AIX, DUX
TCP/IP
PI-API-NTI
Windows NT
PI-IN Interface
TF-1413 SOFTNET-S7 TF-1613
NT compatible
CP-1413 network card CP-1613
H1 industrial ethernet
CP 1434 CP 1430
Simatic TI505 Simatic S5
6
Principles of Operation
For each group of tags (Location 1 parameter) a separate interface process must be started
(/id=Location1).
At startup, the Interface checks all command-line parameters. If one of them is out of
range, the interface generates an error-message and stops. If the parameters are all
correct, the interface runs through initialization. The first step is to open a connection to
the PI Server in order to be able to retrieve necessary tag information. The interface has to
make a login for security reasons. The interface supports 3 methods of logging into the PI
Server:
1. If the interface runs on the PI Server, it can be started using /hosts=localhost and
will not need an additional password. It uses the standard proxy account on the server.
2. The administrator sets up a proxy account for the interface computer and
/host=hostname will lead to read/write privileges for the interface.
3. The interface attempts a logon under the “piadmin” account and will ask for the
password when it is started the first time, ie: no SINET01.PWD file is found. The
user enters the correct password and the interface stores this password into an
encrypted file in the startup directory, where it will make use of it on future startups.
Whenever the password for “piadmin” changes, the user must type in the correct
password again on a new startup of the interface.
Note: It may occur that the administrator changes the “piadmin” password and forgets to
restart the interface in order to type in the new password. In this case, the interface will
not be able to connect to the PI Server when an automatic restart of the interface occurs
(e.g. reboot of the interface computer caused by a power failure). If you want to avoid
such a situation, use method 2, the proxy account.
After successful connection to the PI Server, the interface opens a connection to the related
SIEMENS library. If the library is not present, the interface will stop with an error
message. Once connection is made, a list of all the tags with the interface point source and
configured for this special interface number is collected.
Input
After successful startup, the interface generates a list of PI tags assigned to this interface.
Whenever the first tag for a new PLC channel (TSAP) is found, the interface tries to open
the channel. The interface is configured to transfer up to 480 bytes in one block. This
guarantees the best performance, although the maximum number of bytes can be 4096.
Therefore, the interface groups all tags together which are defined for the same PLC
memory area. A DB range, for example, can have the following blocks: 0 - 479, 480 -
959, etc.
The user can help optimize the performance of the interface by grouping tags for the same
memory block in the same scan class. In the above example all possible 240 tags for the
range 0 - 480 would generate one READ every cycle period.
Inputs are scan-based and different scan classes can be defined. The smallest scan period
is 1 second. But this scan performance can only be achieved if all connected PLCs are in
normal operation. If some channels are not working properly, the interface must wait a
minimum of 5 seconds before attempting to read again.
Inputs can also be event-based. Any PI tag can serve as a trigger tag. Whenever this tag
changes value, the interface tag will perform a block read. “Collect Call” mechanism for
event-triggered input is not recommended.
Siemens SIMATIC NET Interface to the PI System 7
The source of data for a point is defined by evaluating the symbolic address in the
InstrumentTag attribute of that point. The interface will calculate the physical address of
the value from the symbolic address and request the according memory block from the
PLC.
For PCS Systems there are two options. If you have used the option to configure tags via
symbolic address (see chapter “Tag configuration for PCS Systems”), then the interface
treats the tags in the same way as if the system were a plain TI-505 PLC. If the tags are
configured to contain the PCS Tagname in the InstrumentTag attribute, then the interface
looks in the copy of the engineering file (install.tag) to figure out the physical address.
This, of course, requires that the engineering file install.tag be copied to the interface
startup directory first.
A connection break to a single communication channel will mark all concerned tags for
I/O Timeout, but the interface will continue to read blocks, depending on the /rr1
parameter in the startup command line of the interface. The /rr2 parameter defines the
periods where the interface tries to close and reopen the channel.
If an error-marked value is transferred by the interface, this value will be marked as BAD
INPUT in the PI System.
Output
Output of data to the PLCs is internally handled by exception. If it is necessary to update
values with 5-second accuracy, define a PI tag that gets updated every five seconds.
Note: Outputs are not tested for S5 and not yet implemented for Siemens S5 floating
point number. Please contact OSI Software GmbH for further information.
Configuration Files
Softnet – S7
If the Softnet-S7 drivers are used on the interface node, perform the following in the
control panel.
1. Click on the “install” button to install the ISO Ind. Ethernet module. One may need to
reboot after this is done. If the module has already been installed, its name will appear
in the white box that begins with <None>.
2. From the same control panel add an ACCESSPOINT. Clicking on the down arrow
underneath “Access Point of Application” will reveal an option to add or delete an
Access Point.
3. To associate this ACCESSPOINT with an Ethernet Module, highlight the appropriate
Ethernet Module name (which will appear somewhere beneath <None>).
4. Click the “Diagnostics” button and test the configuration. If this test does not pass,
the interface will not be able to establish a connection to the PLC.
Hardnet - CP1413
If the CP1413 drivers are used on the interface node and the PLC has a TF connection
configured for the PC, enable the TF in “setting the PG-PC interface”.
505 Configuration
PC Client 505 CP1434 Server
Local TSAP 1 Local TSAP 1
Read Connection 1 READ Passive (job 1) No DHB required
Write
Local TSAP 2
Connection 2 WRITE Passive (job 2) No DHB required
MSVCIRT.DLL
MSVCRT.DLL
MSVCRT40.DLL
MSVCP50.DLL
MSVCP60.DLL
The following additional Microsoft DLLs are also distributed on the CD-ROM . These
DLLs are only used by a debug version of the interface. Copy these files to the
Winnt\system32 directory only if the files in the winnt\system32 directory are older
than the files on the CD-ROM.
MSVCIRTD.DLL
MSVCRTD.DLL
MSVCP50D.DLL
MSVCP60D.DLL
Interface Directories
The above lines define the \pipc directory as the root of the PIHOME directory tree on the
C: drive. OSIsoft recommends using \pipc as the root directory name. The
PIHOME directory does not need to be on the C: drive.
If the interface cannot be started interactively, one will not be able to run the interface
as a service. It is easier to debug interactively started processes because error
messages are echoed directly to the screen. Once the interface is successfully running
interactively, one can try to run it as a service by following the instructions below.
Service Configuration
Service Name
The Service to Add box shows the name of the current interface service. This service name
is obtained from the interface executable.
Display Name
The Display Name text box shows the current Display Name of the interface service. If
there is currently no service for the selected interface, the default Display Name is the
service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft
suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that
the service is part of the OSI suite of products.
Interface Dependencies
The Installed Services list is a list of the services currently installed on this machine.
Services upon which this Interface is dependant should be moved into the Interface
Dependencies list using the “Add>>” button. For example, if API Buffering is running,
then “bufserv” should be selected from the list at the right and added to the list on the left.
When the PI Interface is started (as a service), the services listed in the dependency list will
be verified as running (or an attempt will be made to start them). If the dependent
service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages that
may indicate the cause for any server not running as expected.
Add>>
To add a dependency from the list of Installed Services, select the dependency name, and
click the Add button.
<<Remove
To remove a selected dependency, highlight the service name in the Installed Dependencies
list, and click the Remove button.
The full name of the service selected in the Installed Services list is displayed below the
Installed Services list box.
Create
The Create button adds the displayed service with the specified Dependencies and with the
specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently installed,
or if the service is currently running, this button will be grayed out.
18
Status of the
Interface Service
When the interface is installed as a service on the PI Server node and when Bufserv is not
implemented, a dependency on the PI network manager is not necessary because the
interface will repeatedly attempt to connect to the PI Server until it is successful.
Note: Interfaces are typically not installed as automatic services when the interface is
installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was
added successfully. One can use the services control panel at any time to change the
interface from an automatic service to a manual service or vice versa .
PI 2 Home Node
Digital states are defined by running the Digtl Stat display from the PI menu. The
states must be contiguous for each status type and may be anywhere within the
Digital State Table outside of the range 193 - 320, which is reserved for OSIsoft. The
digital states need to be defined prior to point configuration. The digital state sets
described in the PI 3 sections below should be entered into the PI 2 Digital State Table.
For more information, see the DA manual.
PI 3 Home Node
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as
the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a
point source character when creating a PI point, the point is assigned a default point
source character of L. Therefore, it would be confusing to use L as the point source
character for an interface.
Before a PI point with a given point source can be created, the point source character must
be added to the PI 2 point source table. For example, if point source S is not defined in the
PI 2 point source table, a point with a point source of S cannot be created. This prevents
the user from accidentally creating a point with an incorrect point source character.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal
PI point naming conventions.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point
that belongs to a particular interface. For additional information, see the /ps command-
line argument and the “Point Source” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example,
integer values from a device can be sent to floating point or digital PI tags. Similarly, a
floating-point value from the device can be sent to integer or digital PI tags, although the
values will be truncated.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on
PI 2 Servers. For more information on the individual point types, refer to the Data Archive
(DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, int16, int32, digital, and string point types are supported on PI 3 Servers.
For more information on the individual point types, see PI Data Archive for NT and
UNIX.
S5 PLC
For S5 PLCs, the interface supports reading memory block and treating the bytes as
characters. This requires string tags on the PI 3 home node.
See the description of the PLCSIG keyword under the description of the Extended
Descriptor attribute.
5x5 PLC
For 5x5 PLCs, when reading memory as PI string types, any non-printable character will
be converted to a space within the length specified in the instrument tag.
The following applies to input points (Location5=0). When an input point has a PI point
type of R, the interface assumes that the PLC stores its values according to standard TF
Encodings (see Appendix). For example, the interface will assume that variables in V
memory are stored in Integer16 format. Likewise, the interface assumes that variables in
V or VF memory are stored in floating-point format. Hence, if all of the memory types
Siemens SIMATIC NET Interface to the PI System 25
that are being read from the PLC are stored according to the standard TF Encodings given
in the Appendix, then one can safely use a point type of R for all PI Points and all values
should be read correctly into PI.
However, not all variables are stored according to their standard TF Encoding. Namely,
variables stored in V or VF memory are sometimes stored in Integer32 format instead of in
floating point format. For this reason, when an input point has a PI point type of I or D,
the interface always assumes that the target variable is stored as an integer. Hence, one
can define a PI point of type I or D and read an Integer32 from V or VF memory.
Location1
Location1 indicates to which copy of the interface the point belongs.
Location2
The Location2 attribute assigns a "logical PLC number" to the PI point. The logical PLC
number that is assigned in Location2 must correspond to a logical PLC number in the
SINET.CFG file, which is described in detail under the section called "Configuration
Files." In the SINET.CFG file the logical PLC number is associated with a TSAP
address / Ethernet (MAC) address pair that must be unique.
One connection can be established to a PCL for every logical PLC number that is assigned
to the PLC. The same logical PLC number cannot be used to both read data from and
write data to a PLC.
Location3
For S5 Series PLC
Location3 is not used for reading data from S5 series PLCs.
Location4
Scan-Based Inputs
For interfaces that support scan-based collection of data, Location4 defines the scan class
for the PI point. The scan class determines the frequency at which input points are scanned
for new values. For more information, see the description of the /f flag in the section
called “The Startup Command File”.
InstrumentTag
For a PI 2 Server, the instrument tag attribute is limited to 32 characters. For a
PI 3 Server, the instrument tag is limited to 32 characters.
S5 Series PLC
The memory location in the S5 that is targeted for reads or writes is defined in the
InstrumentTag field. The syntax is Range[index],(type)[index](.bitnumber).
The (type) is optional. If not used, the interface will use the default type from the table
below. In the current version, the interface only supports DW for DWORD and W for
WORD.
S5 Description Data type
Range
DB Common Data Dword, 32 bit
MB Merker Bereich Byte, 8 bit
EB Process Input Byte, 8 bit
AB Process Output Byte, 8 bit
PB Peripheral Device Byte, 8 bit
ZB Counter Word, 16 bit
TB Timer Word, 16 bit
BS System Data Word, 16 bit
AS Absolute Memory Word, 16 bit
DX Extended DB Dword, 32 bit
DE External DB Dword, 32 bit
QB Extended Peripheral Device Byte, 8 bit
Note: The Interface has only been tested with S5 Range DB, Data type Word, Dword
Examples of symbolic addresses that can be specified in the InstrumentTag field are given
in the following table.
Symbolic Description
Address
DB16,1 DB modul 16, Dword 1
DB16,W1 DB modul 16, word 1
DB16,1.1 DB modul 16, Dword 1, bit 1
DB16,DW1 DB modul 16, Dword 1
Siemens SIMATIC NET Interface to the PI System 27
PI Point Configuration
The second option is available for PCS systems. In PCS systems, PCS tags are mapped to
memory locations in the PLC. This mapping is done in an ASCII file called the install.tag
file. An example of an install.tag file is given below:
Example install.tag file:
Record,ControlNode,TagType,Tag,Description,ProcessGroup,ManualSet,Paren
t,Attribute,Memory,Locations,Upload,Twenty%,Autolog,InitValue
T,STATA,IVAR,78CMAPRODUCT,R78 CMA PRODUCT SELECTION,0xffffffff,N
A,,,,,,,,H_RANGE,,,,,,5000
A,,,,,,,,L_RANGE,,,,,,0
A,,,,,,,,VALUE,V2010,1,N, ,N,0
A,,,,,,,,STATUS,V2010,1,N, ,N,0
T,STATA,IVAR,77CMAPRODUCT,R77 CMA PRODUCT SELECTION,0xffffffff,N
A,,,,,,,,H_RANGE,,,,,,5000
A,,,,,,,,L_RANGE,,,,,,0
A,,,,,,,,VALUE,V2011,1,N, ,N,0
A,,,,,,,,STATUS,V2011,1,N, ,N,0
T,STATA,VLV2,CV647,BD SLOW CLOSE VALVE @ 1603,0xffffffff,N
A,,,,,,,,SETPOINT,C39,1,Y, ,N,0
A,,,,,,,,STATUS,C32,12,N, ,N,0
The PCS tag names are the fourth fields on the lines that begin with T. There are three
PCS tags names that are listed in the above files: 78CMAPRODUCT,
77CMAPRODUCT, and CV647. Attributes for each of these tags are listed on the lines
that begin with A. These attributes are mapped to memory locations in the PLC. For
example, the VALUE and STATUS attributes for tag 78CMAPRODUCT are both mapped
28
to memory location V2010. Similarly, the SETPOINT and STATUS attributes for tag
CV647 are mapped to memory location C39 and C32, respectively.
A particular memory location is designated for the interface by assigning the
InstrumentTag field a name of the form PCSTagname.Attribute. For example, if one
assigns CV647.STATUS to the InstrumentTag field, memory location C32 will be read by
the interface. The InstrumentTag field is limited to 32 characters.
Note: For C memory locations, it is possible to read up to 32 bytes and combine these to
one 32-Bit value. To read, for example, C1234 and the next 11 bytes you have to use
C1234,12 as the memory location. The Interface will take care of this if you use the
INSTALL.TAG file. You may apply a Bit mask to the result to filter out necessary
information. See the description of the BITMASK keyword under the description of the
Extended Descriptor attribute for more information.
IMPORTANT: If the array of up to 32 values will exceed the internal block size of 480
bytes, the array will be truncated to the available bytes. When this happens, a message
to this effect will be written to the log file.
ExDesc
This is the extended descriptor attribute. For a PI 2 Server, the extended descriptor is
limited to 80 characters. For a PI 3 Server, the extended descriptor is limited to
80 characters.
Z=InstZero
The Z keyword is used to specify the instrument zero (InstZero). The instrument zero is
used in the conversions that are described under the SquareRoot PI Point attribute. If the
Z keyword is not found, then InstZero is assumed to be zero.
Performance Points
For UniInt-based interfaces, the extended descriptor is checked for the string
“PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a
performance point. See the section called “Performance Points.”
Trigger-Based Inputs
For trigger-based input points, a separate trigger point must be configured. An input point
is associated with a trigger point by entering a case-insensitive string in the extended
descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by
the name of the trigger point. There should be no spaces in the string. UniInt automatically
assumes that an input point is trigger-based instead of scan-based when the
keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The
new value does not need to be different than the previous Snapshot value to trigger an
input, but the timestamp of the new value must be greater than (more recent than) or equal
to the timestamp of the previous value. This is different than the trigger mechanism for
output points. For output points, the timestamp of the trigger value must be greater than
(not greater than or equal to) the timestamp of the previous value.
BCD=#
The BCD keyword is used to specify that the current memory word inside a DB is of BCD
type. The number in a range of 1 to 8 defines the number of BCD digits stored in one
word. It is only possible to use up to 8 BCD digits in one PI tag. The PI tag should be of
type float to avoid overflows.
Note: Floating point numbers only have 6 significant digits. If you need all BCD digits
significant, you should limit BCD to 4.
PLCSIG=<BYTE,RBYTE,LBYTE,INT16,INT32,FLT>
By default the interface will read the memory from the PLC in the following standard C
data types:
PLCSIG PI Data Type PI Data PI Data
Integer Type Type
Digital Float
<none> Unsigned short Short Integer
BYTE, LBYTE Char - Char
RBYTE Char - Char
INT16 Unsigned short - Short
INT32 Unsigned integer - Integer
FLT Float - Float
STRG - - -
This may be changed by using the parameter PLCSIG in the extended descriptor.
Example:
Exdesc: Read the DWORD 83 from DB 50 as a Siemens S5 floating point
PLCSIG=FLT, number
Instrumenttag:
DB50,DW83
Exdesc: Read the DWORD 83 from DB 50 as an integer
PLCSIG=INT32,
Instrumenttag:
DB50,DW83
Exdesc: Read the WORD 83 from DB 50 and the following 8 Byte (4 WORDS)
PLCSIG=STRG, as string.
Instrumenttag:
DB50,W83,8
Note: If the string is defined of length <x> (DB20,W1,<x>), the maximum string length
to be read is <x>, while the maximum string length to be written is <x-1>. That is
because the interface writes a trailing NULL to the S5 memory. Additionally, the length
of the string will be extended to fit the S5 memory (DB20,W1,3 will be extended to a 4
character string, as S5 word memory is 2-byte oriented).
30
MASK=0xh
The MASK keyword is used to specify the Mask which is applied via logical AND to the
PLC value. If the MASK keyword is not found, then the bit mask is assumed to be
0xffffffff.
The result will be shifted to the first non-zero bit in the bitmask, zero bits within the bit
mask will not be compacted.
OUTPUT_MASTER
The interface can be configured to write data to individual memory locations or a block of
memory locations. When a block of memory locations is written, the write is triggered
with an output master tag. The output master tag must have the keyword
“OUTPUT_MASTER” in the extended descriptor. See “Output Tag Configuration” for
more information.
MASK=0xh
The MASK keyword is used to specify the Mask which is applied via logical AND to
multi-byte C memory locations. If the MASK keyword is not found, then the bit mask is
assumed to be 0xffffffff.
The result will be shifted to the first non-zero bit in the bit mask, zero bits within the bit
mask will not be compacted.
MAP=map
The MAP keyword is used to specify a bitmap. The bits from an integer word that is read
from the PLC are rearranged according to the bitmap, and the result is sent to PI. Bit
mapping is supported only for input tags. Moreover, the input tags must be integer or
digital PI Points otherwise the bit map will not be applied.
The format of the bit map is:
MAP=uuvvwwxxyyzz
where uu, vv, ww, yy, and zz each refer to a single bit. A leading zero is required if the
referenced bit is less than 10. The lowest possible bit is 01 and the highest possible bit is
32. Up to 32 bits can be mapped.
A bitmap of 0307120802 will map the second bit of the original word to the first bit of the
new word, the eighth bit to the second bit, the twelfth bit to the third bit, etc. The high-
order bits of the new word are padded with zeros if the bits are not specified.
For instance, a single 16-bit PLC register holds the state of four different thermocouples.
The first 4 bits correspond to the first thermocouple; the second 4 bits correspond to the
second thermocouple, etc. Four different input tags with four different bitmaps could be
used to read thermocouple states. The first input tag would use a bitmap of 04030201 to
read the state of the first thermocouple; the second input tag would use a bitmap of
08070605 to read the state of the second thermocouple, and so on. If the 16-bit word from
the PLC was 0000 0000 0101 0111 or decimal 87, then the first thermocouple state would
be interpreted as binary 0111 or decimal 7, the second thermocouple state would be
interpreted as 0101 or decimal 5, etc.
OFFS=offset
The OFFS keyword is used to specify an offset to the memory location. If the OFFS
keyword is not found, then offset is assumed to be zero.
Example:
Siemens SIMATIC NET Interface to the PI System 31
PI Point Configuration
If the memory address is V.1234 and offset is specified as 4, the interface will read from
memory location V.1238
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for
the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when
the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is
changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the
PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where UniInt will
write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited
so that the point is no longer valid for the interface, the point will be removed from the
interface, and SCAN OFF will be written to the point. For example, if the PointSource of a
PI point that is currently loaded by the interface is changed, the point will be removed from
the interface and SCAN OFF will be written to the point.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on
configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of
PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown
subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The
timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by
the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which
means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes
in the event of a power failure. For additional information on shutdown events, refer to PI
Data Archive for NT and UNIX.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are
independent of the SHUTDOWN events that are written by the interface when the
/stopstat=Shutdown command-line argument is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting
the Shutdown attribute to 0 for each point. Alternatively, one can change the default
behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that
have their Shutdown attribute set to 0. To change the default behavior, edit the
\PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility
program that provides the capability to store and forward events to a PI Server, allowing
continuous data collection when the Server is down for maintenance, upgrades, backups,
and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect
data for the interface, making it undesirable to write SHUTDOWN events to the PI points
for this interface.
32
SquareRoot
Conversions can be applied to input and output values for tags of type integer or real. The
conversion that is applied depends upon the value of the SquareRoot PI Point attribute as
described in the following table.
Conditions Operation
SquareRoot = 0 No operation. Raw input values are sent to PI for Input Tags
and raw values are output to the PLC for output tags.
SquareRoot = 1 Input tags:
Value = [ (Value - InstZero)/ Convers ] * Span + Zero
Output tags:
Value = [ (Value - Zero)/Span] *Convers + InstZero
Zero, Span, and Convers are standard PI Point attributes. InstZero must be specified in
the extended descriptor. See the description of the extended descriptor for more
information.
Output Points
Output points control the flow of data from the PI Data Archive to any destination that is
external to the PI Data Archive, such as a PLC or a third-party database. For example, to
write a value to a register in a PLC, one would use an output point. Each interface has its
own rules for determining whether a given point is an input point or an output point. There
is no de facto PI point attribute that distinguishes a point as an input point or an output
point.
Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not
scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.
Output tags are used to write values to memory locations in a PLC. A tag is an output tag
if the value of location5 is set to 1.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output, write
a new value to the Snapshot of the output point itself. The new value does not need to be
different than the previous value to trigger an output, but the timestamp of the new value
must be more recent than the previous value.
Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2
has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a
digital state that is indicative of the failure, which is very important for troubleshooting
34
Tag Configuration for PCS Systems
The SIEMENS PCS System consists of TI 505 Series PLC and Engineering Stations. The
PCS System knows Tagnames similar to PI Tagnames. The Tagnames are created in the
Engineering Station and are mapped to physical addresses within a certain PLC. In order
to have maximum performance with our interface, we did not develop a separate PI
interface running on the Engineering Station. Instead, the interface PC is a member of the
H1 network and gets the data from the PLC directly. This concept guarantees maximum
speed. Since Tag handling and address mapping are done in the Engineering Station we of
course need to make sure that we have the same information available for the interface
configured for the PCS System. Therefore, we provide 2 scenarios for the interface:
Option 1
The end user is able to retrieve the physical address for a specific value in the PLC from
the Engineering Station and configures this physical address in the form of symbolic
address strings as shown under “PI Point Configuration - Instrument Tag”.
Note: Whenever a PCS Tag changes its location, the end user needs to track the change
in the PI System as well. The PI Tag needs to be edited and the interface will be notified
of the change automatically (signup for update mechanism).
Option 2
All tag configuration information is stored in an ASCII file called install.tag at the
Engineering Station. If the user copies the file to the interface computer on the interface
startup directory, the interface can make use of the information contained in the file. In
this way the InstrumentTag can be used to just contain the PCS tagname and the interface
will automatically look into the install.tag file to calculate the physical address.
In the case of multiple PLCs, it is required to combine all install.tag files to one file. It is
required that there are no identical tagnames on different PLCs as the interface only refers
to the tagname. The LOCATION2 parameter and the SINET.CFG file do the mapping to
the different PLCs.
Note: If the install.tag file changes (the PCS Tag configuration has changed), a new
copy action has to be done. The interface will only be notified of the change for a certain
tag if the interface was restarted or the PI tag was edited (signup for update mechanism).
Just to copy the new install.tag file is not sufficient.
For example /CSV=11 will write all tags to install.csv and will write the PI short tagname
if available.
To use the Install.CSV file for point configuration, one has to edit the file accordingly. For
a PI2 server the column PI3PointType has to be removed and the PI2PointType has
to be renamed to PointType. For PI3 Systems the column Tag has to be removed and
LongtagName has to be renamed to Tag, the columns PI2PointType and Precision
have to be removed and PI3PointType has to be renamed to PointType.
Siemens SIMATIC NET Interface to the PI System 36
Performance
Interface Performance
Key factors that effect performance of an interface:
1. The number of data blocks that the interface requests and the frequency at which these
requests are made.
2. The update time of the PLCs.
Every time the interface requests a block of data it must wait for the PLC to respond. Say
that there are 30 request blocks associated with the interface and that the update time of
the PLC is 30 milliseconds. It would take a minimum time of (30 blocks * 30
milliseconds/block = 900 milliseconds) to finish processing all 30 request blocks. The
interface would be hard-pressed to scan all 30 blocks every second, but the interface
should be able to scan all 30 blocks every 5 seconds without a problem. The above
calculation provides the minimum time for a PLC to process a request. The calculation
does not include the time it takes the PLC to process the request, which will be affected by
block size. However, testing indicated that the number of request blocks, not the size of
the request blocks, is the major factor that affects performance.
The number of data blocks is affected by:
1. The number of logical PLCs that the interface is talking to.
2. The number of different memory types that the interface reads.
3. The number of tags associated with the interface.
A request for a block of data can only be made to one PLC of one particular memory type
at a time. In addition, a maximum number of 238 integer words or a maximum of 118
floating points can be requested in one block. For example, if memory locations V1 to
V1000 need to be read, the interface would split the request into 5 blocks: V1 to V238,
V239 to V476, V477 to V714, V715 to V952, and V953 to V1000. The request blocks
always start at 1, 239, 477, etc, but the end of the request block depends upon the amount
of data that is requested. That is, if tags have been configured to collect data for V100 to
V300, then the interface will request V1 to V238 in one block and V239 to V300 in
another block.
The user should avoid splitting a request block over 2 scan classes. That is, if the user has
configured 50 tags with location4=1 (scan class 1) to collect data from memory locations
V1 to V50 and 50 tags with location4=2 to collect data from memory locations V51 to
V100, then the interface will request a block from V1 to V100 for each scan class. This
only affects interface performance, not the end result.
To create or delete a Performance Point, right mouse click the line belonging to the tag to
be created, and click Create or Delete. If a tag already exists, the status is marked
“Created”, the Delete option will be enabled. If a tag does not exist, the status is marked
“Not Created” or “Deleted”, and the Create option is enabled.
The Performance Points are created with the following PI attribute values:
Attribute Details
Tag Tag name that appears in the list box
Point Source Point Source for tags for this interface, as specified on the first tab
Compressing Off
Excmax 0
Descriptor Interface name + " Scan Class # Performance Point"
Status
The Status column in the Performance Points table indicates whether the Performance
Point exists for the scan class in column 2. If a Performance Point does exist, a status of
“Created” is displayed. If the Performance Point does not exist, a status of “Not Created”
is displayed. If a Performance Point exists, and is deleted, a status of “Deleted” is
displayed.
Scan Class
The Scan Class column indicates which scan class the Performance Point in the Tagname
column belongs to. There will be one scan class in the Scan Class column for each scan
class listed in the Scan Classes combo box on the Uniint Parameters tab.
Tagname
Siemens SIMATIC NET Interface to the PI System 38
The Tagname column holds the Performance Point tag name.
PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the
interface that is in use.
Tag Status
The Tag Status column indicates whether the IORates tag exists in PI. The possible states
are:
Created – This status indicates that the tag exist in PI
Not Created – This status indicates that the tag does not yet exist in PI
Deleted – This status indicates that the tag has just been deleted
Unknown – This status indicates that the ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates tag listed in the tag name and the event
counter is in the IORates.dat file. The possible states are:
Yes – This status indicates that the tag name and event counter are in the
IORates.dat file
No – This status indicates that the tag name and event counter are not in the
IORates.dat file
Siemens SIMATIC NET Interface to the PI System 41
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the
interface. The command line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the IORates tag.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter
Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Server Nodes
Create an I/O Rate Tag with the following point attribute values.
Attribute Value
PointSource L
PointType float32
Compressing 0
ExcDev 0
The PI-Interface Configuration Utility (PI-ICU) provides a tool for configuring the
Interface startup command file. The interface control for PI-ICU has two (2) tabs with a
total of five (5) sections. A yellow text box indicates that an invalid value has been entered,
or that a required value has not been entered.
General
Connection Parameters
PLC Type
The PLC Type is the type of the connected PLC for the Send/Receive interface. Choose
TI505 for SIMATIC 505 and S5 for SIMATIC S5.
The command line equivalent is /plctype=x, where x is either TI505 or S5. This
parameter is required.
Timeout
The timeout flag is used in conjunction with the persistence flag. The timeout
flag is used to set a timeout in units of 51 milliseconds. For example, timeout=100
corresponds to a timeout of 5.1 seconds.
The command line equivalent is /ct, where x is the number of 51 millisecond timeout
periods used. This parameter is optional. The default value is 100.
Retry rate 1
If there is a communication problem, the interface will try to reconnect to the PLC after
retry rate 1 seconds.
The command line equivalent is /rr1, where x is the number of milliseconds after which
to retry the connection to the PLC initially. This parameter is optional. The default value
is 30. The minimum is 10, and the maximum is 3600.
Retry rate 2
If there is a continued communication problem, the interface will try to reconnect to the
PLC after retry rate 2 seconds. If the reconnect is unsuccessful, subsequent retries will be
attempted every retry rate 2 seconds, where retry rate 2 is specified by the Retry Rate
2 flag.
The command line equivalent is /rr2, where x is the number of milliseconds after which
to retry the connection to the PLC. This parameter is optional. The default value is 120.
The minimum is 120, and the maximum is 28800.
General Parameters
Source of timestamps
The interface uses either the local time on the PI-API node or the remote time on the PI
Server node to timestamp values. It is highly recommended to use the server time to
timestamp values (/time=SERVER). To use a local time, specify, /time=LOCAL.
The command line equivalent is /time=x where x is either SERVER or LOCAL. The
default setting is SERVER. This parameter is optional.
Outputs to PLC
The Outputs to PLC section allows users to control whether data is written to the PLC
(output). The options are:
Enable – value is 0
Disable – value is 1
Disable all but writing to DB area – value is 2
The command line equivalent is /write=x where x is either 0, 1, or 2. The default
setting is 0. This parameter is optional.
CSV File
Install .csv File Creation
This section controls the creation of the install.csv file:
Write all tags: 1 (All tags are written)
Write non-configured tags: 0 (Only in PI not configured tags are written)
Check PI for configured points: 1
Additional Parameters
The Additional Parameters section is provided for any flags that may have been required in
the future.
Note: The UniInt End User Document includes details about other command line
parameters, which may be useful.
Command-Line Parameters
If the interface is to be configured without PI-ICU, then the following section describes the
command line parameters.
Command-line arguments can begin with a / or with a -. For example, the /ps=M and
-ps=M command-line arguments are equivalent.
For NT, command file names have a .bat extension. The NT continuation character (^)
allows one to use multiple lines for the startup command. The maximum length of each
line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum
length of each flag is 1024 characters.
Parameter Description
/time=timesource The interface uses either the local time on the PI-API node or
the remote time on the PI Server node to timestamp values. It
Optional, is highly recommended to use the server time to timestamp
default: /time=SERVER values (/time=SERVER). To use a local time, specify,
/time=LOCAL.
/write=# Disable write data (output) into PLC (security)
Optional, Enable
default: /write=0 Disable
Disable everything else than writing into DB area
/ct=timeout The /ct flag is used in conjunction with the
/persistence flag. The /ct flag is used to set a timeout
Optional,
in units of 51 milliseconds. For example, /ct=100
default: /ct=100 corresponds to a timeout of 5.1 seconds.
/persistence=# persistence is the number of times that a send/receive call will
be retried in the event that a send/receive call times out. For
Optional, example, if /ct=100 and /persistence=10, a
default: /persistence=10 send/receive call that consistently times out will be retried
every 5.1 milliseconds, up to a maximum of 10 times.
Ideally, the combination of the /ct and /persistence
flags sets the maximum time that the interface will hang on a
particular send/receive call. In practice, the timeout period
appears to be "much longer" than the combination of the /ct
and /persistence flags should dictate.
/rr1=rate1 /rr1 is short for retry rate 1. If there is a communication
problem, the interface will try to reconnect to the PLC after
Optional,
rate1 seconds. If the reconnect is unsuccessful, subsequent
default: /rr1=30 retries will be attempted every rate2 seconds, where rate2 is
48
Parameter Description
minimum: 10 specified by the /rate2 flag.
maximum: 3600
/rr2=rate2 See the /rr1 flag.
Optional,
default: /rr2=120
minimum: 120
maximum: 28800
/PLCTYPE=TI505 Type of the connected PLC for the Send/Receive interface.
Choose TI505 for SMATIC 505 and S5 for SIMATIC S5.
Required
/deb=level The /debug flag is used to set the debug level of the
interface between 0 and 9, inclusive. At a debug level of 0, no
Optional,
debug messages are written to the output log file. At a debug
default: /deb=0 level of 9, the maximum number of debug messages is written
to the output log file.
/db=level Optional debug switch for printing debug messages from
UNIINT, which is OSI’s universal interface. The subroutines
Optional, for the TI505 interface are compiled under UNIINT, the main
default: /db=0 subroutine.
/CSV=<a><b> Controls creation of the install.csv file:
Optional, a=1: All tags are written
a=0: Only in PI not configured tags are written
default: /CSV=00
b=1: Check PI for configured points
b=0: Don't check PI for configured points
/ps=x The /ps flag specifies the point source for the interface. x is
not case sensitive and can be any single character. For
Required
example, /ps=P and /ps=p are equivalent.
The point source that is assigned with the /ps flag
corresponds to the PointSource attribute of individual PI
Points. The interface will attempt to load only those PI points
with the appropriate point source.
/id=x The /id flag is used to specify the interface identifier.
Required The interface identifier is a string that is no longer than 9
characters in length. UniInt concatenates this string to the
header that is used to identify error messages as belonging to
a particular interface. See the section called “Error and
Informational Messages” for more information.
UniInt always uses the /id flag in the fashion described
above. This interface also uses the /id flag to identify a
particular interface copy number that corresponds to an
integer value that is assigned to Location1. For this interface,
one should use only numeric characters in the identifier. For
example,
/id=1
/f=SS The /f flag defines the time period between scans in terms of
or hours (HH), minutes (MM), and seconds (SS). The scans can be
/f=SS,SS scheduled to occur at discrete moments in time with an
or optional time offset specified in terms of hours (hh), minutes
/f=HH:MM:SS (mm), and seconds (ss). If HH and MM are omitted, then the
or
Siemens SIMATIC NET Interface to the PI System 49
Startup Command File
Parameter Description
/f=HH:MM:SS,hh:mm:ss time period that is specified is assumed to be in seconds.
Each instance of the /f flag on the command line defines a
scan class for the interface. There is no limit to the number of
Required for reading scan-
scan classes that can be defined. The first occurrence of the
based inputs
/f flag on the command line defines the first scan class of the
interface, the second occurrence defines the second scan class,
and so on. PI Points are associated with a particular scan class
via the Location4 PI Point attribute. For example, all PI Points
that have Location4 set to 1 will receive input values at the
frequency defined by the first scan class. Similarly, all points
that have Location4 set to 2 will receive input values at the
frequency specified by the second scan class, and so on.
Two scan classes are defined in the following example:
/f=00:01:00,00:00:05 /f=00:00:07
or, equivalently:
/f=60,5 /f=7
The first scan class has a scanning frequency of 1 minute with
an offset of 5 seconds, and the second scan class has a
scanning frequency of 7 seconds. When an offset is specified,
the scans occur at discrete moments in time according to the
formula:
scan times = (reference time) + n(frequency) + offset
where n is an integer and the reference time is midnight on the
day that the interface was started. In the above example,
frequency is 60 seconds and offset is 5 seconds for the first
scan class. This means that if the interface was started at
05:06:06, the first scan would be at 05:06:10, the second scan
would be at 05:07:10, and so on. Since no offset is specified
for the second scan class, the absolute scan times are
undefined.
The definition of a scan class does not guarantee that the
associated points will be scanned at the given frequency. If the
interface is under a large load, then some scans may occur late
or be skipped entirely. See the section called “Performance
Point Configuration” for more information on skipped or
missed scans.
Wall Clock Scheduling
Scan classes that strictly adhere to wall clock scheduling are
now possible. This feature is available for interfaces that run
on NT and/or UNIX. Previously, wall clock scheduling was
possible, but not across daylight savings time. For example,
/f=24:00:00,08:00:00 corresponds to 1 scan a day
starting at 8 AM. However, after a Daylight Savings Time
change, the scan would occur either at 7 AM or 9 AM,
depending upon the direction of the time shift. To schedule a
scan once a day at 8 AM (even across daylight savings time),
one should use /f=24:00:00,00:08:00,L. The ,L at the
end of the scan class tells UniInt to use the new wall clock
scheduling algorithm.
/output=filename The /output flag specifies the name of the output log file
where error messages will be sent. filename can be a full path
Optional, but Recommended
name or a relative path name to an output file. The interface
Default: assumes that the sinet.cfg and sinet.ini files reside in the same
50
Parameter Description
/output=C:\sinet5.log directory that the output log file is located.
Examples:
/output=.\sinet5.log
/output=sinet5.log
/output=c:\pipc\interfaces\sinet5.log
In the third example above, if the c:\pipc\interfaces directory
does not exist, the program will not be able to open the
sinet5.log file, and the interface will abort upon startup.
Likewise, if the /output flag is omitted and the computer does
not have a c: drive, then the interface will not be able to
create the default log file, c:\sinet5.log, and the interface will
abort upon startup.
For interfaces that are run as a service, one should use an
unambiguous full path name to point to the output log file.
In the above examples, if the sinet5.log file already exists in
the target directory, the interface will rename the existing log
file to sinet5.log;1, unless sinet5.log;1file already exists, at
which point the file will be renamed to sinet5.log;2, and so
on.
Since NT does not recognize file extensions of the form
“.log;n”, the logassoc.bat file can be run to associate
extensions from .log;1 to .log;29 with text files.
/host=host:port The /host flag is used to specify the PI Home node. host
is the IP address of the PI Sever node or the domain name of
Optional
the PI Server node. port is the port number for TCP/IP
communication. The port is always 5450 for a PI 3 Server and
545 for a PI 2 Server. It is recommended to explicitly define
the host and port on the command line with the /host flag.
Nevertheless, if either the host or port is not specified, the
interface will attempt to use defaults.
Defaults:
The default port name and server name is specified in the
pilogin.ini or piclient.ini file. The
piclient.ini file is ignored if a pilogin.ini file is
found. Refer to the PI-API Installation Instructions manual
for more information on the piclient.ini and
pilogin.ini files.
Examples:
The interface is running on a PI-API node, the domain name
of the PI 3 home node is Marvin, and the IP address of Marvin
is 206.79.198.30. Valid /host flags would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
Parameter Description
/stopstat If the /stopstat flag is present on the startup command
or line, then the digital state I/O Timeout will be written to each
/stopatat= PI Point when the interface is stopped.
digstate
If /stopstat=digstate is present on the command line,
Default: then the digital state, digstate, will be written to each PI
/stopstat= Point when the interface is stopped. For a PI 3 Server,
”Intf shut” digstate must be in the system digital state table. For a
Optional PI 2 Server, where there is only one digital state table
available, digstate must simply be somewhere in the
table. UniInt uses the first occurrence in the table.
If neither /stopstat nor /stopstat=digstate is
specified on the command line, then no digital states will be
written when the interface is shut down.
Examples:
/stopstat=”Intf shut”
The entire parameter is enclosed within double quotes when
there is a space in digstate.
/ec=x The first instance of the /ec flag on the command line is used
to specify a counter number, x, for an I/O Rate point. If x is
Optional
not specified, then the default event counter is 1. Also, if the
/ec flag is not specified at all, there is still a default event
counter of 1 associated with the interface. If there is an I/O
Rate point that is associated with an event counter of 1, each
copy of the interface that is running without /ec=x explicitly
defined will write to the same I/O Rate point. This means that
one should either explicitly define an event counter other than
1 for each copy of the interface or one should not associate
any I/O Rate points with event counter 1. Configuration of I/O
Rate points is discussed in the section called “I/O Rate Tag
Configuration,” p. 41.
For interfaces that run on NT nodes, subsequent instances of
the /ec flag may be used by specific interfaces to keep track
of various input or output operations. One must consult the
interface-specific documentation to see whether subsequent
instances of the /ec flag have any effect. Subsequent
instances of the /ec flag can be of the form /ec*, where * is
any ASCII character sequence. For example, /ecinput=10,
/ecoutput=11, and /ec=12 are legitimate choices for the
second, third, and fourth event counter strings.
52
Parameter Description
/sio The /sio flag stands for “suppress initial outputs.” The flag
applies only for interfaces that support outputs. If the /sio
Optional
flag is not specified, the interface will behave in the following
manner.
When the interface is started, the interface determines the
current Snapshot value of each output tag. Next, the interface
writes this value to each output tag. In addition, whenever an
individual output tag is edited while the interface is running,
the interface will write the current Snapshot value to the
edited output tag.
This behavior is suppressed if the /sio flag is specified on
the command line. That is, outputs will not be written when
the interface starts or when an output tag is edited. In other
words, when the /sio flag is specified, outputs will only be
written when they are explicitly triggered.
/q When the /q flag is present, Snapshots and exceptions are
queued before they are sent to the PI Server node.
Optional
The maximum queue size is 255 bytes for a PI 3 Server and
36 bytes for a PI 2 Server. For example, if the interface is
running on a UNIX node and is communicating to a PI 2
Server, then the maximum queue size is 36. The queue is
flushed between scans if it is not filled.
When the /q flag is specified in non-extended API mode, the
PI-API sends integer values as 16-bit integers instead of 32-bit
integers. Therefore, integer points will be limited to values
between 0 and 32767. Values higher than 32767 need to be
sent to floating-point PI tags.
54
Interface Node Clock
The correct settings for the time and time zone should be set in the Date/Time control
panel. If local time participates in Daylight Savings, from the control panel, configure the
time to be automatically adjusted for Daylight Savings Time. The correct local settings
should be used even if the interface node runs in a different time zone than the PI Server
node.
Make sure that the TZ environment variable is not defined. The currently defined
environment variables can be listed by going to Start | Settings | Control Panel, double
clicking on the system icon, and selecting the environment tab on the resulting dialog box.
Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the
TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being
defined in the System control panel even though the variable is defined. Admittedly,
autoexec.bat files are not typically used on NT, but this does not prevent a rogue user
from creating such a file and defining the TZ variable unbeknownst to the System
Administrator.
A message will be echoed to the screen informing the user whether or not the interface has
been successfully started as a service. Even if the message indicates that the service started
successfully, make sure that the service is still running by checking in the services control
panel. There are several reasons that a service may immediately terminate after startup .
One is that the service may not be able to find the command-line arguments in the
associated .bat file. For this to succeed, the root name of the .bat file and the .exe file
must be the same, and the .bat file and the .exe file must be in the same directory. If the
service terminates prematurely for whatever reason, no error messages will be echoed to
the screen. The user must consult the pipc.log file for error messages. See the section
“Appendix A: Error and Informational Messages,” for additional information.
Service Tab
The Service tab allows for some API Buffering service configuration. For further
configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is
dependent.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API
Buffering. Default values are used if no other value is provided.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server
(milliseconds). Default value is 100. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click
the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before
attempting to send more data to the home node. Default value is 2. Range is 0 to
2,000,000.
The Use Default button places the default value into the text box. To keep this value, click
the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number
of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click
the Apply button.
Note: When buffering is configured to be on, the bufserv process must be started
before other programs using the PI-API, so that these programs can access the shared
buffering resources. Any program that makes a connection to a PI Server has this
requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file
is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under
Windows NT. This file follows the conventions of Microsoft Windows initialization files
with sections, keywords within sections, and values for keywords. All buffering settings
are entered in a section called [APIBUFFER]. To modify settings, simply edit the
piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:
Keywords Values Default Description
BUFFERING 0,1 0 Turn off/on buffering. OFF = 0, ON = 1,
PAUSERATE 0 - 2,000,000 2 When buffers are empty the buffering process
will wait for this long before attempting to
send more data to the home node (seconds)
RETRYRATE 0 - 2,000,000 120 When the buffering process discovers the
home node is unavailable it will wait this
long before attempting to reconnect (seconds)
MAXFILESIZE 1 - 2,000,000 100,000 Maximum buffer file size before buffering
fails and discards events. (Kbytes)
MAXTRANSFEROBJ 1 - 2,000,000 500 Maximum number of events to send between
S each SENDRATE pause.
BUF1SIZE 64 - 2,000,000 32768 Primary memory buffer size. (bytes)
BUF2SIZE 64 - 2,000,000 32768 Secondary memory buffer size. (bytes)
SENDRATE 0 - 2,000,000 100 The time to wait between sending up to
MAXTRANSFEROBJS to the server
(milliseconds)
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define
the default PI server and an optional time offset change that may occur between the client
and server.
64
Keywords Values Default Description
PIHOMENODE string none Windows default server is in
pilogin.ini
DSTMISMATCH 0 - 2,000,000 0 The time that the server and client local
time offset is allowed to jump.
Typically, 3600 if the nodes are in time
zones whose DST rules differ (seconds)
General
A string NameID is pre-pended to error messages written to the message log. Name is a
non-configurable identifier that is no longer than 9 characters. ID is a configurable
identifier that is no longer than 9 characters and is specified using the /id flag on the
startup command line.
PIPC.log File
Messages are written to PIHOME\dat\pipc.log at the following times.
When the interface starts many informational messages are written to the log.
These include the version of the interface, the version of UniInt, the command-line
parameters used, and the number of points.
As the interface retrieves points, messages are sent to the log if there are any
problems with the configuration of the points.
If the /db is used on the command line, then various informational messages are
written to the log file.
Messages
Error messages that are associated with the Send/Receive function calls of the interface
can be categorized as follows:
GetLastError
Error messages that begin with GetLastError= are system errors that occur before any
message can actually be sent to or retrieved from the PLC. For example, if the name of
the access point is misspelled in the sinet.ini file, then the interface will not be able to
establish the network card of interest as an access point and the appropriate GetLastError
code will be displayed.
RB_RESPONSE
Error messages that begin with RB_RESPONSE= may occur due to configuration problems,
such as specifying improper network addresses or TSAP names in the sinet.cfg file.
BYTE8
Error messages that begin with BYTE8= are similar to an RB_RESPONSE code in that a
message was retrieved from the PLC, but there was some communication problem.
Bad Input
If the status of a value derived from the PLC is BAD, then BAD INPUT will be written to
the PI tag.
I/O Timeout
If there are connection problems to the PLC, then I/O Timeout will be written to all the
input PI tags.
Troubleshooting
RB_RESPONSE=16 with CP1413 Card
The symptoms at this time were:
1. After rebooting the S5 some number of times the cp1413 would start communication
with the interface again. It didn't matter if the reboot was a cold, worm, or just a reset
of the Ethernet card. What mattered was the time it took.
2. 2. If the communication was established I could stop the interface for a few seconds
and then restart it and communication would resume. If I stopped the interface for a
few minutes the communication would not resume.
3. In the sinet.log file after the message RB_RESPONSE=16 there were a series of
messages:
4. Wed May 16 13:24:50 2001 DB[1]: connection opened, VCID: 849
Wed May 16 13:26:55 2001 DB[1]: connection opened, VCID:
1105
Wed May 16 13:29:00 2001 DB[1]: connection opened, VCID:
1361
Wed May 16 13:31:05 2001 DB[1]: connection opened, VCID:
1617
Wed May 16 13:33:10 2001 DB[1]: connection opened, VCID:
1873
Wed May 16 13:35:15 2001 DB[1]: connection opened, VCID:
2129
This is the interface trying to reconnect though the cp. The problem is cp1413 is still
holding the old connection open.
SR Trace
Messages from the interface can be monitored by turning on SR Trace. The trace is turned
on from the control panel under Setting the PG/PC interface. While collecting a trace, the
only 1 tag should be loaded for the interface and the interface should be run for a short
period of time to keep the trace small. Otherwise, very large trace files will be generated.
Error Descriptions
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
Make sure both configurations (PC and PLC) are identical for TSAPs and Ethernet
(MAC) addresses:
If an incorrect Ethernet address or TSAP address is configured for the remote node (the
interface node in this case), the PLC will reject communication with an error of
RB_RESPONSE=22. For this reason, a very good option is to use fully unspecified
communication. To use unspecified communication, enter all zeros for the remote
Ethernet address and all zeros for the remote TSAP. With fully unspecified
communication, the interface can connect to the PLC from any node. Partially unspecified
communication is when all zeros are entered for either the remote Ethernet address or the
remote TSAP address, but not for both.
Unfortunately, it is also possible to get an RB_RESPONSE=22 if the control panel
configuration under "Setting the PG/PC Interface" is not set correctly. When one brings
up the control panel, one should make sure that the correct Ethernet card and access point
is highlighted at the time that the control panel is opened (before one types or clicks on
anything). If not, the control panel configuration may be the problem. The access point in
the control panel must match the access point in the sinet.ini file.
TI505 PLCs
The interface can communicate to TI505 PLCs only across an ISO industrial Ethernet
(H1). Although TI505 PLCs can communicate via RFC1006 TCP/IP with the use of a
CP2572 Ethernet adapter, the TI505 PLCs cannot understand the read/write messages that
are sent by interface.
S5 and S7 PLCs
The interface can communicate to S5 and S7 PLCs across an ISO industrial Ethernet.
Theoretically, the interface can also communicate to S5 and S7 PLCs across a TCP/IP
Ethernet by means of RFC1006 TCP/IP. However, the interface has not been tested with
TCP/IP.
Individual Writes
If one wishes to write the value 10 to V memory location 31 in logical PLC 1 for interface
1, one needs to define an output tag and a trigger tag (SourceTag as shown in the tables
below.
To write a value of 10 to the PLC, a value of 10 must be written to the SourceTag. In this
example, the SourceTag happens to be a “laboratory” tag, which simply means that the
PointSource is L for the SourceTag. For the beginner, it may not be obvious how to write a
value to a laboratory point. The PI-API is one option (the PI-API is OSI’s application
programming interface). The SourceTag could have easily have been a calculation tag
(PointSource C) or a Tag for the Siemen’s Simatic Net interface itself (Pointsource S).
Hence, one should not be overly concerned with writing values to laboratory points at this
juncture. The important thing to note is that whenever a new value is written to the
SourceTag, this value is also written to the PLC.
SourceTag Configuration
Attribute Value Description
Tag Source1.tag The name of the trigger tag
PointType Float32 See the description of the PointType attribute.
PointSource L Any PI Point can serve as the trigger tag. A
“laboratory” point (PointSource L) was chosen for
this example. One could just have easily chosen a
calculation point (PointSource C) or a point from
the Siemen’s Simatic Net Interface itself
(PointSource S). The advantage of using a
calculation point is that the PE Scheduler can be
used to periodically write a value to the trigger tag.
84
Appendix G
Tracing Send/Receive Messages
It is possible to trace the send/receive messages that the interface uses. This may be useful
for debugging purposes, but it is not desirable to have tracing on during normal interface
operation because tracing will have a detrimental effect on performance. The following
screen shots demonstrate how tracing can be turned off or on for the interface.
Select Setting the PG/PC Interface from Control Panel
Select Diagnostics
We usually put the distribution files in the i386 folder on one of the local disks.
Select OK to continue.
Select Test.
Test in progress...
94
Successfully completed test. Select OK.
96
Select "all adapters" under the Show Bindings for box.
Disable TCP/IP, etc. on the new card if used for Siemens PLC access.
98
Siemens SIMATIC NET Interface to the PI System 99
Appendix I: Configuring a Second Ethernet Card
100
Once placed in the CD drive, the Simatic Net Software Autorun will display this screen.
Select "Install Software SIMATIC NET"
Select Next
102
Siemens SIMATIC NET Interface to the PI System 103
Appendix I: Configuring a Second Ethernet Card
104
Select "IE SOFTNET-S7 EXT" or "IE SOFTNET-S7 BASIC" as appropriate to the
license purchased.
106
It is best to just select Done, and restart Windows manually.
Open the Control Panel, then the "Setting the PPPG/PC Interface" control panel.
108
Select "Install"
Select "Add"
110
We usually put the distribution files in the i386 folder on one of the local disks.
Once it is done, you will be back in the Network control panel. Select "Bindings".
112
If you are running multiple Ethernet cards, select the card(s) that will NOT be used for
Siemens PLC access and expand the view (+). Select "SIEMENS Industrial Ethernet
(ISO)", then "Disable"
Once disabled on the Ethernet adapter not connected to the PLC network, select close.
114
After the reboot, open the Control Panel, then the "Setting the PPPG/PC Interface" control
panel.
116
Select "ISO Ind. Ethernet..." in the Module Parameter Set Used box.
Select (highlight in blue) S7ONLINE in the Access Point of Application box. Next, select
Diagnostics.
118
Select Test under the "SOFTNET IE" tab.
120
Revision History
Date Author Comments
98 BB initial draft
29-Jul-99 AS changes for S5
21-Oct-99 GWM Changes for release of 1.3.5
27-Dec-99 GWM Connection should be active, static for 1434 card.
19-Apr-00 AS RBYTE, LBYTE and MASK for S5. CP 1613
15-Apr-02 BP Changes for release 1.4.2 – string support for 505
29-May-02 CG Skeleton 1.11; added ICU control
30-May-02 BP Update for 1.4.2
06-Jun-02 BP/AS Updated S7<as> and ICU bufserv section <bp>
10-Jun-02 HAB Updated with current ICU control (1.4.2, doc rev A)