Battery

Enterprise Browser 3.2

Overview

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

Enabling the API

There are two methods of enabling the Battery API:

  • Include all ebapi modules
  • Include only the required API modules

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, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:


<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 required modules

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>