Statistics characteristic (fc540013) decoded: on-device drink log, plus a de-bounce that drops it in debug mode #97

Summary

I decoded the statistics characteristic (fc540013, MugCharacteristic.STATISTICS) against an Ember Mug 2 (14 oz, firmware 406, hardware 10) and wrote it up here: https://github.com/gwhillhouse/ember-mug-app/blob/main/docs/statistics-stream.md. Sharing in case it's useful for the library, along with one thing I noticed in _notify_callback that would stop anyone from seeing the stream through debug=True.

What the stream is

It is the mug's on-device drink log, not live telemetry. The mug buffers records as things happen and drains the whole backlog to the first client that subscribes; a second subscribe afterwards gets only the 05 end marker. New records then arrive live on the open subscription, ~15–20 s after the event. (This looks like the feed behind the Ember app's analytics: it subscribes on connect and uploads to collector.embertech.com, so whichever client subscribes first gets the log.)

Framing. Each notification is one of four packet types, working within the 20-byte ATT MTU:

Records (after reassembling 02+04): 00 | kind | sub | t (u32 BE, seconds since the pour) | ff | fields. Temperatures are big-endian °C×100 (the opposite of the GATT characteristics); 7fff is null.

Everything marked confirmed in the doc was matched second-for-second against my own app's log of the same drink; the 0x15 snapshot fields and one constant are still hypotheses (one mug, one day). Raw capture available on request (stats-capture.jsonl, ~50 packets per drink).

The de-bounce in _notify_callback

event_id = data[0]
now = time()
if (last_time := self._latest_events.get(event_id)) and now - last_time < 5:
    return

This runs before the characteristic check, so it also applies to statistics packets. The backlog arrives as ~48 packets in about five seconds whose first byte is almost always 01, 02 or 04, so with debug=True the library logs three of them and drops the rest, and the 02/04 fragments can never be paired. Skipping the de-bounce when characteristic.uuid == MugCharacteristic.STATISTICS.uuid (or keying it on the characteristic as well as the byte) fixes it. Happy to send a PR for that if you'd like; I held off because it touches behaviour you may want to shape differently once the stream is actually parsed.

Related

Small PR alongside this one (#96): battery temperature from bytes 2–3 of fc540007, which orlopau documented and which explains the "on the coaster but not charging" behaviour on a hot mug.