Repository navigation
DEV-1141: refuse a 2-byte Bluetooth CRC on Shimmer3R firmware whose status push it overruns - #214
Conversation
…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]>
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]>
There was a problem hiding this comment.
🔵 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
left a comment
There was a problem hiding this comment.
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().
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).
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_instreamStatusRespSendbuilds the push inuint8_t selfcmd[6](log-and-stream-commonComms/shimmer_bt_uart.c:2262at f39be8c1f, which 1.0.49 pins):This API never checked:
WriteCRCModesends whateverIsCRCSupported()allows, and with DEV-976: refuse a Bluetooth CRC on Shimmer3R firmware that drops it when sensing stops #211 that is every Shimmer3R LogAndStream from 1.0.11.CRCmodeconstructor argument sends TWO_BYTE while connecting, and the shippedShimmerConsoleAppExamplepasses it (Program.cs:37).SET_INSTREAM_RESPONSE_ACK_PREFIX_STATE(0xA3), so the prefix is always on.Fix
TwoByteCRCOverrunsStatusPush()is a new public check, true for Shimmer3R LogAndStream 1.0.24 to 1.0.49. Its lower bound isIsTwoByteStatusResponseSupported(), the check the status parsing already uses, so the two can't drift apart.WriteCRCMode(TWO_BYTE)WriteCRCMode(ONE_BYTE)and(OFF)CRCmodeconstructor argument TWO_BYTEMSG_WARNINGnotification says whyIsCRCSupported()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:
ReadDatareaches the in-stream handler only behind a0xFF(ShimmerBluetooth.cs:1359-1375). A bare0x8Afalls todefaultand 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,ReadTimeout1000 ms).WriteCRCModewrites 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
ShimmerBluetoothsubclass 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 onTwoByteCRCOverrunsStatusPushrecords 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 their0xFFfromsendAck(: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.ShimmerConsoleAppExamplenow 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'sCrcFirmwareDevice, which records what it would have sent. #211's three helpers inShimmerCrcFirmwareTestbecameinternalso it can share them.WriteCRCMode(TWO_BYTE)throws naming 1.0.50, nothing is sent, and the mode stays OFF. ONE_BYTE and OFF are sent.8B 01and raises oneMSG_WARNING. A ONE_BYTE one raises none.The tests fail without the fix. Each row is a separate build of the library, run against the same tests:
WriteCRCModedoesn't refuseConnect())Built with Visual Studio 2022's MSBuild (a full rebuild of
ShimmerAPITest.sln) and run undervstest.console, as CI does. No new compiler warnings, andShimmerConsoleAppExamplebuilds.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. TheMSG_WARNINGshould 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.csandShimmerAPI/TestSerialPort/Program.cshave no CRC code, so there is nothing to change.ShimmerSDBTandShimmer32FeetAPI'sShimmerSDBT32FeetinheritShimmerBluetooth.WriteCRCMode, so the refusal covers them. Neither turns a CRC on by itself.Control.cs:2924), so it isn't exposed.Wrappers and consumers
ShimmerBridge.cs:24uses the two-argumentShimmerLogAndStreamSystemSerialPortconstructor 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.SET_CRC_COMMAND, so it never turns a link CRC on.Sibling APIs
writeBtCommsCrcModerefuses TWO_BYTE on these releases, and a 2-byte default falls back to 1 byte at connect.connect()sent SET_CRC TWO_BYTE on every connect, before reading any version. It now reads the versions first, then uses 1 byte on these releases and none before 1.0.11, and a later SET_CRC stronger than that is refused. Swift parses no status pushes, so it doesn't take the 0xA3 route either. It was written without Xcode, so its CI run is its first compile.Overlap with open PRs
Checked with
git merge-treeagainst this branch:WriteCRCMode, keep both: the TWO_BYTE refusal goes beforemCRCModeAfterACK = mode;, so a refused call never sets the wait flag, and the docblock keeps both additions. InShimmerUnitTests.csproj, keep both<Compile>lines. Their tests run on Shimmer3R 1.1.17, which this check allows, so nothing in them changes behaviour.ShimmerBLE/ShimmerBLEAPI/Models/BasePayload.cs, which this PR doesn't touch. They conflict with DEV-976: refuse a Bluetooth CRC on Shimmer3R firmware that drops it when sensing stops #211 the same way.🤖 Generated with Claude Code