Skip to content

DEV-1070: decode a GSR code below the reference as open, and nudge GSR - #19

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

JongChern merged 1 commit into
mainfrom
DEV-1070_gsr_below_reference_reads_open

Conversation

@marknolan

@marknolan marknolan commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

DEV-1070

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)

Written on Windows, which has no Swift toolchain, so this PR's CI is its first build: xcodebuild test -scheme ShimmerBluetoothTests on macOS passed, including the four new GSR tests (run 36245323922).

Problem

The GSR amplifier equation, R = Rf / (V/Vref − 1), has no positive solution at or below the amplifier's 0.5 V reference. No skin resistance can pull the output under it, so a code there means the electrodes are open. GSRSensor has long raised a range-3 code below 683 to 683, but 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. The equation gave them a negative resistance, and the conductance was then reported as 0.

Separately, NudgeGsrResistance was never called, so fixed ranges were never clamped to their window.

Fix

  • calibrateGsrDataToResistanceWithOpenCircuitLimit decodes any code below 683 as range 3 at 683, on every range, and absorbs the old range-3 clamp. An open circuit reads the same on every range as the settled range 3 does: 4.5 GΩ, 0.0002 µS. This is the rule the Java driver, the C# API, the web SDK and ASM_BaseStation get under the same ticket.
  • processData now calls NudgeGsrResistance as the full nudge, as in the Java driver: a fixed range clamps to its own window, and auto-range is floored at 8 kΩ (ASM-2156). No code decodes below 8 kΩ now, so in auto-range the floor is only a backstop. On a fixed range, an open circuit reads the top of its window.
  • The nudge no longer traps on an unset range. It used to index its window table with any setting other than 4, so it would have trapped on −1, the value before the InfoMem is read, and on 5–7 from the 3-bit mask. Those now pass through, and nothing is decoded for them, as before.

Tests

SensorTest gains four tests:

  • below-reference codes read open on every range in auto-range
  • fixed ranges clamp to their window
  • codes from the limit up decode as before
  • an unset or invalid range passes through

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 0.5 V reference. No skin resistance
can pull the output under it, so a code there means the electrodes are
open. GSRSensor has long raised a range-3 code below 683 to 683, but 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. The equation
gave them a negative resistance, and the conductance was then reported
as 0.

calibrateGsrDataToResistanceWithOpenCircuitLimit now decodes any code
below 683 as range 3 at 683, on every range, and absorbs the old range-3
clamp. An open circuit reads the same on every range as the settled
range 3 does: 4.5 GOhm, 0.0002 uS. This is the rule the Java driver, the
C# API, the web SDK and ASM_BaseStation get under the same ticket.

NudgeGsrResistance was never called. processData now calls it as the full
nudge, as in the Java driver: a fixed range clamps to its own window, and
auto-range is floored at 8 kOhm (ASM-2156). No code decodes below 8 kOhm
now, so in auto-range the floor is only a backstop. On a fixed range, an
open circuit reads the top of its window. The nudge used to index its
window table with any setting other than 4, so it would have trapped on
-1, the value before the InfoMem is read, and on 5-7 from the 3-bit mask.
Those now pass through, and nothing is decoded for them, as before.

SensorTest gains four tests: below-reference codes read open on every
range in auto-range; fixed ranges clamp to their window; codes from the
limit up decode as before; and an unset or invalid range passes through.

Not built or run: there is no Swift toolchain on the Windows machine this
was written on.

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. The decode now follows the same rules as the Java driver and the C# API: a code below 683 reads as open on every range, auto-range is only floored at 8 kOhm, and a fixed range clamps to its window. The bounds check in NudgeGsrResistance matters now that it's called, because it would otherwise crash on a setting of -1 or 5-7. All four new tests ran and passed on the macOS run at fb027ae.

None of these block the merge:

  1. Wiring in the nudge is the only change here that affects readings taken with skin contact, but no test checks that a normal reading inside a fixed range's window passes through unchanged. I'd add one, either here or as a quick follow-up.
  2. testGSRCodesFromTheLimitUpDecodeAsBefore checks 7 sample codes in auto-range. Looping over every code from 683 to 4095 on every range is cheap, as the Java and C# tests do, and the same loop could cover the fixed ranges for point 1.
  3. Nothing asserts on the conductance channel. A check that an open circuit reads about 0.0002 uS would cover the > 0 guard.
  4. A pre-existing nit, worth fixing while you're here: line 65 prints GSR (kOhms) on every sample, which floods the console of any app using the library.
  5. The description says Shimmer3 only, but Shimmer3Protocol uses this GSRSensor for Shimmer3R too. The values are the same for both, so the change is right for 3R as well.

@JongChern
JongChern merged commit c977149 into main Oct 2, 2026
1 check passed
@JongChern
JongChern deleted the DEV-1070_gsr_below_reference_reads_open branch October 2, 2026 06:43
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