|
| 1 | +package com.shimmerresearch.sensors; |
| 2 | + |
| 3 | +import static org.junit.Assert.assertEquals; |
| 4 | +import static org.junit.Assert.assertNotNull; |
| 5 | +import static org.junit.Assert.assertTrue; |
| 6 | + |
| 7 | +import org.junit.Test; |
| 8 | + |
| 9 | +import com.shimmerresearch.driver.Configuration; |
| 10 | +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; |
| 11 | +import com.shimmerresearch.driver.Configuration.Verisense; |
| 12 | +import com.shimmerresearch.driver.ObjectCluster; |
| 13 | +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; |
| 14 | +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; |
| 15 | +import com.shimmerresearch.driverUtilities.SensorDetails; |
| 16 | +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; |
| 17 | +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; |
| 18 | +import com.shimmerresearch.driverUtilities.ShimmerVerObject; |
| 19 | +import com.shimmerresearch.sensors.SensorADC.MICROCONTROLLER_ADC_PROPERTIES; |
| 20 | +import com.shimmerresearch.sensors.SensorGSR.ObjectClusterSensorName; |
| 21 | +import com.shimmerresearch.verisense.VerisenseDevice; |
| 22 | +import com.shimmerresearch.verisense.sensors.SensorGSRVerisense; |
| 23 | +import com.shimmerresearch.verisense.sensors.SensorGSRVerisense.GSR_RANGE; |
| 24 | + |
| 25 | +/** |
| 26 | + * A GSR code below the amplifier reference is an open circuit, and has to decode as one on every |
| 27 | + * range (DEV-1070). |
| 28 | + * <p> |
| 29 | + * No skin resistance can pull the amplifier's output under its reference, so the equation |
| 30 | + * R = Rf / (V / Vref - 1) goes negative there. Range 3 has long raised such codes to its |
| 31 | + * open-circuit limit. Ranges 0-2 did not, and in auto-range they see them: when the electrodes come |
| 32 | + * off, the device climbs one range at a time and repeats the sample that triggered each switch for |
| 33 | + * 80 ms, tagged with the range it was measured on. The auto-range nudge then floored the negative |
| 34 | + * resistance at 8 kOhm, so an open circuit read 125 uS, the highest conductance the device can |
| 35 | + * report. DEV-793 dataset B6 (ASM_PC Test_056, SR68-9 2511210195BC) has 50 such samples, and their |
| 36 | + * raw words carry these ranges and codes: |
| 37 | + * <ul> |
| 38 | + * <li>at the start of the recording: range 0 at codes 0 and 1131, range 1 at 1131, range 2 at |
| 39 | + * 1132</li> |
| 40 | + * <li>as the 33 kOhm load comes off: range 1 at 1137</li> |
| 41 | + * </ul> |
| 42 | + * Every code below the limit now decodes as range 3 at the limit. The rule is the same on every front |
| 43 | + * end: gen-2 (SR68, SR61-5/6, limit 1138), the Verisense GSR+ (SR62), and the Shimmer3 and ShimmerGQ |
| 44 | + * (limit 683). |
| 45 | + */ |
| 46 | +public class API_00019_GsrBelowReferenceReadsOpen { |
| 47 | + |
| 48 | + /** Conductance below this reads as Disconnected in the C# API and the web SDK. */ |
| 49 | + private static final double DISCONNECTED_BELOW_USIEMENS = 0.03; |
| 50 | + private static final double[][] WINDOWS_KOHMS = SensorGSR.SHIMMER3_GSR_RESISTANCE_MIN_MAX_KOHMS; |
| 51 | + private static final int AUTO_RANGE = 4; |
| 52 | + |
| 53 | + /** The below-reference codes in Test_056, by the range they were measured on. */ |
| 54 | + private static final int[][] TEST_056_CODES_BY_RANGE = new int[][] { |
| 55 | + {0, 1131}, |
| 56 | + {1131, 1137}, |
| 57 | + {1132}}; |
| 58 | + |
| 59 | + private enum FrontEnd { |
| 60 | + SHIMMER3(MICROCONTROLLER_ADC_PROPERTIES.SHIMMER2R3_3V0, SensorGSR.SHIMMER3_GSR_REF_RESISTORS_KOHMS, |
| 61 | + SensorGSR.GSR_UNCAL_LIMIT_RANGE3), |
| 62 | + VERISENSE_GSR_PLUS(MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_3V0, SensorGSR.SHIMMER3_GSR_REF_RESISTORS_KOHMS, |
| 63 | + SensorGSR.GSR_UNCAL_LIMIT_RANGE3), |
| 64 | + VERISENSE_GEN2(MICROCONTROLLER_ADC_PROPERTIES.VERISENSE_1V8, |
| 65 | + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_REF_RESISTORS_KOHMS, |
| 66 | + SensorGSRVerisense.VERISENSE_PULSE_PLUS_GSR_UNCAL_LIMIT_RANGE3); |
| 67 | + |
| 68 | + final MICROCONTROLLER_ADC_PROPERTIES adc; |
| 69 | + final double[] refResistorsKohms; |
| 70 | + final int limit; |
| 71 | + |
| 72 | + FrontEnd(MICROCONTROLLER_ADC_PROPERTIES adc, double[] refResistorsKohms, int limit) { |
| 73 | + this.adc = adc; |
| 74 | + this.refResistorsKohms = refResistorsKohms; |
| 75 | + this.limit = limit; |
| 76 | + } |
| 77 | + |
| 78 | + double equation(int code, int range) { |
| 79 | + return SensorGSR.calibrateGsrDataToKOhmsUsingAmplifierEq(code, range, adc, refResistorsKohms); |
| 80 | + } |
| 81 | + |
| 82 | + double withOpenCircuitLimit(int code, int range) { |
| 83 | + return SensorGSR.calibrateGsrDataToKOhmsWithOpenCircuitLimit(code, range, limit, adc, refResistorsKohms); |
| 84 | + } |
| 85 | + |
| 86 | + double openCircuitKohms() { |
| 87 | + return equation(limit, 3); |
| 88 | + } |
| 89 | + } |
| 90 | + |
| 91 | + @Test |
| 92 | + public void test001_everyCodeBelowTheLimitDecodesAsRange3AtTheLimit() { |
| 93 | + for (FrontEnd frontEnd : FrontEnd.values()) { |
| 94 | + double open = frontEnd.openCircuitKohms(); |
| 95 | + for (int range = 0; range <= 3; range++) { |
| 96 | + for (int code = 0; code < frontEnd.limit; code++) { |
| 97 | + assertEquals(frontEnd + " range " + range + " code " + code, open, |
| 98 | + frontEnd.withOpenCircuitLimit(code, range), 0.0); |
| 99 | + } |
| 100 | + } |
| 101 | + assertTrue(frontEnd + " reads an open circuit as " + (1000.0 / open) + " uS", |
| 102 | + 1000.0 / open < DISCONNECTED_BELOW_USIEMENS); |
| 103 | + } |
| 104 | + } |
| 105 | + |
| 106 | + /** |
| 107 | + * The limit is the first code above the 0.5 V reference on every front end, so the rule moves |
| 108 | + * exactly the codes that the equation decoded to a negative resistance, which are the samples |
| 109 | + * that ASM-2156's 8 kOhm floor already moved. Every other code decodes as it always has. |
| 110 | + */ |
| 111 | + @Test |
| 112 | + public void test002_onlyCodesTheEquationDecodedNegativeChange() { |
| 113 | + for (FrontEnd frontEnd : FrontEnd.values()) { |
| 114 | + for (int range = 0; range <= 3; range++) { |
| 115 | + for (int code = 0; code <= 4095; code++) { |
| 116 | + String context = frontEnd + " range " + range + " code " + code; |
| 117 | + double equation = frontEnd.equation(code, range); |
| 118 | + if (code < frontEnd.limit) { |
| 119 | + assertTrue(context + " decodes to " + equation + " kOhm", equation < 0); |
| 120 | + } else { |
| 121 | + assertTrue(context + " decodes to " + equation + " kOhm", equation > 0); |
| 122 | + assertEquals(context, equation, frontEnd.withOpenCircuitLimit(code, range), 0.0); |
| 123 | + } |
| 124 | + } |
| 125 | + } |
| 126 | + } |
| 127 | + } |
| 128 | + |
| 129 | + /** Range 0 at full scale already decodes above 8 kOhm, so nothing reaches the auto-range floor. */ |
| 130 | + @Test |
| 131 | + public void test003_theAutoRangeFloorIsNoLongerReached() { |
| 132 | + for (FrontEnd frontEnd : FrontEnd.values()) { |
| 133 | + for (int range = 0; range <= 3; range++) { |
| 134 | + for (int code = 0; code <= 4095; code++) { |
| 135 | + double kOhms = frontEnd.withOpenCircuitLimit(code, range); |
| 136 | + assertEquals(frontEnd + " range " + range + " code " + code, kOhms, |
| 137 | + SensorGSR.nudgeGsrResistance(kOhms, AUTO_RANGE, WINDOWS_KOHMS), 0.0); |
| 138 | + } |
| 139 | + } |
| 140 | + } |
| 141 | + } |
| 142 | + |
| 143 | + @Test |
| 144 | + public void test004_sr68AutoRangeTransientFromTest056ReadsOpen() { |
| 145 | + SensorGSRVerisense sensorGsr = createVerisenseSensorGsr(HW_ID.VERISENSE_PULSE_PLUS, 9, GSR_RANGE.AUTO_RANGE); |
| 146 | + assertAutoRangeReadsOpen(sensorGsr, FrontEnd.VERISENSE_GEN2, TEST_056_CODES_BY_RANGE); |
| 147 | + } |
| 148 | + |
| 149 | + @Test |
| 150 | + public void test005_sr61AutoRangeTransientFromTest056ReadsOpen() { |
| 151 | + SensorGSRVerisense sensorGsr = createVerisenseSensorGsr(HW_ID.VERISENSE_IMU, 5, GSR_RANGE.AUTO_RANGE); |
| 152 | + assertAutoRangeReadsOpen(sensorGsr, FrontEnd.VERISENSE_GEN2, TEST_056_CODES_BY_RANGE); |
| 153 | + } |
| 154 | + |
| 155 | + @Test |
| 156 | + public void test006_sr62AutoRangeBelowReferenceReadsOpen() { |
| 157 | + SensorGSRVerisense sensorGsr = createVerisenseSensorGsr(HW_ID.VERISENSE_GSR_PLUS, 1, GSR_RANGE.AUTO_RANGE); |
| 158 | + assertAutoRangeReadsOpen(sensorGsr, FrontEnd.VERISENSE_GSR_PLUS, codesBelowLimit(FrontEnd.VERISENSE_GSR_PLUS)); |
| 159 | + } |
| 160 | + |
| 161 | + /** |
| 162 | + * A fixed range still clamps to its own window (DEV-1068), but an open circuit now pins it to |
| 163 | + * the top of the window, as fixed range 3 already did, instead of the bottom. |
| 164 | + */ |
| 165 | + @Test |
| 166 | + public void test007_verisenseFixedRangesReadTheTopOfTheirWindow() { |
| 167 | + GSR_RANGE[] fixedRanges = new GSR_RANGE[] {GSR_RANGE.RANGE_0, GSR_RANGE.RANGE_1, GSR_RANGE.RANGE_2, GSR_RANGE.RANGE_3}; |
| 168 | + for (int range = 0; range <= 3; range++) { |
| 169 | + SensorGSRVerisense sr68 = createVerisenseSensorGsr(HW_ID.VERISENSE_PULSE_PLUS, 9, fixedRanges[range]); |
| 170 | + assertFixedRangeReadsTopOfWindow(sr68, range, codesBelowLimit(FrontEnd.VERISENSE_GEN2)[0]); |
| 171 | + SensorGSRVerisense sr62 = createVerisenseSensorGsr(HW_ID.VERISENSE_GSR_PLUS, 1, fixedRanges[range]); |
| 172 | + assertFixedRangeReadsTopOfWindow(sr62, range, codesBelowLimit(FrontEnd.VERISENSE_GSR_PLUS)[0]); |
| 173 | + } |
| 174 | + } |
| 175 | + |
| 176 | + @Test |
| 177 | + public void test008_shimmer3BelowReferenceReadsOpen() { |
| 178 | + SensorGSR sensorGsr = new SensorGSR(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 0, 16, 0)); |
| 179 | + sensorGsr.setGSRRange(AUTO_RANGE); |
| 180 | + assertAutoRangeReadsOpen(sensorGsr, FrontEnd.SHIMMER3, codesBelowLimit(FrontEnd.SHIMMER3)); |
| 181 | + |
| 182 | + for (int range = 0; range <= 3; range++) { |
| 183 | + sensorGsr.setGSRRange(range); |
| 184 | + assertFixedRangeReadsTopOfWindow(sensorGsr, range, codesBelowLimit(FrontEnd.SHIMMER3)[0]); |
| 185 | + } |
| 186 | + } |
| 187 | + |
| 188 | + /** The ShimmerGQ decodes to a single channel, in uS. */ |
| 189 | + @Test |
| 190 | + public void test009_shimmerGqBelowReferenceReadsOpen() { |
| 191 | + SensorGSR sensorGsr = new SensorGSR(new ShimmerVerObject(HW_ID.SHIMMER_GQ_802154_NR, FW_ID.GQ_802154, 0, 4, 1)); |
| 192 | + sensorGsr.setGSRRange(AUTO_RANGE); |
| 193 | + double openUS = 1000.0 / FrontEnd.SHIMMER3.openCircuitKohms(); |
| 194 | + int[][] codesByRange = codesBelowLimit(FrontEnd.SHIMMER3); |
| 195 | + for (int range = 0; range < codesByRange.length; range++) { |
| 196 | + for (int code : codesByRange[range]) { |
| 197 | + ObjectCluster ojc = decodeSample(sensorGsr, Configuration.Shimmer3.SENSOR_ID.SHIMMER_GSR, range, code); |
| 198 | + double uS = ojc.getFormatClusterValue(ObjectClusterSensorName.GSR_GQ, CHANNEL_TYPE.CAL.toString()); |
| 199 | + assertEquals("GQ range " + range + " code " + code, openUS, uS, openUS * 1e-12); |
| 200 | + assertTrue("GQ range " + range + " code " + code + " read " + uS + " uS", uS < DISCONNECTED_BELOW_USIEMENS); |
| 201 | + } |
| 202 | + } |
| 203 | + } |
| 204 | + |
| 205 | + private static void assertAutoRangeReadsOpen(SensorGSR sensorGsr, FrontEnd frontEnd, int[][] codesByRange) { |
| 206 | + double openKohms = frontEnd.openCircuitKohms(); |
| 207 | + int sensorId = sensorId(sensorGsr); |
| 208 | + for (int range = 0; range < codesByRange.length; range++) { |
| 209 | + for (int code : codesByRange[range]) { |
| 210 | + ObjectCluster ojc = decodeSample(sensorGsr, sensorId, range, code); |
| 211 | + String context = frontEnd + " auto-range, range " + range + " code " + code; |
| 212 | + double kOhms = ojc.getFormatClusterValue(ObjectClusterSensorName.GSR_RESISTANCE, CHANNEL_TYPE.CAL.toString()); |
| 213 | + double uS = ojc.getFormatClusterValue(ObjectClusterSensorName.GSR_CONDUCTANCE, CHANNEL_TYPE.CAL.toString()); |
| 214 | + double reportedRange = ojc.getFormatClusterValue(ObjectClusterSensorName.GSR_RANGE, CHANNEL_TYPE.CAL.toString()); |
| 215 | + |
| 216 | + assertEquals(context, openKohms, kOhms, 0.0); |
| 217 | + assertTrue(context + " read " + uS + " uS", uS > 0 && uS < DISCONNECTED_BELOW_USIEMENS); |
| 218 | + // Only the resistance changes: the range channel still says which resistor was in circuit |
| 219 | + assertEquals(context, range, reportedRange, 0.0); |
| 220 | + } |
| 221 | + } |
| 222 | + } |
| 223 | + |
| 224 | + private static void assertFixedRangeReadsTopOfWindow(SensorGSR sensorGsr, int range, int[] codes) { |
| 225 | + for (int code : codes) { |
| 226 | + ObjectCluster ojc = decodeSample(sensorGsr, sensorId(sensorGsr), range, code); |
| 227 | + double kOhms = ojc.getFormatClusterValue(ObjectClusterSensorName.GSR_RESISTANCE, CHANNEL_TYPE.CAL.toString()); |
| 228 | + assertEquals("fixed range " + range + " code " + code, WINDOWS_KOHMS[range][1], kOhms, 0.0); |
| 229 | + } |
| 230 | + } |
| 231 | + |
| 232 | + /** 0, and the last code below the limit, on each of ranges 0-2. */ |
| 233 | + private static int[][] codesBelowLimit(FrontEnd frontEnd) { |
| 234 | + int[] codes = new int[] {0, frontEnd.limit - 1}; |
| 235 | + return new int[][] {codes, codes, codes}; |
| 236 | + } |
| 237 | + |
| 238 | + private static int sensorId(SensorGSR sensorGsr) { |
| 239 | + return sensorGsr instanceof SensorGSRVerisense ? Verisense.SENSOR_ID.GSR : Configuration.Shimmer3.SENSOR_ID.SHIMMER_GSR; |
| 240 | + } |
| 241 | + |
| 242 | + private static SensorGSRVerisense createVerisenseSensorGsr(int hwId, int hwRev, GSR_RANGE gsrRange) { |
| 243 | + ExpansionBoardDetails ebd = new ExpansionBoardDetails(hwId, hwRev, 0); |
| 244 | + VerisenseDevice verisenseDevice = new VerisenseDevice(); |
| 245 | + verisenseDevice.setShimmerVersionObject(VerisenseDevice.FW_CHANGES.CCF21_010_3); |
| 246 | + verisenseDevice.setHardwareVersion(ebd.getExpansionBoardId()); |
| 247 | + verisenseDevice.setExpansionBoardDetails(ebd); |
| 248 | + verisenseDevice.sensorAndConfigMapsCreate(); |
| 249 | + |
| 250 | + SensorGSRVerisense sensorGsr = verisenseDevice.getSensorGsr(); |
| 251 | + assertNotNull("no GSR sensor registered for SR" + hwId + "-" + hwRev, sensorGsr); |
| 252 | + sensorGsr.setGsrRange(gsrRange); |
| 253 | + return sensorGsr; |
| 254 | + } |
| 255 | + |
| 256 | + /** One GSR sample as the firmware sends it: range in bits 15-14 over the 12-bit code, LSB first. */ |
| 257 | + private static ObjectCluster decodeSample(SensorGSR sensorGsr, int sensorId, int range, int code) { |
| 258 | + int raw = (range << 14) | code; |
| 259 | + byte[] sample = new byte[] {(byte) (raw & 0xFF), (byte) ((raw >> 8) & 0xFF)}; |
| 260 | + SensorDetails sensorDetails = sensorGsr.getSensorDetails(sensorId); |
| 261 | + assertNotNull("no GSR sensor details", sensorDetails); |
| 262 | + return sensorGsr.processDataCustom(sensorDetails, sample, COMMUNICATION_TYPE.SD, new ObjectCluster(), false, 0); |
| 263 | + } |
| 264 | +} |
0 commit comments