Skip to content

DEV-976: refuse a Bluetooth CRC on Shimmer3R firmware that drops it when sensing stops - #211

Merged
JongChern merged 2 commits into
masterfrom
DEV-976_refuse_crc_on_firmware_that_drops_it
Oct 20, 2026
Merged

JongChern merged 2 commits into
masterfrom
DEV-976_refuse_crc_on_firmware_that_drops_it

Conversation

@marknolan

@marknolan marknolan commented Oct 2, 2026 •

Copy link
Copy Markdown
Member

DEV-976. The C# side of ShimmerResearch/shimmer-web-sdk#178 (merged) and ShimmerResearch/Shimmer-Java-Android-API#316 (open), which refuse a CRC on the same firmware.

Problem

Shimmer3R LogAndStream 0.0.2 to 1.0.10 (November and December 2024) turn the Bluetooth CRC (SET_CRC_COMMAND, 0x8B) off by themselves when sensing stops, and nothing tells the host. In shimmer3r-firmware at LogAndStream_Shimmer3R_v1.00.010, S4Sens_stopSensing clears it (S3R_Production/S4_App/s4_sensing.c:354) once every active mode has been told to stop:

  • on STOP_SDBT (0x97)
  • on STOP_STREAMING (0x20) while only streaming
  • on STOP_LOGGING (0x93), the user button or docking while only logging

The stop's own ACK still carries the CRC, but every reply after it is bare. shimmer3r-firmware c8016de3 removed the clears, so 1.0.11 is the first release that keeps the CRC. Every release also clears it at startup and on disconnect (shimmer_bt_comms.c:1068 and :2543).

This API never notices:

  • IsCRCSupported() was GetCompatibilityCode() >= 8, and SetCompatibilityCode gives every Shimmer3R LogAndStream code 8, so these releases passed.
  • StopStreaming and StopStreamingandLog sleep and flush, but never change BluetoothCRCMode.
  • The LogAndStream StopStreaming sends GET_STATUS 300 ms after the stop, and that is the first reply misread. From then on the parser takes N "CRC" bytes after each response. A later stream on the same link has every packet read as PacketSize+N, so its packets fail the CRC check. This lasts until a reconnect.

A CRC is only on when the caller asked for one: the CRCmode constructor argument, a direct WriteCRCMode call, ShimmerCapture's CRC checkbox (ONE_BYTE), or ShimmerConsoleAppExample (TWO_BYTE).

Fix

IsCRCSupported() now also requires the new public KeepsCRCWhenSensingStops(), which is false for Shimmer3R LogAndStream before 1.0.11.

On Shimmer3R LogAndStream 0.0.2–1.0.10 Before Now
IsCRCSupported() true false
WriteCRCMode(ONE_BYTE / TWO_BYTE) sent throws, sends nothing, names 1.0.11
WriteCRCMode(OFF) sent sent: never refused where the command exists
CRCmode constructor argument sent while connecting not sent. The device connects without a CRC, and a MSG_IDENTIFIER_NOTIFICATION_MESSAGE with MSG_WARNING says why
Connect-time OFF write (SetupDevice constructors without a CRC mode) sent not sent. The firmware clears its CRC at startup and on every disconnect, so the link starts without one. Java #316 skips its connect-time SET_CRC on these releases too
ShimmerCapture CRC checkbox shown hidden, as on firmware without the command

On every other firmware, Shimmer3 included, nothing changes.

How a refusal surfaces. The constructor path warns rather than throws, because it runs inside Connect(). Connect()'s catch turns any exception into "Unable to connect to specified port" and gives up on the connection. A MSG_WARNING notification is how ShimmerLogAndStream already reports problems that do not stop it, such as streaming-only mode on the dock. That step moves into WriteCRCModeToSetup() so it can be tested. A direct WriteCRCMode call throws, as it already does on firmware without the command. Callers that check IsCRCSupported() first now skip the CRC instead of getting the exception.

Why refuse. Refusing is the only answer that covers every stop. Dropping the API's own expectation after StopStreaming would miss the stops the device makes by itself (user button, docking), and nothing tells the host about those.

Why the hardware is checked. Shimmer3 and Shimmer3R version numbers overlap, and no Shimmer3 firmware clears the CRC at a stop, so the hardware version decides. The hardware is taken as the device reports it, which lets one build through. LogAndStream_Shimmer3R_v1.00.008 is a side build for older Consensys: it sets OLD_CONSENSYS_SUPPORT 1, and so DEVICE_VER 3. It cannot be told from a Shimmer3 on LogAndStream 1.0.8. The web SDK and Java make the same call.

