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

Battery

Methods 5  
Properties 1
Examples 2
Remarks 3
Licensing

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"

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

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 concerve 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 :

      Battery.BATTERY_TRIGGER_PERIODIC - (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.
      Battery.BATTERY_TRIGGER_SYSTEM - (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 WP8 you are notified every percentage value change but 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 value between 0 and 100. Only supported on Zebra 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 dependant. 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, Android

    • batteryLifeKnown : BOOLEAN

      Only supported on Zebra 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 Zebra 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 value between 0 and 100. Only supported on Zebra 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 dependant. 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, Android

    • batteryLifeKnown : BOOLEAN

      Only supported on Zebra 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 Zebra 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 which 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 :

      Battery.BATTERY_LAYOUT_LEFT - (left)
      See the remarks section for illustrations of icon layout.
      Battery.BATTERY_LAYOUT_RIGHT - (right)
      See the remarks section for illustrations of icon layout.
      Battery.BATTERY_LAYOUT_UP - (up)
      See the remarks section for illustrations of icon layout.
      Battery.BATTERY_LAYOUT_DOWN - (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 Zebra 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 Zebra 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 accuratley 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 :

      Battery.SMART_BATTERY_HEALTHY - (Battery.SMART_BATTERY_HEALTHY - (healthy))
      The battery is healthy
      Battery.SMART_BATTERY_UNHEALTHY - (Battery.SMART_BATTERY_UNHEALTHY - (unhealthy))
      The battery is unhealthy
      Battery.SMART_BATTERY_UNKNOWN - (Battery.SMART_BATTERY_UNKNOWN - (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 Zebra 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 accuratley 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 :

      Battery.SMART_BATTERY_HEALTHY - (healthy)
      The battery is healthy
      Battery.SMART_BATTERY_UNHEALTHY - (unhealthy)
      The battery is unhealthy
      Battery.SMART_BATTERY_UNKNOWN - (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 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

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

  • Class: This property can only be accessed via the API class object.
    • JavaScript: Rho.Battery.refreshInterval
    • Ruby: Rho::Battery.refreshInterval

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

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.