Getting started¶
Requirements¶
- Any supported Milestone XProtect VMS product and version. See Compatibility.
- Windows PowerShell 5.1.
- .NET Framework 4.7.2 or later.
Info
- Some features in MilestonePSTools rely on specific VMS editions. For example, creating evidence locks requires that you are connected to Milestone XProtect Corporate.
- Some MilestonePSTools features may work on XProtect versions as old as 2014. However, our priority is to ensure compatibility with supported XProtect versions which typically includes all versions released in the last 3 years.
- To check your PowerShell version, open PowerShell and type
$PSVersionTable
. The PSVersion value is your PowerShell version. - If you have an earlier version of PowerShell, you may need to install Windows Management Framework 5.1.
- MilestonePSTools cannot be used on PowerShell Core or PowerShell 7+. However, if you use a newer version of PowerShell for other tasks, you can still use Windows PowerShell 5.1 on the same computer providing it is a Windows operating system.
Installation¶
All users¶
- Requires Administrator privileges and installs the module to the
C:\Program Files\WindowsPowerShell\Modules
directory.
Current user¶
- Installs the module to
Documents\WindowsPowerShell\Modules
for the current user.
Quick Install¶
There are a few common errors you may see when installing or using a PowerShell module for the first time on some Windows versions. The following quick-install script attempts to address these automatically for a quick and easy installation on an internet-connected system. It will download and run install.ps1, and as with any script on the Internet, we encourage you to inspect it and understand what it does before you copy and paste anything into a PowerShell terminal.
Set-ExecutionPolicy RemoteSigned -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; Invoke-Expression (Invoke-RestMethod 'https://www.milestonepstools.com/install.ps1')
Tip
MilestonePSTools does not need to be installed on the Milestone XProtect Management Server. Nearly every command in the module is designed to connect to your VMS the same way XProtect Smart Client and Management Client do.
Manual¶
Follow the steps below if you do not have internet access on the computer where MilestonePSTools will be used.
First, try using the Save-Module
PowerShell command on an internet-connected Windows computer. If this works for you,
you can skip ahead to step 3.
- Make sure to create the
C:\temp
directory first, or use a path to a folder that already exists.
Step 1: Download the raw nupkg file¶
Visit PowerShell Gallery and click Manual Download under Installation Options, then click Download the raw nupkg file.
Step 2: Extract the contents¶
Nupkg files are actually ZIP files. Add the .zip
extension to the file you
downloaded and you can view/extract the contents. Here's what the contents look like for MilestonePSTools...
Tip
Before you extract the ZIP file, make sure to right-click on it and open Properties. If you see a checkbox to "unblock" the files, you should do this before extracting them. Otherwise each individual extracted file will need to be unblocked later.
A quick way to unblock all files under a directory is to use...
Step 3: Copy to the destination¶
After you extract the files for the module, the best place to put them is in one of the locations PowerShell
automatically looks for PowerShell modules. If you install the module for just you, then you should place the module
in your Documents directory under Documents\WindowsPowerShell\Modules
. If the folder(s) do not exist, you may create
them.
Alternatively if you want to make the module available to any user on the local machine you can place them in
C:\Program Files\WindowsPowerShell\Modules
.
Tip
To see where Windows PowerShell will look to auto-import modules in your environment, type
The structure for the Modules folder is that the first level includes a folder matching the name of the module, and the
subfolder contains one or more versions of that module where the name of the folder matches the exact version of the
module as defined in the *.psd1
file inside that folder.
In the example below, we have MilestonePSTools version 24.1.9, and inside that folder are the contents from the screenshot above.
Once you have the modules extracted and placed in the right location, you should be able to run
Import-Module MilestonePSTools
and it will be loaded into your PowerShell session. If you get an error message, check
out this blog post to see if we've already shared some tips on how to handle it.
Compatibility¶
According to the Milestone Product Lifecycle, XProtect VMS releases are typically supported for 3 years before being discontinued. As such, our ability to support MilestonePSTools depends on using a supported version of XProtect.
In the following table you'll find the VMS versions and the most recent version of MilestonePSTools that should be compatible with that VMS version.
XProtect VMS Version | Latest Compatible Module | Date Published | Supported |
---|---|---|---|
XProtect 24.1 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 23.3 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 23.2 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 23.1 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 22.3 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 22.2 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 22.1 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 21.2 | MilestonePSTools 24.1.9 | 2024-08-21 | Yes |
XProtect 21.1 | MilestonePSTools 23.3.51 | 2024-06-22 | No |
XProtect 20.3 | MilestonePSTools 23.2.3 | 2023-10-11 | No |
XProtect 20.2 | MilestonePSTools 23.2.3 | 2023-10-11 | No |
Usage¶
There are over 270 commands in this module and a wide variety of tasks you may like to automate. Here are a few commands
to help get you started. See the command index for a list of available commands, or run
Get-Command -Module MilestonePSTools
to show a list of commands in your PowerShell terminal.
Note
All Get-
commands are safe to use and will not change the state of your XProtect VMS. Most commands which do
change state in a potentially destructive way include support for the -WhatIf
parameter which does not normally
result in actually performing that action. Commands like Remove-VmsHardware
which, by design, will result in the
loss of video, usually require manual confirmation from the user by default.
Get connected¶
- Connecting without specifying
-ShowDialog
or-ServerAddress
will automatically log you into thedefault
connection profile, or prompt you with a login dialog and save those credentials to re-use in the future. - Using
-ShowDialog
will always bring up an interactive login dialog, and the login information will not be saved for later use.
Note
The -AcceptEula
switch is required only the first time you use Connect-Vms
or Connect-ManagementServer
. After
that, a flag is set in %appdata%\MilestonePSTools
.
List all enabled cameras¶
- If you want to retrieve all cameras and not only the enabled ones, use
Get-VmsCamera -EnableFilter All
.
Save a camera report to a CSV file¶
Export hardware to Excel¶
- Microsoft Excel does not need to be installed to export or import using an
.xlsx
file. However, you may also like to export hardware to a more simple CSV file, and that can be done with the same command - just use a.csv
extension instead of.xlsx
.
Import hardware configuration changes¶
Frequently asked questions¶
Can I use a new MilestonePSTools version on an old version of Milestone?¶
Yes. You can typically always use a newer "client" on an older VMS, however there is a limit to the backward compatibility testing performed by Milestone.
Since MilestonePSTools operates the same as a Milestone client application, you should expect to see a similar level of backward compatibility. However, it is possible that some features of this module will require a newer version of the Milestone XProtect Management Server. We will do our best to make it clear in the documentation, and error messages, when you might expect to find an incompatibility.
Can I use an older MilestonePSTools version on a newer version of Milestone?¶
Yes. Milestone Systems makes a significant effort to ensure a level of forward and backward compatibility, and most of the time you may use an older client application to connect to a newer server. Most of the time there is no change in user experience, though there have been a small number of exceptions.
One notable exception is when new encryption options were introduced for client communication with XProtect recording servers. If encryption was enabled on the recording server(s), client versions released prior to the introduction of this feature would be unable to communicate with those recording servers.
Since Milestone can not guarantee forward compatibility of client applications and the MIP SDK, neither can MilestonePSTools promise to always work against newer versions of the Milestone XProtect VMS.
Can I perform the "Replace Hardware" action?¶
As of Milestone XProtect VMS version 2023 R1 (23.1.1), Yes! Sometimes it's necessary to perform the Replace Hardware action in Management Client to either update the properties and features of a camera after a device pack or firmware upgrade, or change the driver used for the camera to take advantage of a new driver.
If you're running Milestone XProtect Management Server version 2023 R1 or later,
and MilestonePSTools version 23.1.1 or later, then you can use the
Set-VmsHardwareDriver
command to run a simplified implementation of the replace-hardware wizard from
Management Client.
If you're using a Milestone VMS version released prior to 2023, then as soon as you upgrade your Management Server to at least 2023 R1, you can take advantage of this feature.
Can I add cameras that are not on the network?¶
No. The MIP SDK, and really the core Milestone XProtect VMS platform does not support the ability to add devices unless network communication with the device is possible from the recording server service to which you are adding the camera. So even with MilestonePSTools, the device(s) must be online in order to add them to a recording server.
There are a few reasons this would be challenging to architect at this stage. One such reason is that the Milestone Device Pack drivers support the concept of "dynamic events" and "dynamic channels". This means that until we talk to the camera, we don't know all of the available edge-based events or the number of camera, microphone, and other device channels to expect.
One possible workaround for relatively basic use cases is to use the universal
driver to add a non-existant camera. You could then configure the name of the
hardware and channels, the permissions, and create views. Then, later, you
could edit the IP address and credentials, then right-click on the hardware in
Management Client and click "Replace hardware", or use the Set-VmsHardwareDriver
command to change the hardware driver and optionally the address and credentials
once the cameras are online.
Why are some commands prefixed with "VMS"?¶
The MilestonePSTools project began in 2019 by an engineer with no prior experience building PowerShell modules. Over time, it became clear that some command names had the potential to collide with commands available in other modules. For example, "Get-VmsHardware" is so generic that there could easily be another unrelated PowerShell module with the same command.
PowerShell module authors are recommended to prefix the "nouns" in their cmdlet names with a short string to minimize the chance of colliding with other modules. We chose to use "VMS", which is short for Video Management System, or Video Management Software.
All new commands should use the new "VMS" prefix. The future for old commands is not yet decided. We can't broadly apply the prefix to all commands due to the risk of breaking any automation setup by customers using the module. Perhaps we'll apply the prefix to all commands, and add aliases for the old command names? If you have suggestions for how to address this with minimal impact to current users, please feel free to contribute to a discussion on GitHub!