Skip to content

DEV-1141: refuse a 2-byte Bluetooth CRC on Shimmer3R firmware whose status push it overruns - #214

Merged
JongChern merged 2 commits into
masterfrom
DEV-1141_two_byte_crc_push_overrun
Oct 20, 2026
Merged

JongChern merged 2 commits into
masterfrom
DEV-1141_two_byte_crc_push_overrun

Conversation

@marknolan

@marknolan marknolan commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

DEV-1141. The C# side of ShimmerResearch/shimmer-web-sdk#183 (merged), ShimmerResearch/Shimmer-Java-Android-API#318 (open) and ShimmerResearch/SwiftAPI#23 (open, DEV-1144).

Stacked on #211 (DEV-976). This PR's base is DEV-976_refuse_crc_on_firmware_that_drops_it, and it is one commit on top of it: it builds on #211's WriteCRCModeToSetup() and its CrcFirmwareDevice test double, and edits the same WriteCRCMode. Merge #211 first. This repo doesn't delete merged branches, so GitHub won't retarget this PR by itself: point it at master once #211 merges. CI runs only on PRs into master, so it hasn't run here yet; the same build and tests were run locally (see Tests).

Problem

Shimmer3R LogAndStream 1.0.24 to 1.0.49 hardfault when the status push they send by themselves carries a 2-byte Bluetooth CRC (DEV-621, fixed in 1.0.50). ShimBt_instreamStatusRespSend builds the push in uint8_t selfcmd[6] (log-and-stream-common Comms/shimmer_bt_uart.c:2262 at f39be8c1f, which 1.0.49 pins):

Push Bytes Fits in 6?
ACK prefix + 0x8A 0x71 + 2 status bytes + 2-byte CRC (1.0.24 to 1.0.49) 7 No. The 7th lands past the end of the buffer.
ACK prefix + 0x8A 0x71 + 2 status bytes + 1-byte CRC 6 Yes
ACK prefix + 0x8A 0x71 + 1 status byte + 2-byte CRC (1.0.23 and earlier, any Shimmer3) 6 Yes
  • When it fires. The firmware pushes on docking and undocking, and when the user button, a trial-duration expiry or a low battery starts or stops sensing. The host's own starts and stops don't push, so the hardfault can come at any point after the CRC goes on, mid-stream included.
  • Range, checked at every tag. v1.00.020 to v1.00.049 pin a log-and-stream-common without merge 4fb8696, which sizes the buffer for the CRC. v1.00.050 to v1.00.060 and v1.01.000 to v1.01.018 all pin one with it.

This API never checked:

Fix

TwoByteCRCOverrunsStatusPush() is a new public check, true for Shimmer3R LogAndStream 1.0.24 to 1.0.49. Its lower bound is IsTwoByteStatusResponseSupported(), the check the status parsing already uses, so the two can't drift apart.

On Shimmer3R LogAndStream 1.0.24 to 1.0.49 Before Now
WriteCRCMode(TWO_BYTE) sent throws, sends nothing, and names a 1-byte CRC and 1.0.50
WriteCRCMode(ONE_BYTE) and (OFF) sent sent
CRCmode constructor argument TWO_BYTE sent while connecting ONE_BYTE is sent, and a MSG_WARNING notification says why
IsCRCSupported() true true

On every other firmware, Shimmer3 included, nothing changes.

Why the constructor path falls back rather than refusing. It runs inside Connect(), whose catch turns any exception into a failed connection, which is why #211 warns there instead of throwing. Unlike #211's releases, these keep a 1-byte CRC fine, and it fits the push, so the caller keeps a check on the link. The constructor's mode itself is left as given.

Why not turn the prefix off, as the web SDK does. shimmer-web-sdk#183 sends 0xA3 0x00 first, which makes the push six bytes and keeps the 2-byte CRC. Two things in this API stand in the way:

  • A push without the prefix would be lost while streaming. ReadData reaches the in-stream handler only behind a 0xFF (ShimmerBluetooth.cs:1359-1375). A bare 0x8A falls to default and is dropped as misaligned (:1399-1403). For a stop the device makes by itself, the API would stay in the streaming state, raise no "Stopped.", and about 11 s later report "Connection lost" and disconnect (:1890-1895, ReadTimeout 1000 ms).
  • It can't tell whether 0xA3 worked. WriteCRCMode writes and sleeps; nothing waits for an ACK, so the 2-byte CRC couldn't be refused when 0xA3 fails, as the web SDK does.

