Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions lib/openstrap_protocol.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
128 changes: 128 additions & 0 deletions lib/src/lefun.dart
Original file line number Diff line number Diff line change
@@ -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<int> 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;
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}
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<int> 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<int> buildLefunFrame(int report, {List<int> params = const <int>[]}) {
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 = <int>[kLefunRequestMarker, length, report, ...params];
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
return <int>[...body, _lefunChecksum(body)];
Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
}

/// 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<int> 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<int> params) {
if (params.length != 1) return null;
final level = params[0];
if (level < 0 || level > 100) return null;
return level;
}
126 changes: 126 additions & 0 deletions test/lefun_test.dart
Original file line number Diff line number Diff line change
@@ -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);
});
});
}
Loading