Battery: use the standard BLE charging flag when a device exposes it

The companion protocol reports only a battery voltage, so charging is a
voltage-trend inference. Some devices could instead expose the standard
GATT Battery Service (0x180F) whose Battery Level Status characteristic
(0x2BED, Battery Service 1.1) carries a real, firmware-reported charging
flag. Dumping the GATT table shows no current MeshCore build implements
it — the BLE profile is just the Nordic UART pipe plus DFU — but wire it
up now so it lights up automatically the day one does.

get_hw_charging() reads 0x2BED best-effort over BLE (reaching the bleak
client the forced-teardown path already uses) and prefers its flag; any
failure — service absent, read refused, short value, non-BLE transport —
is a quiet None, so the poller falls back to the inference and every
current device behaves exactly as before. Verified against a live device:
the read resolves and returns a clean, steady None. The 0x2BED bitfield
decode is a pure function unit-tested against the spec's Charge State enum
so the parse is correct ahead of any hardware that populates it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-14 00:59:19 -04:00
1 parent e73cea9f42
commit 6aecb58e59
3 files changed
+159 -8

No files matched your search

+62 -3
View File
@@ -8,8 +8,10 @@ charging inference are all assertable without a device or a terminal.
from __future__ import annotations
import asyncio
import time
from types import SimpleNamespace
from meshterm.core.connection import charging_from_battery_level_status
from meshterm.services.battery_service import (
_BATTERY_PRESENT_FLOOR_MV,
POLL_S,
@@ -85,15 +87,22 @@ def test_battery_cell_charging_sweeps_bottom_to_full_holding_the_percent() -> No
# --- the poller ---------------------------------------------------------------------------
def _service(levels) -> BatteryService:
"""A ``BatteryService`` over a fake context whose device answers ``levels`` in turn."""
def _service(levels, hw_charging=None) -> BatteryService:
"""A ``BatteryService`` over a fake context whose device answers ``levels`` in turn.
``hw_charging`` is what the device's firmware charging flag reports each poll — ``None``
(the default, and every real MeshCore device) means "no flag", so the poller infers.
"""
seq = list(levels)
async def get_battery() -> dict:
return {"level": seq.pop(0)} if seq else {}
async def get_hw_charging():
return hw_charging
async def device() -> SimpleNamespace:
return SimpleNamespace(get_battery=get_battery)
return SimpleNamespace(get_battery=get_battery, get_hw_charging=get_hw_charging)
ctx = SimpleNamespace(
is_connected=True,
@@ -175,3 +184,53 @@ def test_battery_poller_charging_ignores_load_sag_and_flat_or_falling_packs() ->
svc._history.clear()
svc._history.extend(_history_of(now, [3800, 3900]))
assert svc._charging(now) is False
# --- the standard BLE charging flag (GATT Battery Level Status, 0x2BED) --------------------
def _level_status(charge_state: int, *, flags: int = 0, extra: bytes = b"") -> bytes:
"""A Battery Level Status value: flags byte, the Power State word, then optional tail."""
power_state = (charge_state & 0b11) << 5
return bytes([flags]) + power_state.to_bytes(2, "little") + extra
def test_charging_flag_decodes_the_charge_state_field() -> None:
"""The 2-bit Charge State enum maps to charging / not / unknown per the GSS."""
assert charging_from_battery_level_status(_level_status(1)) is True # charging
assert charging_from_battery_level_status(_level_status(2)) is False # discharging (active)
assert charging_from_battery_level_status(_level_status(3)) is False # discharging (inactive)
assert charging_from_battery_level_status(_level_status(0)) is None # unknown → infer
def test_charging_flag_reads_only_the_power_state_word() -> None:
"""Other Power State bits and the optional identifier/level tail don't sway the verdict."""
# Battery present + wired external power + charging, with identifier & level bytes trailing.
value = _level_status(1, flags=0b011, extra=b"\xab\xcd\x50")
assert charging_from_battery_level_status(value) is True
# A short value (no room for the Power State word) is unknown, never a guess.
assert charging_from_battery_level_status(b"\x00") is None
assert charging_from_battery_level_status(b"") is None
def test_battery_poller_prefers_the_hardware_charging_flag_over_inference() -> None:
"""A firmware charging flag wins over the voltage-trend guess, in both directions."""
now = time.monotonic()
rising = [3700, 3712, 3724, 3736, 3748, 3760, 3772, 3784]
# Baseline: with no hardware flag the rising trend is *inferred* as charging.
svc = _service([3900], hw_charging=None)
svc._history.extend(_history_of(now, rising))
asyncio.run(svc._poll())
assert svc.reading().charging is True
# Same rising trend, but the hardware reports NOT charging → the flag overrides the guess.
svc = _service([3900], hw_charging=False)
svc._history.extend(_history_of(now, rising))
asyncio.run(svc._poll())
assert svc.reading().charging is False
# And a hardware "charging" wins with no trend at all, where inference would say not.
svc = _service([3900], hw_charging=True)
asyncio.run(svc._poll())
assert svc.reading().charging is True