Fixing both means changing the parser every ShimmerBluetooth subclass shares, for firmware that updating to 1.0.50 fixes. Java (ShimmerResearch/Shimmer-Java-Android-API#318) and Swift (ShimmerResearch/SwiftAPI#23) made the same call. The docblock on TwoByteCRCOverrunsStatusPush records why, so nobody aligns it with the web SDK without the parser change.

The firmware side was read at f39be8c1f: the prefix flag is read only for this self-push (shimmer_bt_uart.c:2264), command replies get their 0xFF from sendAck (:1623-1626), and the prefix is turned back on only at startup and on disconnect, both times straight after the CRC is set to off.

ShimmerConsoleAppExample now prints notification messages. It discarded them, so the fallback's warning would never have reached the one shipped caller that asks for TWO_BYTE.

Tests

ShimmerUnitTests/ShimmerCrcStatusPushTest (7 tests) runs on #211's CrcFirmwareDevice, which records what it would have sent. #211's three helpers in ShimmerCrcFirmwareTest became internal so it can share them.

  • 1.0.24 and 1.0.49: WriteCRCMode(TWO_BYTE) throws naming 1.0.50, nothing is sent, and the mode stays OFF. ONE_BYTE and OFF are sent.
  • A link already on ONE_BYTE keeps it when TWO_BYTE is refused.
  • A TWO_BYTE constructor on 1.0.24 and 1.0.49 sends 8B 01 and raises one MSG_WARNING. A ONE_BYTE one raises none.
  • Where the push has room, a TWO_BYTE constructor is sent as it is: Shimmer3R 1.0.23 and 1.0.50, and a Shimmer3 on 1.0.24 and 1.0.49.
  • A sweep: Shimmer3R 1.0.24, 1.0.40 and 1.0.49 overrun. Shimmer3R 1.0.11, 1.0.23, 1.0.50, 1.0.60, 1.1.0, 1.1.18 and 2.0.0 don't, and neither does a Shimmer3 on 1.0.24 or 1.0.49.

The tests fail without the fix. Each row is a separate build of the library, run against the same tests:

Library code ShimmerCrcStatusPushTest
check always false 4 of 7 fail
WriteCRCMode doesn't refuse 2 of 7 fail
connect-time write left as #211 has it (the refusal then throws inside Connect()) 1 of 7 fails
upper bound moved to 1.0.49 3 of 7 fail
upper bound moved to 1.0.51 2 of 7 fail
lower bound 1.0.23 instead of the status width 2 of 7 fail
hardware check dropped 2 of 7 fail
this PR 7 of 7 pass; ShimmerBluetoothTests 42 of 42

Built with Visual Studio 2022's MSBuild (a full rebuild of ShimmerAPITest.sln) and run under vstest.console, as CI does. No new compiler warnings, and ShimmerConsoleAppExample builds.

Hardware: unverified. This rests on the firmware source and a recording test double. To check on a Shimmer3R on LogAndStream 1.0.24 to 1.0.49: run ShimmerConsoleAppExample, which asks for TWO_BYTE. The MSG_WARNING should print and the link should run a 1-byte CRC. Then undock it or press the user button while streaming, and the sensor should stay up.

Other copies in this repo

  • ShimmerCaptureXamarin/ShimmerBluetooth.cs and ShimmerAPI/TestSerialPort/Program.cs have no CRC code, so there is nothing to change.
  • ShimmerSDBT and Shimmer32FeetAPI's ShimmerSDBT32Feet inherit ShimmerBluetooth.WriteCRCMode, so the refusal covers them. Neither turns a CRC on by itself.
  • ShimmerCapture only offers ONE_BYTE (Control.cs:2924), so it isn't exposed.

Wrappers and consumers

  • Shimmer-Labview-API isn't exposed: ShimmerBridge.cs:24 uses the two-argument ShimmerLogAndStreamSystemSerialPort constructor and never turns a CRC on. It picks this up only when rebuilt against a ShimmerAPI package that contains it (it pins 1.3.10), and no republish is needed for its sake.
  • ASM_BaseStation has no SET_CRC_COMMAND, so it never turns a link CRC on.

Sibling APIs

Overlap with open PRs

Checked with git merge-tree against this branch:

🤖 Generated with Claude Code

…tatus push it overruns

Shimmer3R LogAndStream 1.0.24 to 1.0.49 build the status push they send
by themselves in uint8_t selfcmd[6] (ShimBt_instreamStatusRespSend,
log-and-stream-common Comms/shimmer_bt_uart.c:2262 at f39be8c1f, which
1.0.49 pins). With the ACK prefix, which is on by default, the push is
FF 8A 71 and two status bytes, so a 2-byte CRC makes seven bytes and the
seventh lands past the end of the buffer. The sensor hardfaults (DEV-621,
fixed in 1.0.50 by log-and-stream-common merge 4fb8696). The firmware
pushes on docking and undocking, and when the user button, a
trial-duration expiry or a low battery starts or stops sensing, so the
fault can come at any point after the CRC goes on. WriteCRCMode sent
TWO_BYTE to any firmware that passed IsCRCSupported, and
ShimmerConsoleAppExample connects with it.

TwoByteCRCOverrunsStatusPush() is a new public check, true for Shimmer3R
LogAndStream from 1.0.24, the first release with two status bytes
(IsTwoByteStatusResponseSupported), to 1.0.49. There WriteCRCMode(TWO_BYTE)
throws and sends nothing, and a constructor's TWO_BYTE is turned on as
ONE_BYTE with a MSG_WARNING, since an exception there would fail
Connect(). A 1-byte CRC fits the push, and IsCRCSupported() stays true.

The web SDK keeps the 2-byte CRC by turning the push's ACK prefix off
first (0xA3). Not here: while streaming, ReadData only finds a status push
behind the prefix, so a push without it, and any stop it reports, would
be dropped.

ShimmerConsoleAppExample now prints notification messages, so the
warning reaches the one shipped caller that asks for TWO_BYTE.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@JongChern
JongChern deleted the branch DEV-976_refuse_crc_on_firmware_that_drops_it October 20, 2026 03:57
@JongChern JongChern closed this Oct 20, 2026
@JongChern JongChern reopened this Oct 20, 2026
@JongChern
JongChern changed the base branch from DEV-976_refuse_crc_on_firmware_that_drops_it to master October 20, 2026 03:58
@JongChern JongChern closed this Oct 20, 2026
@JongChern JongChern reopened this Oct 20, 2026
Resolves the conflict with #212 (DEV-976, switch the link CRC at the
SET_CRC ACK) as this PR's description sets out:
- WriteCRCMode: the 2-byte refusal runs before mCRCModeAfterACK and the
  ACK wait flag are set, so a refused call never leaves the flag set.
