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..fe712d3 --- /dev/null +++ b/lib/src/lefun.dart @@ -0,0 +1,128 @@ +// 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); +} + +/// 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 — 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, 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 > 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)); +} + +/// 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..eb338b9 --- /dev/null +++ b/test/lefun_test.dart @@ -0,0 +1,126 @@ +// 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, + ); + }); + + 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', () { + 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, + ); + }); + + 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', () { + 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); + }); + }); +}