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