A correction in the second commit. The first commit's message, and its version of the KeepsCRCWhenSensingStops comment, also credit S4Sens_checkStartStreamingConditions (s4_sensing.c:199) with a clear when a stream stops while logging carries on. No stop reaches that clear. With USE_FREERTOS 0 the scheduler runs the lowest pending task bit first. So TASK_STOPSENSING (bit 12) always runs before TASK_SAVEDATA (bit 17), and S4Sens_stopSensing resets btstreamCmd to IDLE before saveData can see the STOP that :199 waits for. With logging still on, the CRC stays on. b24c2c4 corrects the comment. Behaviour is unchanged.

Tests

ShimmerUnitTests/ShimmerCrcFirmwareTest runs on a ShimmerLogAndStream with no connection behind it, which records what it would have sent:

  • Shimmer3R LogAndStream 1.0.10: refused. WriteCRCMode(ONE_BYTE) and (TWO_BYTE) throw naming 1.0.11, nothing is sent, and the mode stays OFF.
  • Shimmer3R LogAndStream 1.0.11: allowed, sends 8B 02.
  • Shimmer3 LogAndStream 1.0.8: allowed, sends 8B 01.
  • WriteCRCMode(OFF) on 1.0.10 still sends 8B 00.
  • A TWO_BYTE constructor on 1.0.10 sends nothing and raises one MSG_WARNING. On 1.0.11, and on a Shimmer3 on 1.0.8, it is sent with no warning.
  • A sweep: Shimmer3R 0.0.2, 1.0.5, 1.0.8 and 1.0.10 refused; 1.0.11, 1.0.45, 1.1.0 and 2.0.0 allowed. Shimmer3 0.13.6 is still unsupported; 0.13.7, 0.16.9, 1.0.8 and 1.0.10 are allowed.

The test fails without the fix. Each row below is a separate build of the library, run against the same test:

Library code ShimmerCrcFirmwareTest
master's ShimmerBluetooth.cs and ShimmerLogAndStream.cs, plus only the two members the test calls, behaving as master does 3 of 7 fail: 1.0.10 refused, the constructor warning, the sweep
gate defined but not applied (IsCRCSupported() back to compat >= 8) the same 3 of 7 fail
boundary moved to 1.0.10 the same 3 of 7 fail
hardware check dropped 3 of 7 fail: the Shimmer3 1.0.8 cases
OFF refused too 1 of 7 fails
constructor path throws instead of warning 1 of 7 fails
this PR 7 of 7 pass; ShimmerBluetoothTests 35 of 35

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

Hardware: unverified. This rests on the firmware source and a recording test double. No Shimmer3R on LogAndStream 1.0.10 or earlier has been run against this change. To check on one: construct a ShimmerLogAndStream with BTCRCMode.TWO_BYTE and connect. You should get the MSG_WARNING. Then start and stop streaming, and confirm the GET_STATUS after the stop is answered.

Other copies in this repo

  • ShimmerCaptureXamarin/ShimmerBluetooth.cs and ShimmerAPI/TestSerialPort/Program.cs have no CRC code, so there is nothing to change. Xamarin carries only the SetCrcCommand value, in its LiteProtocolInstructionSet.cs.
  • ShimmerUnitTests/ShimmerBluetoothReadData.cs hides WriteCRCMode with new and only sets BluetoothCRCMode, so the parser tests can force a CRC on. It sets no firmware version, so the real WriteCRCMode would already have thrown there before this change. It bypasses the gate by design and is unchanged. It only hides the method rather than overriding it, so library code that calls WriteCRCMode still reaches the gated one.

