Skip to content

Commit

Permalink
readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
@maniacx
maniacx committed Mar 1, 2024
1 parent fbe8b20 commit a798e94
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 24 deletions.
4 changes: 2 additions & 2 deletions docs/Bugs-Feature-Request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ gsettings --schemadir /home/$USER/.local/share/gnome-shell/extensions/Airpod-Bat
* Operating system (e.g., Ubuntu 23.10)
* Bluetooth device make, model and type

# Script for getting ManufactorerData
This script can be helpful to get raw data in case you Airpod/Beats model is not detecting or is different model that is not yet supported by this extension. The script starts discovery and prints manufacturer data and other details of all airpod found nearby.
# Script for getting Manufacturer Data
This script can be helpful to get raw data in case you AirPods/Beats model is not detecting or is different model that is not yet supported by this extension. The script starts discovery and prints manufacturer data and other details of all AirPods found nearby.
* Download the [test.js](./resources/test.js){:download="test.js"}
* Disable Airpod-Battery-Monitor extension and close the Gnome Settings App > Bluetooth if opened.
* Open terminal and type.
Expand Down
21 changes: 17 additions & 4 deletions docs/Installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,20 @@ permalink: /installation

* The extension is available on the Gnome Extension Website https://extensions.gnome.org/, where it undergoes a review process upon submission.
* Therefore, it's recommended to install this extension from the website.
* This will require installing an Extensions or Extension Manager app to manage the Gnome extension.


### Using Apps

