feat(battery): Split battery reporting over BLE GATT

[Katona]

This PR implements #764.

The changes are relatively simple:

• the central registers on battery level changes of peripheral over BLE GATT.
• then it 'relays' the peripheral battery level changes to the host using BLE GATT again. :)
• for this to work, the central no longer relies on the Battery Service of Zephyr since that assumes one battery only. Instead, it defines its own BAS with two battery level characteristics.

What I tested

I tested only on my wireless Corne. For the test I used the Web Bluetooth API since that was the easiest to setup for me. Here is a link to a video demonstrating it.

What I didn't test

• I didn't test non split BLE keyboards since I don't have any.
• Tested only using macOS. I don't know how other OSes display battery level when multiple one are present in one device.

As indicated in #764 the OSes doesn't seem to be prepared to devices with more than one battery (macOS certainly not), but not all is lost in my opinion. I still believe this PR is useful since:

• it is actually standard (the BLE standard allows it).
• it is not breaking anything: OSes (macOS) ignore the second battery, so battery level reporting still works for central and, eventually OSes might support it (not likely, though).
• we can develop utilities which can display both batteries in the system tray or menu.

[Katona]

I just realized I can also share the test app relatively easily: https://cdpn.io/pen/debug/ExodqEG?authentication_hash=bYAdyOGvRaRk

Clicking on Pair Device will bring up a window where you have to select Corne from the list (I have to switch to a new profile to appear there) then pair. After that you can check the logs in the developer console (F12 on Chrome) where the battery level change events should be displayed.

[Nicell]

I just realized I can also share the test app relatively easily: https://cdpn.io/pen/debug/ExodqEG?authentication_hash=bYAdyOGvRaRk

This link expired, could you send the non-debug link? Are we aware of any operating systems that utilize two BAS services? Conversely, does this change still work on OSs that don't? It would be nice to test this on a real OS that can show the two battery levels.

[Katona]

@Nicell I hosted it here: https://zmk-split-battery-report.herokuapp.com/ (JS playgrounds usually run the app in an iframe which can not access the Bluetooth API, so I tried to share the debug link instead).

As I said, I have only access to macOS Monterey which still displays only one battery, the central one. This at least means it doesn't break existing battery level reporting, but to be honest, I am not sure if it's a macOS limitation or a bug in my implementation, since Apple Airpods have proper battery level reporting: https://support.apple.com/en-us/HT207012#status. But of course, Airpods might be treated specially, I will try to investigate it further.

#764 claims that Windows 11 don't support it either, I have no info about linux unfortunately.

[tadfisher]

Apple has its own peripheral communication protocol that allows for multiple battery level reporting. I know my Sony earbuds support it.

[Katona]

Which is probably proprietary and we don't get the chance to implement it (without some certification). But I still think this PR makes sense even with zero OS support, we could create small apps which would display the battery level in system tray/menu, or is this overkill?

[tadfisher]

Actually it's pretty well-documented: https://developer.apple.com/accessories/Accessory-Design-Guidelines.pdf

Problem is, it's for devices using the hands-free profile (using HFP AT commands), so it's of little use for HID-over-GATT devices like keyboards.

[Katona]

@tadfisher You're right, I was not aware of that.

[Katona]

