> Configuration > Script Software Repository > Building a Custom Intel® vPro™ Power Control Script

Build a custom Intel® vPro™ Power Control script

You can leverage the integration of MSP N-central with Intel® Active Management (AMT) Technology to power on a device, run a custom script and power down the device.

MSP N-central supports Intel AMT (Active Management Technology) 4.0.

MSP N-central enables you to run a VBScript (.vbs) or batch file (.BAT) and uses AMTPowerManager.exe to power on, power off, or reboot devices. The key components to build your own custom script are provided below. These include a sample Intel® vPro™ Power Control script, command line parameters, return codes that may be generated by the script, and important tips on running the script. Use this as a starting point to create your own scripts.

After you build your own Intel® vPro™ Power Control script and upload it to the repository, your customers can use it in the creation of management tasks. For more information about Scheduled Tasks, see What are scheduled tasks.

Sample Intel® vPro™ Power Control script

This sample provided performs the following tasks:

  • Verifies the power state of an Intel® vPro™ device and powers it up it up if required.
  • Runs a defragmentation analysis of the Intel® vPro™ device using the remote execution tool.
  • Powers off the Intel® vPro™ device ONLY if it was powered on by this script.

Tips for running this script

  • The first parameter must be an IP address that the windows probe used when it executes the script.
  • Additional parameters can be provided through the command line parameter field in MSP N-central.
  • All commands must be executed sequentially.
  • The following macros must be present in the script:
    • set wspUser=<@wspUsername>
    • set wspPass=<@wspPassword>
    • set amtUser=<@amtUsername>
    • set amtPass=<@amtPassword>
    • set timeout=<@wspProcessTimeout>

    The Windows probe replaces the values in the macros with the appropriate credentials. The "@" is required for the script to execute correctly.

  • The sample Intel® vPro™ Power Control script includes the AMTPowerManager.exe utility, which can perform the following commands on Intel AMT enabled devices: 
    • power on,
    • power off,
    • reboot

This script uses the AMTPowerManager.exe to powerup the device and psexec.exe to power off the device. We do not recommend using the AMTPowerManager.exe to power off the device. AMTPowerManager.exe causes an ungraceful shutdown, which may result in the possible loss of data.

Sample script

@ECHO OFF
SETLOCAL ENABLEEXTENSIONS
SETLOCAL DISABLEDELAYEDEXPANSION
set retCode=0
IF "%1"=="" (
echo The first parameter must be the Intel® vPro™ device's IP address.
set retCode=1
Goto ErrorHandler
)
set host=%1%
REM The following macros MUST be present in this script file.
set wspUser=<@wspUsername>
set wspPass=<@wspPassword>
set amtUser=<@amtUsername>
set amtPass=<@amtPassword>
Set timeout=<@wspProcessTimeout>
set POWER_UP_WORKING=240
set POWER_SOFT_OFF=245
AMTPowerManager.exe -h %host% -c status -u %amtUser% -p %amtPass% -v
set oldPowerState=%ERRORLEVEL%
echo oldPowerState: %oldPowerState%
if %oldPowerState% NEQ %POWER_UP_WORKING% (
echo Turning PC on...
AMTPowerManager.exe -h %host% -c poweron -u %amtUser% -p %amtPass% -v
set retCode=%Errorlevel%
IF %retCode% NEQ 0 Goto ErrorHandler
ping -n 1 -w 90000 0.0.0.1
)
if %oldPowerState% EQU %POWER_UP_WORKING% echo PC is already in ON state
echo Starting defragmentation...
set waitCount=0
:WaitForOS
psexec \\%host% -u %wspUser% -p %wspPass% defrag -a c:
set retCode=%Errorlevel%
IF %retCode% NEQ 0 Goto ErrorHandler
echo Defrag completed
if %oldPowerState% EQU %POWER_SOFT_OFF% {
echo Turning PC off...
psexec \\%host% -d -u %wspUser% -p %wspPass% shutdown -f -s
set retCode=%Errorlevel%
IF %retCode% NEQ %POWER_SOFT_OFF% Goto ErrorHandler
}
echo COMPLETED
:ErrorHandler
if %retCode% EQU 53 (
set /a waitCount=%waitCount%+1
if %waitCount% LSS 10 Goto WaitForOS
)
echo Return Code: %retCode%
set host=
set wspUser=
set wspPass=
set amtUser=
set amtPass=

Command line parameters

The table below provides a list of common command line parameters you can use when building a script.

Comand Line Parameter

Description

Data Type

-h

The host address of the AMT device. It can be a fully qualified domain name or an IP address; for example: 192.168.1.2

string

-c

The command to be perform on this device.

Supported commands:

  • POWERON: turns on the AMT device,
  • POWEROFF: turns off the AMT device,
  • POWERCYCLE: restarts the device,
  • STATUS: gets the current power status of this device.

string

-tls

