Obtener información sobre la batería

Artículo
07/05/2024

En este tema se describe cómo obtener un informe de batería que incluye información detallada de la batería (como la carga, la capacidad y el estado de una batería o un agregado de baterías) y controlar los cambios de estado en los elementos del informe.

(BatteryReport)

Los ejemplos de código proceden de la aplicación de batería básica que aparece al final de este tema.

API importantes

Obtención del informe de batería agregada

Algunos dispositivos tienen más de una batería y no siempre es obvio cómo cada batería contribuye a la capacidad de energía general del dispositivo. Aquí es donde entra la clase AggregateBattery. La batería agregada representa todos los controladores de batería conectados al dispositivo y puede proporcionar un único objeto BatteryReport general.

Nota Una clase Battery corresponde realmente a un controlador de batería. Dependiendo del dispositivo, a veces el controlador está conectado a la batería física y a veces está conectado al gabinete del dispositivo. Por lo tanto, es posible crear un objeto de batería incluso cuando no haya baterías presentes. Otras veces, el objeto de batería puede ser null.

Una vez que tenga un objeto de batería agregada, llame a GetReport para obtener el objeto BatteryReport correspondiente.

private void RequestAggregateBatteryReport()
{
    // Create aggregate battery object
    var aggBattery = Battery.AggregateBattery;

    // Get report
    var report = aggBattery.GetReport();

    // Update UI
    AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
}

Obtención de informes de batería individuales

También puede crear un objeto BatteryReport para baterías individuales. Use GetDeviceSelector con el método FindAllAsync para obtener una colección de objetos DeviceInformation que representan los controladores de batería que están conectados al dispositivo. A continuación, mediante la propiedad Id del objeto DeviceInformation deseado, cree una batería correspondiente con el método FromIdAsync. Por último, llame a GetReport para obtener el informe de batería individual.

En este ejemplo se muestra cómo crear un informe de batería para todas las baterías conectadas al dispositivo.

async private void RequestIndividualBatteryReports()
{
    // Find batteries 
    var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
    foreach(DeviceInformation device in deviceInfo)
    {
        try
        {
        // Create battery object
        var battery = await Battery.FromIdAsync(device.Id);

        // Get report
        var report = battery.GetReport();

        // Update UI
        AddReportUI(BatteryReportPanel, report, battery.DeviceId);
        }
        catch { /* Add error handling, as applicable */ }
    }
}

Obtener acceso a los detalles del informe

El objeto BatteryReport proporciona mucha información de batería. Para obtener más información, consulta la referencia de API para sus propiedades: Status (una enumeración BatteryStatus), ChargeRateInMilliwatts, DesignCapacityInMilliwattHours, FullChargeCapacityInMilliwattHours y RemainingCapacityInMilliwattHours. En este ejemplo se muestran algunas de las propiedades del informe de batería usadas por la aplicación de batería básica, que se proporciona más adelante en este tema.

...
TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };
...
...

Solicitud de actualizaciones de informes

El objeto Battery desencadena el evento ReportUpdated cuando cambia la carga, la capacidad o el estado de la batería. Esto suele ocurrir inmediatamente para los cambios de estado y periódicamente para todos los demás cambios. En este ejemplo se muestra cómo registrarse para las actualizaciones del informe de batería.

...
Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
...

Control de las actualizaciones de informes

Cuando se produce una actualización de batería, el evento ReportUpdated pasa el objeto Battery correspondiente al método del controlador de eventos. Sin embargo, no se llama a este controlador de eventos desde el subproceso de la interfaz de usuario. Deberá usar el objeto Dispatcher para invocar los cambios de la interfaz de usuario, como se muestra en este ejemplo.

async private void AggregateBattery_ReportUpdated(Battery sender, object args)
{
    if (reportRequested)
    {

        await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }
        });
    }
}

Ejemplo: aplicación de batería básica

Pruebe estas API mediante la compilación de la siguiente aplicación básica de batería en Microsoft Visual Studio. En la página de inicio de Visual Studio, haga clic en Nuevo proyecto y, a continuación, en las plantillas universales de Windows > de Visual C#>, cree una nueva aplicación con la plantilla Aplicación en blanco.

A continuación, abra el archivo MainPage.xaml y copie el siguiente XML en este archivo (reemplazando su contenido original).

Nota:

Si la aplicación no se denomina App1, deberá reemplazar la primera parte del nombre de clase en el fragmento de código siguiente por el espacio de nombres de la aplicación. Por ejemplo, si creó un proyecto denominado BasicBatteryApp, reemplace por x:Class="App1.MainPage" x:Class="BasicBatteryApp.MainPage" y xmlns:local="using:App1" por xmlns:local="using:BasicBatteryApp".

<Page
    x:Class="App1.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App1"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">

    <StackPanel Background="{ThemeResource ApplicationPageBackgroundThemeBrush}" >
        <StackPanel VerticalAlignment="Center" Margin="15,30,0,0" >
            <RadioButton x:Name="AggregateButton" Content="Aggregate results" GroupName="Type" IsChecked="True" />
            <RadioButton x:Name="IndividualButton" Content="Individual results" GroupName="Type" IsChecked="False" />
        </StackPanel>
        <StackPanel Orientation="Horizontal">
        <Button x:Name="GetBatteryReportButton" 
                Content="Get battery report" 
                Margin="15,15,0,0" 
                Click="GetBatteryReport"/>
        </StackPanel>
        <StackPanel x:Name="BatteryReportPanel" Margin="15,15,0,0"/>
    </StackPanel>
</Page>

A continuación, abra el archivo MainPage.xaml.cs del proyecto y reemplace el código existente por lo siguiente.

Nota:

