Repository navigation
DEV-982: handle NACK from a Shimmer3/3R instead of timing out the connection - #204
Conversation
The protocol has had a NACK (0xFE) reply for a long time; this API never learned about it. A 0xFE fell through to the switch default in both branches of ReadData(): while streaming that logged "Misaligned ByteStream Detected" and discarded the packet in progress, and otherwise it was dropped silently. Either way the reply the caller was waiting for never arrived, ReadByte() carried on raising TimeoutException, and once StreamTimeOutCount passed 10 the API raised "Connection lost" and disconnected - about ten seconds after a refusal the device had already reported cleanly. A refused command was indistinguishable from a dead link, and the log actively misdirected. This is the same defect as Shimmer-Java-Android-API#293, found by checking the sibling implementations of the wire format after that one. The timing and the mechanism differ - Java tore the link down after two seconds via its ACK timer - but the cause is identical: only ACK was tested for. The firmware refuses more than it used to. Every command except SET_SD_SYNC_COMMAND and ACK is refused while SD sync is enabled (ShimBt_isCmdAllowedWhileSdSyncing), which includes the whole connect sequence, so a sync-enabled Shimmer cannot be connected to at all. Also any SET while sensing, a sync-mode mismatch, an out-of-range InfoMem or calibration write, and several commands the dispatcher accepts but that were never implemented. ProcessNackFromCommand() is protected virtual so an application can surface the refusal; by default it logs and raises a notification event. It clears mWaitingForStartStreamingACK, which a refused START_STREAMING would otherwise leave set for the rest of the session, and consumes the CRC bytes the firmware appends to the NACK packet when CRC mode is on - those would otherwise be read as the next packet header. None of the three SDBT_switch overrides looked at 0xFE, so adding an explicit case ahead of the default changes nothing else. ShimmerCaptureXamarin carries a second, diverged copy of ShimmerBluetooth.cs with the same defect. It is deliberately left alone: nothing has touched it since July 2017, neither CI workflow builds it, and Xamarin is end of life, so a change there could not be verified by anything. Worth fixing if that sample is ever revived. ShimmerAPI builds clean; the ten warnings are pre-existing and in files this does not touch. Co-Authored-By: Claude Opus 5 <[email protected]>
e5bf48a to
69442ca
Compare
|
Two things found while working on #212 (DEV-976), which changes how 1. When not streaming, a NACK's CRC is dropped twice.
Suggested fix, tried in the scratch merge: leave the NACK out of the trailing drop. if (b != 0xff && b != (byte)PacketTypeShimmer2.NACK_COMMAND)With that, the rate is read in both modes. 2. A refused
Suggested fix, tried in the scratch merge on top of #212:
With both changes the API stays at 🤖 Generated with Claude Code |
|
This drops a NACK's CRC twice while connected. With a link CRC on, if (BluetoothCRCMode != BTCRCMode.OFF)
{
if (b != 0xff) // 0xFE passes, so the NACK's CRC is dropped a second timeBefore this PR, that trailing drop alone took a NACK's CRC correctly:
The streaming branch has no trailing drop, so there the drop in How I reproduced it. I merged this branch onto #212, with and without #213, and ran the API's read loop against #212's
Suggested fix. Drop the CRC in the streaming branch's // streaming branch only
case (byte)PacketTypeShimmer2.NACK_COMMAND:
for (int k = 0; k < (int)BluetoothCRCMode; k++)
{
ReadByte();
}
ProcessNackFromCommand();
break;Then remove the CRC loop from I found this while fixing DEV-1145 in #213, which deals with the same trailing drop for a bare ACK. |
While connected, ProcessNackFromCommand dropped the NACK's link CRC and the drop after every reply that does not start with an ACK dropped it again, taking the next reply's first bytes: with a two-byte CRC, the ACK and response code of the next reply, or the start command's ACK. The drop now happens in ReadData only: after the switch while connected, and in the NACK case while streaming, where nothing else drops it. The firmware refuses SET_CRC_COMMAND before it switches, and frames the NACK in the old mode. WriteCRCMode applied the new mode anyway when its wait ended; it now keeps the old one when the command is refused. ShimmerNackTest runs the read loop against CrcLinkDevice, which can now refuse chosen commands. Five of its seven tests fail without these fixes; the mid-stream one fails if the streaming drop is removed. Co-Authored-By: Claude Opus 5.5 <[email protected]>
There was a problem hiding this comment.
🟡 Changes recommended
Moderate CRC-handling and protocol-state issues remain unresolved.
1 open issue
What changed in this PR
Adds Shimmer3/3R NACK handling so refused commands are reported instead of causing stream corruption or connection loss.
Changes:
- Handles NACK responses and CRC-aware state handling.
- Preserves streaming and CRC state after refusals.
- Adds simulated-device regression tests.
| File | Reviewed changes |
|---|---|
ShimmerAPI/ShimmerUnitTests/ShimmerUnitTests.csproj |
Includes the new NACK test file. |
ShimmerAPI/ShimmerUnitTests/ShimmerNackTest.cs |
Adds NACK behavior regression tests. |
ShimmerAPI/ShimmerUnitTests/ShimmerCrcSwitchTest.cs |
Extends the test device to emit NACK responses. |
ShimmerAPI/ShimmerAPI/ShimmerBluetooth.cs |
Implements NACK parsing, notifications, CRC handling, and state updates. |
Review effort: Lite
| /// or after calling this, so an override that does not call it cannot | ||
| /// leave the CRC in the stream. | ||
| /// </remarks> | ||
| protected virtual void ProcessNackFromCommand() |
JongChern
left a comment
There was a problem hiding this comment.
Approved. Both of Mark's findings are fixed in 9357f83:
- A NACK's link CRC is now dropped once. While connected, the drop after every reply that does not start with an ACK takes it; while streaming, the NACK case does. ProcessNackFromCommand no longer drops it.
- A NACKed SET_CRC_COMMAND keeps the old CRC mode, since the firmware refuses before it switches.
ShimmerNackTest adds 7 tests against CrcLinkDevice, which can now refuse chosen commands. Five fail without the fixes, and the mid-stream test fails if the streaming drop is removed. 77/77 pass locally and in CI, with master merged in.

The protocol has had a
NACK_COMMAND_PROCESSED(0xFE) reply for a long time. ThisAPI never learned about it, so
0xFEfell through to theswitchdefault in bothbranches of
ReadData().What was happening
"Misaligned ByteStream Detected"and nullsthe packet in progress. A clean refusal was reported as stream corruption.
Either way the reply the caller was waiting for never arrived,
ReadByte()carried onraising
TimeoutException, and onceStreamTimeOutCountpassed 10 the API raised"Connection lost"and disconnected — roughly ten seconds after the device hadalready told us, cleanly, that it would not do the thing.
A refused command was indistinguishable from a dead link, and the log actively
misdirected.
Why this is being raised now
This is the same defect as
Shimmer-Java-Android-API#293,
found by checking the sibling implementations of the wire format afterwards. The
mechanism and the timing differ — Java tore the link down after two seconds via its ACK
timer, this API times out and disconnects after about ten — but the cause is identical:
only ACK was ever tested for.
SwiftAPIhas the same gap and is being fixed alongside;the TypeScript SDK already handles it.
Where it bites
Of the ~14
sendNacksites in the firmware'sshimmer_bt_uart.c, only one is theblocked-while-sensing gate, and sending commands mid-stream is not a supported
operation anyway. The rest are reachable while idle:
SET_SD_SYNC_COMMANDand ACK —ShimBt_isCmdAllowedWhileSdSyncingargs[]SET_SAMPLING_RATE_COMMANDwith a zero clock dividerSET_INFOMEM_COMMANDoffset out of rangeSET_DAUGHTER_CARD_MEMEEPROM write failureSET_CHARGE_STATUS_LED_COMMAND,SET_BT_COMMS_BAUD_RATEThe SD sync one is the sharpest: with sync enabled the firmware refuses the whole
connect sequence, so a sync-enabled Shimmer cannot be connected to at all.
What this changes
ProcessNackFromCommand()isprotected virtual, so an application can override it tosurface the refusal; by default it logs and raises a notification event on the existing
MSG_IDENTIFIER_NOTIFICATION_MESSAGEchannel. It also:mWaitingForStartStreamingACK— a refusedSTART_STREAMINGwouldotherwise leave that flag set for the rest of the session, so the next stray ACK
would flip the state machine to
STREAMING.on. The firmware writes the refusal as a complete response packet and appends CRC to
it exactly as it would to a response, so without this those bytes would be read as
the next packet header.
None of the three
SDBT_switchoverrides looked at0xFE, so adding an explicit caseahead of the default changes nothing else.
The Xamarin duplicate is deliberately left alone
ShimmerCaptureXamarincarries a second, diverged copy ofShimmerBluetooth.cswiththe same defect. I patched it, then took it back out: nothing has touched that tree
since July 2017, neither CI workflow builds it, and Xamarin is end of life, so
nothing could verify the change — not CI, not a local build. I would rather flag it here
than ship unverified edits to dead code. Worth doing if that sample is ever revived.
Verification
ShimmerAPIbuilds clean — 0 errors. The ten warnings are pre-existing and in filesthis does not touch (
TestRadio.cs,SerialPortRadio.cs,ShimmerSDLog.cs,ShimmerLogAndStream.cs) plusNU1701package-restore noise.No hardware test. There is no fake transport for the receive path in this repo, so
exercising a NACK end-to-end would mean building one; that is worth its own piece of
work rather than being half-built inside this change. The equivalent change in
pyshimmerdoes carry tests, because that repo already has the fixtures for it.Worth a bench check alongside the Java one: enable SD sync on a Shimmer, connect, and
confirm the connection now survives and the refusal is reported, where previously it
dropped with
"Connection lost".🤖 Generated with Claude Code