Battery Module - Zebra Technologies TechDocs

Overview

The Battery API is used to notify the user of the remaining power in the battery. Windows Mobile/CE devices also support the display of a small indicator to indicate the power remaining.

Enabling the API

There are two methods of enabling the Battery API:

Include all ebapi modules or
Include only the API modules you need

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, you must copy the ebapi-modules.js file to a location accessible by your app's files and include the JavaScript file in your app. For instance, to include the modules file in your index.html, with the file in the same directory as your index.html, you would add the following line to the section of your index.html:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the modules you need

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the Battery API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.battery.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Persistence

With the old PocketBrowser APIs, any events, such as batteryEvent were canceled when a full navigate was performed. The original reason for this was a limitation of the IE engine on WM5 devices. When moving to the common API this was changed so that callbacks are not canceled.

Methods

batteryDiagnostics()

The BatteryDiagnostics method returns parameters for further battery analysis. Not all return values will be supported by all batteries. Any parameters that cannot be retrieved will return 'undefined'. In Android, Currently supported only on the MC18 device

Parameters

callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

stateOfHealthPercent : STRING
The current maximum battery capacity as a percentage of the battery rated capacity
batteryCapacityPercent : STRING
The remaining battery capacity percentage
batteryCapacityMinutes : STRING
The remaining battery capacity in minutes. Calculations are based on the averageCurrentConsumption parameter
batteryExpirationInMonths : STRING
Prediction in number of months when the battery should be replaced. Returns undefined for Android.
previousBatteryReplacement : STRING
Duration in days since the battery was last replaced
timeSinceLastColdBoot : STRING
Time in minutes since the device was last cold booted
requiredChargeTime : STRING
Calculates the charge time required in minutes based on the tripDuration and averageCurrentConsumption parameters.
chargingTime : STRING
The duration of time for which the unit was last charging, in minutes

Returns

Synchronous Return:

HASH
- stateOfHealthPercent : STRING
  The current maximum battery capacity as a percentage of the battery rated capacity
- batteryCapacityPercent : STRING
  The remaining battery capacity percentage
- batteryCapacityMinutes : STRING
  The remaining battery capacity in minutes. Calculations are based on the averageCurrentConsumption parameter
- batteryExpirationInMonths : STRING
  Prediction in number of months when the battery should be replaced. Returns undefined for Android.
- previousBatteryReplacement : STRING
  Duration in days since the battery was last replaced
- timeSinceLastColdBoot : STRING
  Time in minutes since the device was last cold booted
- requiredChargeTime : STRING
  Calculates the charge time required in minutes based on the tripDuration and averageCurrentConsumption parameters.
- chargingTime : STRING
  The duration of time for which the unit was last charging, in minutes

Platforms

Android
Windows CE
Zebra Devices Only

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.batteryDiagnostics()

batteryStatus(HASH propertyMap)

Retrieve the current battery level. If a callback is provided to retrieve the battery then it will be called periodically at a frequency determined by the trigger property.

Parameters

propertyMap : HASH
The properties associated with accessing the battery status.

trigger : STRING Default: Platform Dependant
What will cause the batteryStatus callback to fire. It is recommended to use system events to conserve battery life.
Possible Values :

Constant: EB.Battery.BATTERY_TRIGGER_PERIODIC
String:periodic
The batteryStatus callback will fire periodically at the specified refresh interval. This is the default setting on Windows Mobile / CE / Embedded but those platforms do also support the system trigger. Not supported on Android.
Constant: EB.Battery.BATTERY_TRIGGER_SYSTEM
String:system
The batteryStatus callback will fire when the underlying operating system notifies that there has been a change to the battery level. The resolution of this change will vary depending on operating system, for example on Windows Mobile the notifications only occur when 'critical', 'full' etc.
refreshInterval : INTEGER
Alternative way of specifying the refreshInterval parameter. If you are using a system trigger then this parameter will be ignored.

callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

