Set Up the OSI Agent

6 min

Review the following information for setting up and configuring the OSI Agent driver.

Before You Begin

Install an OSI Server and OSI Agent on a Windows system.
Follow up with your account executive to download the OSI Agent and required files.
Make sure the OSI Client dll is on the same system running the OSI Agent.
Open port 443 and 4777 between Windows and Manufacturing Connect Edge. Otherwise, the OSI Agent won't work.
Configure Windows authentication so that the OSI Pi Server can work.
Create API Credentials in Manufacturing Connect Edge.

Step 1: Install OSI Agent

Install the ZIP file with the OSI Agent and all required files on a Windows system.

Step 2: Run and Configure the DH Historian Agent

To run and configure the DH Historian Agent:

Run the DH Historian Agent EXE file. A Windows service starts and connects to the OSI Agent so that it can collect data from the OSI Agent.
Review the introductory screen and click Next. The appearance configuration settings displays.
Agent introductory screen
Configure the appearance settings.
Agent appearance settingss
Click Save, and then Next. The Server Settings section displays.
Sever settings
In the PI Server section, click the Load PI Servers button. You will be able to view all PI servers properly set up with DCOM rules on the correct network.
Open the drop-down list for Server to view accessible servers and select the appropriate server.
Select an authentication method.
- PI User: This is local user. To define the DCOM rules for this user, open the PI System Management Tool and navigate to Security > PI Users and Groups. Enter the correct username and password.
- Windows: The PI Server needs to be properly configured to use Windows authentication.
Once the PI Server is configured, click Test Connection. Verify the status is Success or Fail.
In the Operation Mode section, select how data will be collected. Both modes allow the first value on startup to get published to NATS.
- Events-Based: The recommended selection. Whenever the value changes on the PI server, you will receive a NATS message.
- Polling: Define the polling interval in seconds. The timestamp for the message is when the data was published to the DH Historian Agent, not when Manufacturing Connect Edge collects the data.
In the Logs section, select how to view logs. The logs will records failures with details.
- Events Log: To view logs, start the OSI Agent.
- Log file folder: Define a local folder to store log files.
Click Save, and then Next. The Site Settings section displays.
Site settings
Configure the site settings.
- Host: Enter the IP address for the Manufacturing Connect Edge instance.
- Port: Enter 4777.
- User: Enter the username to connect to the server in DeviceHub.
- Password: Enter the password to connect to the server in DeviceHub.
- API Token: Follow the steps to Create API Credentials, copy the token, and paste it here. The token is used to create the device and tags.
- Device Name: Enter the name for the device that will be created in Manufacturing Connect Edge DeviceHub.
- Device Id: This field is optional. The ID is automatically generated.
Click Test Connection to ensure the settings are configured correctly.
Click Create Device. If a device is successfully created, a Created a new Device message will display. The OSI Agent driver device will be created in the Manufacturing Connect Edge DeviceHub pane.
Click Save, and then Next. The Tags section displays.
Tags settings
Search for tags you want to add.
- You can search by using regular expression.
- The * character displays all tags on the server.
- The Server Tags column displays tags on the OSI Agent.
- The Agent Tags column displays tags that will be sent to Manufacturing Connect Edge and mapped to the OSI Agent driver device in DeviceHub.
After selecting tags to be sent to Manufacturing Connect Edge, click Update Tags. The tags will be added to the OSI driver in Manufacturing Connect Edge. You can view them in DeviceHub > Tags.
If needed, click Save. This saves the settings in the DeviceHubAgentMain.UI.exeConfig file, which is a password encrypted text file. The next time you start the Historian Agent, the saved settings from the configuration file will load.
In the folder that installed the DH Historian Agent, navigate to the PI Agent sub-folder.
Double-click the DeviceHubAgentSvc.exe file. This will enable the connection to the server.
Follow the command to install the service. Once installed and the task management is properly set up to run the service when logged off, data will still be sent to the driver when users are logged out.
Log in to Manufacturing Connect Edge and navigate to DeviceHub > Devices. You should see a Connected status for the OSI Agent device.

OSI Agent Driver Settings in Manufacturing Connect Edge

If you review or edit the settings of the OSI Agent device, refer to the following parameters.

Parameter	Value
Type	OSI
Driver	OSI Agent
Network Port	The port configured in the DH Historian Agent. The default value is 4777.
Interface	You have the option of selecting the interface for accepting client connections. The default value is 0.0.0.0, which means using all network interfaces for accepting connections from clients.
User	The username configured in the DH Historian Agent.
Password	The password configured in the DH Historian Agent.

Tag Parameters in Manufacturing Connect Edge

If you Add Tags in Manufacturing Connect Edge, select the R register name, and then refer to the following supported data types and tag parameters.

uint32
uint64
float64
string
byte[]
float32[]
bool
byte
float64[]
string[]
uint16
int64
uint16[]
sbyte
int16
int16[]
int32[]
int64[]
uint64[]
float32
bool[]
uint32[]
int32
sbyte[]

Tag Parameters

Name: Select R.

Value Type: Select a value type.

Tag Name: Enter a name for the tag.

Description (Optional): Enter a description for the tag.

Tag Formula: Enter a formula for the tag to process the generated data. Two variables are permitted: value (current tag value) and timestamp (current tag UNIX time in milliseconds). The following math functions are available:

sqrt

power: power(x) performs the operation 10^x.

log: log(x) is the natural logarithm (the logarithm is in base e).

exp: exp(x) performs the operation e^x.

Only Publish on Change of Value: Select the checkbox to customize NATS messages to be published only when the value parameter changes from a previous value to a new one. Change of Value only applies to boolean, numeric (such as int or float), and simple string data types. It does not apply to complex types, such as JSON or array. Poll-once topics will not be affected by Change of Value settings. These topics will still only see a single message.

Meta Data: Metadata summarizes basic information about data. This feature allows you to define key-value pair data for the device output payload later on. It can then be used to find, use, and reuse particular instances of data.

Note: If you use special characters in meta data key names, the special characters are replaced with underscore characters in the payload. This can cause two key names to be combined into one. For example, configuring the key names a**b and a&&b will cause only one key name to be created (a__b).