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 screen | Top 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>