acLineStatus : BOOLEAN
Whether or not the device is connected to external power.
batteryLifePercent : INTEGER
Displays the remaining battery power as a percentage value between 0 and 100. For some Zebra Android devices, the API will return a value of 255 at all times while the battery is being charged. The same value also might be displayed for a few seconds initially after reboot while the battery is being discharged. This is in accordance with hardware design specs and should be taken into account when using the API.
backupBatteryLifePercent : INTEGER
The remaining backup battery power as a percentage between 0 and 100. Supported only on Symbol Technologies Windows Mobile / CE / Embedded devices. Platforms: WM
trigger : STRING
Human readable form of what has caused this callback to fire. This value will be OS dependent. On Windows Mobile / CE / Embedded it will be one of: "High Battery", "Low Battery", "Critical Battery", "Charging", "No Battery", "Unknown". In the case of periodic updates, this field will contain the last known status of the battery. Platforms: WM, CE, Android
batteryLifeKnown : BOOLEAN
Supported only on Symbol Technologies' Windows Mobile / CE / Embedded devices. The battery life will not be readable for a period of time after removing from an AC power source and this parameter will state whether the batteryLifePercent value is accurate. Platforms: WM
backupBatteryLifeKnown : BOOLEAN
Supported only on Symbol Technologies' Windows Mobile / CE / Embedded devices. The battery life will not be readable for a period of time after removing from an AC power source and this parameter will state whether the backupBatteryLifePercent value is accurate. Platforms: WM

Returns

Synchronous Return:

HASH
- acLineStatus : BOOLEAN
  Whether or not the device is connected to external power.
- batteryLifePercent : INTEGER
  Displays the remaining battery power as a percentage value between 0 and 100. For some Zebra Android devices, the API will return a value of 255 at all times while the battery is being charged. The same value also might be displayed for a few seconds initially after reboot while the battery is being discharged. This is in accordance with hardware design specs and should be taken into account when using the API.
- backupBatteryLifePercent : INTEGER
  The remaining backup battery power as a percentage between 0 and 100. Supported only on Symbol Technologies Windows Mobile / CE / Embedded devices. Platforms: WM
- trigger : STRING
  Human readable form of what has caused this callback to fire. This value will be OS dependent. On Windows Mobile / CE / Embedded it will be one of: "High Battery", "Low Battery", "Critical Battery", "Charging", "No Battery", "Unknown". In the case of periodic updates, this field will contain the last known status of the battery. Platforms: WM, CE, Android
- batteryLifeKnown : BOOLEAN
  Supported only on Symbol Technologies' Windows Mobile / CE / Embedded devices. The battery life will not be readable for a period of time after removing from an AC power source and this parameter will state whether the batteryLifePercent value is accurate. Platforms: WM
- backupBatteryLifeKnown : BOOLEAN
  Supported only on Symbol Technologies' Windows Mobile / CE / Embedded devices. The battery life will not be readable for a period of time after removing from an AC power source and this parameter will state whether the backupBatteryLifePercent value is accurate. Platforms: WM

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.batteryStatus(HASH propertyMap)

hideIcon()

Hide the icon if it has been previously set by the 'showIcon' call.

Parameters

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE
Zebra Devices Only

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.hideIcon()

showIcon(HASH propertyMap)

Overlays a small battery icon on top of the view indicating the remaining battery strength. This is particularly useful in full screen applications that cover the system battery level indicator.

Parameters

propertyMap : HASH
The properties associated with the indicator, its position and color.

left : INTEGER Default: [Top left of the screen]
The absolute horizontal position of the indicator in pixels. This value is relative to the screen and not the view, so non-fullscreen applications should take care not to display the indicator off screen.
top : INTEGER Default: [Top left of the screen]
The absolute vertical position of the indicator in pixels. Positive numbers go towards the bottom of the screen. This value is relative to the screen and not the view, so non-fullscreen applications should take care not to display the indicator off screen.
layout : STRING Default: [Right]
Sets the orientation of the icon, see the remarks section for illustrations.
Possible Values :

