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); } }