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
- stateOfHealthPercent : STRING
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.
- Constant: EB.Battery.BATTERY_TRIGGER_PERIODIC
- 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
- acLineStatus : BOOLEAN
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.
- Constant: EB.Battery.BATTERY_LAYOUT_LEFT
- 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.
- Constant: EB.Battery.SMART_BATTERY_HEALTHY
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.
- Constant: EB.Battery.SMART_BATTERY_HEALTHY
- serialNumber : STRING
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
Layout:Right
Layout:Up
Layout:Down
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>