From 11e4d313ca8ff415927a01a2f7f1b377c99104be Mon Sep 17 00:00:00 2001 From: Mohammad Abdul Sahil <127765312+abdulsaheel@users.noreply.github.com> Date: Sat, 5 Sep 2026 01:52:56 +0530 Subject: [PATCH 1/2] lefun: envelope codec + battery decode --- lib/openstrap_protocol.dart | 1 + lib/src/lefun.dart | 102 ++++++++++++++++++++++++++++++++++++ test/lefun_test.dart | 94 +++++++++++++++++++++++++++++++++ 3 files changed, 197 insertions(+) create mode 100644 lib/src/lefun.dart create mode 100644 test/lefun_test.dart diff --git a/lib/openstrap_protocol.dart b/lib/openstrap_protocol.dart index 10abe3c..c344d9d 100644 --- a/lib/openstrap_protocol.dart +++ b/lib/openstrap_protocol.dart @@ -18,6 +18,7 @@ export 'src/band.dart' show DeviceType, GattProfile, BandProfile; // sharing one barrel must not share a bare verb. export 'src/oura.dart'; export 'src/hrs.dart'; +export 'src/lefun.dart'; // Source 1 — record decoders. export 'src/records.dart' diff --git a/lib/src/lefun.dart b/lib/src/lefun.dart new file mode 100644 index 0000000..08edb8d --- /dev/null +++ b/lib/src/lefun.dart @@ -0,0 +1,102 @@ +// A shared OEM wire format used across a family of white-label BLE fitness +// rings and bands sold under many storefront names on one common reference +// design. One write/notify characteristic pair, one small envelope, plain +// unencrypted GATT. +// +// NOTHING HERE HAS MET HARDWARE (ASSUMPTIONS R6). The envelope and its +// checksum are the only things this file decodes with confidence — battery +// level is the one report this file turns into a value, because it is a +// single bounded byte with an unambiguous meaning. Steps, sleep, heart rate +// and PPG all ride the same envelope under their own report codes, and none +// of them has a decoder here: a layout is not hardware-verified just because +// it is documented, and a wrong number is worse than no number. +// +// PLAIN, UNENCRYPTED GATT. There is no nonce, no key and no challenge/response +// anywhere in this envelope — a session is a bare write/notify pair from the +// moment the link connects. + +/// Host to device. +const int kLefunRequestMarker = 0xAB; + +/// Device to host. +const int kLefunResponseMarker = 0x5A; + +/// Marker + length + report code + trailing checksum — the fixed part of +/// every frame regardless of direction. +const int kLefunHeaderLength = 4; + +/// One GATT write/notify value never carries more than this many bytes. +const int kLefunMaxFrameLength = 20; + +/// Report code: battery level. Same code both ways — a bare request with no +/// arguments, a one-byte percentage in reply. +const int kLefunReportBattery = 0x03; + +/// Report code: firmware/type info. Request only; this file does not decode +/// the reply. +const int kLefunReportFirmwareInfo = 0x00; + +/// The reflected CRC-8 this family's checksum byte turns out to be — bit 0 of +/// the running value against bit 0 of each input byte, shifting the byte out +/// LSB-first and feeding 0x18 back in on a mismatch. Computed bit-by-bit +/// rather than table-driven: the table costs 256 entries to save a function +/// this small ever needs to call more than once per frame. +int _lefunChecksum(List data) { + var crc = 0; + for (final byte in data) { + var b = byte & 0xff; + for (var bit = 0; bit < 8; bit++) { + if (((b ^ crc) & 1) == 0) { + crc >>= 1; + } else { + crc = ((crc ^ 0x18) >> 1) | 0x80; + } + b >>= 1; + } + } + return crc & 0xff; +} + +/// One decoded envelope: a report code and its argument bytes, checksum +/// already verified. +class LefunFrame { + final int report; + final List params; + const LefunFrame(this.report, this.params); +} + +/// Build one host-to-device frame. Throws if [params] would push the frame +/// past [kLefunMaxFrameLength] — there is no multi-segment chunking here, so a +/// command that cannot fit one write has no builder in this file. +List buildLefunFrame(int report, {List params = const []}) { + final length = kLefunHeaderLength + params.length; + if (length > kLefunMaxFrameLength) { + throw ArgumentError('Lefun frame does not fit one GATT write'); + } + final body = [kLefunRequestMarker, length, report, ...params]; + return [...body, _lefunChecksum(body)]; +} + +/// Parse one device-to-host frame. Null for anything too short, missing the +/// response marker, whose declared length disagrees with what actually +/// arrived, or whose checksum does not match — the last two mean a partial or +/// corrupted delivery, never a value to patch up and keep. +LefunFrame? parseLefunFrame(List value) { + if (value.length < kLefunHeaderLength) return null; + if (value[0] != kLefunResponseMarker) return null; + final length = value[1]; + if (length < kLefunHeaderLength || length > value.length) return null; + final body = value.sublist(0, length - 1); + if (_lefunChecksum(body) != value[length - 1]) return null; + return LefunFrame(value[2], value.sublist(3, length - 1)); +} + +/// Decode a battery report's single-byte argument. Null when the argument +/// count is wrong or the value falls outside 0-100 — either means a misread, +/// not a percentage to clamp and keep. +int? decodeLefunBattery(List params) { + if (params.length != 1) return null; + final level = params[0]; + if (level < 0 || level > 100) return null; + return level; +} diff --git a/test/lefun_test.dart b/test/lefun_test.dart new file mode 100644 index 0000000..56399ae --- /dev/null +++ b/test/lefun_test.dart @@ -0,0 +1,94 @@ +// Envelope + battery decode for the Lefun-family OEM ring/band protocol. +// +// NOTHING HERE HAS MET HARDWARE. These fixtures are hand-built to the +// documented envelope shape, not captured off a device. + +import 'package:test/test.dart'; +import 'package:openstrap_protocol/openstrap_protocol.dart'; + +void main() { + group('buildLefunFrame', () { + test('a bare battery request', () { + expect( + buildLefunFrame(kLefunReportBattery), + [0xAB, 0x04, 0x03, 0xEE], + ); + }); + + test('a request with arguments', () { + expect( + buildLefunFrame(kLefunReportFirmwareInfo), + [0xAB, 0x04, 0x00, 0x0C], + ); + }); + + test('too long to fit one write throws', () { + expect( + () => buildLefunFrame(0x01, params: List.filled(20, 0)), + throwsArgumentError, + ); + }); + }); + + group('parseLefunFrame', () { + test('a battery reply round-trips', () { + final frame = parseLefunFrame(const [0x5A, 0x05, 0x03, 0x57, 0xFB])!; + expect(frame.report, kLefunReportBattery); + expect(frame.params, [0x57]); + }); + + test('a zero battery reply round-trips', () { + final frame = parseLefunFrame(const [0x5A, 0x05, 0x03, 0x00, 0xA3])!; + expect(frame.params, [0x00]); + }); + + test('wrong marker byte is refused', () { + expect( + parseLefunFrame(const [0xAB, 0x05, 0x03, 0x57, 0xFB]), + isNull, + ); + }); + + test('too short is refused', () { + expect(parseLefunFrame(const [0x5A, 0x05, 0x03]), isNull); + expect(parseLefunFrame(const []), isNull); + }); + + test('a declared length longer than the buffer is refused', () { + expect( + parseLefunFrame(const [0x5A, 0x06, 0x03, 0x57]), + isNull, + ); + }); + + test('a corrupted checksum is refused', () { + expect( + parseLefunFrame(const [0x5A, 0x05, 0x03, 0x57, 0x00]), + isNull, + ); + }); + }); + + group('decodeLefunBattery', () { + test('a mid-range level', () { + expect(decodeLefunBattery(const [87]), 87); + }); + + test('zero is valid', () { + expect(decodeLefunBattery(const [0]), 0); + }); + + test('full charge is valid', () { + expect(decodeLefunBattery(const [100]), 100); + }); + + test('out of range is refused, not clamped', () { + expect(decodeLefunBattery(const [101]), isNull); + }); + + test('wrong argument count is refused', () { + expect(decodeLefunBattery(const []), isNull); + expect(decodeLefunBattery(const [1, 2]), isNull); + }); + }); +} From 4284f9a2829381f4a09cdda27fa72a4bdacfa231 Mon Sep 17 00:00:00 2001 From: Mohammad Abdul Sahil <127765312+abdulsaheel@users.noreply.github.com> Date: Sat, 5 Sep 2026 02:14:06 +0530 Subject: [PATCH 2/2] lefun: bound parser to the device's own frame ceiling, validate wire bytes --- lib/src/lefun.dart | 36 +++++++++++++++++++++++++++++++----- test/lefun_test.dart | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 5 deletions(-) diff --git a/lib/src/lefun.dart b/lib/src/lefun.dart index 08edb8d..fe712d3 100644 --- a/lib/src/lefun.dart +++ b/lib/src/lefun.dart @@ -65,27 +65,53 @@ class LefunFrame { const LefunFrame(this.report, this.params); } +/// Throws unless [b] is a single wire byte. Every field this envelope carries +/// — the report code and every argument — is one GATT-frame byte, and a +/// caller passing something outside 0-255 would otherwise silently produce a +/// frame with a value no receiving device's byte reader can represent. +void _checkByte(int b, String name) { + if (b < 0 || b > 0xff) { + throw ArgumentError.value(b, name, 'must be a single byte (0-255)'); + } +} + /// Build one host-to-device frame. Throws if [params] would push the frame /// past [kLefunMaxFrameLength] — there is no multi-segment chunking here, so a -/// command that cannot fit one write has no builder in this file. +/// command that cannot fit one write has no builder in this file — or if +/// [report] or any of [params] falls outside 0-255. List buildLefunFrame(int report, {List params = const []}) { final length = kLefunHeaderLength + params.length; if (length > kLefunMaxFrameLength) { throw ArgumentError('Lefun frame does not fit one GATT write'); } + _checkByte(report, 'report'); + for (final p in params) { + _checkByte(p, 'params'); + } final body = [kLefunRequestMarker, length, report, ...params]; return [...body, _lefunChecksum(body)]; } /// Parse one device-to-host frame. Null for anything too short, missing the -/// response marker, whose declared length disagrees with what actually -/// arrived, or whose checksum does not match — the last two mean a partial or -/// corrupted delivery, never a value to patch up and keep. +/// response marker, declaring a length outside `kLefunHeaderLength .. +/// kLefunMaxFrameLength`, or whose checksum does not match — any of those +/// means a partial or corrupted delivery, never a value to patch up and keep. +/// +/// A DECLARED LENGTH SHORTER THAN THE BUFFER IS ACCEPTED, deliberately: this +/// codec has not been checked against a real capture, and a device in this +/// family appending bytes past its own declared length — the way the Oura +/// ring is known to (see `oura.dart`) — would otherwise have every one of its +/// notifications refused outright instead of parsed with the extra bytes +/// available to whoever archives the raw delivery. LefunFrame? parseLefunFrame(List value) { if (value.length < kLefunHeaderLength) return null; if (value[0] != kLefunResponseMarker) return null; final length = value[1]; - if (length < kLefunHeaderLength || length > value.length) return null; + if (length < kLefunHeaderLength || + length > kLefunMaxFrameLength || + length > value.length) { + return null; + } final body = value.sublist(0, length - 1); if (_lefunChecksum(body) != value[length - 1]) return null; return LefunFrame(value[2], value.sublist(3, length - 1)); diff --git a/test/lefun_test.dart b/test/lefun_test.dart index 56399ae..eb338b9 100644 --- a/test/lefun_test.dart +++ b/test/lefun_test.dart @@ -28,6 +28,22 @@ void main() { throwsArgumentError, ); }); + + test('an out-of-range report code throws', () { + expect(() => buildLefunFrame(256), throwsArgumentError); + expect(() => buildLefunFrame(-1), throwsArgumentError); + }); + + test('an out-of-range argument byte throws', () { + expect( + () => buildLefunFrame(0x01, params: const [256]), + throwsArgumentError, + ); + expect( + () => buildLefunFrame(0x01, params: const [-1]), + throwsArgumentError, + ); + }); }); group('parseLefunFrame', () { @@ -67,6 +83,22 @@ void main() { isNull, ); }); + + test('a declared length longer than the device ceiling is refused', () { + // Declares 21 bytes, one past kLefunMaxFrameLength, regardless of what + // the buffer itself holds. + expect(parseLefunFrame(const [0x5A, 21, 0x03]), isNull); + }); + + test('bytes past the declared length are tolerated, not refused', () { + // A valid battery reply with one undeclared trailing byte — the same + // shape a device in this family that pads past its own length would + // send (see the module doc on why this is accepted, not refused). + final frame = + parseLefunFrame(const [0x5A, 0x05, 0x03, 0x57, 0xFB, 0x00])!; + expect(frame.report, kLefunReportBattery); + expect(frame.params, [0x57]); + }); }); group('decodeLefunBattery', () {