Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Battery

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

In order to use this API you must include the following extension in your build.yml.

extensions: ["indicators"]

The indicators extension is also included automatically if you specify the following in your build.yml

app_type: "rhoelements"

If you are building a Windows Mobile or Windows CE app with this API, you must set your app_type as “rhoelements” in your build.yml as shown in this build-time settings example.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

batteryDiagnostics(CallBackHandler callback)

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’

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded Zebra Devices Only (Currently only supported on the MC18 device)

Parameters

callback : CallBackHandler Optional

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. Calculates are based on the averageCurrentConsumption parameter
batteryExpirationInMonths : STRING

Prediction in number of months when the battery should be replaced
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

Synchronous Return:

HASH : this method also supports async callbacks - check the Callback tab for callback return parameters.
- 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. Calculates are based on the averageCurrentConsumption parameter
- batteryExpirationInMonths : STRING
  
  Prediction in number of months when the battery should be replaced
- 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

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Battery.batteryDiagnostics(CallBackHandler callback)
- Ruby: Rho::Battery.batteryDiagnostics(CallBackHandler callback)

batteryStatus(HASH propertyMap, CallBackHandler callback)

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

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. Please note, that iOS devices have no system triggers and will provide updates only with a specified period (Trigger value will be ignored)

Possible Values :

Constant: Rho::Battery.BATTERY_TRIGGER_PERIODIC (For Ruby use "::" instead of ".")
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: Rho::Battery.BATTERY_TRIGGER_SYSTEM (For Ruby use "::" instead of ".")
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 Optional

Async Callback Returning Parameters: HASH

acLineStatus : BOOLEAN

Whether or not the device is connected to external power.
batteryLifePercent : INTEGER

The remaining battery power as a value between 0 and 100.
backupBatteryLifePercent : INTEGER

The remaining backup battery power as a percentage between 0 and 100. Only supported 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

Only supported 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

Only supported 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

Synchronous Return:

HASH : this method also supports async callbacks - check the Callback tab for callback return parameters.
- acLineStatus : BOOLEAN
  
  Whether or not the device is connected to external power.
- batteryLifePercent : INTEGER
  
  The remaining battery power as a value between 0 and 100.
- backupBatteryLifePercent : INTEGER
  
  The remaining backup battery power as a percentage between 0 and 100. Only supported 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
  
  Only supported 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
  
  Only supported 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

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Battery.batteryStatus(HASH propertyMap, CallBackHandler callback)
- Ruby: Rho::Battery.batteryStatus(HASH propertyMap, CallBackHandler callback)

hideIcon()

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

JavaScript Ruby Android Windows Mobile, Windows CE, Windows Embedded Zebra Devices Only (All platforms support batteryStatus which can be used to draw your own level indicator or display an appropriate graphic.)

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Battery.hideIcon()
- Ruby: Rho::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 which 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: Rho::Battery.BATTERY_LAYOUT_LEFT (For Ruby use "::" instead of ".")
String:left

See the remarks section for illustrations of icon layout.

Constant: Rho::Battery.BATTERY_LAYOUT_RIGHT (For Ruby use "::" instead of ".")
String:right

See the remarks section for illustrations of icon layout.

Constant: Rho::Battery.BATTERY_LAYOUT_UP (For Ruby use "::" instead of ".")
String:up

See the remarks section for illustrations of icon layout.

Constant: Rho::Battery.BATTERY_LAYOUT_DOWN (For Ruby use "::" instead of ".")
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.

Synchronous Return:

Void

Method Access:

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