[<img src="./assets/images/installation/extension.png" width="45%">](https://flathub.org/apps/org.gnome.Extensions)[<img src="./assets/images/installation/extension-manager.png" width="45%" class="float-right">](https://flathub.org/apps/com.mattjakeman.ExtensionManager)

* Either search for the extension by its name, "Airpod Battery Monitor" or use the website link below<br><https://extensions.gnome.org/extension/6778/airpod-battery-monitor/>
* This will require installing an Extensions or Extension Manager app to manage the Gnome extension.
* Either search for the extension by its name, "Bluetooth Battery Meter" or use the website link below<br><https://extensions.gnome.org/extension/6778/airpod-battery-monitor/>

### Using dbus command

```bash
busctl --user call org.gnome.Shell.Extensions /org/gnome/Shell/Extensions org.gnome.Shell.Extensions InstallRemoteExtension s Airpod-Battery-Monitor@maniacx.github.com
```
* Running this in console/terminal will download and install extension from Gnome Extension Website.

## From Github

Expand All @@ -28,14 +36,19 @@ permalink: /installation
* A prerequisite is that gettext needs to be installed.
* Run `./install.sh` from terminal to install.
* Open terminal and
```

## Uninstallation

To uninstall this extension, use the `Extensions` or `Extension Manager` app.
<br>
<br>
Or
<br>
<br>
Using commandline to uninstall
```bash
gnome-extensions uninstall Airpod-Battery-Monitor@maniacx.github.com
```
Although not neccesary, to take a step further and remove all gsettings saved by this extension, you can use the following terminal command:
```bash
gsettings --schemadir /home/$USER/.local/share/gnome-shell/extensions/Airpod-Battery-Monitor@maniacx.github.com/schemas reset-recursively org.gnome.shell.extensions.Airpod-Battery-Monitor
Expand Down
73 changes: 55 additions & 18 deletions index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,16 @@ permalink: /
>
> `43, 44, 45`
**Airpod Battery Monitor is a Gnome Extension to report Airpod/Beats headphone battery level, using indicator icons as battery meter in system tray and message tray, or using Panel button with PopupMenus**
**Airpod Battery Monitor is a Gnome Extension to report AirPods/Beats headphone battery level, using indicator icons as battery meter in system tray and message tray, or using Panel button with PopupMenus**
<br>
<br>

{: .note }
>
> * This extension is not compatible with Bluetooth configurations in BR/EDR-only mode. Dual mode is required.
> * As this extension initiates the discovery mode, it may lead to audio distortion on Broadcom Bluetooth adapters when the extension is running. If audio distortion occurs while playing audio and opening Gnome Settings > Bluetooth, the same issue may arise when using this program, as both involve starting the discovery process.

<br>
<br>

Expand All @@ -24,35 +33,35 @@ permalink: /

# Feature

* Display Battery information status for Airpods and Beats headphone
* Display Battery information status for AirPods and Beats headphone
* Option to choose user interface. Panel labels with popupmenu and Meter Indicator Icon with information on Message tray.

---

# How does it work

* Airpods do not provide battery information through Bluetooth Battery Service (BAS) like other Bluetooth headsets/devices.
* Instead, Airpods utilize BLE advertising packets containing Battery Information and model.
* To address privacy concerns, the BLE MAC address of Airpods is randomized every 15 minutes.
* This randomization makes it challenging to identify whether the broadcasting Airpod is the one connected to the device or a different Airpod nearby.
* The extension functions by searching for all nearby broadcasting Airpods, filtering them based on the matching model, and selecting the one with the strongest signal.
* AirPods do not provide battery information through Bluetooth Battery Service (BAS) like other Bluetooth headsets/devices.
* Instead, AirPods utilize BLE advertising packets containing Battery Information and model.
* To address privacy concerns, the BLE MAC address of AirPods is randomized every 15 minutes.
* This randomization makes it challenging to identify whether the broadcasting AirPods is the one connected to the device or a different AirPods nearby.
* The extension functions by searching for all nearby broadcasting AirPods, filtering them based on the matching model, and selecting the one with the strongest signal.
* Finally, the extension displays the Battery information of the chosen Airpod.

<br>

{: .note }
>
> * If there are two Airpods of the same model, the extension will choose the one with the strongest signal. Therefore, there is no guarantee which Airpod will be displayed if they report the same signal strength.
> * Scanning and discovering Airpods takes time, so the extension may take up to a minute to display battery information.
> * In Gnome, when the screen is locked, extensions are disabled. When the screen is unlocked, the extension is enabled. Therefore, do not expect the Airpod battery information to be displayed instantaneously during screen lock.
> * If there are two AirPods of the same model, the extension will choose the one with the strongest signal. Therefore, there is no guarantee which AirPods will be displayed if they report the same signal strength.
> * Scanning and discovering AirPods takes time, so the extension may take up to a minute to display battery information.
> * In Gnome, when the screen is locked, extensions are disabled. When the screen is unlocked, the extension is enabled. Therefore, do not expect the AirPods battery information to be displayed instantaneously during screen lock.
---

# How to use
* Enable the extension in your system settings.
* Once Airpods are connected to your system, they will be listed in the extension preferences.
* Choose the specific Airpod model in the preferences, and the extension will commence scanning for the BLE beacon advertising that model.
* The extension will then display the battery information of the Airpod with the strongest Bluetooth signal.
* Once AirPods are connected to your system, they will be listed in the extension preferences.
* Choose the specific AirPods model in the preferences, and the extension will commence scanning for the BLE beacon advertising that model.
* The extension will then display the battery information of the AirPods with the strongest Bluetooth signal.

---

Expand All @@ -61,10 +70,38 @@ permalink: /
<img src="./assets/images/home/extension-prefs.png" width="100%">

### Choose model of Airpod
* This section comprises the list of paired or connected Airpods.
* The extension will only start scanning for the airpod when correct model is chosen.
* The selected model is then compared with the BLE advertising model variant, and upon a match, the nearest Airpod of that model is selected to report battery levels.
* The information is persistently stored, even after the Airpod is unpaired, for future reference.
* If you wish to discontinue the use of an Airpod, you can remove it from the list using the `Delete` button. This button is accessible only when the Airpod is unpaired from the system.
* This section comprises the list of paired or connected AirPods.
* The extension will only start scanning for the AirPods when correct model is chosen.
* The selected model is then compared with the BLE advertising model variant, and upon a match, the nearest AirPods of that model is selected to report battery levels.
* The information is persistently stored, even after the AirPods is unpaired, for future reference.
* If you wish to discontinue the use of an Airpod, you can remove it from the list using the `Delete` button. This button is accessible only when the AirPods is unpaired from the system.

---

# Verify Bluetooth Adapter Controller Mode

If the extension is continuously scanning and unable to detect AirPods, examine the contents of a system file.

```
/etc/bluetooth/main.conf
```

If `ControllerMode = bredr`, the extension will not function correctly since it relies on `le` mode to retrieve AirPods battery information.

To resolve this, switch the adapter to Dual mode by executing the following command:
Locate the line `ControllerMode = bredr` and modify it to `ControllerMode = dual`

Restart Bluetooth Service

```
sudo systemctl restart bluetooth
```

Disable and Enable the extension.

{: .note }
>
> * Some Bluetooth adapters may not pair/connect AirPods in `ControllerMode = dual`. So after switching to Dual please check, pairing, unpairing, and audio playpack with AirPods.


0 comments on commit a798e94

Please sign in to comment.