Si la aplicación no se denomina App1, deberá cambiar el nombre del espacio de nombres en el ejemplo siguiente con el nombre que asignó al proyecto. Por ejemplo, si creó un proyecto denominado BasicBatteryApp, reemplazaría el espacio de nombres App1 por el espacio de nombres BasicBatteryApp.

using System;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Media;
using Windows.Devices.Enumeration;
using Windows.Devices.Power;
using Windows.UI.Core;

namespace App1
{
    public sealed partial class MainPage : Page
    {
        bool reportRequested = false;
        public MainPage()
        {
            this.InitializeComponent();
            Battery.AggregateBattery.ReportUpdated += AggregateBattery_ReportUpdated;
        }


        private void GetBatteryReport(object sender, RoutedEventArgs e)
        {
            // Clear UI
            BatteryReportPanel.Children.Clear();


            if (AggregateButton.IsChecked == true)
            {
                // Request aggregate battery report
                RequestAggregateBatteryReport();
            }
            else
            {
                // Request individual battery report
                RequestIndividualBatteryReports();
            }

            // Note request
            reportRequested = true;
        }

        private void RequestAggregateBatteryReport()
        {
            // Create aggregate battery object
            var aggBattery = Battery.AggregateBattery;

            // Get report
            var report = aggBattery.GetReport();

            // Update UI
            AddReportUI(BatteryReportPanel, report, aggBattery.DeviceId);
        }

        async private void RequestIndividualBatteryReports()
        {
            // Find batteries 
            var deviceInfo = await DeviceInformation.FindAllAsync(Battery.GetDeviceSelector());
            foreach(DeviceInformation device in deviceInfo)
            {
                try
                {
                // Create battery object
                var battery = await Battery.FromIdAsync(device.Id);

                // Get report
                var report = battery.GetReport();

                // Update UI
                AddReportUI(BatteryReportPanel, report, battery.DeviceId);
                }
                catch { /* Add error handling, as applicable */ }
            }
        }


        private void AddReportUI(StackPanel sp, BatteryReport report, string DeviceID)
        {
            // Create battery report UI
            TextBlock txt1 = new TextBlock { Text = "Device ID: " + DeviceID };
            txt1.FontSize = 15;
            txt1.Margin = new Thickness(0, 15, 0, 0);
            txt1.TextWrapping = TextWrapping.WrapWholeWords;

            TextBlock txt2 = new TextBlock { Text = "Battery status: " + report.Status.ToString() };
            txt2.FontStyle = Windows.UI.Text.FontStyle.Italic;
            txt2.Margin = new Thickness(0, 0, 0, 15);

            TextBlock txt3 = new TextBlock { Text = "Charge rate (mW): " + report.ChargeRateInMilliwatts.ToString() };
            TextBlock txt4 = new TextBlock { Text = "Design energy capacity (mWh): " + report.DesignCapacityInMilliwattHours.ToString() };
            TextBlock txt5 = new TextBlock { Text = "Fully-charged energy capacity (mWh): " + report.FullChargeCapacityInMilliwattHours.ToString() };
            TextBlock txt6 = new TextBlock { Text = "Remaining energy capacity (mWh): " + report.RemainingCapacityInMilliwattHours.ToString() };

            // Create energy capacity progress bar & labels
            TextBlock pbLabel = new TextBlock { Text = "Percent remaining energy capacity" };
            pbLabel.Margin = new Thickness(0,10, 0, 5);
            pbLabel.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            ProgressBar pb = new ProgressBar();
            pb.Margin = new Thickness(0, 5, 0, 0);
            pb.Width = 200;
            pb.Height = 10;
            pb.IsIndeterminate = false;
            pb.HorizontalAlignment = HorizontalAlignment.Left;

            TextBlock pbPercent = new TextBlock();
            pbPercent.Margin = new Thickness(0, 5, 0, 10);
            pbPercent.FontFamily = new FontFamily("Segoe UI");
            pbLabel.FontSize = 11;

            // Disable progress bar if values are null
            if ((report.FullChargeCapacityInMilliwattHours == null)||
                (report.RemainingCapacityInMilliwattHours == null))
            {
                pb.IsEnabled = false;
                pbPercent.Text = "N/A";
            }
            else
            {
                pb.IsEnabled = true;
                pb.Maximum = Convert.ToDouble(report.FullChargeCapacityInMilliwattHours);
                pb.Value = Convert.ToDouble(report.RemainingCapacityInMilliwattHours);
                pbPercent.Text = ((pb.Value / pb.Maximum) * 100).ToString("F2") + "%";
            }

            // Add controls to stackpanel
            sp.Children.Add(txt1);
            sp.Children.Add(txt2);
            sp.Children.Add(txt3);
            sp.Children.Add(txt4);
            sp.Children.Add(txt5);
            sp.Children.Add(txt6);
            sp.Children.Add(pbLabel);
            sp.Children.Add(pb);
            sp.Children.Add(pbPercent);
        }

        async private void AggregateBattery_ReportUpdated(Battery sender, object args)
        {
            if (reportRequested)
            {

                await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
                {
                    // Clear UI
                    BatteryReportPanel.Children.Clear();


                    if (AggregateButton.IsChecked == true)
                    {
                        // Request aggregate battery report
                        RequestAggregateBatteryReport();
                    }
                    else
                    {
                        // Request individual battery report
                        RequestIndividualBatteryReports();
                    }
                });
            }
        }
    }
}

Sugerencia

Para recibir valores numéricos del objeto BatteryReport, depure la aplicación en el equipo local o en un dispositivo externo. Al depurar en un emulador de dispositivo, el objeto BatteryReport devuelve null a las propiedades de capacidad y velocidad.

Compartir a través de