The new PowerShell Tools for the PI System have been released! These PowerShell cmdlets are installed with the PI System Management Tools 2015 (3.5.1.7). You might recall that we had a CTP release (version 1.1.0.0) a few years ago, available only to vCampus members. The current version is a rewrite of the previous release, and offer many functional and performance enhancements over the CTP version. It is also available to all licensed customers and PI DevClub members.

 

These PowerShell Tools are designed to provide PI System Administrators the ability to create reusable scripts for common or bulk system management operations. While it is not primarily a data access tool, I will be testing out some data read and write operations to get familiar with the new tools. I am by no means a PowerShell expert: the purpose of the blog post is to bring awareness to the tools available and offer a quick start guide to anyone who is interested!

 

Getting Started

Before we start, please note that PowerShell Tools for the PI System requires Windows PowerShell 4.0 (see release notes). You can check your PowerShell version by running

$PSVersionTable.PSVersion

 

After an installation or upgrade to PI SMT 2015, the PowerShell tools are available as a PowerShell module named OSIsoft.PowerShell. Beginning in Windows PowerShell 3.0, modules are automatically imported when you use a command in the module. Since it is no longer provided as a PSSnapin as in the CTP version, there is no need to calll Add-PSSnapin. This version of the PowerShell Tools is installed in %pihome%\OSIsoft.PowerShell. The path should already been added to the PSModulePath environment variable:

$env:PSModulePath

 

You should see your %pihome% directory listed.

 

To confirm that the OSIsoft.PowerShell module is imported in the current session, run

Get-Module

and look for OSIsoft.PowerShell under the name column. However, the OSIsoft.PowerShell module will only show up if a command in the module has previously been used in the session. If you don't see OSIsoft.PowerShell module in the list, run a command (e.g. Get-Command -Module OSIsoft.PowerShell) and then run Get-Module to check again.

 

To get a list of all the cmdlets available in the OSIsoft.PowerShell module:

Get-Command -Module OSIsoft.PowerShell

 

From the resulting list, you might have noticed that there are no cmdlets available to access PI AF (which were previously included in the vCampus CTP version). The AF cmdlets are actively being developed now and are planned for inclusion in the next release. For more information, please refer to KB01248.

Note: AF Server support to PowerShell Tools for the PI System has been added in the SMT 2015 R2 release!

 

To get the description and example for specific cmdlets, run the Get-Help cmdlet. E.g.

Get-Help Connect-PIDataArchive

 

You can specify specific information to obtain in Get-Help by supplying different parameters (e.g. -examples, -full, etc.).

 

Connecting to the PI Data Archive

First, let's create a connection to the PI Data Archive. Let's check out the Connect-PIDataArchive cmdlet:

Get-Help Connect-PIDataArchive

 

DESCRIPTION

    The Connect-PIDataArchive cmdlet allows a connection to be made to the specified PI Data Archive.  A PI Data Archive can be specified by machine name, or entry in the local Known Servers Table.

 

It looks like we can make a connection to the PI Data Archive by name! (You might recall the CTP version requires us to get a PI Server object first.) To see specific examples:

Get-Help Connect-PIDataArchive -Examples

 

Now, let's attempt a connection (make sure you have the appropriate Windows mapping/trust set up):

$myPI = Connect-PIDataArchive -PIDataArchiveMachineName DNG-PI2012

 

$myPI.Connected should return true. We have successfully connected to our PI Data Archive!

 

Getting some values

Next, let’s try to get some values from a PI tag. Let’s see what are the available cmdlets which contain the word “value” as the noun:

Get-Command -Noun *value* -Module OSIsoft.PowerShell

 

CommandType     Name                                          ModuleName

-----------               ----                                               ----------

Cmdlet               Add-PIValue                                  OSIsoft.PowerShell

Cmdlet               Get-PIValue                                  OSIsoft.PowerShell

Cmdlet               Remove-PIValue                            OSIsoft.PowerShell

Ah! Let's use Get-PIValue. (Don't forget to use Get-Help to look for examples if needed!)

 

One way to get the current value of sinusoid:

Get-PIValue -PointName sinusoid -Connection $myPI -Time ([DateTime]::Now)

 

AnnotationHandle :     0

Value                  :     89.76907

TimeStamp          :     7/20/2015 5:45:40 PM

WriteMode           :      NoReplace

UpdateType         :      None

Annotation           :

IsServerError        :      False

IsQuestionable     :      False

IsSubstituted        :      False

IsAnnotated          :      False

IsGood                :      True

StreamId              :      1

Notice that the TimeStamp is displayed as UTC time.

 

As another example, let's get the list of compressed values of sinusoid between 8 am - 5 pm on 7/19/2015:

Get-PIValue -PointName sinusoid -Connection $myPI -StartTime "19-Jul-2015 8:00:00" -EndTime "19-Jul-2015 17:00:00" 

 

To format the results into an easily viewable format, you can append

  • Format-Table; or
  • Select-Object -Property TimeStamp, Value (or Select TimeStamp, Value); etc.

at the end of the command. E.g.

Get-PIValue -PointName sinusoid -Connection $myPI -StartTime "19-Jul-2015 8:00:00" -EndTime "19-Jul-2015 17:00:00" | Select TimeStamp, Value

 

TimeStamp                                                                                                         Value

---------                                                                                                                 -----

7/19/2015 12:37:23 PM                                                                                         0.9707313

7/19/2015 1:42:23 PM                                                                                             3.3811

7/19/2015 2:56:23 PM                                                                                           23.64582

7/19/2015 5:30:23 PM                                                                                            85.4732

7/19/2015 6:39:23 PM                                                                                           99.19289

7/19/2015 7:44:23 PM                                                                                           96.29641

7/19/2015 8:57:23 PM                                                                                            75.9825

Notice that only the TimeStamp and Value columns are display. Again, TimeStamps are in UTC time (I am at UTC-4 right now).

 

Writing some values

Recall that there is a Add-PIValue cmdlet that looks to be suitable for writing values to PI tags.

 

To add a value of 10 to a tag TestTag at current time:

Add-PIValue -PointName TestTag -Value 10 -Connection $myPI

 

By default, the write mode of "append" is used" unless specified otherwise with the -WriteMode parameter. In addition, you can specify the timestamp, or write different values to multiple tags at the same time. The Get-Help examples contain detailed information.

 

Conclusion

Even though this version of the PowerShell Tools is a re-write of the vCampus CTP version, a lot of the cmdlets and parameters are similar. If you are interested, I encourage checking out some excellent blog posts in the past about using the PowerShell Tools to carry out different tasks:

 

If you have already upgraded to PI SMT 2015, test out some of the cmdlets! As always, please leave your comments and feedback

 

Notes (as of Aug 2015)

  • For timestamps, PI relative times (e.g. *) cannot be used.
  • Data writes with Add-PIValue cannot be buffered right now. There is an enhancement request in place to allow buffered writes in a future release.