Power Manager

EMDK For Xamarin - 2.4

Overview

The PowerMgr allows an app to perform certain OS- and power-related actions on the device, such as resetting to a factory-fresh state, putting the device into Sleep mode, rebooting or performing an OS update. PowerMgr performs only actions; there are currently no queries supported other than the ability to query the version of the CSP that implements PowerMgr itself.

It's important to note that PowerMgr actions such as Reboot and Reset, once executed, will prevent the execution of subsequent actions submitted by the Request XML document, including the submission of a Result XML to the application sending the original Request. Zebra therefore recommends using Condition Manager in conjunction with PowerMgr to ensure that appropriate conditions exist on a device before attempting to perform "risky" operations such as OS updates, the failure of which can render a device unusable, severely limited or otherwise in need of service.

Main Functionality

  • Put a Device into Sleep Mode
  • Reboot a Device
  • Perform an Enterprise Reset on a Device
  • Perform a Factory Reset on a Device
  • Wipe a Device (and erase all cards)
  • Update the OS on a Device
  • Perform multiple updates in a single step

Sleep Mode

On Android devices, Sleep mode turns off the device display screen and places some subsystems into low-power states. Depending on device configuration settings, certain apps and/or subsystems such as Wi-Fi and Cellular might remain active.

Reboot

Rebooting an Android device generally causes only volatile information such as application state and transient data to be lost. Non-volatile data such as device settings and stored apps and data are preserved. A Reboot is sometimes referred to as a "Reset" or "Normal Reset," but is not to be confused with an Enterprise Reset or Factory Reset (explained below).

Note: The Reboot Action causes the device to immediately restart, preventing any subsequent Actions from executing, including the submission of a Result XML to the application sending the original request.

Enterprise Reset

Enterprise Reset is intended to return the device to an Enterprise-defined default state, generally as determined by the contents of the /enterprise partition. On Zebra Android devices, an Enterprise Reset is the same as a Factory Reset except that the /enterprise partition is preserved. This action is supported only on Zebra devices running Android 4.4 KitKat and higher. On Zebra Android devices running Android Jelly Bean lower, the same action could be performed using the "OS Update" action if a suitable OS Update ZIP file was used.

Note: This Action causes the device to Reboot (into Recovery Mode), preventing any subsequent Actions from executing, including the submission of a Result XML to the application sending the original request.

Factory Reset

The Factory Reset is intended to return the device to its factory-fresh condition with the exception of certain conditions related to its internal storage card(s) (see below). On Zebra Android devices, a Factory Reset erases all key partitions and storage cards containing /data, /cache, and /enterprise partitions. This action is supported only on Zebra devices running Android 4.4 KitKat and higher. On Zebra Android devices running Android Jelly Bean lower, the same action could be performed using the "OS Update" Action if a suitable OS Update ZIP file was used.

Note: This Action causes the device to Reboot (into Recovery Mode), preventing any subsequent Actions from executing, including the submission of a Result XML to the application sending the original request.

Resetting Storage Cards

A Factory Reset will erase a storage card if:

  • The card was implemented within the /data or /enterprise partitions

A Factory Reset will NOT erase a storage card if:

  • The card was implemented with its own dedicated partition
  • The card is physically removable

Full Device Wipe

The Full Device Wipe is intended to return the device to its condition as it would have shipped from the factory with its current OS plus any subsequent OS update(s). On Zebra Android devices, a Full Device Wipe is the same as a Factory Reset plus the unconditional erasure of all storage cards. This action is supported only on Zebra devices running Android 4.4 KitKat and higher. On Zebra Android devices running Android Jelly Bean lower, the same action could be performed using the "OS Update" Action if a suitable OS Update ZIP file was used.

Note: This Action causes the device to Reboot (into Recovery Mode), preventing any subsequent Actions from executing, including the submission of a Result XML to the application sending the original request.

OS Update

