Skip to content

DEV-976: stop turning the link CRC on for Shimmer3R firmware that drops it at a stop - #316

Merged
MAzalya merged 1 commit into
masterfrom
DEV-976_no_crc_on_s3r_stop_clear
Oct 5, 2026
Merged

MAzalya merged 1 commit into
masterfrom
DEV-976_no_crc_on_s3r_stop_clear

Conversation

@marknolan

@marknolan marknolan commented Oct 2, 2026 •

Copy link
Copy Markdown
Member

The Java counterpart of the DEV-976 fix in ShimmerResearch/shimmer-web-sdk#178. That fix refuses setCrcMode(1|2) on the same firmware and exports SHIMMER3R_LINK_CRC_MIN_FIRMWARE = {1, 0, 11}.

Defect

  • Shimmer3R LogAndStream v0.00.002 to v1.00.010 (hardware 10, November and December 2024) turn the Bluetooth link CRC (SET_CRC_COMMAND, 0x8B) off by themselves whenever sensing stops. The clear is in S4Sens_stopSensing (S3R_Production/S4_App/s4_sensing.c:354 at LogAndStream_Shimmer3R_v1.00.010).
    • It runs after STOP_STREAMING (0x20), STOP_SDBT (0x97) and STOP_LOGGING (0x93), and when the user button or docking ends SD logging.
    • Nothing tells the host. The stop's own ACK still carries the CRC, but every reply after it is bare.
  • shimmer3r-firmware c8016de3 removed the clear, so v1.00.011 is the first release that keeps the CRC. Later releases clear it only at startup and on disconnect.
  • The driver gives every Shimmer3R LogAndStream from 0.0.1 firmware code 8. So isBtCrcModeSupported() was true, and initializeShimmer3or3R turned on the default CRC (1 byte) at every connect.
  • The stop paths never change mBtCommsCrcModeCurrent. After a stop, GET replies were still read with a CRC byte and stream packets were still sized with one.
  • Consensys's "CRC Mode" setting defaults to the driver default ("1-byte CRC Enabled"). So a default Consensys session on these firmwares lost sync after every stop.

Fix

  • New isBtCrcClearedWhenSensingStops(). It is true for Shimmer3R LogAndStream before 1.0.11, checked against the hardware, firmware ID and version with isThisVerCompatibleWith(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 11).
  • isBtCrcModeSupported() is now getFirmwareVersionCode() >= 8 && !isBtCrcClearedWhenSensingStops(). The connect path already asks it, so connecting now leaves the CRC off. When a CRC default is set, it logs why.
  • writeBtCommsCrcMode() refuses a CRC wherever isBtCrcModeSupported() is false. That covers enableBtCommsOneByteCrc() and enableBtCommsTwoByteCrc() too, which the Android example calls directly. Turning the CRC off is never refused where the command exists.
  • Why refuse rather than reset after a stop: refusing also covers the stops the device makes on its own (user button, docking), which the host never hears about.
  • Skipping SET_CRC at connect is safe. v1.00.010 clears the CRC at startup and on every disconnect (shimmer_bt_comms.c:1068 and :2543), and the driver already assumes it is off on connect.

Why the hardware is checked: Shimmer3 and Shimmer3R LogAndStream versions overlap (Shimmer3 has v1.00.003 to v1.01.005), and no Shimmer3 release clears the CRC at a stop. Shimmer3 v1.00.008 clears it only at protocol init and on disconnect.

One build reports the wrong hardware. LogAndStream_Shimmer3R_v1.00.008 is a side build for older Consensys (OLD_CONSENSYS_SUPPORT 1) that reports hardware 3. As in the web SDK, the gate follows the reported hardware and lets it through. Refusing every Shimmer3 on v1.0.8 would be wrong far more often.

Testing

  • New API_00025_Shimmer3rBtCrcGateTest (4 tests, in ShimmerDriverPC):

    • Shimmer3R 1.0.10, 1.0.7 and 0.0.2 are refused by isBtCrcModeSupported(), writeBtCommsCrcMode() and both enable helpers, and nothing is queued.
    • Shimmer3R 1.0.11, 1.1.0 and 2.0.0 are allowed. 1.1.0 is there because the internal number restarts at each minor release.
    • Shimmer3 1.0.8, 1.0.10 and 0.13.7 are allowed, and 0.13.6 is still not.
    • OFF is never refused.
  • Connect path: the simulator suites now check the CRC mode after connecting. It is off for the simulated Shimmer3R (LogAndStream v0.0.1) and 1 byte for the simulated Shimmer3 (v0.16.0).

  • Proof the tests catch the bug (unpatched driver): shimmer3rBeforeV1_00_011IsRefused fails on "Shimmer3R LogAndStream v1.0.10", and the Shimmer3R simulator check fails with expected:<OFF> but was:<ONE_BYTE_CRC>.

  • Simulator log, before and after: the 8 simulated Shimmer3R connects sent SET_CRC_COMMAND [0x8B 0x01] 8 times before and 0 times after. The Shimmer3 suites still send it.

  • Full suites:

    Command Result
    cd ShimmerDriver && ./gradlew test 154 tests, 0 failures
    cd ShimmerDriverPC && ./gradlew build -i BUILD SUCCESSFUL, 33 tests, 0 failures
  • An unrelated flake, seen once: API_0000X_ByteCommunicationShimmer3.test002 (a Shimmer3, so outside this change) failed in one full run. Its connect stalled after initialisation, inside the progress-callback delivery, with nothing transmitted. It then passed 5 of 5 reruns with this change and 5 of 5 without. The simulator suites never disconnect their devices, so earlier tests' devices keep running and their traffic shows up in later suites' logs. That is worth a separate look.

