Moto Z Software: Mod Battery

Introduction

Support for Battery and power-providing Moto Mod is integrated natively with the Moto Mod platform. Your Moto Z will automatically leverage an attached Moto Mod battery, based on its declared type, without requiring you to provide an application or use the ModBattery Android API.

The Moto Mod Android SDK enables a developer which needs additional information about an attached Moto Mod battery to recognize when an attached Moto Mod has a battery, determine the type of this battery, query the battery capacity and get topical information about its this Moto Mod battery charge level and charging status.

An application can obtain information about a Moto Mod battery through the methods exposed by the Moto Mod SDK’s ModBattery class.


Prerequisites

Android Prerequisites

Development environment

Before using the classes described below in your application, you must have installed the Moto Mod Android SDK on your development device as described in the tool section.

Familiarity with the Android BatteryManager

You should be familiar with the Android BatteryManager API, as the Moto Mod specific battery information returned by the ModBattery class closely follows the conventions of Android’s BatteryManager.

Familiarity with the PTP and Battery Firmware documentation

The Power Transfer and Battery firmware developer documentation provide fine-grain control over battery and power-provider configuration. The behavior of a Moto Mod battery will vary based on its PTP configuration and the Moto Mod developer interesting in issuing, or building a power-providing Moto Mod should gain a solid understanding of these protocols first.

Hardware Prerequisites

Battery specific functions exposed through the Moto Mod Android SDK will only be available if a Moto Mod is attached to your smartphone, if the attached Moto Mod has a well-formed hardware manifest, and if it declares support for the battery and power-transfer-protocol Greybus class.


Supported Mod Battery type

A Moto Mod can embed its own battery. When a Moto Mod is attached to a smartphone, the charge and discharge behavior of the Moto Mod battery is controlled by its firmware Battery and Power-transfer protocol configuration, as described in the Power Transfer and Battery firmware developer documentation.

The platform supports different Moto Mod power-provider/battery profiles. A Moto Mod battery must declare its supported profile in the firmware. The device will automatically make optimal use of the battery based on this profile declaration. The supported battery profiles are:

  • The Moto Mod declares its battery as a SUPPLEMENTAL battery. Your Moto Mod should use this profile when it hosts a battery which primary function is to keep your Moto Z powered (e.g: the Moto Mod is a battery pack).

  • The Moto Mod declares its battery as a REMOTE (or ‘NEVER‘ as defined at the Power Transfer firmware page) battery. Your Moto Mod should use this profile when it hosts a battery which sole function is to provide power to the Moto Mod, and never to a Moto Z.

  • The Moto Mod declares its battery as a REMOTE EMERGENCY (or ‘LOW POWER SAVER’ at the Power Transfer firmware page) battery. Your Moto Mod should use this profile when it hosts a battery which primary function is to provide power to the Moto Mod but could be used to power a Moto Z when the smartphone battery gets low.

The Moto Mod could also elect, through its Power-Transfer protocol definition, to not receive or provide power to the attached Moto Z. The Moto Mod will need to include its own charging apparatus. The functionality of a Moto Mod battery is automatically controlled by the Moto Z software and based on the battery type declared by the Moto Mod firmware upon attach, an application can not change the advertised battery type of a Moto Mod. The Moto Mod SDK only enables any application to track charge, discharge and information about a Moto Mod battery.


Standard Battery behavior 

The user experience on a Moto Z will vary slightly based on the declared battery profile. This section provides a short overview of the behavioral differences experienced on a Moto Z when different types of Moto Mod batteries are attached.

A Moto Mod battery provides power to Moto Z A charging Moto Z can charge the Moto Mod battery The status bar indicates when Moto Mod is providing power to Moto Z Moto Z Settings and Quick settings show the charge level of the Moto Mod battery
SUPPLEMENTAL Yes, to keep the Moto Z charged Yes Yes Yes
REMOTE (‘NEVER’) No Yes No Yes
EMERGENCY (‘Low power saver’) Yes, buy only when the Moto Z battery is Low Yes Yes Yes

Top-Off vs. Efficiency mode

Under the Moto Mod settings for a battery, the user can choose to set a supplemental battery usage policy to “top-off” or “efficiency” through Moto Mod settings. 

  • In the default mode (the default usage policy of a battery), your Moto Z will use a supplemental battery to always stay fully charged (100%) as long as the Moto Mod battery can provide power.
  • In EFFICIENCY mode, your Moto Z will leverage the attached supplemental battery optimally, and will stay charged at 80% (not 100%) as long as the Moto Mod battery can provide power

Working with a Moto Mod Battery: Added ModBattery Class

The Moto Mod SDK provides an additional ModBattery class which enables an application to know what the declared battery profile of the attached Moto Mod battery is, query the capacity, charge level and charging status of a Moto Mod battery.

Determining whether the attached ModDevice embeds a battery

To detect when a Moto Mod is attached, your application should listen on Moto Mod ACTION_MOD_ATTACH and ACTION_MOD_DETACH intents - or register a ModListener - as described at the Mod Management page. Once a Moto Mod is attached to your device, an application can use the ModDevice.hasDeclaredProtocol() function to check whether the attached ModDevice declares the BATTERY and PTP (power transfer) protocol.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    // We know this device has a battery and supports battery metering
    }

