How to Manage Surface Pro 3 UEFI Through PowerShell
Hi, Kyle Blagg here. I’m a Premier Field Engineer who works with enterprise customers for everything Surface. Recently the Surface Engineering team released a firmware update that enabled some new capabilities in the UEFI that are of significant importance for a lot of customers. We now allow you to enable/disable features like the Front and/or Rear Camera, Wireless, Bluetooth, Network Boot as well as some other nifty features.
If you’re trying to deploy or manage hundreds, thousands or even tens of thousands of Surface Pro 3 devices, the last thing you want to have to do is manually set a password in the UEFI or manually modify those settings for all of your devices. As a result of the Surface Engineering team’s hard work, you can now utilize a Powershell script to control the UEFI settings.
What are the requirements?
First, let’s discuss the requirements:
· Surface Pro 3
· UEFI Firmware v3.11.760.0 (Download Here or download via Windows Update)**
· Surface Pro 3 Firmware Tools MSI (Download Here)
· Administrative Rights on your Surface
** This version of UEFI should already be installed if you use Windows Update. If you use WSUS/SCCM for updates, then you'll need to push out the latest drivers/firmware by using our new MSI (Link)
Now that we know the requirements, now what?
Now let’s get into the details. On our TechNet site (Link) we have some documentation and some sample scripts of how to identify and configure the settings. We’ll cover some of the same information here to provide a good base, but also provide some suggestions to make the process easier.
Before we can leverage any of the PowerShell scripts, we need to install the Surface Pro 3 Firmware Tools MSI on the device that you wish to configure. You can push out that MSI through your normal software distribution processes (i.e. System Center Configuration Manager).
If you’re installing it locally, just continue following through the Install prompts to complete the installation. If you need to do a silent install, you can get the supported switches via command line by running: “Surface Firmware Tool.msi” /? . That will give you all of the options available.
In our example, let's suppose we want to install it silently via command line without the installer forcing a restart.
Now that we have the requirements installed, now what?
Now that we have the Surface Firmware Tool installed, let’s see what we can do with it. Go ahead and open up the Powershell ISE to begin developing your script that we’ll use to configure your Surface Pro 3 devices.
The first thing that we’ll need to do is load the Extension that will allow us to access the UEFI options. We do that by running the command below:
[System.Reflection.Assembly]::Load( "SurfaceUefiManager, Version=1.0.5483.22783, Culture=neutral, PublicKeyToken=20606f4b5276c705" )
If your device is already configured to use an Administrator Password, you’ll need to provide the current UEFI Administrator password. If you don’t have a password currently assigned, then this option will be ignored if you try to run it. You’ll just need to run the line below and substitute 1234 with your currently configured Password.
[Microsoft.Surface.FirmwareOption]::Unlock( "1234" )
At this point, you should now have access to the UEFI via Powershell, but now what? Thankfully, we can now access that information via a simple PowerShell script. If you’ll take a look at the TechNet page, you’ll see a few script samples to give you some ideas of what you can do. One thing that I like to do when scripting in Powershell is creating Functions so it’s easy to execute it on demand. Here’s what that would look like if you decide to go down that road:
Function Get-UEFIOptions
{
# Get the collection of all configurable settings
[Microsoft.Surface.FirmwareOption]::All() | Foreach {
[PSCustomObject]@{
Name = $_.Name
Description = $_.Description
CurrentValue = $_.CurrentValue
DefaultValue = $_.DefaultValue
ProposedValue = $_.ProposedValue
AllowedValues = $_.FriendlyRegEx
RegularExpression = $_.RegEx
}
}
}
If I execute that function in PowerShell, I can get all of the available options and their allowed values. In order to keep things short, I’ve only provided a partial screenshot of the available options.
So how do I interpret the data that it gives me? In the screenshot, you can see an option for Password and TPM. We can see that the allowed values for a Password is that it has to be alphanumeric and must be between 4 and 20 characters in length. TPM can be enabled or disabled by setting the value to either 1 or 0.
Now that we know our options, how do we actually configure the options?
Now that we know what we can set and the values that we need to set, how do we actually set them? I’m glad that you asked. There’s a command for that too. The TechNet article shows you a way of being able to set the password so we’ll leverage that, but what if we want an easy to use Function that we can use for all of the different UEFI Options and minimize the amount of scripting that we have to do. One thing you may notice between my scripts and the sample scripts on the TechNet site is the lack of the loading of the extension and the password as part of the function. That is because those are the first two lines of my PowerShell script. That way those steps are completed as soon as the script is executed rather than be called each time I try to set a setting.
Wouldn’t it be great if you could set the password and other options using a PowerShell function using parameters? Here’s how:
Function Set-UEFISetting
{
param(
[Parameter(mandatory=$true)]$Setting,
[Parameter(mandatory=$true)]$Value)
$UEFISetting = [Microsoft.Surface.FirmwareOption]::Find($Setting)
$UEFISetting.ProposedValue = "$Value"
}
Let’s take a look at what we’re doing. We’ve created a Powershell Function that allows you to set the UEFI options by using Parameters. The function has two parameters that are mandatory in order for the UEFI Options to be set correctly. The first would be the actual name of the Setting and the second would be the Value that you want to Apply. Earlier I showed how to get all of the available options. Once we run that we’ll see that one of the fields returned is Name. That is what we’ll use as the Setting Parameter. One of the other fields returned is Allowed Values, these will be what you’ll use as the Value parameter.
Here’s what it will look like if you want to set many of the current options available on the SP3:
Set-UEFISetting -Setting "Password" -Value "Password"
Set-UEFISetting -Setting "FrontCamera" -Value "00"
Set-UEFISetting -Setting "TPM" -Value "0"
Set-UEFISetting -Setting "PxeBoot" -Value "FE"
Set-UEFISetting -Setting "SideUsb" -Value "FE"
Set-UEFISetting -Setting "DockingPorts" -Value "00"
Set-UEFISetting -Setting "FrontCamera"-Value "00"
Set-UEFISetting -Setting "RearCamera" -Value "00"
Set-UEFISetting -Setting "WiFi" -Value "00"
Set-UEFISetting -Setting "Bluetooth" -Value "00"
Set-UEFISetting -Setting "Audio" -Value "00"
Set-UEFISetting -Setting "SdPort" -Value "00"
Set-UEFISetting -Setting "AltBootOrder" -Value "2"
After you run the commands above, you’ll need to restart for the settings to be applicable. If you accidently apply the wrong setting or need to revert back to the Default Values, there is a sample script on the TechNet page to show how to do that.
So there we have it, an easy to use PowerShell function to be able to modify the UEFI values for the Surface Pro 3. Feel free to add additional logic and/or error handling to your script. Kudos to the Surface team for adding this new functionality.
-Kyle Blagg