Constant: EB.Battery.BATTERY_LAYOUT_LEFT
String:left
See the remarks section for illustrations of icon layout.
Constant: EB.Battery.BATTERY_LAYOUT_RIGHT
String:right
See the remarks section for illustrations of icon layout.
Constant: EB.Battery.BATTERY_LAYOUT_UP
String:up
See the remarks section for illustrations of icon layout.
Constant: EB.Battery.BATTERY_LAYOUT_DOWN
String:down
See the remarks section for illustrations of icon layout.
color : STRING
The color of the icon. This value must be specified as a Hex value in the format #000000 to #FFFFFF. Alpha values are not supported, i.e. you can only use the component parts RRGGBB.

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE
Zebra Devices Only

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.showIcon(HASH propertyMap)

smartBatteryStatus()

Returns the various parameters relating to battery charge and battery hardware. Not all return values may be supported by all batteries.

Parameters

callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

serialNumber : STRING
The serial number of the battery.
partNumber : STRING
The Symbol Technologies' part number of the battery, e.g. 21-65587 Rev. A.
batteryChargeCycles : INTEGER
The number of times the battery has been charged. Partial charges are aggregated, therefore each charge cycle count represents one full charge / discharge cycle. The battery charge cycle count gets updated when the battery charging state changes from charging to not charging. Cycle count may not accurately predict the life of a battery.
ratedCapacity : INTEGER
Rated capacity of the battery in mAh.
manufactureDate : STRING
Date the battery was manufactured expressed as MM/DD/YYYY.
stateOfHealth : STRING
The health of the battery.
Possible Values :

Constant: EB.Battery.SMART_BATTERY_HEALTHY
String:healthy
The battery is healthy.
Constant: EB.Battery.SMART_BATTERY_UNHEALTHY
String:unhealthy
The battery is unhealthy.
Constant: EB.Battery.SMART_BATTERY_UNKNOWN
String:unknown
The battery health is unknown.

Returns

Synchronous Return:

HASH
- serialNumber : STRING
  The serial number of the battery.
- partNumber : STRING
  The Symbol Technologies' part number of the battery, e.g. 21-65587 Rev. A.
- batteryChargeCycles : INTEGER
  The number of times the battery has been charged. Partial charges are aggregated, therefore each charge cycle count represents one full charge / discharge cycle. The battery charge cycle count gets updated when the battery charging state changes from charging to not charging. Cycle count may not accurately predict the life of a battery.
- ratedCapacity : INTEGER
  Rated capacity of the battery in mAh.
- manufactureDate : STRING
  Date the battery was manufactured expressed as MM/DD/YYYY.
- stateOfHealth : STRING
  The health of the battery.
  Possible Values :
  
  Constant: EB.Battery.SMART_BATTERY_HEALTHY
  String:Constant: EB.Battery.SMART_BATTERY_HEALTHY
  String:healthy
  The battery is healthy.
  Constant: EB.Battery.SMART_BATTERY_UNHEALTHY
  String:Constant: EB.Battery.SMART_BATTERY_UNHEALTHY
  String:unhealthy
  The battery is unhealthy.
  Constant: EB.Battery.SMART_BATTERY_UNKNOWN
  String:Constant: EB.Battery.SMART_BATTERY_UNKNOWN
  String:unknown
  The battery health is unknown.

Platforms

Windows Mobile
Zebra Devices Only

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.smartBatteryStatus()

stopBatteryStatus()

If the battery status is being retrieved via callback by a previously invoked call to batteryStatus, this method will stop the callback from firing.

Parameters

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.Battery.stopBatteryStatus()

Properties

averageCurrentConsumption

Type

INTEGER

Description

Supported only by the MC18 device. Sets an average current consumption (in mA) that is used in subsequent power-related calculations. If set to 0, the value will be provided by the device driver based on the running average.

Access

