https://github.com/nikvoronin/xm4battery
Battery level of WH-1000XM4 headphones. Based on WMI wrapper for Plug-n-Play devices
https://github.com/nikvoronin/xm4battery
battery-level battery-monitor bluetooth csharp dotnet plug-and-play plug-n-play wf-1000xm4 wh-1000xm3 wh-1000xm4 windows winforms-desktop-application wmi wmi-query
Last synced: about 1 year ago
JSON representation
Battery level of WH-1000XM4 headphones. Based on WMI wrapper for Plug-n-Play devices
- Host: GitHub
- URL: https://github.com/nikvoronin/xm4battery
- Owner: nikvoronin
- License: gpl-3.0
- Created: 2023-02-18T20:12:00.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-03-23T21:28:37.000Z (about 1 year ago)
- Last Synced: 2025-03-23T22:31:20.206Z (about 1 year ago)
- Topics: battery-level, battery-monitor, bluetooth, csharp, dotnet, plug-and-play, plug-n-play, wf-1000xm4, wh-1000xm3, wh-1000xm4, windows, winforms-desktop-application, wmi, wmi-query
- Language: C#
- Homepage:
- Size: 152 KB
- Stars: 11
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Xm4Battery
--over WMI for plug-and-play devices
> WMI = Windows Management Interface.
The primary goal of the project is to get battery level of `WH-1000XM4` headphones. Perhaps `Xm4Battery` might also works with similar models of headphones such as WH-1000XM3, WF-1000XM3 or WF-1000XM4.
- [Desktop Application](#desktop-application)
- [User interface](#user-interface)
- [Tray icon mods](#tray-icon-mods)
- [Xm4Poller](#xm4poller)
- [Start and stop device polling](#start-and-stop-device-polling)
- [Xm4State](#xm4state)
- [Xm4Entity](#xm4entity)
- [Create XM4 instance](#create-xm4-instance)
- [Is connected or not?](#is-connected-or-not)
- [What was the last connected time?](#what-was-the-last-connected-time)
- [Headphones battery level](#headphones-battery-level)
- [Re/Connect already paired](#reconnect-already-paired)
- [PnpEntity](#pnpentity)
- [How To find PNP-device?](#how-to-find-pnp-device)
- [Get and update a specific property of a device](#get-and-update-a-specific-property-of-a-device)
- [Enumerate all properties of device](#enumerate-all-properties-of-device)
- [Enable or disable device](#enable-or-disable-device)
- [Device specific properties](#device-specific-properties)
- [XM4 related properties](#xm4-related-properties)
- [Windows Radio](#windows-radio)
- [References](#references)
## Desktop Application
The Windows Forms, trayiconed and window-less application at once.\
Ready to run app is available under the [Latest Release](https://github.com/nikvoronin/WmiPnp/releases/latest) section.
__System requirements:__ Windows 10 x64, [.NET Desktop Runtime 8.0](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
| Headphones | Win 10 | Win 11 |
| ----------- | ------ | ------- |
| WH-1000_XM4 | Yes | Yes |
| WH-1000_XM3 | Yes | Unknown |
### User interface
- __F__ - 100% fully charged
- __4..9__ - 40..90%
- __3__ yellow - 30%
- __2__ orange - 20%
- __!__ red - 10%
- __X__ - headphones disconnected.
- __%__ - headphones disconnected, the last known battery level was low (30% or lower).
When headphones are disconnected, a tooltip displays the last known battery level and the last known date/time of the headphone connection.
`Right Mouse Button` opens a context menu:
- Connect - tries connect already paired headphones. ⚠
- Disconnect - tries disconnect headphones (not unpair, just disconnect). ⚠
- About - leads to this page.
- Quit - closes and unloads application at all.
>⚠ __Connect / Disconnect__ items appear if the app is run as an administrator.\
>⚠ These functions may cause system artefacts or unusual behavior of Volume Control, Sound Mixer, Bluetooth Device Manager, etc.\
>⚠ Especially the Disconnect item. Connect is a law-abiding one.
### Tray icon mods
The real icon size is 256x256 pixels. It is automatically scaled by system depend on display scaling factor.
>The app icon is currently adjusted to 125% display scale. Other scale factors may lead to uglifying tray icon.
Icon text color and background are defined in the `CreateXmIcon` method:
```csharp
// icon background color
var iconBackgroundBrush =
uiBatteryLevel switch {
<= DisconnectedLevel => Brushes.Transparent,
<= CriticalPowerLevel => Brushes.Red,
<= LowPowerLevel => Brushes.Orange,
<= WarningPowerLevel => Brushes.Yellow,
_ => Brushes.White // 40..100(F)
};
// icon text color
var iconTextBrush =
uiBatteryLevel switch {
<= DisconnectedLevel => Brushes.WhiteSmoke,
<= CriticalPowerLevel => Brushes.White,
//<= LowPowerLevel => Brushes.Magenta,
//<= WarningLevel => Brushes.Cyan,
_ => Brushes.Black
};
```
Font of the notification icon text (battery level or headphones status):
```csharp
static readonly Font _notifyIconFont =
new( "Segoe UI", 124, FontStyle.Regular );
```
## Xm4Poller
Automatically updates status of headphones.
### Start and stop device polling
```csharp
var xm4result = Xm4Entity.Create();
if ( xm4result.IsFailed ) return 1;
Xm4Entity xm4 = xm4result.Value;
var statePoller = new Xm4Poller (
xm4,
( previousState, newState ) => {
// this handler is called when xm4 state changed:
// connection status or/and battery charge level.
// previousState <> newState - always unequal!
UpdateUi_ForExample(newState);
} );
statePoller.Start();
// starts main loop of window-less WinForms app
Application.Run();
// application was closed, quit
statePoller.Stop();
```
### Xm4State
```csharp
namespace WmiPnp.Xm4;
public record Xm4State
{
public bool Connected // true if connected, false - otherwise.
public int BatteryLevel // battery charge level
```
## Xm4Entity
### Create XM4 instance
```csharp
var xm4result = Xm4Entity.CreateDefault();
if ( xm4result.IsFailed ) return; // headphones did not found at all
Xm4Entity _xm4 = xm4result.Value;
```
### Is connected or not?
```csharp
...
bool connected = _xm4.IsConnected;
```
### What was the last connected time?
We don't know how to get the last connected time if headphones is online and already connected. This property is valid only if headphones are DISconnected.
```csharp
Result dt = _xm4.LastConnectedTime;
```
```csharp
bool disconnected = !_xm4.IsConnected;
if ( disconnected )
Console.WriteLine( $"Last connected time: {_xm4.LastConnectedTime.Value}.\n" );
else
var it_is_true = _xm4.LastConnectedTime.IsFailed; // can not get the last connected time
```
### Headphones battery level
It can get the actual battery level if headphones are connected. Otherwise, headphones are DISconnected, it returns the last known level.
```csharp
int level = _xm4.BatteryLevel;
```
### Re/Connect already paired
When headphones are used with multiple sources (laptop, pc, smartphone, etc) you have to reconnect headphones from time to time. So headphones are already paired but disconnected. In this case `WmiPnp` has experimental `Xm4Entity.TryConnect()` and very unstable `Xm4Entity.TryDisconnect()`. Both want the application run as administrator. Otherwise these functions are ignored.
If you are curious to find out about turn off bluetooth at all, see topic about [Windows Radio](#windows-radio).
## PnpEntity
First, we should know a `name` or `device id` of the device we are working with or at least a part of the device name.
- ByFriendlyName - exact a friendly name.
- ByDeviceId - exact a device id, like `{GUID} pid`.
- FindByFriendlyName - a part of a friendly name. Returns a list of founded devices `IEnumerable` or empty list otherwise.
- FindByNameForExactClass - same as `FindByFriendlyName` but with exact class name equality.
- EntityOrNone - a `where` part of WQL request to retrieve exact a single device only.
- EntitiesOrNone - a `where` part of WQL request to retrieve zero, one or several devices at once.
All of methods produce instances of `PnpEntity` or `Result.Fail` if the given device was not found.
### How To find PNP-device?
```csharp
Result result =
PnpEntity.ByFriendlyName( "The Bluetooth Device #42" );
if ( result.IsSuccess ) { // device found
PnpEntity btDevice = result.Value;
...
}
```
### Get and update a specific property of a device
```csharp
...
PnpEntity btDevice = result.Value;
while ( !Console.KeyAvailable ) {
Result propertyResult =
btDevice.GetDeviceProperty(
Xm4Entity.DeviceProperty_IsConnected );
if ( propertyResult.IsSuccess ) {
DeviceProperty dp = propertyResult.Value;
bool connected = (bool)(dp.Data ?? false);
Console.WriteLine(
$"{btDevice.Name} is {(connected ? "connected" : "disconnected")}" );
}
// wait a little before the next attempt
Thread.Sleep( TimeSpan.FromSeconds( 1 ) );
}
```
### Enumerate all properties of device
```csharp
...
PnpEntity btDevice = result.Value;
IEnumerable properties = btDevice.GetProperties();
foreach( var p in properties ) {
Console.WriteLine( $"{p.KeyName}: {p.Data}" );
...
}
```
### Enable or disable device
Some devices could be enabled or disabled.
```csharp
...
PnpEntity btDevice = result.Value;
btDevice.Disable();
btDevice.Enable();
```
## Device specific properties
> Key = {GUID} pid
### Battery level
- Key = `{104EA319-6EE2-4701-BD47-8DDBF425BBE5} 2`
- Type = 3 (Byte)
`Data` is in percents
### Is connected or not
- Key = `{83DA6326-97A6-4088-9453-A1923F573B29} 15`
- Type = 17 (Boolean)
Data = False → device is disconnected
### Last arrival date
- Key = `{83DA6326-97A6-4088-9453-A1923F573B29} 102`
- KeyName = DEVPKEY_Device_LastArrivalDate
- Type = 16 (FileTime)
Data = 20230131090906.098359+180 → 2023 Jan 31, 9:09:06 GMT+3
### Last removal date
Key = {83da6326-97a6-4088-9453-a1923f573b29} 103
## XM4 related properties
- `WH-1000XM4 Hands-Free AG` - exact name for PnpEntity to get a __BATTERY LEVEL__ only.
- `WH-1000XM4` - exact name for PnpEntity to get a __STATE__ of the xm4.
> Actually, the app utilize templates like `W_-1000XM_` to generalize model of headphones (WH-1000XM3, WF-1000XM4, etc.)
### DEVPKEY_Device_DevNodeStatus
> Instead of this bit flags, we can use [Is Connected](#is-connected) property to retrieve a connection status of xm4.
- Key = `{4340A6C5-93FA-4706-972C-7B648008A5A7} 2`
- KeyName = DEVPKEY_Device_DevNodeStatus
- Type = 7 (Uint32)
- Connected = 25190410 (fall bit#25): value & 0x20000 == 0
- Disconnected = 58744842 (set bit#25): value & 0x20000 == 0x20000
### DEVPKEY_Bluetooth_LastConnectedTime
This is only property to retrieve the last connection date-time of headphones. This property appears only when headphones are DISconnected.
- Key = `{2BD67D8B-8BEB-48D5-87E0-6CDA3428040A} 11`
- KeyName = DEVPKEY_Bluetooth_LastConnectedTime
- Type = 16 (FileTime)
For ex.: Data = 20230131090906.098359+180 → 2023 Jan 31, 9:09:06, GMT+3
### ?Last connected time
Contains the same data as the [DEVPKEY_Bluetooth_LastConnectedTime](#devpkey_bluetooth_lastconnectedtime) property. Same behavior.
- Key = `{2BD67D8B-8BEB-48D5-87E0-6CDA3428040A} 5`
- Type = 16 (FileTime)
## Windows Radio
### Preparation
There is a way to use UWP functions from desktop application. Just setup a `TargetFramework` in `YourProject.csproj` to use specific version of dotNet-framework-windows-only like: `netX.x-windows10.0.xxxxx.x`. For example:
```xml
WinExe
net6.0-windows10.0.17763.0
...
```
### Switch system bluetooth on and off
Now we can use `Windows.Devices.Radios` namespace:
```csharp
using Windows.Devices.Radios;
```
>⚠ Be aware, this one could switch off system bluetooth radio __at all__ (not only enable or disable).\
>⚠ Use at your own risk!
```csharp
public static async Task OsEnableBluetooth() =>
InternalBluetoothState( enable: true );
public static async Task OsDisableBluetooth() =>
InternalBluetoothState( enable: false );
private async Task InternalBluetoothState( bool enable )
{
var result = await Radio.RequestAccessAsync();
if (result != RadioAccessStatus.Allowed) return;
var bluetooth =
(await Radio.GetRadiosAsync())
.FirstOrDefault(
radio => radio.Kind == RadioKind.Bluetooth );
await bluetooth?.SetStateAsync(
enable ? RadioState.On
: RadioState.Off );
}
```
> We can also use `Windows.Devices.Bluetooth` namespace or even `Windows.Devices.***` for other peripheral devices.
## References
- [Enumerating windows device](https://www.codeproject.com/articles/14412/enumerating-windows-device). Enumerating the device using the SetupDi* API provided with WinXP. CodeProject // 17 Jun 2006
- [How to get the details for each enumerated device?](https://social.msdn.microsoft.com/Forums/en-US/65086709-cee8-4efa-a794-b32979abb0ea/how-to-get-the-details-for-each-enumerated-device?forum=vbgeneral) MSDN, Archived Forums 421-440. `Visual Basic`
- [Query battery level for WH-1000XM4 wireless headphones](https://gist.github.com/nikvoronin/e8fc8a1631dd0e851f1ab821d0e3cf01). GitHub gist. `PowerShell`
- [Enable/disable already paired bluetooth devices](https://stackoverflow.com/questions/62502414/how-to-connect-to-a-paired-audio-bluetooth-device-using-windows-uwp-api/71539568#71539568). StackOverflow. How to connect to a paired audio Bluetooth device using Windows UWP API? `PowerShell`
- [Talking to robots (or other devices) using Bluetooth from a Windows Runtime app](https://blogs.windows.com/windowsdeveloper/2014/05/07/talking-to-robots-or-other-devices-using-bluetooth-from-a-windows-runtime-app/). `Windows.Devices.Bluetooth.Rfcomm` namespace // May 7, 2014
- [My Bluetooth headset can now be switched on and off from the command line](https://superuser.com/a/1815325). `PowerShell`