Speeds up connection time on AMT devices that are TLS enabled. It is equivalent to running remote command on port 16993. (optional)

Boolean

-t

The number of retries if the command failed. (optional)

integer

-proxy

Proxy (optional)

string

-u

AMT user name.

string

-p

AMT user name.

string

-v

Prints command status and extra information while the command is running.

N/A

The command format using the AMTPowerManager utility and command line parameters is:

AMTPowerManager -h hostname -u username -p password -c command [-tls] [-t number] [-v]

For example,

A command to turn on an Intel® vPro™ device looks like:

  • AMTPowerManager.exe –h 192.168.20.228 -u admin -p Password1. -c poweron -v

This command produces the following output:

User's inputs ----------

Hostname: 192.168.20.228

Username: admin

Password: Password1.

Port: 16992 Power

status: Working(240)

Attempt to run: PowerUp

Waiting for system's state: .....

System is set to: POWER_UP_WORKING

Return Code: PT_STATUS_SUCCESS

If you would prefer concise output, do not include -v (which indicates verbose). Without the -v parameter the return code will be the only output.

Return codes

If the command successfully runs, the AMTPowerManager.exe program returns the power status of the Intel® vPro™ device; otherwise, an error code will be returned.

ATM error codes

PT_STATUS_SUCCESS = 0x0

PT_STATUS_INTERNAL_ERROR = 0x1

PT_STATUS_INVALID_PT_MODE = 0x3

PT_STATUS_INVALID_MESSAGE_LENGTH = 0xA

PT_STATUS_INVALID_NAME = 0xC

PT_STATUS_INVALID_BYTE_COUNT = 0xF

PT_STATUS_NOT_PERMITTED = 0x10

PT_STATUS_MAX_LIMIT_REACHED = 0x17

PT_STATUS_INVALID_AUTH_TYPE = 0x18

PT_STATUS_INVALID_DHCP_MODE = 0x1A

PT_STATUS_INVALID_IP_ADDRESS = 0x1B

PT_STATUS_INVALID_DOMAIN_NAME = 0x1C

PT_STATUS_INVALID_PROVISIONING_STATE = 0x20

PT_STATUS_INVALID_TIME = 0x22

PT_STATUS_INVALID_INDEX = 0x23

PT_STATUS_INVALID_PARAMETER = 0x24

PT_STATUS_INVALID_NETMASK = 0x25

PT_STATUS_FLASH_WRITE_LIMIT_EXCEEDED = 0x26

PT_STATUS_NETWORK_IF_ERROR_BASE = 0x800 

PT_STATUS_UNSUPPORTED_OEM_NUMBER = 0x801

PT_STATUS_UNSUPPORTED_BOOT_OPTION = 0x802

PT_STATUS_INVALID_COMMAND = 0x803

PT_STATUS_INVALID_SPECIAL_COMMAND = 0x804

PT_STATUS_INVALID_HANDLE = 0x805

PT_STATUS_INVALID_PASSWORD = 0x806

PT_STATUS_INVALID_REALM = 0x807

PT_STATUS_STORAGE_ACL_ENTRY_IN_USE = 0x808

PT_STATUS_DATA_MISSING = 0x809

PT_STATUS_DUPLICATE = 0x80A

PT_STATUS_EVENTLOG_FROZEN = 0x80B

PT_STATUS_PKI_MISSING_KEYS = 0x80C

PT_STATUS_PKI_GENERATING_KEYS = 0x80D

PT_STATUS_INVALID_KEY = 0x80E

PT_STATUS_INVALID_CERT = 0x80F

PT_STATUS_CERT_KEY_NOT_MATCH = 0x810

PT_STATUS_MAX_KERB_DOMAIN_REACHED = 0x811

Probe error codes

PT_STATUS_CONF_READ_ERROR = 0xEA

PT_STATUS_PROXY_ERROR = 0xEB

PT_STATUS_CONNECT_FAILURE = 0xEC

PT_STATUS_NON_AMT = 0xED

PT_STATUS_AUTHEN_ERROR = 0xEE

PT_STATUS_UNKNOWN_ERROR = 0xEF

Command status codes

POWER_UP_WORKING = 0xF0 // S0

POWER_UP_SLEEP = 0xF1 // S1

POWER_SLEEP_NO_CONTEXT = 0xF2 // S2

POWER_SLEEP_WITH_MEM = 0xF3

POWER_SLEEP_SUSPENDED = 0xF4

POWER_SOFT_OFF = 0xF5

POWER_SOFT_OFF_UNK = 0xF6

POWER_MECH_OFF = 0xF7

POWER_LEGACY_SLEEP = 0xF8

POWER_SLEEP_UNK = 0xF9

POWER_OVERRIDE = 0xFA

POWER_LEGACY_ON = 0xFB

POWER_LEGACY_OFF = 0xFC

POWER_UNK = 0xFE

POWER_RESERVED = 0xFF