@Nicell Based on the discussion above, I think the best is to assume that no OS is supporting this at the moment (and to be honest, it's unlikely that they ever will be) but, as I said, it is possible to create some utility which can display the battery level (and other things as well) of both sides. I know it's not ideal, but I think it's feasible.

[Katona]

Making this PR more attractive:

I created a (very) POC macOS app which displays the battery levels in the menubar.

[zhenchaopro]

Making this PR more attractive:

I created a (very) POC macOS app which displays the battery levels in the menubar.

Awesome! Would it be possible to make it as a SwiftBar plugin?

[Katona]

@steve-fan probably yes, but as I said it's just a POC at the moment :)

[zhenchaopro]

@Katona Great! What API to use to get the battery info in MacOS? I'd love do some test.

[Katona]

@steve-fan I am using the Core Bluetooth API at the moment, but it's not too convenient in my opinion. I plan to use RxBluetoothKit, that seems better.

[kien242]

Hi sir, there is a bug i would like to report. When I build the firmware for Corne keyboard, I can't build for the main side when the OLED feature is enabled. it gives error : "battery_status.c:61: undefined reference to ` bt_bas_get_battery_level ' ". The slave side built normally.

[petejohanson]

Hi sir, there is a bug i would like to report. When I build the firmware for Corne keyboard, I can't build for the main side when the OLED feature is enabled. it gives error : "battery_status.c:61: undefined reference to ` bt_bas_get_battery_level ' ". The slave side built normally.

Yeah, this makes sense. We'll need a solution for a reasonable API abstraction for the consumers to show battery state, like for the display widget.

[Katona]

@kien242 Thanks for reporting it! I think I was able to fix this, but I don't have the necessary hardware to test it. @petejohanson is there way to test things when the required hardware is not available?

[kien242]

@Katona, Thank you for fixing that bug. One wish of mine is probably a bit annoying to you, but Can you make a widget to display the slave's battery on the master's screen? I really wish there was that widget for a split keyboard with only one screen on the main side.

[Katona]

@kien242 Actually, I am working on making the display superfluous altogether :) Maybe it's just me, but I think there is no real use case of the screen, apart from maybe debugging.

[kien242]

@kien242 Actually, I am working on making the display superfluous altogether :) Maybe it's just me, but I think there is no real use case of the screen, apart from maybe debugging.

@Katona, yes sir, but It seems that the widget is not working as expected, when I try with lily58's firmware, the OLED screen always says the battery capacity is 0

[abonham]

Can confirm it works like a charm on macOS 12, using a Ferris Sweep + nice!nano v2.0 x 2.

[WarpspeedSCP]

Yup, can confirm this working well on linux as well. problem is blueman also ignores the additional battery report.

If anyone is planning on using this code and rebasing on zmk master, I recommend creating a new branch from zmk master and manually patching any edited files. there are some conflicting changes in this branch which prevent a clean rebase. You will experience horrible cmake errors if you just try to rebase.

[Maksim-Isakau]

The feature is a must-have, thanks for this PR @Katona! Having dedicated displays for battery feels like a complete waste of energy.

Are we waiting for https://github.com/zmkfirmware/zmk/pull/836 to be merged before this PR can go further?

If anyone is looking for a Windows app, I made one based on Katona's POC: https://github.com/Fukkei/zmk-split-battery

[Katona]

@Fukkei thanks! Yes we are waiting for #836.

[equiman]

Tested on Windows. Works with @Katona PR and @Fukkei WindowsApp

[equiman]

Sadly, I reverted the PR on my repo because &kp SEMICOLON was acting as &kp COLON.

Repo without PR: https://github.com/deinsoftware/zmk/tree/main (same as zmk last version) Repo with PR: https://github.com/deinsoftware/zmk/tree/battery

Once I reverted the changes, works again as expected. This is the morph that is failing.

mp_cs: morph_dev_comma_semi {
    compatible = "zmk,behavior-mod-morph";
    label = ", ;";
    #binding-cells = <0>;
    mods = <(MOD_LSFT|MOD_RSFT)>;
    bindings = <&kp COMMA>, <&kp SEMICOLON>;
};

This is my ZMK configuration that is failing: https://github.com/deinsoftware/swept-zmk-config/tree/v3.4.0

Let me know if I can help with more information

[caksoylar]

Sadly, I reverted the PR on my repo because &kp SEMICOLON was acting as &kp COLON.

This is because your branch is missing the mod-morph commit that added mod masking by default: https://github.com/deinsoftware/zmk/commit/ef2e6e9156806760d9e91c0d635cd809058c3ee7

You could probably merge this PR branch into current ZMK main (rather than directly using it) and that would resolve it.

[Katona]

@equiman Updated this branch with main, you can try if you want. Please note that this is still a POC.

[gaoDean]

+1, works amazingly on macos 13.1 with nice nano v2s

[equiman]

Works again as expected.

Thanks @caksoylar and @Katona

[snprajwal]

Is this PR still in the pipeline to be added to the next ZMK release? I would love to have this feature available in the firmware by default (happy ZMK user with a Ferricy here)