Skip to content

DEV-1070: decode a GSR code below the reference as open on every range - #206

Merged
JongChern merged 1 commit into
masterfrom
DEV-1070_gsr_below_reference_reads_open
Oct 1, 2026
Merged

JongChern merged 1 commit into
masterfrom
DEV-1070_gsr_below_reference_reads_open

Conversation

@marknolan

@marknolan marknolan commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

DEV-1070. Stacked on #205 (DEV-1067); it targets that branch, so the diff is this change only.

Explainer: before/after charts for DEV-1067, DEV-1068 and DEV-1070, and a table of the sibling PRs across every host API: https://claude.ai/artifact/6hDc2Ue9hdF8gcUDZXzFts (Shimmer sign-in)

Problem

The GSR amplifier equation, R = Rf / (V/Vref − 1), 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 (683, or 1138 on the SR68 since #205). 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.

On ranges 0–2 the equation gives those samples a negative resistance:

  • ShimmerBLEAPI SensorGSR (Verisense) floors it at 8 kΩ (ASM-2156, ASM-2156 Negative GSR output values #111): 125 µS, the highest conductance the device can report, and Connected.
  • ShimmerAPI ShimmerBluetooth has no floor, so its Shimmer3/3R and Shimmer2 decodes report a negative resistance and conductance.

On a fixed range both read the bottom of the window. DEV-793 B6 (ASM_PC Test_056, an SR68-9) has such samples on range 0 at codes 0 and 1131, range 1 at 1131 and 1137, and range 2 at 1132.

Fix

Every range now decodes a code below the front end's limit as range 3 at the limit:

  • ShimmerBLEAPI SensorGSR: GetGsrUncalLimitRange3 picks the SR68 or SR62 limit as the range-3 clamp did, and the clamp now applies on every range. Other identifiers still get no limit.
  • ShimmerAPI ShimmerBluetooth: both the Shimmer3/3R and the Shimmer2 decode call CalibrateGsrDataToResistanceWithOpenCircuitLimit on every range. It absorbs the old range-3 clamp.

Only the resistance, conductance and connectivity change; the raw values are as before. An open circuit now reads the same on every range as the settled range 3 does: about 536 MΩ (0.0019 µS, Disconnected) on the SR68, and 4.5 GΩ on the SR62 and the Shimmer3. A fixed range still clamps to its own window, so there an open circuit now reads the top of it. On the 683 front ends the rule moves only codes that decoded negative. The SR68 decode divides by 0.4986 V, so it also moves 1135–1137, which are above that reference but below the 1138 limit, as range 3 already does. Every code at or above the limit decodes exactly as before.

Tests

  • ShimmerBLETests/Sensors/SensorGSRBelowReferenceTest covers the SR68 with Test_056's codes, the SR62, fixed ranges, and every code from the limit up unchanged.
  • ShimmerUnitTests/ShimmerGsrDecodeTest puts packets through BuildMsg on a Shimmer3, a 3R and a 2R, through a ShimmerBluetooth with no connection. It is its own file because ShimmerTest's GetShimmerAddress throws, and BuildMsg calls it first.
Rule Result
range 3 only 3 of 4 BLE tests fail (8 kΩ); 2 of 3 BuildMsg tests fail (−40.2 kΩ on a Shimmer3)
this PR ShimmerBLETests 125/125, ShimmerBluetoothTests 28/28

This was built with Visual Studio's MSBuild, because the dotnet CLI fails on Fody and Realm in ShimmerBLEAPI; ShimmerUnitTests ran under vstest.console.

Merging with DEV-1069

DEV-1069 (not yet a PR) gives the SR61-5/6 the SR68 front end. It rewrites the same range-3 block, so the two conflict. The resolution keeps this structure, with GetGsrUncalLimitRange3() returning HasSecondGenerationGsrFrontEnd() ? GSR_UNCAL_LIMIT_RANGE3_SR68 : GSR_UNCAL_LIMIT_RANGE3_SR62. A test merge with that resolution passes all 134 ShimmerBLETests, including DEV-1069's check that five other identifiers decode every code exactly as the SR68 does.

Sibling PRs (same rule, same ticket)

🤖 Generated with Claude Code

The GSR amplifier equation, R = Rf / (V/Vref - 1), 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 (683,
or 1138 on the SR68 since DEV-1067). 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.

On ranges 0-2 the equation gave those samples a negative resistance.
ShimmerBLEAPI's SensorGSR floored it at 8 kOhm (ASM-2156): 125 uS, the
highest conductance the device can report, and Connected. ShimmerAPI's
ShimmerBluetooth has no floor, so its Shimmer3/3R and Shimmer2 decodes
reported a negative resistance and conductance. On a fixed range both
read the bottom of the window. DEV-793 B6 (ASM_PC Test_056, an SR68-9)
has such samples on range 0 at codes 0 and 1131, range 1 at 1131 and
1137, and range 2 at 1132.

Every range now decodes a code below the front end's limit as range 3 at
the limit:

- ShimmerBLEAPI SensorGSR (Verisense). GetGsrUncalLimitRange3 picks the
  SR68 or SR62 limit as the range-3 clamp did, and the clamp now applies
  on every range. Other identifiers still get no limit.
- ShimmerAPI ShimmerBluetooth. Both the Shimmer3/3R and the Shimmer2
  decode call CalibrateGsrDataToResistanceWithOpenCircuitLimit on every
  range, and it absorbs the old range-3 clamp.

Only the resistance, conductance and connectivity change; the raw values
are as before. An open circuit now reads the same on every range as the
settled range 3 does: about 536 MOhm (0.0019 uS, Disconnected) on the
SR68, and 4.5 GOhm on the SR62 and the Shimmer3. A fixed range still
clamps to its own window, so there an open circuit now reads the top of
it. On the 683 front ends the rule moves only codes that decoded
negative. The SR68 decode divides by 0.4986 V, so it also moves 1135-1137,
which are above that reference but below the 1138 limit, as range 3
already does. Every code at or above the limit decodes exactly as before.

Tests:

- ShimmerBLETests SensorGSRBelowReferenceTest covers the SR68 with
  Test_056's codes, the SR62, fixed ranges, and every code from the limit
  up unchanged.
- ShimmerUnitTests ShimmerGsrDecodeTest puts packets through BuildMsg on
  a Shimmer3, a 3R and a 2R, through a ShimmerBluetooth with no
  connection. It is its own file because ShimmerTest's GetShimmerAddress
  throws, and BuildMsg calls it first.

With the rule restricted to range 3, 3 of the 4 BLE tests fail (8 kOhm),
and 2 of the 3 BuildMsg tests fail (-40.2 kOhm on a Shimmer3). All 125
ShimmerBLETests and all 28 ShimmerBluetoothTests pass.

Stacked on DEV-1067, without which the SR68's limit of 1134 itself
decodes negative. DEV-1069, which gives the SR61-5/6 the SR68's front
end, rewrites the same range-3 block, so the two conflict. The
resolution keeps this structure, with GetGsrUncalLimitRange3 choosing
the SR68 limit when HasSecondGenerationGsrFrontEnd() and the SR62 limit
otherwise.

Built with Visual Studio's MSBuild (the dotnet CLI fails on Fody and
Realm in ShimmerBLEAPI); ShimmerUnitTests run under vstest.console.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

@JongChern JongChern left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. This applies the same rule as Java #307, and it covers every amplifier-equation decode in the repo: the Verisense SensorGSR and both ShimmerBluetooth.BuildMsg blocks (Shimmer3/3R and Shimmer2R). The tests check every code from the limit up on every range and hardware type, so readings taken with skin contact are unchanged.

CI hasn't run on this branch, because it targets #205's branch. I ran both suites at a666ad5 the way CI does: ShimmerBLETests 125/125 and ShimmerBluetoothTests 28/28. With the old decode put back, 3 of the new ShimmerBLE tests and 2 of the 3 BuildMsg tests fail, so the tests do catch a regression.

Comments, none blocking:

  1. After #205 merges, change this PR's base to master and push or close/reopen it, so CI runs before merging.
  2. GetGsrUncalLimitRange3() returning 0 is worth a one-line comment, something like "no limit, as before this change; SR61-5/6 pending DEV-1069". Without it, it reads like a bug. Please don't make it throw: it runs once per sample, and the streaming path (parseStreamingPayload) has no try/catch, so SR61 users would lose GSR and battery data entirely. If we want fail-fast, a one-time check where GSR is enabled is a better place.
  3. SR61-5/6 still gets no open-circuit handling here, because it reports VERISENSE_IMU. That's DEV-1069, and the resolution in the description looks right.

Base automatically changed from DEV-1067_gsr_range3_open_circuit_limit to master October 1, 2026 08:38
@JongChern
JongChern merged commit bc8137b into master Oct 1, 2026
@JongChern
JongChern deleted the DEV-1070_gsr_below_reference_reads_open branch October 1, 2026 08:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants