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

Battery

Methods6
Methods - Class
batteryDiagnosticsbatteryStatushideIconshowIconsmartBatteryStatusstopBatteryStatus
Properties3
Class Properties
averageCurrentConsumptionrefreshIntervaltripDuration
Examples2
Retrieve the Battery statusWorking with the Battery indicator
Remarks3
Icon LayoutOverlapping IndicatorsScreen Orientation

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"

Note: 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.

Persistence

With the old PocketBrowser / RhoElements 1 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
(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’. In Android, Currently supported only on the MC18 device

(Currently supported only 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. 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

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

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.

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 "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      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

      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

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

      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

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.

(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 that cover the system battery level indicator.

(All platforms support batteryStatus, which can be used to draw your own level indicator or display an appropriate graphic.)

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 "::" for all "." when referencing constants)
      String:left

      See the remarks section for illustrations of icon layout.

      Constant: Rho::Battery.BATTERY_LAYOUT_RIGHT (For Ruby use "::" for all "." when referencing constants)
      String:right

      See the remarks section for illustrations of icon layout.

      Constant: Rho::Battery.BATTERY_LAYOUT_UP (For Ruby use "::" for all "." when referencing constants)
      String:up

      See the remarks section for illustrations of icon layout.

      Constant: Rho::Battery.BATTERY_LAYOUT_DOWN (For Ruby use "::" for all "." when referencing constants)
      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.

(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 "::" for all "." when referencing constants)
      String:Constant: Rho::Battery.SMART_BATTERY_HEALTHY (For Ruby use "::" for all "." when referencing constants)
      String:healthy

      The battery is healthy.

      Constant: Rho.Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" for all "." when referencing constants)
      String:Constant: Rho::Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" for all "." when referencing constants)
      String:unhealthy

      The battery is unhealthy.

      Constant: Rho.Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" for all "." when referencing constants)
      String:Constant: Rho::Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" for all "." when referencing constants)
      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 "::" for all "." when referencing constants)
      String:healthy

      The battery is healthy.

      Constant: Rho::Battery.SMART_BATTERY_UNHEALTHY (For Ruby use "::" for all "." when referencing constants)
      String:unhealthy

      The battery is unhealthy.

      Constant: Rho::Battery.SMART_BATTERY_UNKNOWN (For Ruby use "::" for all "." when referencing constants)
      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.

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

averageCurrentConsumption
: INTEGER

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.

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.

Default: 5000

Property Access:

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

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.

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 interested only 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

  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 level, then you can register to receive values through a callback

  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.

  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.

  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.