smartBatteryStatus(CallBackHandler callback)

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

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded Zebra Devices Only (Scanners on Symbol Technologies' Windows Mobile / CE / Embedded devices)

Parameters

callback : CallBackHandler Optional

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: Rho.Battery.SMART_BATTERY_HEALTHY (For Ruby use "::" instead of ".")
String:Constant: Rho::Battery.SMART_BATTERY_HEALTHY (For Ruby use "::" instead of ".")
String:healthy

The battery is healthy.

Constant: Rho.Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" instead of ".")
String:Constant: Rho::Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" instead of ".")
String:unhealthy

The battery is unhealthy.

Constant: Rho.Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" instead of ".")
String:Constant: Rho::Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" instead of ".")
String:unknown

The battery health is unknown.

Synchronous Return:

HASH : this method also supports async callbacks - check the Callback tab for callback return parameters.
- 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: Rho::Battery.SMART_BATTERY_HEALTHY (For Ruby use "::" instead of ".")
  String:healthy
  
  The battery is healthy.
  
  Constant: Rho::Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" instead of ".")
  String:unhealthy
  
  The battery is unhealthy.
  
  Constant: Rho::Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" instead of ".")
  String:unknown
  
  The battery health is unknown.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Battery.smartBatteryStatus(CallBackHandler callback)
- Ruby: Rho::Battery.smartBatteryStatus(CallBackHandler callback)

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

Void

Method Access:

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

Properties

Only supported 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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.averageCurrentConsumption

refreshInterval : INTEGER

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.

JavaScript Ruby iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Default: 5000

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.refreshInterval

tripDuration : INTEGER

Description
Access

Only supported 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.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Property Access:

Instance: This property can be accessed via an instance object of this class:
- myObject.tripDuration

Examples

Retrieve the Battery status

Synchronously: If you are only interested in the current battery level, for example to decide whether you have sufficient battery for the worker to start their shift, then you can immediately determine the level as follows

JavaScript
Ruby

  function battery_status_sync(){
    batteryValues = Rho.Battery.batteryStatus({});
    console.log("Battery Level is: " + batteryValues['batteryLifePercent']);
  }

  def battery_status_sync
    batteryValues = Rho::Battery.batteryStatus
    puts "Battery Level is: " + batteryValues['batteryLifePercent']
  end

Asynchronously: If you want to be notified of changes to the battery levelthen you can register to receive values through a callback

JavaScript
Ruby

  function battery_status_async(){
    console.log("Registering Battery Callback");
    Rho.Battery.batteryStatus({},batteryEvent);
  }

   function batteryEvent(params){
    console.log("Battery Event Fired:");
    console.log("Battery Event (Asynchronous). AC Line Status: " + params["acLineStatus"] + " Battery Life Percent: " + params["batteryLifePercent"] + " Backup Battery Life Percent: " + params["backupBatteryLifePercent"] + " Status: " + params["batteryStatus"] + " Battery Life Known: " + params["batteryLifeKnown"] + " Backup Battery Life Known: " + params["backupBatteryLifeKnown"]);
  }

  def battery_status_async
    puts "Registering Battery Callback"
    Rho::Battery.batteryStatus(url_for(:action => :batteryEvent))
  end

   def batteryEvent
    puts "Battery Event Fired: #{@params}"
    puts "Battery Event (Asynchronous). AC Line Status: #{@params["acLineStatus"]}, Battery Life Percent: #{@params["batteryLifePercent"]}, Backup Battery Life Percent: #{@params["backupBatteryLifePercent"]}, Status: #{@params["batteryStatus"]}, Battery Life Known: #{@params["batteryLifeKnown"]}, Backup Battery Life Known: #{@params["backupBatteryLifeKnown"]}"
  end

Working with the Battery indicator

If you just want to display the battery indicator in the default position and default color then call as follows.

JavaScript
Ruby

  function show_battery_icon(){
    Rho.Battery.showIcon({});
  }

  def show_battery_icon
    Rho::Battery.showIcon({})
  end

To display the battery icon at the default position but blue and vertical specify as follows.

JavaScript
Ruby

  function show_battery_icon(){
    Rho.Battery.showIcon({ left: 0, top: 40, color: '#FF0000', layout: Rho.Battery.BATTERY_LAYOUT_RIGHT });  
  }

  def show_battery_icon
    Rho::Battery.showIcon { left: 0, top: 40, color: '#FF0000', layout: Rho::Battery.BATTERY_LAYOUT_RIGHT }

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.

Licensing

You can fully use all features of this API during evaluation, development or testing without obtaining a license. A message will be displayed on application startup and will also display a nag screen periodically. Before deploying an application to a production environment, you must obtain a license key. Read more about licensing.