From fb027ae9283bc9c6c8ce27533d35d06afbabe225 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Sat, 26 Sep 2026 13:40:32 +0100 Subject: [PATCH] DEV-1070: decode a GSR code below the reference as open, and nudge GSR The GSR amplifier equation, R = Rf / (V/Vref - 1), has no positive solution at or below the amplifier's 0.5 V reference. No skin resistance can pull the output under it, so a code there means the electrodes are open. GSRSensor has long raised a range-3 code below 683 to 683, but ranges 0-2 did not, and in auto-range they see these codes too. When the electrodes come off, the device climbs one range at a time, and the firmware repeats the sample that triggered each switch through the 80 ms settling time, tagged with the range it was measured on. The equation gave them a negative resistance, and the conductance was then reported as 0. calibrateGsrDataToResistanceWithOpenCircuitLimit now decodes any code below 683 as range 3 at 683, on every range, and absorbs the old range-3 clamp. An open circuit reads the same on every range as the settled range 3 does: 4.5 GOhm, 0.0002 uS. This is the rule the Java driver, the C# API, the web SDK and ASM_BaseStation get under the same ticket. NudgeGsrResistance was never called. processData now calls it as the full nudge, as in the Java driver: a fixed range clamps to its own window, and auto-range is floored at 8 kOhm (ASM-2156). No code decodes below 8 kOhm now, so in auto-range the floor is only a backstop. On a fixed range, an open circuit reads the top of its window. The nudge used to index its window table with any setting other than 4, so it would have trapped on -1, the value before the InfoMem is read, and on 5-7 from the 3-bit mask. Those now pass through, and nothing is decoded for them, as before. SensorTest gains four tests: below-reference codes read open on every range in auto-range; fixed ranges clamp to their window; codes from the limit up decode as before; and an unset or invalid range passes through. Not built or run: there is no Swift toolchain on the Windows machine this was written on. Co-Authored-By: Claude Opus 5.5 --- .../ShimmerBluetooth/GSRSensor.swift | 53 +++++++++++++++---- .../ShimmerBluetoothTests/SensorTest.swift | 51 ++++++++++++++++++ 2 files changed, 93 insertions(+), 11 deletions(-) diff --git a/ShimmerBluetooth/ShimmerBluetooth/GSRSensor.swift b/ShimmerBluetooth/ShimmerBluetooth/GSRSensor.swift index 67b59f1..62090da 100644 --- a/ShimmerBluetooth/ShimmerBluetooth/GSRSensor.swift +++ b/ShimmerBluetooth/ShimmerBluetooth/GSRSensor.swift @@ -19,7 +19,8 @@ public class GSRSensor: Sensor , SensorProcessing{ 287.000, //Range 1 1000.000, //Range 2 3300.000]; //Range 3 - // Equation breaks down below 683 for range 3 + // Equation breaks down below 683 on every range: 683 is the first code above the 0.5 V + // amplifier reference at 3.0 V (see calibrateGsrDataToResistanceWithOpenCircuitLimit) public static let SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS : [[Double]] = [ @@ -35,7 +36,7 @@ public class GSRSensor: Sensor , SensorProcessing{ let rawDataX = Double(ShimmerUtilities.parseSensorData(sensorData: x, dataType: SensorDataType.u16)!) if (calibrationEnabled){ var newGSRRange = gsrRange - var gsrData = Double((Int(rawDataX) & 4095)); + let gsrData = Double((Int(rawDataX) & 4095)); var gsrResistanceKOhms: Double = 0 if (gsrRange == 4) { @@ -43,27 +44,24 @@ public class GSRSensor: Sensor , SensorProcessing{ } if (gsrRange == 0 || newGSRRange == 0) { - gsrResistanceKOhms = calibrateGsrDataToResistanceFromAmplifierEq(gsrData, 0); + gsrResistanceKOhms = calibrateGsrDataToResistanceWithOpenCircuitLimit(gsrData, 0); } else if (gsrRange == 1 || newGSRRange == 1) { - gsrResistanceKOhms = calibrateGsrDataToResistanceFromAmplifierEq(gsrData, 1); + gsrResistanceKOhms = calibrateGsrDataToResistanceWithOpenCircuitLimit(gsrData, 1); } else if (gsrRange == 2 || newGSRRange == 2) { - gsrResistanceKOhms = calibrateGsrDataToResistanceFromAmplifierEq(gsrData, 2); + gsrResistanceKOhms = calibrateGsrDataToResistanceWithOpenCircuitLimit(gsrData, 2); } else if (gsrRange == 3 || newGSRRange == 3) { - if (gsrData < GSRSensor.GSR_UNCAL_LIMIT_RANGE3) - { - gsrData = GSRSensor.GSR_UNCAL_LIMIT_RANGE3; - } - gsrResistanceKOhms = calibrateGsrDataToResistanceFromAmplifierEq(gsrData, 3); + gsrResistanceKOhms = calibrateGsrDataToResistanceWithOpenCircuitLimit(gsrData, 3); } + gsrResistanceKOhms = NudgeGsrResistance(gsrResistanceKOhms, gsrRange) print("GSR (kOhms): \(gsrResistanceKOhms)") objectCluster.addData(sensorName: GSRSensor.GSR_SKIN_RESISTANCE, formatName: SensorFormats.Calibrated.rawValue, unitName: SensorUnits.kiloOhms.rawValue, value: gsrResistanceKOhms) @@ -88,15 +86,48 @@ public class GSRSensor: Sensor , SensorProcessing{ return max(minVal, min(maxVal, valToNudge)) } + /// Clamp a fixed range to its own window; floor auto-range at 8 kOhm, the smallest resistance any + /// range can measure, as the Java driver and the C# API do (ASM-2156). Any other setting (-1 before + /// the InfoMem is read, or 5-7 from the 3-bit mask) has no window, and passes through rather than + /// trapping on the array index. func NudgeGsrResistance(_ gsrResistanceKOhms : Double,_ gsrRangeSetting: Int) ->Double { - if (gsrRangeSetting != 4) + if (gsrRangeSetting == 4) + { + return max(GSRSensor.SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS[0][0], gsrResistanceKOhms); + } + if (gsrRangeSetting >= 0 && gsrRangeSetting < GSRSensor.SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS.count) { return nudgeDouble(gsrResistanceKOhms, GSRSensor.SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS[gsrRangeSetting][0], GSRSensor.SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS[gsrRangeSetting][1]); } return gsrResistanceKOhms; } + /// calibrateGsrDataToResistanceFromAmplifierEq, reading an open circuit as open on every range + /// (DEV-1070). + /// + /// The amplifier equation has no positive solution at or below the amplifier's 0.5 V reference: no + /// skin resistance can pull the output under it, so a code there means the electrodes are open. + /// Range 3 has long raised such a code to GSR_UNCAL_LIMIT_RANGE3, the first code above the + /// reference, so that an open circuit decodes as thousands of MOhm. Ranges 0-2 did not, and in + /// auto-range they see these codes too. When the electrodes come off, the device climbs one range + /// at a time and repeats the sample that triggered each switch through the 80 ms settling time, + /// tagged with the range it was measured on. On ranges 0-2 the equation gave those samples a + /// negative resistance. + /// + /// So a code below the limit decodes as range 3 at the limit, whatever range it was measured on, + /// and an open circuit reads the same on every range as the settled range 3 does. Codes at or above + /// the limit decode on their own range, as before. The Java driver and the C# API apply the same + /// rule. + func calibrateGsrDataToResistanceWithOpenCircuitLimit(_ gsrUncalibratedData : Double, _ range : Int) -> Double + { + if (gsrUncalibratedData < GSRSensor.GSR_UNCAL_LIMIT_RANGE3) + { + return calibrateGsrDataToResistanceFromAmplifierEq(GSRSensor.GSR_UNCAL_LIMIT_RANGE3, 3); + } + return calibrateGsrDataToResistanceFromAmplifierEq(gsrUncalibratedData, range); + } + func calibrateGsrDataToResistanceFromAmplifierEq(_ gsrUncalibratedData : Double, _ range : Int) -> Double { let rFeedback = GSRSensor.SHIMMER3_GSR_REF_RESISTORS_KOHMS[range]; diff --git a/ShimmerBluetooth/ShimmerBluetoothTests/SensorTest.swift b/ShimmerBluetooth/ShimmerBluetoothTests/SensorTest.swift index 4846cf6..b3dc66f 100644 --- a/ShimmerBluetooth/ShimmerBluetoothTests/SensorTest.swift +++ b/ShimmerBluetooth/ShimmerBluetoothTests/SensorTest.swift @@ -291,4 +291,55 @@ class SensorTest: XCTestCase { } + // DEV-1070: a GSR code below the range-3 open-circuit limit, 683, puts the amplifier output under + // its 0.5 V reference, which no skin resistance can do, so the electrodes are open, on every range. + // In auto-range ranges 0-2 see such codes as the device climbs after the electrodes come off, and + // they decoded to a negative resistance. They now decode as range 3 at the limit. + func testGSRBelowReferenceReadsOpenOnEveryRangeInAutoRange(){ + let open = gsrResistanceKOhms(gsrRange: 4, range: 3, code: 683) + XCTAssertEqual(open, 4504500.0, accuracy: 0.001) + for range in 0...3 { + for code in [0, 500, 682] { + XCTAssertEqual(gsrResistanceKOhms(gsrRange: 4, range: range, code: code), open, "auto-range, range \(range), code \(code)") + } + } + } + + // The nudge is now called, so a fixed range clamps to its own window: an open circuit reads the + // top of it, and full scale on range 1 (57.4 kOhm) the bottom. + func testGSRFixedRangesClampToTheirWindow(){ + let top = [63.0, 220.0, 680.0, 4700.0] + for range in 0...3 { + XCTAssertEqual(gsrResistanceKOhms(gsrRange: range, range: range, code: 0), top[range], "fixed range \(range)") + } + XCTAssertEqual(gsrResistanceKOhms(gsrRange: 1, range: 1, code: 4095), 63.0) + } + + func testGSRCodesFromTheLimitUpDecodeAsBefore(){ + let gsrSensor = GSRSensor() + for range in 0...3 { + for code in [683, 684, 700, 1000, 2000, 3000, 4095] { + XCTAssertEqual(gsrResistanceKOhms(gsrRange: 4, range: range, code: code), gsrSensor.calibrateGsrDataToResistanceFromAmplifierEq(Double(code), range), "range \(range), code \(code)") + } + } + } + + // -1 before the InfoMem is read, or 5-7 from the 3-bit mask: nothing is decoded, and the nudge + // must not trap on its array index. + func testGSRUnsetRangePassesThrough(){ + for gsrRange in [-1, 5, 6, 7] { + XCTAssertEqual(gsrResistanceKOhms(gsrRange: gsrRange, range: 0, code: 2000), 0, "range setting \(gsrRange)") + } + } + + /// Decode one GSR sample, range in bits 15-14 over the 12-bit code, LSB first, and return its resistance. + private func gsrResistanceKOhms(gsrRange: Int, range: Int, code: Int) -> Double { + let gsrSensor = GSRSensor() + gsrSensor.packetIndex = 0 + gsrSensor.gsrRange = gsrRange + let raw = (range << 14) | code + let objectCluster = gsrSensor.processData(sensorPacket: [UInt8(raw & 0xFF), UInt8((raw >> 8) & 0xFF)], objectCluster: ObjectCluster(deviceName: "test")) + let name = [GSRSensor.GSR_SKIN_RESISTANCE, Sensor.SensorFormats.Calibrated.rawValue, Sensor.SensorUnits.kiloOhms.rawValue].joined(separator: "_") + return objectCluster.SignalData[objectCluster.SignalNames.firstIndex(of: name)!] + } }