Java port of calibration algorithm for Android CGM apps

[ErikDeBruijn]

Summary

Complete Java port of the CareSens Air CGM calibration algorithm, designed as a standalone library for integration into Android CGM apps such as xDrip+, Jugluco, and AndroidAPS.

This port was prompted by a request from Jon Ande (jamorham), the lead developer of xDrip+, who asked about converting the C implementation to Java for native integration without binary library dependencies.

What this adds

Java calibration library (java/)

A pure Java implementation of the full 14-step calibration pipeline that converts raw ADC sensor readings into calibrated glucose values (mg/dL), matching the behavior of the proprietary i-SENS libCALCULATION.so library.

Source files (17):

File	Purpose
CareSensCalibrator.java	Public facade — the main entry point for integrators
SensorConfig.java	Immutable sensor factory parameters with Builder pattern
CalibrationResult.java	Immutable result object (glucose, trend, errors)
BlePacketParser.java	Parses raw BLE C5 notification bytes (84 bytes)
CalibrationAlgorithm.java	Internal: 14-step calibration pipeline
SignalProcessing.java	Internal: LOESS, Hampel, SG smoothing, IRLS, FIR
CheckError.java	Internal: 7 error detectors (err1/2/4/8/16/32/128)
MathUtils.java	Internal: 28 math/statistics functions
LoessKernel.java	Internal: 4050 precomputed LOESS regression coefficients
OracleBinaryReader.java	Test utility: reads oracle binary verification files
model/*.java (7 files)	Data model classes (AlgorithmState, DeviceInfo, etc.)

Test files (9), 323 tests total:

File	Tests	Purpose
MathUtilsTest.java	80	All math functions incl. NaN, overflow, edge cases
SignalProcessingTest.java	42	LOESS pipeline, SG smoothing, regression, error helpers
CheckErrorTest.java	51	All 7 error detectors with state machine verification
CalibrationAlgorithmTest.java	63	Pipeline steps, Kalman convergence, safety guards
CareSensCalibratorTest.java	39	Public API, state persistence, input validation
BlePacketParserTest.java	10	Packet parsing, defensive copies, error handling
OracleBinaryReaderTest.java	23	Binary file parsing across all 5 sensor lots
OracleVerificationTest.java	7	Full pipeline vs. oracle (2000 readings, 5 lots)
EndToEndIntegrationTest.java	10	BLE bytes → glucose, state persistence, error paths

C implementation improvements (pre-existing branch work)

The branch also includes C-side improvements that were developed during the oracle verification phase:

• Trendrate computation
• SG smoothing fixes
• lot_type=2 support
• Real sensor data tooling
• Multiple error detector implementations (err1/2/4/8/16/32/128)
• Oracle infrastructure updates

Oracle verification results

The Java implementation was verified against 2000 oracle readings generated by the proprietary ARM binary across 5 sensor lots:

Lot	eapp	Profile	Glucose	Errcode	Stage	Trendrate	Debug fields
lot0	0.10067	Normal	100% ✓	100% ✓	100% ✓	100% ✓	99.97%
lot1	0.15	Extreme	100% ✓	100% ✓	100% ✓	100% ✓	100%
lot2	0.05	Low-eapp	100% ✓	100% ✓	100% ✓	100% ✓	99.98%
lot3	0.10067	Hypo (45 mg/dL)	100% ✓	100% ✓	100% ✓	100% ✓	99.91%
lot4	0.10067	Hyper (380+ mg/dL)	100% ✓	100% ✓	100% ✓	100% ✓	99.97%

All safety-critical outputs match 100%. Debug intermediate fields match 99.995% (263,987 / 264,000). The 13 remaining mismatches are in a single internal diagnostic field (err2_crt_current[1]) that does not affect any patient-facing output.

Known limitation: SG smooth_result_glucose

The Savitzky-Golay smoothed glucose output (smooth_result_glucose[0..5]) has ~391 mismatches per lot starting at seq 10. Analysis of the ARM binary disassembly revealed that the proprietary implementation uses a causal convolution with a data-dependent kernel that differs from the C reimplementation's weighted average approach. This is a limitation of the C reimplementation itself, faithfully reproduced in the Java port. This does not affect the primary result_glucose value, which matches 100%.

Public API usage

// 1. Configure from BLE advertisement data
SensorConfig config = new SensorConfig.Builder()
    .eapp(0.10067f)
    .vref(1.2f)
    .slope100(3.5226f)
    .basicWarmup(24)
    .err345Seq2(5)
    .wSgX100(new int[]{80, 130, 90, 80, 110, 90, 80})
    .build();

// 2. Create calibrator
CareSensCalibrator calibrator = new CareSensCalibrator(config);

// 3. On each BLE C5 notification (~every 5 minutes)
BlePacketParser.ParsedReading reading = BlePacketParser.parse(bleBytes);
CalibrationResult result = calibrator.processReading(
    reading.getSequenceNumber(),
    reading.getTimestamp(),
    reading.getAdcSamples(),
    reading.getTemperature());

if (result.isValid()) {
    double glucose = result.getGlucoseMgdl();    // or getGlucoseMmol()
    double trend = result.getTrendRateMgdlPerMin();
}

// 4. Persist state across app restarts
byte[] state = calibrator.saveState();
CareSensCalibrator restored = CareSensCalibrator.restoreState(state, config);

Medical safety considerations

This library produces glucose values that people with diabetes use to dose insulin. Incorrect values can cause dangerous hypoglycemia or hyperglycemia. The following safety measures are in place:

• Oracle verification: every safety-critical output field matches the reference implementation across 2000 readings covering normal, hypoglycemic, and hyperglycemic profiles
• Division-by-zero guards: all critical division paths (glucose computation, trendrate) are guarded against zero denominators
• NaN/Infinity protection: isTrendAvailable() rejects NaN and Infinity; extreme temperature guard prevents near-zero slopeRatioTemp
• Input validation: SensorConfig.Builder validates required fields; processReading() validates ADC array length
• Immutable results: CalibrationResult and SensorConfig are immutable with defensive array copies
• State versioning: serialized state includes a version header for forward compatibility
• 50-reading Kalman convergence test: verifies the Holt-Kalman filter converges and produces finite glucose values over extended sequences

Design decisions

1. Pure Java, zero Android dependencies — works as a JAR in any JVM environment. BLE transport is the host app's responsibility.
2. Java 8 source compatibility — maximum Android device coverage.
3. Package-private internals — only CareSensCalibrator, SensorConfig, CalibrationResult, and BlePacketParser are public. All algorithm internals are hidden.
4. No build tool requirement — build.sh auto-detects JDK and downloads JUnit. Also includes build.gradle for Gradle-based Android projects.
5. Field names follow C originals (camelCased) — makes cross-referencing with the C implementation straightforward for verification.
6. Generic library, not app-specific — designed for xDrip+, Jugluco, AndroidAPS, or any custom app.

Integration documentation

• java/README.md — Quick start, API reference, build instructions, Android integration guide
• java/INTEGRATION.md — xDrip+ integration analysis, specific file locations, data flow, generic design principles

Test plan

• All 323 unit/integration tests pass
• Oracle verification: 100% glucose match across 5 sensor lots (2000 readings)
• End-to-end test: BLE bytes → parsed reading → calibrated glucose
• State persistence: save/restore produces identical glucose continuity
• Edge cases: NaN, Infinity, zero denominators, extreme temperatures, negative ADC
• Code review: medical safety issues identified and fixed
• Real sensor data validation (requires physical CareSens Air device)