The new PowerShell Tools for the PI System have been released! These PowerShell cmdlets are installed with the PI System Management Tools 2015 (220.127.116.11). You might recall that we had a CTP release (version 18.104.22.168) 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!
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
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:
You should see your %pihome% directory listed.
To confirm that the OSIsoft.PowerShell module is imported in the current session, run
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.
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:
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
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
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.
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:
- Get-Content "Rhys' PI and PowerShell mash up" -Filter "Section='Connections'" | Set-Content "Part 1 Blog Post"
- PowerShell to the rescue; solving the PI Server Archive Management shortcomings
- How to retrieve connection statistics from the PI Server message log using PowerShell Tools for the PI System
- The specified item was not found.
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.