Battery

Article
11/29/2023

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IBattery interface to check the device's battery information and monitor for changes. This interface also provides information about the device's energy-saver status, which indicates if the device is running in a low-power mode.

The default implementation of the IBattery interface is available through the Battery.Default property. Both the IBattery interface and Battery class are contained in the Microsoft.Maui.Devices namespace.

Get started

To access the Battery functionality the following platform-specific setup is required.

The BatteryStats permission is required and must be configured in the Android project. You can configure the permission in the following ways:

Add the assembly-based permission:

Open the Platforms/Android/MainApplication.cs file and add the following assembly attribute after using directives:
```
[assembly: UsesPermission(Android.Manifest.Permission.BatteryStats)]
```
- or -
Update the Android Manifest:

Open the Platforms/Android/AndroidManifest.xml file and add the following line in the manifest node:
```
<uses-permission android:name="android.permission.BATTERY_STATS" />
```
- or -
Update the Android Manifest in the manifest editor:

In Visual Studio double-click on the Platforms/Android/AndroidManifest.xml file to open the Android manifest editor. Then, under Required permissions check the BATTERY_STATS permission. This will automatically update the AndroidManifest.xml file.

Check the battery status

The battery status can be checked by accessing the Battery.Default property, which is the default implementation of the IBattery interface. This interface defines various properties to provide information about the state of the battery, such as ChargeLevel to read how much battery is left. The ChargeLevel property returns a value between 0.0 and 1.0, indicating the battery's charge level from empty to full, respectively.

The BatteryInfoChanged event is also available, and is raised when the state of the battery changes. The following example demonstrates how to use the monitor the BatteryInfoChanged event and report the battery status to Label controls:

private void BatterySwitch_Toggled(object sender, ToggledEventArgs e) =>
    WatchBattery();

private bool _isBatteryWatched;

private void WatchBattery()
{
    
    if (!_isBatteryWatched)
    {
        Battery.Default.BatteryInfoChanged += Battery_BatteryInfoChanged;
    }
    else
    {
        Battery.Default.BatteryInfoChanged -= Battery_BatteryInfoChanged;
    }

    _isBatteryWatched = !_isBatteryWatched;
}

private void Battery_BatteryInfoChanged(object sender, BatteryInfoChangedEventArgs e)
{
    BatteryStateLabel.Text = e.State switch
    {
        BatteryState.Charging => "Battery is currently charging",
        BatteryState.Discharging => "Charger is not connected and the battery is discharging",
        BatteryState.Full => "Battery is full",
        BatteryState.NotCharging => "The battery isn't charging.",
        BatteryState.NotPresent => "Battery is not available.",
        BatteryState.Unknown => "Battery is unknown",
        _ => "Battery is unknown"
    };
    
    BatteryLevelLabel.Text = $"Battery is {e.ChargeLevel * 100}% charged.";
}

Low-power energy-saver mode

Devices that run on batteries can be put into a low-power energy-saver mode. Sometimes devices are switched into this mode automatically, like when the battery drops below 20% capacity. The operating system responds to energy-saver mode by reducing activities that tend to deplete the battery. Applications can help by avoiding background processing or other high-power activities when energy-saver mode is on.

Important

Applications should avoid background processing if the device's energy-saver status is on.

The energy-saver status of the device can be read by accessing the EnergySaverStatus property, which is either On, Off, or Unknown. If the status is On, the application should avoid background processing or other activities that may consume a lot of power.

The battery raises the EnergySaverStatusChanged event when the battery enters or leaves energy-saver mode. You can also obtain the current energy-saver status of the device using the EnergySaverStatus property:

The following code example monitors the energy-saver status and sets a property accordingly.

private bool _isBatteryLow = false;

private void BatterySaverSwitch_Toggled(object sender, ToggledEventArgs e)
{
    // Capture the initial state of the battery
    _isBatteryLow = Battery.Default.EnergySaverStatus == EnergySaverStatus.On;
    BatterySaverLabel.Text = _isBatteryLow.ToString();

    // Watch for any changes to the battery saver mode
    Battery.Default.EnergySaverStatusChanged += Battery_EnergySaverStatusChanged;
}

private void Battery_EnergySaverStatusChanged(object sender, EnergySaverStatusChangedEventArgs e)
{
    // Update the variable based on the state
    _isBatteryLow = Battery.Default.EnergySaverStatus == EnergySaverStatus.On;
    BatterySaverLabel.Text = _isBatteryLow.ToString();
}

Power source

The PowerSource property returns a BatteryPowerSource enumeration that indicates how the device is being charged, if at all. If it's not being charged, the status is BatteryPowerSource.Battery. The BatteryPowerSource.AC, BatteryPowerSource.Usb, and BatteryPowerSource.Wireless values indicate that the battery is being charged.

The following code example sets the text of a Label control based on power source.

private void SetChargeModeLabel()
{
    BatteryPowerSourceLabel.Text = Battery.Default.PowerSource switch
    {
        BatteryPowerSource.Wireless => "Wireless charging",
        BatteryPowerSource.Usb => "USB cable charging",
        BatteryPowerSource.AC => "Device is plugged in to a power source",
        BatteryPowerSource.Battery => "Device isn't charging",
        _ => "Unknown"
    };
}

Platform differences

This section describes the platform-specific differences with the battery.

No platform differences.