From 81a1a5b0f51955987555f0b3eb57d3d5c95e88d2 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Wed, 30 Sep 2026 20:08:48 +0100 Subject: [PATCH] Decode Verisense SR68/SR61 GSR against its 0.4986 V amplifier reference The SR68 and SR61-5/6 GSR front end biases its amplifier from a 261k/100k divider off the 1.8 V rail: 1.8 x 100 / 361 = 0.4986 V, confirmed by the hardware designer, and the same on every Verisense revision that has the front end. The decode divided by the Shimmer3's 0.5 V instead, so every resistance read about 0.5-1% high (a real 2.7 MOhm load, DEV-793 B4d, read 2778 kOhm rather than 2758) and an open circuit about 4.0 GOhm rather than 541 MOhm. The C# API and the web SDK already divide by 0.4986 V. SensorGSR gains a per-front-end amplifier reference beside the resistors and the open-circuit limit, defaulting to 0.5 V; SensorGSRVerisense sets the divider value for the SR68 and SR61. The static decode methods keep their signatures, at 0.5 V, and gain overloads that take the reference, so the Shimmer3, ShimmerGQ and SR62 paths, and outside callers such as the GQ emulator in Shimmer-Advance-API, are unchanged. The range-3 open-circuit limit stays 1138, the value the C# API and the web SDK use. It clears the corrected reference (code 1134.3), and the codes it now also moves, 1135-1137, decode to 0.7-3.0 GOhm, an open circuit either way. API_00015 and API_00019 are updated for that, and API_00015 gains a check on the reference and on the B4d load. Co-Authored-By: Claude Opus 5.5 --- .../shimmerresearch/sensors/SensorGSR.java | 63 ++++++++++++++++--- .../verisense/sensors/SensorGSRVerisense.java | 27 ++++++-- .../API_00019_GsrBelowReferenceReadsOpen.java | 28 +++++---- ...PI_00015_VerisenseGsrOpenCircuitLimit.java | 62 +++++++++++++++--- 4 files changed, 145 insertions(+), 35 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/SensorGSR.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/SensorGSR.java index 80a6ec9d3..e5aa00dbc 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/SensorGSR.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/SensorGSR.java @@ -41,7 +41,16 @@ public class SensorGSR extends AbstractSensor { private double[] currentGsrRefResistorsKohms = SHIMMER3_GSR_REF_RESISTORS_KOHMS; private double[][] currentGsrResistanceKohmsMinMax = SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS; private int currentGsrUncalLimitRange3 = GSR_UNCAL_LIMIT_RANGE3; - + private double currentGsrAmplifierRefVoltage = GSR_AMPLIFIER_REF_VOLTAGE; + + /** + * The voltage on the GSR amplifier's non-inverting input, which the amplifier equation divides + * by: 0.5 V on the Shimmer3, the ShimmerGQ and the Verisense GSR+ (SR62). The Verisense Pulse+ + * (SR68) and SR61-5/6 front end has its own: + * {@code SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE}. + */ + public static final double GSR_AMPLIFIER_REF_VOLTAGE = 0.5; + public static final double[] SHIMMER3_GSR_REF_RESISTORS_KOHMS = new double[] { 40.2, //Range 0 287.0, //Range 1 @@ -361,7 +370,7 @@ public ObjectCluster processDataCustom(SensorDetails sensorDetails, byte[] senso // gsrAdcValueUnCal = SensorGSR.nudgeGsrADC(gsrAdcValueUnCal, currentGSRRange); //...and on ranges 0-2 too, where only the resistance changes (DEV-1070) - gsrResistanceKOhms = SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit(gsrAdcValueUnCal, currentGSRRange, currentGsrUncalLimitRange3, microcontrollerAdcProperties, currentGsrRefResistorsKohms); + gsrResistanceKOhms = SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit(gsrAdcValueUnCal, currentGSRRange, currentGsrUncalLimitRange3, microcontrollerAdcProperties, currentGsrRefResistorsKohms, currentGsrAmplifierRefVoltage); gsrResistanceKOhms = SensorGSR.nudgeGsrResistance(gsrResistanceKOhms, getGSRRange(), currentGsrResistanceKohmsMinMax); gsrConductanceUSiemens = SensorGSR.convertkOhmToUSiemens(gsrResistanceKOhms); // } else { @@ -602,17 +611,27 @@ public static double calibrateGsrDataToSiemens(double gsrUncalibratedData, doubl return gsrCalibratedData; } - /** Based on circuit theory of the GSR non-inverting amplifier. - * + /** Based on circuit theory of the GSR non-inverting amplifier, with the 0.5 V reference of the + * Shimmer3, the ShimmerGQ and the Verisense GSR+ (SR62). + * * @param gsrUncalibratedData * @param range - * @param microcontrollerAdcProperties + * @param microcontrollerAdcProperties * @return */ public static double calibrateGsrDataToKOhmsUsingAmplifierEq(double gsrUncalibratedData, int range, MICROCONTROLLER_ADC_PROPERTIES microcontrollerAdcProperties, double[] gsrRefResistorsKohms){ + return calibrateGsrDataToKOhmsUsingAmplifierEq(gsrUncalibratedData, range, microcontrollerAdcProperties, gsrRefResistorsKohms, GSR_AMPLIFIER_REF_VOLTAGE); + } + + /** Based on circuit theory of the GSR non-inverting amplifier: R = Rf / (V / Vref - 1). + * + * @param gsrAmplifierRefVoltage the front end's amplifier reference: {@link #GSR_AMPLIFIER_REF_VOLTAGE}, + * or {@code SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE} on gen-2 + */ + public static double calibrateGsrDataToKOhmsUsingAmplifierEq(double gsrUncalibratedData, int range, MICROCONTROLLER_ADC_PROPERTIES microcontrollerAdcProperties, double[] gsrRefResistorsKohms, double gsrAmplifierRefVoltage){ double rFeedback = gsrRefResistorsKohms[range]; double volts = SensorADC.calibrateAdcChannelToVolts(gsrUncalibratedData, microcontrollerAdcProperties); - double rSource = rFeedback/((volts/0.5)-1.0); + double rSource = rFeedback/((volts/gsrAmplifierRefVoltage)-1.0); return rSource; } @@ -622,7 +641,7 @@ public static double calibrateGsrDataToKOhmsUsingAmplifierEq(double gsrUncalibra *

* The amplifier equation has no positive solution at or below the amplifier's 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 its open-circuit limit, the first code above the reference, so + * has long raised such a code to its open-circuit limit, a code just 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 * the firmware repeats the sample that triggered each switch through the 80 ms settling time, @@ -641,10 +660,18 @@ public static double calibrateGsrDataToKOhmsUsingAmplifierEq(double gsrUncalibra * or {@code SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3} on gen-2 */ public static double calibrateGsrDataToKOhmsWithOpenCircuitLimit(double gsrUncalibratedData, int range, int gsrUncalLimitRange3, MICROCONTROLLER_ADC_PROPERTIES microcontrollerAdcProperties, double[] gsrRefResistorsKohms){ + return calibrateGsrDataToKOhmsWithOpenCircuitLimit(gsrUncalibratedData, range, gsrUncalLimitRange3, microcontrollerAdcProperties, gsrRefResistorsKohms, GSR_AMPLIFIER_REF_VOLTAGE); + } + + /** + * {@link #calibrateGsrDataToKOhmsWithOpenCircuitLimit(double, int, int, MICROCONTROLLER_ADC_PROPERTIES, double[])} + * with the front end's own amplifier reference. + */ + public static double calibrateGsrDataToKOhmsWithOpenCircuitLimit(double gsrUncalibratedData, int range, int gsrUncalLimitRange3, MICROCONTROLLER_ADC_PROPERTIES microcontrollerAdcProperties, double[] gsrRefResistorsKohms, double gsrAmplifierRefVoltage){ if(gsrUncalibratedData + * The SAADC samples GSR against VDD/4 with a gain of 1/4, so its full scale is the rail itself. + * If the divider is fed from that same rail, the reference sits at code 1134.3 whatever the + * rail's exact level. + */ + public static final double VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE = 1.8 * 100.0 / (261.0 + 100.0); /** * Codes below this, on any range, decode as range 3 at it so that an open circuit reads as open * ({@link SensorGSR#calibrateGsrDataToKOhmsWithOpenCircuitLimit}; range 3 only until DEV-1070). - * It has to be the first code above the 0.5 V amplifier reference that - * {@link SensorGSR#calibrateGsrDataToKOhmsUsingAmplifierEq} divides by: 0.5 V is code 1137.5 at - * this front end's 1.8 V full scale, so 1138, as 683 is at the Shimmer3's 3.0 V. Anything lower - * decodes to a negative resistance, which the auto-range nudge floors at 8 kOhm, reading an open - * circuit as 125 uS. It was 1134, the last code below 0.4986 V, until DEV-1067. + * It has to be above the {@link #VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE 0.4986 V} + * reference (code 1134.3 at this front end's 1.8 V full scale). Anything at or below it decodes + * to a negative resistance, which the auto-range nudge floors at 8 kOhm, reading an open circuit + * as 125 uS. It was 1134 until DEV-1067, one code short. + *

+ * 1138 is the first code above 0.5 V, which this decode divided by until the reference was + * corrected. It is kept, rather than lowered to 1135, because it is the value the C# API and the + * web SDK use, and because codes 1135-1137 are an open circuit too: on range 3 they decode to + * 0.7-3.0 GOhm. */ public static final int VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3 = 1138; @@ -133,6 +149,7 @@ public SensorGSRVerisense(ShimmerVerObject svo) { || svo.getHardwareVersion() == HW_ID.VERISENSE_IMU) { setCurrentGsrRefResistorsKohms(VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS); setCurrentGsrUncalLimitRange3(VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3); + setCurrentGsrAmplifierRefVoltage(VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE); } } //--------- Constructors for this class end -------------- diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/sensors/API_00019_GsrBelowReferenceReadsOpen.java b/ShimmerDriver/src/test/java/com/shimmerresearch/sensors/API_00019_GsrBelowReferenceReadsOpen.java index 72c1204d9..a44306aaa 100644 --- a/ShimmerDriver/src/test/java/com/shimmerresearch/sensors/API_00019_GsrBelowReferenceReadsOpen.java +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/sensors/API_00019_GsrBelowReferenceReadsOpen.java @@ -58,29 +58,32 @@ public class API_00019_GsrBelowReferenceReadsOpen { private enum FrontEnd { SHIMMER3(MICROCONTROLLER_ADC_PROPERTIES.SHIMMER2R3_3V0, SensorGSR.SHIMMER3_GSR_REF_RESISTORS_KOHMS, - SensorGSR.GSR_UNCAL_LIMIT_RANGE3), + SensorGSR.GSR_UNCAL_LIMIT_RANGE3, SensorGSR.GSR_AMPLIFIER_REF_VOLTAGE), VERISENSE_GSR_PLUS(MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_3V0, SensorGSR.SHIMMER3_GSR_REF_RESISTORS_KOHMS, - SensorGSR.GSR_UNCAL_LIMIT_RANGE3), + SensorGSR.GSR_UNCAL_LIMIT_RANGE3, SensorGSR.GSR_AMPLIFIER_REF_VOLTAGE), VERISENSE_GEN2(MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_1V8, SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS, - SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3); + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3, + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE); final MICROCONTROLLER_ADC_PROPERTIES adc; final double[] refResistorsKohms; final int limit; + final double refVoltage; - FrontEnd(MICROCONTROLLER_ADC_PROPERTIES adc, double[] refResistorsKohms, int limit) { + FrontEnd(MICROCONTROLLER_ADC_PROPERTIES adc, double[] refResistorsKohms, int limit, double refVoltage) { this.adc = adc; this.refResistorsKohms = refResistorsKohms; this.limit = limit; + this.refVoltage = refVoltage; } double equation(int code, int range) { - return SensorGSR.calibrateGsrDataToKOhmsUsingAmplifierEq(code, range, adc, refResistorsKohms); + return SensorGSR.calibrateGsrDataToKOhmsUsingAmplifierEq(code, range, adc, refResistorsKohms, refVoltage); } double withOpenCircuitLimit(int code, int range) { - return SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit(code, range, limit, adc, refResistorsKohms); + return SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit(code, range, limit, adc, refResistorsKohms, refVoltage); } double openCircuitKohms() { @@ -104,19 +107,22 @@ public void test001_everyCodeBelowTheLimitDecodesAsRange3AtTheLimit() { } /** - * The limit is the first code above the 0.5 V reference on every front end, so the rule moves - * exactly the codes that the equation decoded to a negative resistance, which are the samples - * that ASM-2156's 8 kOhm floor already moved. Every other code decodes as it always has. + * The rule moves only codes that were an open circuit already. On the Shimmer3, the ShimmerGQ and + * the SR62 the limit is the first code above the 0.5 V reference, so these are exactly the codes + * that decoded to a negative resistance, the samples ASM-2156's 8 kOhm floor already moved. On + * gen-2 the reference is 0.4986 V (code 1134.3) and the limit 1138, so codes 1135-1137 move too; + * they decode above the top of range 3 on every range. Every other code decodes as it always has. */ @Test - public void test002_onlyCodesTheEquationDecodedNegativeChange() { + public void test002_onlyCodesThatWereAlreadyOpenChange() { for (FrontEnd frontEnd : FrontEnd.values()) { for (int range = 0; range <= 3; range++) { for (int code = 0; code <= 4095; code++) { String context = frontEnd + " range " + range + " code " + code; double equation = frontEnd.equation(code, range); if (code < frontEnd.limit) { - assertTrue(context + " decodes to " + equation + " kOhm", equation < 0); + assertTrue(context + " decodes to " + equation + " kOhm", + equation < 0 || equation > WINDOWS_KOHMS[3][1]); } else { assertTrue(context + " decodes to " + equation + " kOhm", equation > 0); assertEquals(context, equation, frontEnd.withOpenCircuitLimit(code, range), 0.0); diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/verisense/sensors/API_00015_VerisenseGsrOpenCircuitLimit.java b/ShimmerDriver/src/test/java/com/shimmerresearch/verisense/sensors/API_00015_VerisenseGsrOpenCircuitLimit.java index 67e5f1b28..5823d3461 100644 --- a/ShimmerDriver/src/test/java/com/shimmerresearch/verisense/sensors/API_00015_VerisenseGsrOpenCircuitLimit.java +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/verisense/sensors/API_00015_VerisenseGsrOpenCircuitLimit.java @@ -1,5 +1,6 @@ package com.shimmerresearch.verisense.sensors; +import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertNotNull; import static org.junit.Assert.assertTrue; @@ -12,6 +13,7 @@ import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; import com.shimmerresearch.driverUtilities.SensorDetails; import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.sensors.SensorADC; import com.shimmerresearch.sensors.SensorADC.MICROCONTROLLER_ADC_PROPERTIES; import com.shimmerresearch.sensors.SensorGSR; import com.shimmerresearch.sensors.SensorGSR.ObjectClusterSensorName; @@ -25,10 +27,11 @@ * With nothing across the electrodes the amplifier's gain falls to one and its output settles on * the reference, so the ADC reads a few codes either side of it. The decode raises every range-3 * code below {@link SensorGSRVerisense#VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3} to that limit, - * which only works if the limit is itself above the reference. It was 1134, below the 0.5 V this - * decode divides by (code 1137.5 at 1.8 V), so codes 1134 to 1137 decoded to a negative - * resistance: auto-range floored it at 8 kOhm, the highest conductance the device can report, and - * fixed range 3 pinned it to 680 kOhm, the bottom of the range. On an SR68-9 with the electrodes + * which only works if the limit is itself above the reference. It was 1134, below the reference + * (0.4986 V, code 1134.3 at 1.8 V; this decode divided by 0.5 V, code 1137.5, until the reference + * was corrected), so the clamped codes decoded to a negative resistance: auto-range floored it at + * 8 kOhm, the highest conductance the device can report, and fixed range 3 pinned it to 680 kOhm, + * the bottom of the range. On an SR68-9 with the electrodes * open (DEV-793 dataset B6, ASM_PC Test_056) the range-3 codes peak at 1126-1136, so most of an * open-circuit recording read 125 uS. *

@@ -65,14 +68,50 @@ public void test004_sr61FixedRange3OpenCircuitReadsOpen() { } /** - * The limit is exactly the first code above the reference: one lower and the clamp produces - * negative resistances again, any higher and it overwrites codes that decode properly. + * The limit has to clear the amplifier reference, or the clamp produces negative resistances + * again, as the old limit of 1134 did. It is the first code above 0.5 V, the value the C# API and + * the web SDK use too; the codes between the reference and the limit are an open circuit anyway. */ @Test - public void test005_limitIsTheFirstCodeAboveTheAmplifierReference() { + public void test005_limitClearsTheAmplifierReference() { int limit = SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3; assertTrue(calibrateRange3(limit) > 0); - assertTrue(calibrateRange3(limit - 1) < 0); + assertTrue(calibrateRange3(1134) < 0); + assertTrue(volts(limit) > 0.5 && volts(limit - 1) < 0.5); + for (int code = limit - 3; code < limit; code++) { + assertTrue("code " + code, calibrateRange3(code) > RANGE_3_MAX_KOHMS); + } + } + + /** A 261k/100k divider off the 1.8 V rail: the value the C# API and the web SDK round to 0.4986 V. */ + @Test + public void test006_amplifierReferenceIsTheDividerVoltage() { + assertEquals(0.4986, SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE, 0.00005); + assertEquals(SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE, + createSensorGsr(HW_ID.VERISENSE_PULSE_PLUS, 9).getCurrentGsrAmplifierRefVoltage(), 0.0); + assertEquals(SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE, + createSensorGsr(HW_ID.VERISENSE_IMU, 5).getCurrentGsrAmplifierRefVoltage(), 0.0); + assertEquals(SensorGSR.GSR_AMPLIFIER_REF_VOLTAGE, + createSensorGsr(HW_ID.VERISENSE_GSR_PLUS, 1).getCurrentGsrAmplifierRefVoltage(), 0.0); + } + + /** + * A real 2.7 MOhm load on an SR68-9 (DEV-793 dataset B4d, median code about 1850 on range 3) + * decodes as the C# API and the web SDK decode it, 2758 kOhm, and closer to the load than the old + * 0.5 V reference put it (2778 kOhm). + */ + @Test + public void test007_realLoadDecodesAsTheOtherApisDo() { + SensorGSRVerisense sensorGsr = createSensorGsr(HW_ID.VERISENSE_PULSE_PLUS, 9); + sensorGsr.setGsrRange(GSR_RANGE.AUTO_RANGE); + double kOhms = decodeRange3Sample(sensorGsr, 1850) + .getFormatClusterValue(ObjectClusterSensorName.GSR_RESISTANCE, CHANNEL_TYPE.CAL.toString()); + + double otherApis = SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS[RANGE_3] / (volts(1850) / 0.4986 - 1.0); + assertEquals(otherApis, kOhms, otherApis * 1e-4); + double oldReference = SensorGSR.calibrateGsrDataToKOhmsUsingAmplifierEq(1850, RANGE_3, + MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_1V8, SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS); + assertTrue(kOhms + " vs " + oldReference, Math.abs(kOhms - 2700.0) < Math.abs(oldReference - 2700.0)); } private static void assertOpenCircuitReadsOpen(int hwId, int hwRev, GSR_RANGE gsrRange) { @@ -114,6 +153,11 @@ private static ObjectCluster decodeRange3Sample(SensorGSRVerisense sensorGsr, in private static double calibrateRange3(int code) { return SensorGSR.calibrateGsrDataToKOhmsUsingAmplifierEq(code, RANGE_3, MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_1V8, - SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS); + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS, + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_AMPLIFIER_REF_VOLTAGE); + } + + private static double volts(int code) { + return SensorADC.calibrateAdcChannelToVolts(code, MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_1V8); } }