Skip to content

DEV-1141: never send a 2-byte link CRC to Shimmer3R LogAndStream v1.00.024-v1.00.049 - #318

Merged
MAzalya merged 1 commit into
masterfrom
DEV-1141_two_byte_crc_push_overrun
Oct 5, 2026
Merged

MAzalya merged 1 commit into
masterfrom
DEV-1141_two_byte_crc_push_overrun

Conversation

@marknolan

@marknolan marknolan commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

The Java counterpart of the DEV-1141 fix in ShimmerResearch/shimmer-web-sdk#183. It keeps a 2-byte link CRC off the Shimmer3R firmware whose status push it overruns.

Stacked on #316 (DEV-976). This PR's base is DEV-976_no_crc_on_s3r_stop_clear. Both PRs change writeBtCommsCrcMode, the CRC block in initializeShimmer3or3R and the CRC javadoc, so built on master they would conflict in four places. Merge #316 first; GitHub then retargets this to master. gradle.yml runs only on PRs into master, so CI will not run here until then. The same commands were run locally (see Testing).

Defect

  • The buffer. Shimmer3R LogAndStream v1.00.024 to v1.00.049 build the unsolicited status push in a six-byte stack buffer: uint8_t selfcmd[6] in ShimBt_instreamStatusRespSend (log-and-stream-common Comms/shimmer_bt_uart.c:2262 at f39be8c1f).
  • The overrun. With the ACK prefix on, which is the default, the push is ACK + 0x8A 0x71 + 2 status bytes. A 2-byte CRC makes it 7 bytes, and the 7th lands past the end of the buffer: the sensor hardfaults (DEV-621, fixed in v1.00.050).
  • When it fires. The firmware pushes on docking and undocking, the user button, a trial-duration expiry and a low-battery stop, not on the host's own starts and stops. So the fault can come at any point in a session, long after the CRC went on.
  • How the driver got there:
    • initializeShimmer3or3R sends DEFAULT_BT_CRC_MODE_IF_SUPPORTED at every connect. It is 1 byte by default, but Consensys's "2-bytes CRC Enabled" setting changes it through setDefaultBtCrcModeToUseIfFwSupported.
    • enableBtCommsTwoByteCrc() and writeBtCommsCrcMode(TWO_BYTE_CRC) send it directly. ShimmerAndroidAPI's shimmerBasicExample offers it.
    • The only gate was the firmware code, which every Shimmer3R LogAndStream passes.
  • Not affected: a 1-byte CRC; v1.00.023 and earlier, which send one status byte; v1.00.050 and later; any Shimmer3.

Fix

  • New isTwoByteCrcOverrunningStatusPush(). It is isSupportedUSBPluggedInStatus() and not v1.00.050 or later. isSupportedUSBPluggedInStatus() is the driver's existing gate for the second status byte (Shimmer3R LogAndStream v1.00.024 and later), so the two boundaries cannot drift apart.
  • writeBtCommsCrcMode() refuses TWO_BYTE_CRC there: it returns false and queues nothing. It is the only sender of SET_CRC_COMMAND in the Java tree, so this covers both enable helpers and every consumer.
  • At connect, a 2-byte default falls back to 1 byte there (getBtCrcModeToUseOnConnect()), with a debug log line. One byte is the low byte of the same CRC, so the link keeps its check. The static setting is left alone, so the next device still gets 2 bytes if it can take them.
  • Javadoc. getDefaultBtCrcModeIfFwSupported() claimed it returned the mode in use once connected. It returns the setting, so the doc now says so.

With #316's gate, the two combine as follows:

