Battery Module

RhoElements 2.x API

Overview

The Battery Module is used to set the attributes of the battery indicator and retrieve the status of the battery. For more information about positioning these indicators, please refer to the indicator layout overview page.

Syntax

battery (Module) <META> Syntax

<META HTTP-Equiv="Battery" content="[parameter]">

<META HTTP-Equiv="Battery" content="BatteryEvent:url('[jsFunction | url]')">

Battery JavaScript Object Syntax:
By default the JavaScript Object 'battery' will exist on the current page and can be used to interact directly with the battery.
To Invoke battery methods via JavaScript use the following syntax: battery.method();

e.g. battery.getSmartBatteryStatus();
To Set battery parameters via JavaScript use the following syntax: battery.parameter = 'value'; remembering to enclose your value in quotes where appropriate.

e.g. battery.visibility = 'value';
To Set battery return events via JavaScript use the following syntax: battery.event = JavaScript Function;

e.g. battery.batteryEvent = 'doFunction(%json)';

For more details on the event syntax and parameters see the Retrieval Events page.
To set multiple EMML parameters / events on a single line use the following syntax: battery.setEMML("[Your EMML Tags]");

e.g. battery.setEMML("visibility:value;batteryEvent:url('JavaScript:doFunction(%json)');getSmartBatteryStatus");

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description Default Value
getSmartBatteryStatus Triggers a SmartBatteryEvent. This returns attributes about the battery such as number of charge cycles and date of manufacture. Please note that the Smart Battery is only supported on Zebra Devices running Windows Embedded Hand-held or CE and is dependent on the available hardware. N/A
getBatteryStatus Triggers a BatteryEvent. This returns attributes about the battery such as battery life and AC line status etc. N/A

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description Default Value
visibility:[Value] visible or hidden Sets whether or not the battery indicator is shown Hidden
left:[Value] Pixel value Sets the horizontal position of the battery indicator in pixels. If it is negative the then indicator will be moved off screen Top left of screen
top:[Value] Pixel value Sets the vertical position of the battery indicator in pixels. if value is negative then indicator will be moved off screenTop left of screen.
layout:[Value] Left, Right, Up, Down Sets the orientation of the battery icon Right
color:[Value] Hex Values (#000000 - #FFFFFF) RGB value that sets the color of the battery indicator using HTML web colors #000000
sampleInterval:[Value] Refresh interval The battery refresh interval, specified in milliseconds. A value of 0 disables the automatic refresh. 5000 milliseconds
setSystemNotifications:[Value] Enabled, Disabled Sets the system notifications for battery. If we enable the system Notifications then its recommended to disable the auto refresh by setting the sampleInterval to 0 otherwise the eventSource in the battery status gets overwritten to "Timed Interval". Please note that the system notifications are reported only once by the operating system and hence the low battery conditions are not reported if the device is already in low battery condition. Disabled

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.

batteryEvent

The BatteryEvent gives an indication of the remaining battery level. Once registered for you will receive a BatteryEvent at regular intervals, as specified by the BatteryRefresh configuration setting.

ID Name Description
1 acLineStatus The AC line status (whether or not on external power).
2 batteryLifePercent Displays the remaining battery power as a percentage. 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.
3 backupBatteryLifePercent Remaining backup battery power as a percentage.
4 eventSource Reason for event firing ("Timed Interval", "User Request", "Low Battery", "Critical Battery", "AC Connect" and "AC Disconnect"). "Timed Interval" is when the status gets refreshed automatically and "User Request" is when the user manually calls getBatteryStatus method and the remaining are generated through system notifications.
5 batteryLifeKnown Battery life will not be readable for a period of time after removing from an AC power source. This parameter will state whether the batteryLifePercent is accurate ("true"/"false").
6 backupBatteryLifeKnown Backup battery life will not be readable for a period of time after removing from an AC power source. This parameter will state whether the backupBatteryLifePercent is accurate ("true"/"false").

smartBatteryEvent

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

ID Name Description
1 serialNumber The serial number of the battery
2 partNumber The Zebra part number of the battery, e.g. 21-65587 Rev. A
3 batteryChargeCycles 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 accuratley predict the life of a battery.
4 ratedCapacity Rated capacity of the battery in mAh
5 manufactureDate Date the battery was manufactured expressed as MM/DD/YYYY.
6 stateOfHealth "Healthy", "Unhealthy" or "Unknown"

Remarks

Overlapping

Do not display the Battery indicator overlapping with the Signal indicator.

Indicator Positions

For an illustrative guide to the meaning of the Layout parameter, see the 'Indicator Positions' section.

Parameter Deprecation

For users migrating their PocketBrowser apps to RhoElements please note that due to the difference in the battery indicator graphic, the GraphPosition and IconPosition parameters have been deprecated. Please use the Layout parameter instead.

Requirements

RhoElements Version 1.0.0 or above
Supported Devices All supported devices.
Minimum Requirements None.
Persistence Partially Persistent - Changes to this module will persist when navigating to a new page with the exception of the view finder: this will be hidden on page navigation.

HTML/JavaScript Examples

The following example shows the battery indicator, sets the x and y co-ordinates to 50, the color of the indicator to red and positions the indicator at the bottom of the screen growing from right to left:


<META HTTP-Equiv="battery" Content="visibility:visible">
<META HTTP-Equiv="battery" Content="Left:50">
<META HTTP-Equiv="battery" Content="Top:50">
<META HTTP-Equiv="battery" Content="Layout:Left">
<META HTTP-Equiv="battery" Content="Color:#FF0000">   

Example shown above can also be written as shown below


<META HTTP-Equiv="Battery" Content="Left:50;Top:50;Layout:Left;color:#FF0000;visibility:visible">

Parameters can also be concatenated as shown below


<META HTTP-Equiv="Battery-Left" Content="Left:50">
<META HTTP-Equiv="Battery-Top" Content="Top:50">
<META HTTP-Equiv="Battery-Color" Content="Color:#FF0000">

The following example navigates to a new page with parameters upon a battery status change.


<META HTTP-Equiv="Battery" Content="BatteryEvent:url('mypage.asp?Data=%s&Source=%s&Type=%s&Time=%s&Length=%s')">

The following example alerts the user with battery notifications such as low battery warning.


<HTML>
    <HEAD>
    <TITLE>Low Battery Notification</TITLE>
    <META HTTP-EQUIV="battery" content="sampleInterval:0;batteryEvent:url('javascript:lowBattery(%json);')">
    </HEAD> 
    <SCRIPT type="text/javascript">
    function lowBattery(jsonObject)
    {
        alert("Event: " + jsonObject.eventSource + " ,Battery remaining: " + jsonObject.batteryLifePercent + 
        "% ,Backup battery remaining:" + jsonObject.backupBatteryLifePercent + "% ,AC line status: " + jsonObject.acLineStatus);
    }
    </SCRIPT>
    <BR><INPUT type="button" value="EnableNotifications" onclick="battery.setSystemNotifications='Enabled';">
    <BR><INPUT type="button" value="DisableNotifications" onclick="battery.setSystemNotifications='Disabled';">
</HTML>