From 5719d3848459c8c691041e574f0d5f3e5c0b39ed Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Sun, 4 Oct 2026 21:49:00 +0100 Subject: [PATCH 1/2] DEV-1148: add a local unit-test setup to the library src/test had no JUnit dependency, so nothing in the library could be tested on the JVM. Add JUnit 4 and have the stub android.jar return defaults: Shimmer's constructor and its logging call into it. Co-Authored-By: Claude Opus 5.5 --- .../ShimmerAndroidInstrumentDriver/build.gradle | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/build.gradle b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/build.gradle index 672f4b69..0399b7e1 100644 --- a/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/build.gradle +++ b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/build.gradle @@ -56,6 +56,12 @@ android { sourceCompatibility JavaVersion.VERSION_11 targetCompatibility JavaVersion.VERSION_11 } + testOptions { + // Local unit tests (src/test) run on the JVM against a stub android.jar. + // Shimmer's constructor and its logging call into it, so the stubs + // return defaults rather than throw. + unitTests.returnDefaultValues = true + } } @@ -110,4 +116,5 @@ dependencies { implementation 'androidx.appcompat:appcompat:1.7.0' implementation 'com.github.Jasonchenlijian:FastBle:2.4.0' implementation 'androidx.documentfile:documentfile:1.0.1' + testImplementation 'junit:junit:4.13.2' } From 378b5c92e98e15209ea24d870aa6d577c004d171 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Sun, 4 Oct 2026 21:49:00 +0100 Subject: [PATCH 2/2] DEV-1148: consume a bare ACK's link CRC while streaming With a Bluetooth link CRC on, the firmware sends a CRC after a bare ACK too, so a SET command's reply while streaming is FF F4 65, or FF F4 with a 1-byte CRC. Shimmer.processPacket() overrides the driver's parser and took the F4 for a parse error: it threw away the data packet before the ACK a byte at a time, never processed the ACK, and 2 s later the ACK timer cleared the instruction queue. startSDLogging() on a streaming device therefore never sent START_LOGGING_ONLY_COMMAND. Port DEV-1147's driver fix to the override. When the bytes after the ACK are the bare ACK's CRC, wait for all of it, pass the packet on if its own CRC checks out, consume the packet, the ACK and its CRC exactly once (keeping later bytes and their timestamps), and process the ACK. The bulk-read loop in processWhileStreaming() is unchanged. Also override checkCrc() so it only checks. On the pinned driver (0.11.7_beta) it skips to the next frame itself when a 2-byte CRC fails on its second byte, and processPacket() then discarded a byte more: the start of the next packet. AAPI_00002_StreamingBareAckCrcTest ports the driver's API_00027_StreamingBareAckCrcTest and replays each scenario with the bytes arriving in reads of every size from 1 to 48. Co-Authored-By: Claude Opus 5.5 --- .../com/shimmerresearch/android/Shimmer.java | 108 ++++- .../AAPI_00002_StreamingBareAckCrcTest.java | 424 ++++++++++++++++++ 2 files changed, 522 insertions(+), 10 deletions(-) create mode 100644 ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/test/java/com/shimmerresearch/bluetooth/AAPI_00002_StreamingBareAckCrcTest.java diff --git a/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/main/java/com/shimmerresearch/android/Shimmer.java b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/main/java/com/shimmerresearch/android/Shimmer.java index 58124cee..8ae9faef 100644 --- a/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/main/java/com/shimmerresearch/android/Shimmer.java +++ b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/main/java/com/shimmerresearch/android/Shimmer.java @@ -149,6 +149,7 @@ import com.shimmerresearch.bluetooth.BluetoothProgressReportPerCmd; import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; import com.shimmerresearch.driver.CallbackObject; import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; @@ -747,6 +748,14 @@ protected void clearSingleDataPacketFromBuffers(byte[] bufferTemp, int packetSiz } } + + /** + * With a link CRC on, the firmware sends one after a bare ACK too (the reply + * to a SET command). It is the CRC of the single byte 0xFF: F4 65, low byte + * first. + */ + private static final byte[] BARE_ACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {ACK_COMMAND_PROCESSED}, 1); + @Override protected void processPacket() { setIamAlive(true); @@ -778,6 +787,29 @@ protected void processPacket() { else if(bufferTemp[0]==DATA_PACKET && bufferTemp[getPacketSizeWithCrc()+1]==ACK_COMMAND_PROCESSED){ + //With a link CRC on, a bare ACK is followed by its own CRC rather than + //by the next packet + if(isBareAckCrcSoFar(allBytes)){ + int bareAckEnd = getPacketSizeWithCrc()+2+mBtCommsCrcModeCurrent.getNumCrcBytes(); + if(allBytes.lengthgetPacketSizeWithCrc()+2){ allBytes = mByteArrayOutputStream.toByteArray(); bufferTemp = new byte[getPacketSizeWithCrc()+3]; //check if the next byte is data packet @@ -788,16 +820,7 @@ else if(bufferTemp[0]==DATA_PACKET clearSingleDataPacketFromBuffers(bufferTemp, getPacketSizeWithCrc()+2); //clear an extra byte which is the ack //Then handle the ACK from the last SET command - if(isKnownSetCommand(mCurrentCommand)){ - stopTimerCheckForAckOrResp(); //cancel the ack timer - mWaitForAck=false; - - processAckFromSetCommand(mCurrentCommand); - - mTransactionCompleted = true; - setInstructionStackLock(false); - } - printLogDataForDebugging("Ack Received for Command: \t\t\t" + btCommandToString(mCurrentCommand)); + processAckWhileStreaming(); } //this is for LogAndStream support, command is transmitted and ack received @@ -848,6 +871,71 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR } } + /** + * Whether the bytes received so far after the ACK that follows a data packet + * are the CRC on a bare ACK. Nothing else can start that way: an in-stream + * response starts 0x8A, a data packet 0x00, and no response opcode is 0xF4. + * + * @param allBytes the contents of mByteArrayOutputStream + */ + private boolean isBareAckCrcSoFar(byte[] allBytes) { + int crcStart = getPacketSizeWithCrc()+2; + int numCrcBytesReceived = Math.min(allBytes.length-crcStart, mBtCommsCrcModeCurrent.getNumCrcBytes()); + if(numCrcBytesReceived<=0){ + return false; + } + for(int i=0;i + * The driver's own checkCrc() (0.11.8_beta and earlier) also skips to the + * next frame when a 2-byte CRC fails on its second byte, and processPacket() + * then discarded a byte more: the start of the next packet. DEV-1147 takes + * the skip out of the driver; once the driver pin includes that, this + * override can go. + */ + @Override + public boolean checkCrc(byte[] bufferTemp, int length) { + byte[] crcCalc = ShimmerCrc.shimmerUartCrcCalc(bufferTemp, length); + + if (mBtCommsCrcModeCurrent == BT_CRC_MODE.ONE_BYTE_CRC || mBtCommsCrcModeCurrent == BT_CRC_MODE.TWO_BYTE_CRC) { + // + 1 as this is the location of the CRC's LSB + if (bufferTemp[getPacketSize() + 1] != crcCalc[0]) { + return false; + } + } + + if (mBtCommsCrcModeCurrent == BT_CRC_MODE.TWO_BYTE_CRC) { + // + 2 as this is the location of the CRC's MSB + if (bufferTemp[getPacketSize() + 2] != crcCalc[1]) { + return false; + } + } + return true; + } + protected void discardFirstBufferByte(){ byte[] bTemp = mByteArrayOutputStream.toByteArray(); mByteArrayOutputStream.reset(); diff --git a/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/test/java/com/shimmerresearch/bluetooth/AAPI_00002_StreamingBareAckCrcTest.java b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/test/java/com/shimmerresearch/bluetooth/AAPI_00002_StreamingBareAckCrcTest.java new file mode 100644 index 00000000..cb3735b1 --- /dev/null +++ b/ShimmerAndroidInstrumentDriver/ShimmerAndroidInstrumentDriver/src/test/java/com/shimmerresearch/bluetooth/AAPI_00002_StreamingBareAckCrcTest.java @@ -0,0 +1,424 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import android.content.Context; +import android.os.Handler; + +import java.io.ByteArrayOutputStream; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Deque; +import java.util.List; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.android.Shimmer; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.driverUtilities.UtilShimmer; + +/** + * DEV-1148: with a Bluetooth link CRC on, the firmware appends it to every + * reply, a bare ACK included, so a SET command sent while streaming is + * answered FF F4 65, or FF F4 with a 1-byte CRC: F4 65 is the CRC of the + * single byte 0xFF. Shimmer.processPacket() took the byte after a streaming + * ACK to be the next packet's DATA_PACKET or an in-stream response's 0x8A, so + * F4 was a parse error. It threw away the data packet before the ACK a byte at + * a time and never processed the ACK, and the ACK timer then cleared the + * instruction queue. For startSDLogging() that meant START_LOGGING_ONLY_COMMAND, + * queued behind SET_RWC_COMMAND, was never sent. + *