Shimmer3R LogAndStream CRC the driver will turn on
before v1.00.011 none (#316)
v1.00.011 to v1.00.023 any
v1.00.024 to v1.00.049 1 byte at most (this PR)
v1.00.050 and later any

Why not the web SDK's route. The web SDK sends SET_INSTREAM_RESPONSE_ACK_PREFIX_STATE (0xA3) with 0 before a 2-byte CRC, which makes the push 6 bytes. This driver's in-stream parsers assume the prefix is there:

  • When idle, a push without it is dropped. processBytesAvailableAndInstreamSupported acts only on a leading 0xFF, then clears the buffer.
  • While streaming, it is resynced over. processPacket treats a bare 0x8A after a data packet as a bad header.

Teaching both of those, and the in-flight-command path, a prefix-less push would change parsing shared by every Shimmer3 and Shimmer3R. That would buy 2 bytes on 26 releases that already have a fixed successor.

Testing

  • New API_00026_Shimmer3rTwoByteCrcGateTest (5 tests, in ShimmerDriverPC):

    • v1.00.024 and v1.00.049: 2 bytes is refused by writeBtCommsCrcMode() and enableBtCommsTwoByteCrc(), and nothing is queued. 1 byte and off are still queued.
    • v1.00.023, v1.00.050, v1.01.000 and a Shimmer3 on v1.00.030 still get 2 bytes. v1.01.000 is there because the internal number restarts at each minor release.
    • At connect, a 2-byte default gives 1 byte on the affected releases and 2 elsewhere, and the setting itself stays at 2. Off and 1-byte defaults are unchanged.
  • Proof the tests catch the bug: with the refusal and the fallback disabled (the predicate left in), twoByteCrcIsRefusedWhereItOverrunsThePush and twoByteDefaultFallsBackToOneByteWhenConnecting fail, and the other three pass.

  • Full suites (JDK 11, Gradle 8.14.3):

    Command Result
    cd ShimmerDriver && ./gradlew test 154 tests, 0 failures
    cd ShimmerDriverPC && ./gradlew build -i BUILD SUCCESSFUL, 38 tests, 0 failures

Not verified on hardware

No Shimmer3R on v1.00.024 to v1.00.049 has been run against this. The fix rests on the firmware source, as read for DEV-1141, and on the instruction stack.

To check on one:

  1. Set Consensys to "2-bytes CRC Enabled".
  2. Connect, and confirm getCurrentBtCommsCrcMode() reports 1 byte.
  3. Dock and undock while streaming, and confirm the sensor keeps going.

After merge: consumers

None of these picks this up on its own:

  • ShimmerAndroidAPI pins shimmerdriver and shimmerbluetoothmanager at 0.11.7_beta. shimmerdriver 0.11.8_beta is already published without this, so it needs a new shimmerdriver release and both pins bumped.
    • shimmerBasicExample ignores the return of enableBtCommsTwoByteCrc() (MainActivity.java:131). After the bump, a refused 2-byte choice would still show as selected, so that is worth fixing in the same change.
  • Shimmer-MATLAB-ID vendors the driver as libs/ShimmerJavaClass.jar. It is not exposed to this defect: none of its scripts choose a CRC mode, so it runs the 1-byte default. DEV-976: stop turning the link CRC on for Shimmer3R firmware that drops it at a stop #316 already needs that jar rebuilt, and rebuilding after both merge carries both fixes.
  • 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-1141: keep a 2-byte CRC from overrunning the Shimmer3R status push shimmer-web-sdk#183, by the 0xA3 route.
  • C# (Shimmer-C-API): being ported under DEV-1141. InitializeShimmer3SDBT() writes whatever CRC mode the caller passes, and the shipped console example passes TWO_BYTE.
  • Swift (SwiftAPI): needs it, and is the most exposed. Shimmer3Protocol.connect() turns on a 2-byte CRC at every connect, before reading any version. Not changed here.
  • pyshimmer: not affected. It never enables a link CRC.

🤖 Generated with Claude Code

…0.024-049

Those releases build the unsolicited status push in uint8_t selfcmd[6]. ACK +
0x8A 0x71 + two status bytes + a 2-byte CRC is seven bytes, so the sensor
hardfaults the next time it pushes: on docking or undocking, the user button,
a trial-duration expiry or a low battery (DEV-621, fixed in v1.00.050).

writeBtCommsCrcMode is the only sender of SET_CRC_COMMAND, so the gate goes
there. On those releases a 2-byte request returns false and queues nothing,
and a 2-byte connect default (Consensys's "2-bytes CRC Enabled") falls back
to 1 byte, the low byte of the same CRC. Other firmware is unchanged.

The web SDK's route, turning the push's ACK prefix off with 0xA3 first, was
not taken: this driver's in-stream parsers expect the prefix, so a push
without it would be dropped when idle and resynced over while streaming.

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 tested, looks good

@MAzalya
MAzalya merged commit 5893474 into master Oct 5, 2026
@MAzalya
MAzalya deleted the DEV-1141_two_byte_crc_push_overrun branch October 5, 2026 04:23
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