if (device.hasDeclaredProtocol(ModProtocol.Protocol.PTP)) {
    // We know this device can provide or receive power to the Moto Z
    }

The state and level of this Moto Mod battery will be automatically reported by the ModBattery class and its associated method. ModBattery will only be available when a battery device is present and has enumerated successfully. As the power transfer logic between the Moto Mod and and the Moto Z is automatically controlled by the Moto Z, there are no exposed functions for an application to change this predefined behavior.

Working with the ModBattery Class

If an attached Moto Mod supports the BATTERY protocol, and your application wants to get information about this Moto Mod battery, it must first acquire a ModBattery object by calling the ModManager.getClassManager() function, after your application verified that a ModDevice is attached and that this ModDevice supports the battery protocol.

The code sample below shows how to get access to the ModBattery class from the ModManager. Your application should first confirm that the attached Moto Mod declares support for the PTP and BATTERY protocols, as shown above.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    ModBattery mb = (ModBattery)mManager.getClassManager(modDev,
    ModProtocol.Protocol.BATTERY);
    ...
    }

Getting the Moto Mod Battery Capacity

When a battery Moto Mod is attached, an Android application can determine the maximum capacity of the attached Moto Mod battery by calling the ModBattery.getBatteryCapacity() method. This method will return the capacity of the attached battery in mAH, or Long.MIN_VALUE if the Moto Mod did not return its capacity through greybus.

The code sample below shows how to retrieve the Moto Mod battery capacity.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    ModBattery mb = (ModBattery)mManager.getClassManager(modDev,
    ModProtocol.Protocol.BATTERY);
    if (mb != null) {
      modbatterycapacity = mb.getBatteryCapacity();

Getting the Moto Mod Battery Level

When a battery Moto Mod is attached, an Android application can track changes in the battery charge level by using the ModBattery.getBatteryLevel() method. This method will return the charge level of the attached battery as a percentage (0-100).

The code sample below shows how to retrieve the Moto Mod battery level.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    ModBattery mb = (ModBattery)mManager.getClassManager(modDev,
    ModProtocol.Protocol.BATTERY);
    if (mb != null) {
      modbatterylevel = mb.getBatteryLevel(); 
      // we know what the battery level is

Determining the declared type of the attached Moto Mod battery

The ModBattery.getBatteryType() method returns the type of the battery on the Moto Mod. ModBattery.getBatteryType() will return either BATTERY_USAGE_TYPE_SUPPLEMENTAL, BATTERY_USAGE_TYPE_REMOTE, BATTERY_USAGE_TYPE_EMERGENCY or BATTERY_USAGE_TYPE_UNKNOWN.

The code sample below shows how to retrieve the Moto Mod battery type.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    ModBattery mb = (ModBattery)mManager.getClassManager(modDev,
    ModProtocol.Protocol.BATTERY);
    if (mb != null) {
      modbatterytype = mb.getBatteryType();

Determining whether a ModBattery is charging or discharging

The ModBattery.getBatteryStatus() method enables your application to determine whether the battery on the Moto Mod is charging or discharging. A Moto Mod battery could be charging when your Moto Z is plugged in a USB-C charger, or when the Moto Mod itself has its own charging apparatus and is attached to a charger.

The value returned by ModBattery.getBatteryStatus() follows the convention set forth by Android for reporting device battery charge status. An application can use this value to determine whether the Moto Mod battery is charging, discharging or full.

if (device.hasDeclaredProtocol(ModProtocol.Protocol.BATTERY)) {
    ModBattery mb = (ModBattery)mManager.getClassManager(modDev,
    ModProtocol.Protocol.BATTERY);
    if (mb != null) {
      modbatterystatus = mb.getBatteryStatus();
Returned Constant Value Details
BATTERY_STATUS_UNKNOWN 1 The Mod Battery status is not known
BATTERY_STATUS_CHARGING 2 The Mod Battery is charging
BATTERY_STATUS_DISCHARGING 3 The Mod Battery is discharging
BATTERY_STATUS_NOT_CHARGING 4 The Mod Battery is not charging
BATTERY_STATUS_FULL 5 The Mod Battery is full

Determining whether your Moto Z is charging from an attached Moto Mod

The ModBattery.isPlugTypeMod() method enables your application to determine whether the attached Moto Mod can charge the phone. ModManager.isPlugTypeMod() will return true if no external charger is attached and the device can be charged from the Moto Mod battery.


When a battery reports issues

If a Moto Mod embeds a battery, the Moto Mod is responsible for thermal mitigation and reporting errors to the smartphone. Motorola has defined a vendor specific channel to report asynchronous Moto Mod errors, including thermal, current and oem specific data.

An application which needs to listen for these sudden capabilities change (as an example, a thermal incident on the Moto Mod causing the Moto Mod to report it is operating in a reduced state) can register a ModListener (as described below).

This listener onCapabilityChanged() function will be called back when the Moto Mod reports a capability change event. An application can then use the ModManager.getCapabilityLevel() and ModManager.getCapabilityReason() to determine the cause of this capability change, as described in the Mod Management software and Mod Management firmware documents.

An application which needs to be immediately informed of capability change on an attached battery should register a listener with the com.motorola.mod.ModManager.registerModListener() API.

mManager.registerModListener(MainActivity.this, new int[] {ModProtocol.BATTERY});

More Information

For more information, see the ModBattery Javadoc API.