The OS Update allows the device operating system to be replaced or patched using a specified OS Update Zip File or a text file containing a list of OS updates and/or patches. Depending on the contents of the file(s), this process also can be used to perform an Enterprise Reset, Factory Reset or Full Device Wipe to facilitate the installation of the update or patch contained in the file(s).

Note: This Action causes the device to Reboot (into Recovery Mode), preventing any subsequent Actions from executing, including the submission of a Result XML to the application sending the original request.

Reset Action

Used to invoke a OS- or power-related action on the device. Read Overview carefully for important information about Reset Actions.

Parm Name: ResetAction

Option Name Description Requires
0 Do nothing This value (or the absence of this parm from the XML) will cause no action to be performed on the device; any previously selected setting will be retained.

MX: 4.2+

1 Sleep Mode Puts the device into Sleep mode, reducing power usage and some app functions. See Overview for more information.

MX: 4.1+

4 Reboot Reboots the operating system on the device, resetting volatile memory and terminating execution of any subsequent PowerMgr actions (non-volatile settings and storage are preserved).

MX: 4.2+

Android API Level: 16+

5 Enterprise Reset Performs an Enterprise Reset, returning the device to an enterprise-defined default state as generally determined by the contents of the /enterprise partition. See Overview for more information.

OSX: 4.2+

MX: 4.2+

Android API Level: 19+

6 Factory Reset Performs a Factory Reset, erasing all data partitions, including /data, /cache and /enterprise, and some storage cards. See Overview for more information.

OSX: 4.2+

MX: 4.2+

Android API Level: 19+

7 Full Device Wipe Erases all data on the device and storage cards, if any. See Overview for more information.

OSX: 4.2+

MX: 4.2+

Android API Level: 19+

8 OS Update Launches an OS Update on the device using the specified OS Update Zip file. See Overview for more information.

MX: 4.1+

Android API Level: 16+

OS Update File

Used to specify the path and filename of the file to be consumed when updating the device using the OS Update Reset Action. The OS Update file must either be the specific .zip file being applied, or a text file (with .upl extension) containing a list of patches (multiple .zip files) to be applied in the desired order from top to bottom.

For example, if the .zip files M99N0KXXVPUCP14500.zip and CFE-M99-L-N0-010101_G_00_02.zip are to be applied in that order, the OS Update text file should be created as follows:


//Contents of the "osupdate.upl" text file:

package:M99N0KXXVPUCP14500.zip
package:CFE-M99-L-N0-010101_G_00_02.zip

// Note the package files are preceded by the notation "package:" 

Update File Rules

  • Required file(s) must be on the device before the Reset Action is initiated.
  • The .upl file and all referenced .zip files must be in the same device folder.
  • The folder used for storing file(s) must be a supported location according to the Android Location Rules and Device Location Rules below.
  • Location rules and characteristics vary by device.

Android Location Rules

  • Update file location must not be blocked by SdCardMgr or any other means.

  • Removable media must be physically present. Storage partitions implemented on a removable medium such as a Micro SD Card must be inserted in the device when the Reset Action is initiated.

  • The location must not be encrypted. A location that is encrypted cannot be used for OS Updates. For example, if Full Storage Card Encryption is enabled for a particular Storage Card, that card contains no suitable locations for OS Updates. Similarly, if an Encrypted File System was mounted on a Storage Card, that card also would be unsuitable for OS Updates.

  • The update entity must have write permissions in the update file location.

  • Emulated Storage Cards are not supported on Jelly Bean. Devices running KitKat and higher are not effected by this limitation.

  • Adoptable Storage is not supported. Zebra devices by default do not implement the Android Adoptable Storage spec, which formats the SD Card for use with a single device. An Adoptable SD Card cannot be used to store update files.

Note: The path specified using this parameter would normally be the same as the path to which the file was written when it was transferred to the device. However, path names can sometimes appear to be different while ending at the same destination, and it's possible that some such paths will fail to initiate an OS Update when specified using this parameter. Therefore, Zebra recommends using paths in the following table when specifying the OS Update file to the PowerMgr.