Wrappers and consumers

  • Shimmer-Labview-API wraps this API through the ShimmerAPI NuGet package, pinned at 1.3.10 (ShimmerLabviewC#Wrapper/packages.config). It picks this change up only when it is rebuilt against a ShimmerAPI release that contains it. It is not exposed in the meantime. ShimmerBridge.cs uses the two-argument ShimmerLogAndStreamSystemSerialPort constructor, which leaves SetupDevice false, and never calls WriteCRCMode or IsCRCSupported. So it never turns a CRC on, and its traffic will not change when it is rebuilt.
  • ASM_BaseStation has no SET_CRC_COMMAND, WriteCRCMode or BTCRCMode, so it never turns a Shimmer3/3R link CRC on.

Sibling APIs

Overlap with open PRs

Checked with git merge-tree against this branch:

🤖 Generated with Claude Code

marknolan and others added 2 commits October 2, 2026 22:19
…hen sensing stops

Shimmer3R LogAndStream 0.0.2 to 1.0.10 (November and December 2024)
turn the Bluetooth CRC off by themselves whenever sensing stops: in
S4Sens_stopSensing (s4_sensing.c:354 at LogAndStream_Shimmer3R_v1.00.010),
and in S4Sens_checkStartStreamingConditions when a stream stops while
logging carries on. Between them they cover STOP_STREAMING, STOP_SDBT
and STOP_LOGGING, and the user button or docking ending SD logging, and
nothing tells the host. The stop's own ACK still carries the CRC, but
every reply after it is bare. StopStreaming and StopStreamingandLog never
change BluetoothCRCMode, so the API went on taking CRC bytes out of
replies that no longer had them. The first is the GET_STATUS that the
LogAndStream StopStreaming sends straight after the stop, and a later
stream on the same link had every packet read as PacketSize+N.
shimmer3r-firmware c8016de3 removed the clears, so 1.0.11 is the first
release that keeps the CRC.

IsCRCSupported() was GetCompatibilityCode() >= 8, and every Shimmer3R
LogAndStream gets code 8. It now also requires KeepsCRCWhenSensingStops(),
a new public check that is false for Shimmer3R LogAndStream before
1.0.11. So:

- WriteCRCMode(ONE_BYTE or TWO_BYTE) on those releases throws, sends
  nothing, and names 1.0.11. WriteCRCMode(OFF) is never refused where
  the command exists, so a caller that turns it off to be safe still can.
- A constructor's CRC mode is applied while connecting, where an
  exception would fail the connection. So the device connects without a
  CRC, and a MSG_IDENTIFIER_NOTIFICATION_MESSAGE with MSG_WARNING says
  why. That step moves into WriteCRCModeToSetup() so it can be tested.
  On those releases the connect-time OFF write is no longer sent either.
  The firmware clears its CRC at startup and on every disconnect, so the
  link starts without one anyway.
- ShimmerCapture's CRC checkbox follows IsCRCSupported(), so it is now
  hidden on those releases, as it is on firmware without the command.

Refusing, rather than dropping the API's expectation after a stop, is
the only answer that also covers the stops the device makes on its own.

Shimmer3 and Shimmer3R version numbers overlap, and no Shimmer3 firmware
clears the CRC at a stop, so the hardware version decides and Shimmer3
is unchanged. The hardware is taken as reported, which lets one build
through: LogAndStream_Shimmer3R_v1.00.008, a side build for older
Consensys, reports hardware 3 and cannot be told from a Shimmer3 on
LogAndStream 1.0.8. The web SDK makes the same call (shimmer-web-sdk#178).

ShimmerCrcFirmwareTest pins the boundary on a ShimmerLogAndStream with
no connection: Shimmer3R LogAndStream 1.0.10 refused, 1.0.11 allowed,
Shimmer3 LogAndStream 1.0.8 allowed, OFF never refused, and the
constructor path warning instead of throwing. Restoring the old gate,
moving the boundary to 1.0.10, or dropping the hardware check each fail
3 of its 7 tests. All 35 ShimmerBluetoothTests pass (Visual Studio's
MSBuild, vstest.console).

Derived from the firmware source. No Shimmer3R on 1.0.10 or earlier has
been run against this change.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The KeepsCRCWhenSensingStops comment said S4Sens_checkStartStreamingConditions
also clears the CRC when a stream stops while logging carries on. No stop
reaches that clear. BtUart_processCmd runs as TASK_BTPROCESS, and with
USE_FREERTOS 0 the scheduler always runs the lowest pending task bit first,
so TASK_STOPSENSING (bit 12) runs before TASK_SAVEDATA (bit 17).
S4Sens_stopSensing resets btstreamCmd to IDLE before saveData can see the
STOP that s4_sensing.c:199 waits for. With logging still on, the CRC stays on.

So the clear that matters is S4Sens_stopSensing's (s4_sensing.c:354 at
LogAndStream_Shimmer3R_v1.00.010), and it runs only once every active mode
has been told to stop: on STOP_SDBT, on STOP_STREAMING while only streaming,
and on STOP_LOGGING, the user button or docking while only logging. This is
also how shimmer-web-sdk#178 reads the same source. Comment only.

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.

Verified against shimmer3r-firmware: setBtCrcMode(CRC_OFF) at s4_sensing.c:354 in LogAndStream_Shimmer3R_v1.00.010, removed by c8016de3, which v1.00.011 is the first tag to contain. The gate refuses exactly Shimmer3R LogAndStream < 1.0.11 (compareVersions is >=), matching Java #316 and web SDK #178. CI re-run against today's master: all green (unit tests 47/47, PublishNuGet pack).

@JongChern
JongChern merged commit 5320cfe into master Oct 20, 2026
6 checks passed
@JongChern
JongChern deleted the DEV-976_refuse_crc_on_firmware_that_drops_it branch October 20, 2026 03:57
@JongChern
JongChern restored the DEV-976_refuse_crc_on_firmware_that_drops_it branch October 20, 2026 03:58
@JongChern
JongChern deleted the DEV-976_refuse_crc_on_firmware_that_drops_it branch October 20, 2026 03:58
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