Configure the interface with PI ICU

Note: PI ICU requires PI 3.3 or later.

The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (PITCPResp.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the PI Module Database of the destination Data Archive. The procedure below describes the necessary steps for using PI ICU to configure the interface.

1. From the PI ICU menu, select Interface> NewWindows Interface Instance from EXE.

2. Browse to the PITCPResp.exe executable file.

3. Enter values for Host PI Data Server, Point Source and Interface ID#.

   The Configure a New Interface window opens.

   

   Note: PITCPresp1 will add PI- as a prefix to this name and it will be the display name in the services menu.

4. Click Add.

   The PI ICU Register Interface window opens.

   

   Note: In this example, the host Data Archive is JPERRY7910. To configure the interface to communicate with a remote PI Data server, select Connections on the PI Interface Configuration Utility > Interface menu and select the default server. If the remote node is not present in the list of servers, it can be added. Once the interface is added to PI ICU, near the top of the main PI ICU window, the interface type should be <interfacename>. If not, use the drop-down box to change the interface type to <interfacename>.

5. Click Apply.

   The PI ICU gets enabled to manage this instance of the TCPResponse interface and specify the desired scan classes.

   

6. OSIsoft recommends configuring this interface to write the digital state Intf Shut at interface. PI ICU's UniInt tab should look like the following:

   

7. Configure the interface-specific settings on the TCPResponse tab as shown in the following figure.

   

   

   On the TCPResponse Interface-Specific Parameters tab, in the Device Authentication Configuration box, there are two check boxes:

   • Checking the box next to the text Read and encrypt authentication info from file enables the Passord File Edit button which you should click to configure the interface to configures to use the password file, pitcpresp#.password, for authentication and data security information.

   • Checking the box next to the text Delete plain text password file after encryption (start of interface) causes the interface to store the information in the Windows Credential Manager and delete password files when the interface starts. Checking this box is equivalent to specifying -enc in the startup command file.

     Note: # in the password file name is the service ID for the interface.

     The password fie, pitcpresp#.password, is a case-sensitive plain text file. Use the ICU control to invoke the Notepad editor by clicking the Edit button in the Password File box in the TCPResponse Interface-Specific Parameters area of the ICU Control to create or modify the password file. The format of the password files is described in the Web page loading time topic; that information is restated here for clarity.

     The interface supports a user-based security model. You must specify the user name, password and authentication type. User name, password and authentication type are configured as follows:

   • For the web page URL use the keyword device=web page URL. For example: device=www.theWebSite.com/thePage.html

   • For the user name use the keyword user=username. For example: user=theUser;

   • For the password, use the keyword password=mypassword. For example: password=thePassword;

     The password file is best maintained by using PI ICU and the PITCTPResponse ICU Control; the format of this plain text file is as follows:

     # pitcprespinterface service ID.password
     # a '#' indicates a comment line
     # specify a grouping of device, username, and password
     device=www.theWebSite.com/thePage.html
     user=theUser
     password=thePassword
     # for easier legibility, use '#' to separate a group of device,
     # username, password
     device=www.theWebSite.com/thePage.html
     user=anotherUser
     password=anotherPassword
     #
     device=www.company.com/cgi-bin/theApp.exe
     user=user1
     password=passwordForUser1
     # end of pitcprespinterface service ID.password

     Note that a comment line cannot occur within a group of device, username, and password. The following is illegal:

     # Invalid pitcprespinterface service ID.password file
     device=www.theWebSite.com/thePage.html
     user=theUser
     # you cannot have a comment within a grouping
     password=thePassword

     You should also use the -ENC command line parameter, which will cause the interface to store authentication information in Windows Credential Manager and delete password files when the interface starts.

     Note: For authentication, use the keyword auth=authentication type in each PI point's InstrumentTag. For example: auth=NTLM;. The supported authentication types are BASIC and NTLM.

     TCPResponse measures the response times of servers. By default, if a server takes longer than 5000 milliseconds (5 seconds) to respond, the interface writes I/O Timeout to the particular interface point.

     To enable the interface to wait for a different duration, check the Enable wait time box and specify the amount of time, in milliseconds, in the text box. For example, to tell the interface to wait 5 seconds:

     

     The minimum allowable wait time is 100 milliseconds. In addition, a point's non-zero Location3 attribute overrides this wait time parameter for that particular point.

     Note: A yellow field indicates that an invalid value has been entered.