+ * The driver fixed this in ShimmerBluetooth (DEV-1147, whose + * API_00027_StreamingBareAckCrcTest this ports), but Shimmer overrides that + * parser with its own. Shimmer's parser also reads every byte that has arrived + * rather than one at a time, so each scenario here is replayed with the bytes + * arriving in reads of every size, from one byte to all of them at once. + *

+ * No hardware: the parser reads from an in-memory byte queue. It lives in this + * package because the parser's state is protected or package-private in + * ShimmerBluetooth. + */ +public class AAPI_00002_StreamingBareAckCrcTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + + /** More than any scenario here sends in one go, so the largest read takes everything at once */ + private static final int MAX_READ_SIZE = 48; + + /** A Shimmer whose Bluetooth link is in memory */ + private static class QueueShimmer extends Shimmer { + final Deque rx = new ArrayDeque(); + final ByteArrayOutputStream tx = new ByteArrayOutputStream(); + int bytesSkipped = 0; + + QueueShimmer() { + super((Handler) null, (Context) null); + } + + void queue(byte[] bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + /** What the IO thread does on each pass while streaming */ + void ioThreadPass() { + processWhileStreaming(); + } + + /** Parses what is already in the buffer */ + void parseBuffered() { + processPacket(); + } + + @Override + protected int availableBytes() { + return rx.size(); + } + + @Override + protected byte[] readBytes(int numberofBytes) { + // Shimmer's would block for bytes that have not arrived, and none will + assertTrue("read " + numberofBytes + " bytes but only " + rx.size() + " had arrived", numberofBytes<=rx.size()); + byte[] bytes = new byte[numberofBytes]; + for(int i=0;i mDevices = new ArrayList(); + + @After + public void stopAckTimers() { + for(QueueShimmer device:mDevices){ + device.stopTimerCheckForAckOrResp(); + } + } + + /** + * Shimmer reads whatever has arrived, so a frame can be split across reads + * anywhere. Runs the scenario with the bytes arriving one at a time, two at + * a time and so on, up to all of them at once. + */ + private static void forEveryReadSize(Scenario scenario) throws Exception { + for(int readSize=1;readSize<=MAX_READ_SIZE;readSize++){ + try { + scenario.run(readSize); + } + catch(AssertionError e){ + throw new AssertionError("bytes arriving " + readSize + " at a time: " + e.getMessage(), e); + } + } + } + + /** A Shimmer3R part way through streaming PACKET_SIZE-byte packets */ + private QueueShimmer streamingShimmer3r(BT_CRC_MODE crcMode) { + QueueShimmer device = new QueueShimmer(); + mDevices.add(device); + device.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 7)); + device.setPacketSize(PACKET_SIZE); + device.setCurrentBtCommsCrcMode(crcMode); + device.setBluetoothRadioState(BT_STATE.STREAMING); + // Queue each parsed packet rather than build an ObjectCluster from it + device.mUseProcessingThread = true; + return device; + } + + /** What the IO thread does when it sends the next queued instruction while streaming */ + private static void sendNextInstruction(QueueShimmer device) { + device.mCurrentCommand = device.getListofInstructions().get(0)[0]; + device.setInstructionStackLock(true); + device.mWaitForAck = true; + device.startTimerCheckForAckOrResp(2); + } + + /** Hands the frames to the streaming parser readSize bytes at a time, one IO thread pass per read */ + private static void receive(QueueShimmer device, int readSize, byte[]... frames) { + ByteArrayOutputStream bytes = new ByteArrayOutputStream(); + for(byte[] frame:frames){ + bytes.write(frame, 0, frame.length); + } + byte[] all = bytes.toByteArray(); + for(int start=0;start expected = new ArrayList(); + for(byte[] payload:expectedPayloads){ + expected.add(hex(payload)); + } + List parsed = new ArrayList(); + // Package-private, so Shimmer does not inherit it + ShimmerBluetooth parser = device; + for(RawBytePacketWithPCTimeStamp packet:parser.mABQPacketByeArray){ + parsed.add(hex(packet.mDataArray)); + } + assertEquals("every good data packet is parsed, once and in order", expected, parsed); + } + + private static void assertAckProcessed(QueueShimmer device) { + assertFalse("the ACK is taken", device.mWaitForAck); + assertFalse("the next instruction can be sent", device.isInstructionStackLock()); + assertNull("the ACK timer is cancelled, so it cannot clear the instruction queue", device.mTimerCheckForAckOrResp); + } + + /** What is left in the parser's buffer, each byte with its PC timestamp */ + private static void assertBuffered(QueueShimmer device, byte... expected) { + assertEquals(hex(expected), hex(device.mByteArrayOutputStream.toByteArray())); + assertEquals("one PC timestamp per buffered byte", expected.length, device.mListofPCTimeStamps.size()); + } + + /** The parser never lost its place, so every frame, a bare ACK's CRC included, was consumed whole and once */ + private static void assertNoResync(QueueShimmer device) { + assertEquals("bytes skipped to find the next frame", 0, device.bytesSkipped); + } + + /** + * startSDLogging() while streaming sends SET_RWC_COMMAND and then + * START_LOGGING_ONLY_COMMAND, and the firmware answers each with a bare ACK + */ + private void startSdLoggingWhileStreaming(BT_CRC_MODE crcMode, int readSize) { + QueueShimmer device = streamingShimmer3r(crcMode); + device.startSDLogging(); + + sendNextInstruction(device); + assertEquals(ShimmerObject.SET_RWC_COMMAND, device.mCurrentCommand); + receive(device, readSize, dataPacket(payload(1), crcMode), bareAck(crcMode), + dataPacket(payload(2), crcMode), dataPacket(payload(3), crcMode)); + assertAckProcessed(device); + assertEquals("START_LOGGING_ONLY_COMMAND is still queued", 1, device.getListofInstructions().size()); + + sendNextInstruction(device); + assertEquals(ShimmerObject.START_LOGGING_ONLY_COMMAND, device.mCurrentCommand); + receive(device, readSize, dataPacket(payload(4), crcMode), bareAck(crcMode), + dataPacket(payload(5), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertAckProcessed(device); + assertTrue(device.getListofInstructions().isEmpty()); + assertTrue(device.isSDLogging()); + assertEquals(BT_STATE.STREAMING_AND_SDLOGGING, device.getBluetoothRadioState()); + + assertParsed(device, payload(1), payload(2), payload(3), payload(4), payload(5)); + assertBuffered(device, ShimmerObject.DATA_PACKET); + assertNoResync(device); + } + + @Test + public void bareAckWithOneByteCrcWhileStreaming() throws Exception { + forEveryReadSize(readSize -> startSdLoggingWhileStreaming(BT_CRC_MODE.ONE_BYTE_CRC, readSize)); + } + + @Test + public void bareAckWithTwoByteCrcWhileStreaming() throws Exception { + forEveryReadSize(readSize -> startSdLoggingWhileStreaming(BT_CRC_MODE.TWO_BYTE_CRC, readSize)); + } + + /** Already worked: with no CRC the ACK is followed by the next packet's DATA_PACKET */ + @Test + public void bareAckWithoutCrcWhileStreaming() throws Exception { + forEveryReadSize(readSize -> startSdLoggingWhileStreaming(BT_CRC_MODE.OFF, readSize)); + } + + /** + * Already worked: an in-stream response's 0x8A follows the ACK, and its CRC + * comes at the end. Each frame arrives whole here, in a read of its own or + * all in one: split across reads, an in-stream response has defects of its + * own in processInstreamResponse(), which this change leaves alone. + */ + private void inStreamResponseWhileStreaming(BT_CRC_MODE crcMode, boolean framePerRead) { + QueueShimmer device = streamingShimmer3r(crcMode); + device.readBattery(); + assertEquals("while streaming, Shimmer writes the command straight out rather than queue it", + hex(new byte[] {ShimmerObject.GET_VBATT_COMMAND}), hex(device.tx.toByteArray())); + // [ACK][INSTREAM_CMD_RESPONSE][VBATT_RESPONSE][ADC, LSB first][charger status][CRC] + byte[] vbatt = withCrc(new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED, ShimmerObject.INSTREAM_CMD_RESPONSE, + ShimmerObject.VBATT_RESPONSE, 0x24, 0x0B, (byte) 0x80}, crcMode); + byte[][] frames = {dataPacket(payload(1), crcMode), vbatt, dataPacket(payload(2), crcMode), new byte[] {ShimmerObject.DATA_PACKET}}; + if(framePerRead){ + receiveFramePerRead(device, frames); + } + else { + receive(device, MAX_READ_SIZE, frames); + } + assertEquals(0x0B24, device.getBattStatusDetails().getBattAdcValue(), 0); + assertParsed(device, payload(1), payload(2)); + assertBuffered(device, ShimmerObject.DATA_PACKET); + assertNoResync(device); + } + + @Test + public void inStreamResponseWithOneByteCrcWhileStreaming() { + inStreamResponseWhileStreaming(BT_CRC_MODE.ONE_BYTE_CRC, true); + inStreamResponseWhileStreaming(BT_CRC_MODE.ONE_BYTE_CRC, false); + } + + @Test + public void inStreamResponseWithTwoByteCrcWhileStreaming() { + inStreamResponseWhileStreaming(BT_CRC_MODE.TWO_BYTE_CRC, true); + inStreamResponseWhileStreaming(BT_CRC_MODE.TWO_BYTE_CRC, false); + } + + /** + * The ACK's own CRC shows it is an ACK, so a corrupt data packet ahead of it + * is dropped without losing the ACK + */ + private void bareAckAfterACorruptPacket(BT_CRC_MODE crcMode, int indexToCorrupt, int readSize) { + QueueShimmer device = streamingShimmer3r(crcMode); + device.stopSDLogging(); + sendNextInstruction(device); + byte[] corrupt = dataPacket(payload(1), crcMode); + corrupt[indexToCorrupt] ^= 0x01; + receive(device, readSize, corrupt, bareAck(crcMode), dataPacket(payload(2), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertAckProcessed(device); + assertTrue(device.getListofInstructions().isEmpty()); + assertParsed(device, payload(2)); + assertBuffered(device, ShimmerObject.DATA_PACKET); + assertNoResync(device); + } + + @Test + public void bareAckWithOneByteCrcAfterACorruptPacket() throws Exception { + forEveryReadSize(readSize -> bareAckAfterACorruptPacket(BT_CRC_MODE.ONE_BYTE_CRC, 1, readSize)); + } + + /** Only the CRC's second byte is wrong, which is checked separately */ + @Test + public void bareAckWithTwoByteCrcAfterACorruptPacket() throws Exception { + forEveryReadSize(readSize -> bareAckAfterACorruptPacket(BT_CRC_MODE.TWO_BYTE_CRC, 1+PACKET_SIZE+1, readSize)); + } + + /** + * A read can bring bytes beyond the ACK with it. Exactly the packet, the ACK + * and its CRC are consumed, and the rest stay with their timestamps as the + * start of the next frame. + */ + private void bareAckWithTheNextFrameAlreadyBuffered(BT_CRC_MODE crcMode) throws Exception { + QueueShimmer device = streamingShimmer3r(crcMode); + device.stopSDLogging(); + sendNextInstruction(device); + byte[] nextFrameStart = Arrays.copyOf(dataPacket(payload(2), crcMode), 4); + ByteArrayOutputStream buffered = new ByteArrayOutputStream(); + buffered.write(dataPacket(payload(1), crcMode)); + buffered.write(bareAck(crcMode)); + buffered.write(nextFrameStart); + device.mByteArrayOutputStream.write(buffered.toByteArray()); + for(long timestamp=0;timestamp { + BT_CRC_MODE crcMode = BT_CRC_MODE.TWO_BYTE_CRC; + QueueShimmer device = streamingShimmer3r(crcMode); + byte[] corrupt = dataPacket(payloadWithoutFrameStarts(1), crcMode); + corrupt[corrupt.length-1] ^= 0x01; + receive(device, readSize, corrupt, dataPacket(payloadWithoutFrameStarts(2), crcMode), + dataPacket(payloadWithoutFrameStarts(3), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertParsed(device, payloadWithoutFrameStarts(2), payloadWithoutFrameStarts(3)); + assertBuffered(device, ShimmerObject.DATA_PACKET); + }); + } +}