DEV-982: handle NACK from a Shimmer3/3R instead of timing out the connection

[marknolan]

The protocol has had a NACK_COMMAND_PROCESSED (0xFE) reply for a long time. This
API never learned about it, so 0xFE fell through to the switch default in both
branches of ReadData().

What was happening

• While streaming — the default logs "Misaligned ByteStream Detected" and nulls
  the packet in progress. A clean refusal was reported as stream corruption.
• Otherwise — the byte was consumed and 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 — roughly ten seconds after the device had
already 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. SwiftAPI has the same gap and is being fixed alongside;
the TypeScript SDK already handles it.

Where it bites

Of the ~14 sendNack sites in the firmware's shimmer_bt_uart.c, only one is the
blocked-while-sensing gate, and sending commands mid-stream is not a supported
operation anyway. The rest are reachable while idle:

Condition
SD sync enabled	refuses everything except SET_SD_SYNC_COMMAND and ACK — ShimBt_isCmdAllowedWhileSdSyncing
a sync command while sync is disabled	same XOR gate
payload truncated past args[]
SET_SAMPLING_RATE_COMMAND with a zero clock divider
calibration RAM write out of range
SET_INFOMEM_COMMAND offset out of range
SET_DAUGHTER_CARD_MEM EEPROM write failure
SET_CHARGE_STATUS_LED_COMMAND, SET_BT_COMMS_BAUD_RATE	dispatched but never implemented

The 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() is protected virtual, so an application can override it to
surface the refusal; by default it logs and raises a notification event on the existing
MSG_IDENTIFIER_NOTIFICATION_MESSAGE channel. It also:

• clears mWaitingForStartStreamingACK — a refused START_STREAMING would
  otherwise leave that flag set for the rest of the session, so the next stray ACK
  would flip the state machine to STREAMING.
• consumes the CRC bytes the firmware appends to the NACK packet when CRC mode is
  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_switch overrides looked at 0xFE, so adding an explicit case
ahead of the default changes nothing else.

The Xamarin duplicate is deliberately left alone

ShimmerCaptureXamarin carries a second, diverged copy of ShimmerBluetooth.cs with
the 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

ShimmerAPI builds clean — 0 errors. The ten warnings are pre-existing and in files
this does not touch (TestRadio.cs, SerialPortRadio.cs, ShimmerSDLog.cs,
ShimmerLogAndStream.cs) plus NU1701 package-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
pyshimmer does 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