Skip to content

DEV-1431: a log start the device refuses (NACK) ends at once, idle or mid-stream - #345

Merged
JongChern merged 1 commit into
masterfrom
DEV-1431_nack_refused_log_start
Nov 13, 2026
Merged

JongChern merged 1 commit into
masterfrom
DEV-1431_nack_refused_log_start

Conversation

@marknolan

@marknolan marknolan commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Firmware that cannot start a log will refuse the start with a NACK (ShimmerResearch/log-and-stream-common#228, DEV-1431). This makes the driver ready for that, and it has to land before that firmware ships.

Stacked on #293 (DEV-982, NACK handling), whose branch is this PR's base, so the diff here is DEV-1431's alone. Merge #293 first, then this, then the firmware.

Since the first review

The review comment above was right on every point: the firmware also refuses a log start in the middle of a stream, this PR handled only the idle case, and it duplicated #293's NACK_COMMAND_PROCESSED. The branch is rebuilt on #293 (after merging master into #293, which merged cleanly) and now covers the mid-stream case. The firmware PR stays in draft until this and the Android port are done.

The problem

The firmware starts a log only when the device is undocked, off USB power, has an SD card in with no file error, and has logging turned on in its configuration. Released firmware ACKs START_LOGGING_ONLY_COMMAND (0x92) and START_SDBT_COMMAND (0x70) even when it can't log, and does nothing (START_SDBT then streams alone). The new firmware NACKs them instead (0xFE) and starts nothing. Its rule doesn't look at streaming, so a 0x92 sent mid-stream on USB power is refused too, the NACK coming between two data packets.

On master the driver had no NACK handling:

  • Idle: processNotStreamingWaitForAck dropped the 0xFE, and the ACK timer ran out 5 s later. For START_LOGGING_ONLY, checkForAckOrRespTask's Consensys special case took the device to be logging, a false success. For START_SDBT it dropped the connection.
  • Mid-stream: processPacket threw the NACK away with the packet in front of it, and 2 s later the same special case took the device to be logging.

The change

  • One NACK path. Handle NACK from a Shimmer3/3R instead of dropping the connection #293's processNackFromCommand() unwinds the refused command and keeps the link. A refused log start then goes to processLogStartRefused(command):
    • the device is left not logging (after START_SDBT, not streaming either; a stream running when 0x92 was sent goes on);
    • after START_SDBT, the status reads that startDataLogAndStreaming() stopped start again;
    • the new protected hook eventLogStartRefused(byte command) is called, before Handle NACK from a Shimmer3/3R instead of dropping the connection #293's eventCommandRefused. By default it passes LOG_START_REFUSED_MESSAGE to sendStatusMSGtoUI, which Android shows as a toast. ShimmerPC's sendStatusMSGtoUI is empty, so Consensys sees the device stay "not logging" but gets no message yet. Telling the user is a separate Consensys change.
  • A NACK mid-stream now waits for its own link CRC (C5, or C5 56) and checks it, as a bare ACK's already is. This is the CRC follow-up raised in Handle NACK from a Shimmer3/3R instead of dropping the connection #293's review:
  • processNackFromCommand() is protected, because ShimmerAndroidAPI's Shimmer.java has its own streaming parser and must fail the command the same way.

An ACKed start is unchanged.

How often Consensys will meet it

Consensys disables Start to SD while a device is docked, or on USB power (a bit only Shimmer3R firmware 1.0.24 and later reports). It doesn't check for a missing card, a card error, or logging turned off, so those cases still reach the NACK, idle or streaming. Consensys sends only START_LOGGING_ONLY; START_SDBT comes from startDataLogAndStreaming() callers such as the PC examples and Android apps.

Tests

  • API_00036_LogStartRefusedTest (idle; the real IOThread over an in-memory radio, which now appends real CRCs):

    • a refused log-only start with no CRC, a 1-byte and a 2-byte CRC, and a refused combined start: each is handled in well under the ACK timer, leaves the device not logging, keeps the connection, and lets the next command through;
    • the refused combined start reads the status again;
    • an ACKed start still logs.
  • API_00037_StreamingLogStartRefusedTest (the streaming parser, fed one byte at a time):

    • a 0x92 refused between two packets, with no CRC, a 1-byte and a 2-byte CRC: refused at once, not logging, still streaming, every packet parsed;
    • still not logging after the ACK timer would have run out;
    • a corrupt packet before the NACK;
    • the next frame already buffered;
    • a 0xFE whose CRC doesn't match;
    • a NACK with no command in flight.

    Against master's parser 9 of the 10 fail; against Handle NACK from a Shimmer3/3R instead of dropping the connection #293's, 6.

ShimmerDriver 178/178, ShimmerDriverPC 118/118. Not yet run against firmware that NACKs.

Owed elsewhere

  • ShimmerAndroidAPI: the idle refusal reaches it through the published driver once the pin moves. Its Shimmer.java overrides processPacket() and had no NACK branch, so the mid-stream case is hand-ported in DEV-1431: a log start refused mid-stream ends at once ShimmerAndroidAPI#153 (draft; it calls this PR's now-protected processNackFromCommand(), so it builds only once a driver release carries this). Its tests pass locally against a build of this branch's driver.
  • C# API: already handles the NACK, idle and streaming, but its isLogging flag stays set after a refused START_SDBT. Small follow-up.
  • pyshimmer: raises CommandRefused.
  • Web SDK / Shimmer Capture: handled.
  • Swift: sends neither command.

DEV-1431

🤖 Generated with Claude Code

@JongChern

Copy link
Copy Markdown
Contributor

Looks right for an idle device. One gap before the firmware change ships:

No NACK handling while streaming. The firmware also refuses a log start mid-stream (no log running and none can start, e.g. streaming on USB power). startSDLogging() still sends START_LOGGING_ONLY while streaming, and the streaming parser skips the 0xFE as a stray byte. Five seconds later the ACK timer's special case marks the device as logging: the same false success this PR fixes for the idle case.

Suggest keeping ShimmerResearch/log-and-stream-common#228 in draft until this is covered.

… mid-stream

Firmware that cannot start a log (no SD card or a bad one, docked, on
USB power, logging turned off in its configuration) is to NACK
START_LOGGING_ONLY_COMMAND (0x92) and START_SDBT_COMMAND (0x70) and
start nothing, including when 0x92 is sent in the middle of a stream.
On master the driver dropped the 0xFE: when idle the ACK timer took
START_LOGGING_ONLY for started and dropped the connection for
START_SDBT; mid-stream the NACK went with the packet in front of it and
the timer again took the device for logging.

Built on DEV-982's NACK handling (processNackFromCommand), which unwinds
the refused command and keeps the link. On top of it:
- A refused log start is taken for a log that did not start
  (processLogStartRefused): the device is left not logging, the status
  reads startDataLogAndStreaming() stopped start again after START_SDBT,
  and eventLogStartRefused(command), a new protected hook, is called
  before eventCommandRefused. By default it passes
  LOG_START_REFUSED_MESSAGE to sendStatusMSGtoUI, which Android shows as
  a toast; ShimmerPC's is empty.
- While streaming, a NACK after a data packet waits for its own link CRC
  (C5, or C5 56) and checks it, as a bare ACK's is: exactly the packet,
  the NACK and its CRC are consumed, and what follows stays as the next
  frame. DEV-982 cleared the whole buffer at the NACK, so the CRC landed
  where the next header should be and bytes already buffered were lost.
  A packet whose CRC fails is dropped without losing the NACK; a 0xFE
  whose CRC does not match is not a NACK; a NACK with no command in
  flight is ignored, as it is when not streaming.
- processNackFromCommand() is protected, for ShimmerAndroidAPI's Shimmer,
  whose own streaming parser has to fail the command the same way.

Tests:
- API_00036_LogStartRefusedTest (idle, IOThread over an in-memory radio):
  refused log-only and combined starts, no CRC, 1- and 2-byte CRC, each
  handled at once with the next command answered; an ACKed start still
  logs. The radio now appends real CRCs.
- API_00037_StreamingLogStartRefusedTest (the streaming parser): a 0x92
  refused between two packets with no CRC, 1- and 2-byte CRC; still not
  logging after the ACK timer would have run; a corrupt packet before the
  NACK; the next frame already buffered; a 0xFE with the wrong CRC; a
  NACK with no command in flight. Against master's parser 9 of the 10
  fail; against DEV-982's, 6.
ShimmerDriver 178/178, ShimmerDriverPC 118/118.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@marknolan
marknolan force-pushed the DEV-1431_nack_refused_log_start branch from d396b5a to 4561b05 Compare November 10, 2026 14:35
@marknolan marknolan changed the title DEV-1431: a log start the device refuses (NACK) ends at once DEV-1431: a log start the device refuses (NACK) ends at once, idle or mid-stream Nov 10, 2026
@marknolan
marknolan changed the base branch from master to DEV-982_nack_handling November 10, 2026 14:35
@marknolan

Copy link
Copy Markdown
Member Author

Thanks, all three points were right. #345 is now rebuilt on #293: its base is #293's branch, so the diff here is DEV-1431's alone.

One small correction: mid-stream the ACK timer is 2 s, not 5 s. The 5 s case is an idle SET.

@marknolan marknolan self-assigned this Nov 12, 2026
@marknolan
marknolan requested a review from JongChern November 12, 2026 14:16
Base automatically changed from DEV-982_nack_handling to master November 13, 2026 03:12
@JongChern
JongChern marked this pull request as ready for review November 13, 2026 03:13

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

Approving. The mid-stream refusal is handled (the NACK's CRC is checked before it's taken), it goes through #293's shared NACK handler, and API_00036/API_00037 cover the idle and streaming cases. Next: the Java HIL at master, the Java release, then the Android driver bump with ShimmerResearch/ShimmerAndroidAPI#153.

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