Class: This property can only be accessed via the API class object.
- EB.Battery.averageCurrentConsumption

Platforms

Android
Windows CE

refreshInterval

Type

INTEGER

Description

A callback to retrieve the battery strength can be specified to occur periodically with the batteryStatus method. This value specifies the periodicity of the callback as well as the update frequency of the battery icon, if shown. Setting this value to zero will disable the batteryStatus callback. Note that most platforms will not support periodic updates to the battery level, this is only supported on Windows Mobile / CE / Embedded.

Params

Default: 5000

Access

Class: This property can only be accessed via the API class object.
- EB.Battery.refreshInterval

Platforms

Windows Mobile
Windows CE

tripDuration

Type

INTEGER

Description

Supported only by the MC18 device. Sets the desired working time (in minutes) out of the cradle, which is used in subsequent power-related calculations. If set to 0, the driver default value of 45 minutes will be used.

Access

Class: This property can only be accessed via the API class object.
- EB.Battery.tripDuration

Platforms

Android
Windows CE

Remarks

Icon Layout

Windows Mobile / CE and Handheld devices support the display of a small battery icon. This section explains the layout parameter, which can be provided to showIcon(...).

Layout:Left

Left Layout Battery Indicator

Layout:Right

Right Layout Battery Indicator

Layout:Up

Up Layout Battery Indicator

Layout:Down

Down Layout Battery Indicator

Overlapping Indicators

The position of the signal and battery indicators should not be set to overlap.

Screen Orientation

The indicator positions are absolute and so when rotating the screen you should also move the indicator positions accordingly to accommodate the new screen layout.

Internet Explorer (IE) Rendering Engine

When using the this feature on a CE device using the IE engine, screen distortion may be noticed when scrolling. This is due to a limitation of the IE engine and can be worked around using any of the following options:

Not using debug buttons - If your app must use the IE engine, do not use debug buttons in the app.
If you need to use the signal or battery indicators either:
- Don't scroll the page.
- Don't use the signal / battery indicators
- Use the Webkit engine.

Examples

Show battery icon

This example shows how to show/hide the Battery icon as well as a way to adjust for a change in screen orientation. This example assumes that the ebapi-modules.js file is in the same folder as the html file invoking it.


<head>
    <script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

    <title>Battery API Test</title>

    <script>
        function showBatteryIcon(){
            EB.Battery.showIcon(defineIconProperties(), batteryCallback);
            EB.Battery.batteryStatus({trigger:EB.Battery.BATTERY_TRIGGER_SYSTEM}, batteryCallback);
            // The batteryStatus() is used to tell the icon when to refresh.
            // We are leaving this up to the system events by using the BATTERY_TRIGGER_SYSTEM constant.
        }

        function hideBatteryIcon(){
            EB.Battery.hideIcon();
            EB.Battery.stopBatteryStatus();
        }

        function batteryCallback(params){
            if(params){     // Most of these methods have callbacks but null 'params' sent.
                console.log(params);
            }
            else
                console.log("No Params");
        }

        function defineIconProperties(){
            var props = {
                color:  "#66CD00",
                layout: EB.Battery.BATTERY_LAYOUT_UP,
                top:        0,                                                      // Top of screen
                left:   EB.System.screenWidth - 25      // Far right of screen, accounting for actual viewable area.
            }
            return props;
        }

        function adjustIcon(){
            EB.Battery.hideIcon();
            EB.Battery.showIcon(defineIconProperties(), batteryCallback);
        }

        // If the screen orientation changes, adjust the battery Icon.
        EB.ScreenOrientation.setScreenOrientationEvent(adjustIcon);
    </script>
</head>

<body>
    <h1>Battery API Test</h1>
    <div id="display">
    </div>
    <br/>
    <br/>
    <button onclick="showBatteryIcon()">Show Battery Status Icon</button><br/>
    <button onclick="hideBatteryIcon()">Hide Battery Status Icon</button>
</body>