- Its docblock keeps both PRs' additions.
- ShimmerUnitTests.csproj compiles both ShimmerCrcStatusPushTest.cs and
  ShimmerCrcSwitchTest.cs.

Built ShimmerAPITest.sln with VS 18 MSBuild and ran ShimmerBluetoothTests
under vstest.console, as CI does: 65 of 65 pass (master's 58 plus this
PR's 7). ShimmerConsoleAppExample, which CI does not build, also builds.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 20, 2026 04:32

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The Shimmer3R fallback is currently unreachable because compatibility initialization does not produce the required result.

No open issues 🎉

What changed in this PR

Adds firmware-aware protection against unsafe 2-byte CRCs on affected Shimmer3R LogAndStream firmware.

Changes:

  • Refuses unsafe 2-byte CRC configuration and falls back to 1-byte CRC.
  • Adds firmware-boundary tests and shared test helpers.
  • Displays notification messages in the console example.
File Reviewed changes
ShimmerConsoleAppExample/​ShimmerConsoleAppExample/​Program.cs Prints notification messages.
ShimmerAPI/​ShimmerUnitTests/​ShimmerUnitTests.csproj Includes the new test file.
ShimmerAPI/​ShimmerUnitTests/​ShimmerCrcStatusPushTest.cs Tests firmware ranges and CRC fallback behavior.
ShimmerAPI/​ShimmerUnitTests/​ShimmerCrcFirmwareTest.cs Shares test helpers.
ShimmerAPI/​ShimmerAPI/​ShimmerLogAndStream.cs Implements constructor fallback and warning; compatibility initialization makes the fallback unreachable for affected Shimmer3R devices, and documentation needs rewording.
ShimmerAPI/​ShimmerAPI/​ShimmerBluetooth.cs Adds CRC-overrun detection and refusal logic.

Review effort: Lite

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

Verified the firmware overrun: Shimmer3R v1.00.049 pins log-and-stream-common f39be8c1f, where the status push is built in uint8_t selfcmd[6] (Comms/shimmer_bt_uart.c:2262); with two status bytes and a 2-byte CRC it is 7 bytes. v1.00.050 pins 4661e333a, which has merge 4fb8696 (DEV-621) and sizes the buffer for the CRC. The 1.0.24 to 1.0.49 range matches Java's isTwoByteCrcOverrunningStatusPush (#318, shipped in 0.11.9_beta).

Merged master in (5e9096f) with the resolution the description sets out: the 2-byte refusal runs before #212's ACK wait flag is set. Built ShimmerAPITest.sln and ran ShimmerBluetoothTests under vstest locally (65/65), and ShimmerConsoleAppExample builds; CI on 5e9096f is green (65/65, PublishNuGet pack).

Copilot's "fallback is unreachable" note was checked and doesn't hold: the state is Connecting (ShimmerBluetooth.cs:980) before Connect(), and the hardware- and firmware-version reply handlers call SetCompatibilityCode() (code 8 for Shimmer3R LogAndStream) before InitializeShimmer3SDBT(), so IsCRCSupported() is true on 1.0.24 to 1.0.49 and the 1-byte fallback runs. The unit test reaches it through the same real SetCompatibilityCode().

@JongChern
JongChern merged commit 38ee5d0 into master Oct 20, 2026
5 checks passed
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.

3 participants