Not verified on hardware

No Shimmer3R on v1.00.010 or earlier has been run against this. The fix rests on the firmware source and the simulator. To check on one: connect with Consensys at its default CRC mode, start and stop streaming, and confirm the next command is answered.

After merge: consumers

None of these picks this up on its own:

  • ShimmerAndroidAPI pins shimmerdriver and shimmerbluetoothmanager at 0.11.7_beta (ShimmerAndroidInstrumentDriver/build.gradle). It needs a shimmerdriver release containing this, and the pin bumped.
  • Shimmer-MATLAB-ID connects through its bundled libs/ShimmerJavaClass.jar, the ShimmerDriverPC shadow jar built 2025-11-24, which still has the old gate. The jar needs rebuilding and re-vendoring.
  • Consensys builds the driver from source through sibling projects, so it gets this when built against a checkout that contains it.
  • ASM_PC needs no bump for this. Nothing there uses the Bluetooth driver.

Siblings (CLAUDE.md §4)

  • Web SDK: fixed in DEV-976: refuse a link CRC on Shimmer3R firmware that drops it when sensing stops shimmer-web-sdk#178.
  • Swift (SwiftAPI): needs it. Shimmer3Protocol.connect() turns on a 2-byte CRC at every connect, before reading any version, and never drops it after a stop. It supports the Shimmer3R over BLE. Not changed here.
  • C# (Shimmer-C-API): needs it, but only when a consumer opts in. ShimmerLogAndStream(..., BTCRCMode CRCmode) writes the requested CRC at connect whenever IsCRCSupported() is true, and that is true for every Shimmer3R LogAndStream. BluetoothCRCMode is reset only on Connect(). The default is off.
  • pyshimmer: not affected. It never sends SET_CRC.

🤖 Generated with Claude Code

…ps it at a stop

Shimmer3R LogAndStream v0.00.002 to v1.00.010 turn the Bluetooth link CRC
off by themselves whenever sensing stops (S4Sens_stopSensing,
s4_sensing.c:354 at v1.00.010): after STOP_STREAMING, STOP_SDBT and
STOP_LOGGING, and when the user button or docking ends SD logging. Nothing
tells the host. The stop's own ACK still carries the CRC, but every reply
after it is bare. The driver turned the default CRC on at every connect for
these releases too (firmware code 8 from Shimmer3R LogAndStream 0.0.1), and
kept expecting it after a stop, so default Consensys sessions lost sync
after every stop. c8016de3 removed the clear, and v1.00.011 is the first
release that keeps the CRC.

isBtCrcModeSupported() is now false for those releases, through the new
isBtCrcClearedWhenSensingStops(), so connecting leaves the CRC off and logs
why. writeBtCommsCrcMode() refuses a CRC wherever isBtCrcModeSupported() is
false, which also covers the enableBtComms*Crc() helpers; turning the CRC
off is never refused where the command exists. Refusing, rather than
dropping the expectation after a stop, also covers the stops the device
makes on its own.

The gate checks the hardware, because Shimmer3 and Shimmer3R LogAndStream
versions overlap and no Shimmer3 release clears the CRC at a stop. It
follows the reported hardware, so the v1.00.008 side build, which reports a
Shimmer3, is let through, as in the web SDK (shimmer-web-sdk#178).

API_00025 pins the boundary: Shimmer3R 1.0.10 refused, 1.0.11 allowed,
Shimmer3 1.0.8 allowed, and OFF never refused. The simulator suites now
assert the CRC mode after connecting: off for the simulated Shimmer3R
(v0.0.1), the default for the Shimmer3.

Not run against a real Shimmer3R on v1.00.010 or earlier.

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

@MAzalya MAzalya 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.

ok looks good

@MAzalya
MAzalya merged commit 273aa02 into master Oct 5, 2026
2 checks passed
@MAzalya
MAzalya deleted the DEV-976_no_crc_on_s3r_stop_clear branch October 5, 2026 03:56
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