Device Location Rules

Device Model Android Version(s) Supported Paths Comment
ET1N0 JB 4.1-4.3.1 /sdcard

/data/tmp

Removable Micro SD Card (must be physically present)

Internal Data Partition (folder exists and is world-writable)

ET1N2 JB 4.1-4.3.1 /sdcard

/data/tmp

Removable Micro SD Card (must be physically present)

Internal Data Partition (folder exists and is world-writable)

MC32 JB 4.1-4.3.1 /sdcard

/data/tmp

Removable Micro SD Card (must be physically present)

Internal Data Partition (folder exists and is world-writable)

MC40 JB 4.1-4.3.1 /sdcard

/data/tmp

Internal Storage Card

Internal Data Partition (folder exists and is world-writable)

MC40 KK 4.4 /sdcard

/storage/sdcard0

Internal Storage Card

Internal Storage Card

MC67 JB 4.1-4.3.1 /sdcard

/data/tmp

Removable Micro SD Card (must be physically present)

Internal Data Partition (folder exists and is world-writable)

TC55 KK w/GMS 4.4 /sdcard

/storage/sdcard0

/storage/sdcard1

Internal Storage Card

Internal Storage Card

Removable Micro SD Card (must be physically present)

TC55 KK 4.4 /sdcard

/storage/sdcard0

/storage/sdcard1

Internal Storage Card

Internal Storage Card

Removable Micro SD Card (must be physically present)

TC70 GA1 KK 4.4 /sdcard

/storage/sdcard0

/storage/sdcard1

/data/tmp

Removable Micro SD Card (must be physically present)

Removable Micro SD Card (must be physically present)

Internal Storage Card

Internal Data Partition (folder exists and is world-writable)

TC75 KK 4.4 /sdcard

/storage/sdcard0

/data/tmp

Internal Storage Card

Internal Storage Card

Internal Data Partition (folder exists and is world-writable)

(multiple)

Lollipop and higher

/data/tmp/public Zebra recommends using this path; it will be supported on all devices running Android 5.0 Lollipop and higher. See note below.


Note: Zebra devices running Android Lollipop and Marshmallow might support update-file locations other than the location recommended in the table above. Other supported locations might include:

  • /storage/sdcard0 (internal)
  • /storage/sdcard1 (external)

However, support of such locations is subject to changes that are beyond Zebra's control. Zebra recommends testing any update procedure on a working device before the process is considered for mass deployment.

Parm value input rules:

  • String from 1-255 characters containing full path and file name of OS Update .zip or .upl file

Shown if: The Reset Action is "OS Update"

Parm Name: ZipFile

Requires:

  • MX: 4.1+
  • Android API Level: 16+

Examples

Reboot the Device


<wap-provisioningdoc>
    <characteristic type="PowerMgr" version="4.2" >
        <parm name="ResetAction" value="4"/>
    </characteristic>
</wap-provisioningdoc>

Enterprise Reset the Device


<wap-provisioningdoc>
    <characteristic type="PowerMgr" version="4.2" >
        <parm name="ResetAction" value="5"/>
    </characteristic>
</wap-provisioningdoc>

Factory Reset the Device


<wap-provisioningdoc>
    <characteristic type="PowerMgr" version="4.2" >
        <parm name="ResetAction" value="6"/>
    </characteristic>
</wap-provisioningdoc>

Full Device Wipe


<wap-provisioningdoc>
    <characteristic type="PowerMgr" version="4.2" >
        <parm name="ResetAction" value="7"/>
    </characteristic>
</wap-provisioningdoc>

OS Update


<wap-provisioningdoc>
    <characteristic type="PowerMgr" version="4.2" >
        <parm name="ResetAction" value="8"/>
        <characteristic type="file-details">
            <parm name="ZipFile" value="/sdcard/osupdate.zip"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>