From b6842e6e918ada248ffb994a1b894c6f7d79d43c Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Thu, 3 Sep 2026 14:01:22 +0100 Subject: [PATCH 01/11] DEV-982: handle NACK from a Shimmer3/3R instead of dropping the connection The Shimmer3/Shimmer3R protocol has had a NACK_COMMAND_PROCESSED (0xFE) reply for a long time, but the driver never learned about it. There was no NACK constant anywhere on the Shimmer3 side, and both protocol implementations tested only for ACK with no else branch, so a NACK was read, silently discarded, and the transaction stalled with mWaitForAck still true and the instruction stack still locked. Two seconds later the ACK timer expired and checkForAckOrRespTask called connectionLost(): a refused command was indistinguishable from a dead link, and there was no retry to soften it because NUMBER_OF_TX_RETRIES_LIMIT is 0 and reading the NACK byte itself resets mNumberofTXRetriesCount, making the soft-recovery branch dead code. This is already reachable on shipping firmware - any SET command while the device is sensing, a sync-mode mismatch, a failed SET_DAUGHTER_CARD_MEM, and the BMP180/BMP280 calibration reads on a Shimmer3R all NACK. The existing coping strategy was avoidance rather than handling; see the comment on GET_PRESSURE_CALIBRATION_COEFFICIENTS_COMMAND, which is skipped for a BMP581 specifically because the firmware NACKs it. A refusal now unwinds the transaction and keeps the connection: - ShimmerObject: add NACK_COMMAND_PROCESSED = (byte) 0xFE. - ShimmerBluetooth.processNackFromCommand(): stop the ACK timer, clear mWaitForAck/mWaitForResponse, drop the refused instruction so the stack advances (as both ACK paths do for their own command), complete the transaction and release the stack lock. - Handled in three places: waiting for an ACK while not streaming (the main path), waiting for a response while not streaming, and a data packet followed by a NACK while streaming, which is the SET-while-sensing case. - eventCommandRefused() is the application hook. It is deliberately concrete with an empty default rather than abstract, and not a new ProtocolListener callback, so every existing subclass and listener implementation keeps compiling. Override it to surface the refusal. Two supporting changes: - The resync helper accepted only 0x00 and 0xFF as a packet boundary, so a NACK in the buffer could not be skipped past cleanly. It now accepts 0xFE too, and is renamed from findOffsetOfNextZeroOrFF to findOffsetOfNextPacketBoundary to match what it does. - NACK is registered in mBtCommandMapOther so btCommandToString names it in the logs. Deliberately not in mBtResponseMap: isKnownResponse() must stay false for it, or processResponseCommand() would try to parse it as a response body. A stray NACK arriving with no command in flight is logged and ignored rather than turned into a refusal, in processBytesAvailableAndInstreamSupported() which runs only when !mWaitForAck && !mWaitForResponse. The TypeScript SDK gates its own NACK framing the same way, so a leaked stream byte cannot fabricate a refusal. LiteProtocol gets the same treatment. Its NACK value is declared locally because the generated LiteProtocolInstructionSet has no NACK entry; adding it to LiteProtocolInstructionSet.proto and regenerating would be tidier but rewrites a large generated file committed in two places for one constant. Compile-verified only - there is no test harness for the BT receive path (ShimmerBluetooth is abstract with many abstract I/O methods and no test instantiates it), and no hardware was involved. Co-Authored-By: Claude Opus 5 --- .../bluetooth/ShimmerBluetooth.java | 106 ++++++++++++++++-- .../comms/radioProtocol/LiteProtocol.java | 50 +++++++++ .../shimmerresearch/driver/ShimmerObject.java | 1 + 3 files changed, 149 insertions(+), 8 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 18bfc999c..6f3dd7ebf 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -305,6 +305,7 @@ public enum SHIMMER_FEATURE { aMap.put(DATA_PACKET, new BtCommandDetails(DATA_PACKET, "DATA_PACKET")); aMap.put(ROUTINE_COMMUNICATION, new BtCommandDetails(ROUTINE_COMMUNICATION, "ROUTINE_COMMUNICATION")); aMap.put(ACK_COMMAND_PROCESSED, new BtCommandDetails(ACK_COMMAND_PROCESSED, "ACK_COMMAND_PROCESSED")); + aMap.put(NACK_COMMAND_PROCESSED, new BtCommandDetails(NACK_COMMAND_PROCESSED, "NACK_COMMAND_PROCESSED")); mBtCommandMapOther = Collections.unmodifiableMap(aMap); } @@ -866,6 +867,14 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } + /* The Shimmer refused the command. Without this branch the NACK + * was discarded, mWaitForAck stayed true and the instruction stack + * stayed locked until the ACK timer expired and tore the + * connection down - a refusal was indistinguishable from a dead + * link. */ + else if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED) { + processNackFromCommand(); + } } } } @@ -877,8 +886,15 @@ private void processNotStreamingWaitForResp() { if(byteBuffer!=null){ setIamAlive(true); + /* A NACK can arrive here rather than in the ACK state if the + * firmware decides it cannot serve a GET only while building the + * response. Checked before isKnownResponse() so it is handled as a + * refusal rather than falling through to the ACK timeout. */ + if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED){ + processNackFromCommand(); + } //Check to see whether it is a response byte - if(isKnownResponse(byteBuffer[0])){ + else if(isKnownResponse(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; processResponseCommand(responseCommand); @@ -918,7 +934,14 @@ && bytesAvailableToBeRead()) { byteBuffer=readBytes(1); if(byteBuffer!=null){ - if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { + /* Deliberately log-only: this path runs with no command in + * flight (!mWaitForAck && !mWaitForResponse), so there is no + * transaction to fail and a stray 0xFE must not be turned into a + * refusal. The buffer is cleared below either way. */ + if(byteBuffer[0]==NACK_COMMAND_PROCESSED) { + printLogDataForDebugging("NACK received with no command awaiting a reply - ignored"); + } + else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { printLogDataForDebugging("ACK RECEIVED , Connected State!!"); byteBuffer = readBytes(1, INSTREAM_CMD_RESPONSE); if(byteBuffer!=null && byteBuffer[0]==ACK_COMMAND_PROCESSED){ //an android fix.. not fully investigated (JC) @@ -1014,6 +1037,25 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR } } + //Data packet followed by a NACK (a command refused while streaming, e.g. + //any SET blocked by the firmware because it is sensing) + else if(bufferTemp[0]==DATA_PACKET + && bufferTemp[getPacketSizeWithCrc()+1]==NACK_COMMAND_PROCESSED){ + + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF && !checkCrc(bufferTemp, getPacketSize() + 1)) { + discardBufferBytesToNextPacket(); + return; + } + + //Handle the data packet first, then fail the command in flight + processDataPacket(bufferTemp); + processNackFromCommand(); + + /* clearBuffers() rather than clearSingleDataPacketFromBuffers(), + * because the NACK is a single byte with no payload behind it and that + * helper would push it back as the next packet header. */ + clearBuffers(); + } //TODO: ACK in bufferTemp[0] not handled //else if else { @@ -1303,13 +1345,14 @@ protected void clearBuffers() { } /** - * Next packet start should begin with DATA_PACKET or ACK_COMMAND_PROCESSED byte so skip to that point + * Next packet start should begin with DATA_PACKET, ACK_COMMAND_PROCESSED or + * NACK_COMMAND_PROCESSED byte so skip to that point */ protected void discardBufferBytesToNextPacket(){ byte[] bTemp = mByteArrayOutputStream.toByteArray(); //Find index of first DATA_PACKET or ACK byte within the buffer - int offset = findOffsetOfNextZeroOrFF(bTemp); + int offset = findOffsetOfNextPacketBoundary(bTemp); //If not found, just skip one byte offset = (offset == -1) ? 1 : offset; @@ -1323,15 +1366,16 @@ protected void discardBufferBytesToNextPacket(){ } /** - * Finds the offset/index of the next DATA_PACKET (0x00) or ACK_COMMAND_PROCESSED (0xFF) byte. + * Finds the offset/index of the next DATA_PACKET (0x00), ACK_COMMAND_PROCESSED + * (0xFF) or NACK_COMMAND_PROCESSED (0xFE) byte. * * @param buffer a byte array to search within - * @return index of the first 0x00 or 0xFF byte found after position 0, or -1 if not found + * @return index of the first 0x00, 0xFF or 0xFE byte found after position 0, or -1 if not found */ - private static int findOffsetOfNextZeroOrFF(byte[] buffer) { + private static int findOffsetOfNextPacketBoundary(byte[] buffer) { for (int i = 1; i < buffer.length; i++) { byte b = buffer[i]; - if (b == 0 || b == (byte) 0xFF) + if (b == 0 || b == ACK_COMMAND_PROCESSED || b == NACK_COMMAND_PROCESSED) return i; } return -1; @@ -1903,6 +1947,52 @@ else if(responseCommand==BT_FW_VERSION_STR_RESPONSE) { } } + /** + * Unwinds the in-flight transaction after the Shimmer answered a command + * with NACK (0xFE) instead of ACK. + * + *

The refused instruction is dropped and the stack advances, exactly as + * it would on an ACK, so one refused command no longer stalls everything + * queued behind it. The connection is left up: a refusal means the device + * declined this command, not that the link is gone. + */ + private void processNackFromCommand() { + stopTimerCheckForAckOrResp(); //cancel the ack timer + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); + + byte refusedCommand = mCurrentCommand; + + mWaitForAck=false; + mWaitForResponse=false; + + //Drop the refused instruction, as both ACK paths do for their command + if(getListofInstructions().size()>0){ + removeInstruction(0); + } + removeAllNulls(); + + mTransactionCompleted=true; + setInstructionStackLock(false); + + eventCommandRefused(refusedCommand); + } + + /** + * Called when the Shimmer refused a command with a NACK. The transaction has + * already been unwound and the connection is still up. + * + *

Deliberately concrete rather than abstract so that existing subclasses + * keep compiling; override to surface the refusal to the application. A + * refusal is expected in normal use - most SET commands are rejected while + * the device is sensing, and some GETs are rejected for hardware that does + * not have the feature. + * + * @param command the command byte that was refused + */ + protected void eventCommandRefused(byte command) { + //Default: no application-level notification, the log line above stands + } + // TODO: Consider removing this, replace by SET then GET and let the // RESPONSE update the variables in ShimmerObject - removes duplication of // code and ensure ShimmerObject it up-to-date with exactly what is on diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java index dc1634651..63ac6f93a 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java @@ -126,6 +126,12 @@ public class InstructionsGet{ protected String mDirectoryName; protected int numBytesToReadFromExpBoard=0; private static final int MAX_CALIB_DUMP_MAX = 4096; + /* The generated LiteProtocolInstructionSet has no NACK entry, so the value + * is declared here rather than read from InstructionsSet. Adding it to + * grpcprotosrc/src/LiteProtocolInstructionSet.proto and regenerating would + * be tidier, but that rewrites a large generated file committed in two + * places for the sake of one constant. */ + private static final int NACK_COMMAND_PROCESSED_VALUE = 0xFE; /** @@ -606,6 +612,12 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } + /* The Shimmer refused the command. Without this branch the NACK + * was discarded and the transaction stalled until the ACK timer + * expired, which is treated as a lost connection. */ + else if((((int)byteBuffer[0])&0xFF)==NACK_COMMAND_PROCESSED_VALUE) { + processNackFromCommand(); + } } } } @@ -1295,6 +1307,44 @@ private int availableBytes() throws ShimmerException { public void eventLogAndStreamStatusChanged(int currentCommand){ mProtocolListener.eventLogAndStreamStatusChangedCallback(currentCommand); } + + /** + * Unwinds the in-flight transaction after the Shimmer answered a command + * with NACK (0xFE) instead of ACK. The refused instruction is dropped so the + * stack advances, and the connection is left up - a refusal means the device + * declined this command, not that the link is gone. + */ + private void processNackFromCommand() { + stopTimerCheckForAckOrResp(); //cancel the ack timer + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); + + int refusedCommand = ((int)mCurrentCommand)&0xFF; + + mWaitForAck=false; + mWaitForResponse=false; + + if(getListofInstructions().size()>0){ + getListofInstructions().remove(0); + } + getListofInstructions().removeAll(Collections.singleton(null)); + + mTransactionCompleted=true; + setInstructionStackLock(false); + + eventCommandRefused(refusedCommand); + } + + /** + * Called when the Shimmer refused a command with a NACK. The transaction has + * already been unwound and the connection is still up. Concrete rather than + * a new ProtocolListener callback so that existing implementers keep + * compiling; override to surface the refusal to the application. + * + * @param command the command value that was refused + */ + protected void eventCommandRefused(int command) { + //Default: no application-level notification, the log line above stands + } private void isNowStreaming() { mProtocolListener.isNowStreaming(); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 4a6808c69..b2a435524 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -457,6 +457,7 @@ public class BTStream { public static final byte GET_RWC_COMMAND = (byte) 0x91; public static final byte ROUTINE_COMMUNICATION = (byte) 0xE0; + public static final byte NACK_COMMAND_PROCESSED = (byte) 0xFE; public static final byte ACK_COMMAND_PROCESSED = (byte) 0xFF; public static final byte START_LOGGING_ONLY_COMMAND = (byte) 0x92; From 648897ba72a514a177f763cff11ef8deb94fde49 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Thu, 3 Sep 2026 14:47:08 +0100 Subject: [PATCH 02/11] DEV-982: only drop the queued instruction when it is still queued (Copilot review) processNackFromCommand() removed instruction 0 unconditionally, but a GET's instruction is already removed when its ACK arrives. A NACK arriving in the response-wait state therefore dropped whatever was queued behind it and silently skipped that command. It is now dropped only when mWaitForAck was still set, which is exactly the state that still has it queued. Same fix in LiteProtocol, and the javadoc no longer claims the drop is unconditional. Also from the review: - LiteProtocol was missing the response-wait NACK branch that ShimmerBluetooth has, so a NACK there would still have fallen through to the timeout. Added, checked before isKnownResponseByte() to match. - The resync helper's inline comment still said it looked for DATA_PACKET or ACK only. - The helper used a raw 0 rather than the DATA_PACKET constant it now sits alongside (suppressed review comment). Co-Authored-By: Claude Opus 5 --- .../bluetooth/ShimmerBluetooth.java | 24 ++++++++++++------- .../comms/radioProtocol/LiteProtocol.java | 17 +++++++++++-- 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 6f3dd7ebf..55132210e 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -1351,7 +1351,7 @@ protected void clearBuffers() { protected void discardBufferBytesToNextPacket(){ byte[] bTemp = mByteArrayOutputStream.toByteArray(); - //Find index of first DATA_PACKET or ACK byte within the buffer + //Find index of first DATA_PACKET, ACK or NACK byte within the buffer int offset = findOffsetOfNextPacketBoundary(bTemp); //If not found, just skip one byte offset = (offset == -1) ? 1 : offset; @@ -1375,7 +1375,7 @@ protected void discardBufferBytesToNextPacket(){ private static int findOffsetOfNextPacketBoundary(byte[] buffer) { for (int i = 1; i < buffer.length; i++) { byte b = buffer[i]; - if (b == 0 || b == ACK_COMMAND_PROCESSED || b == NACK_COMMAND_PROCESSED) + if (b == DATA_PACKET || b == ACK_COMMAND_PROCESSED || b == NACK_COMMAND_PROCESSED) return i; } return -1; @@ -1951,10 +1951,12 @@ else if(responseCommand==BT_FW_VERSION_STR_RESPONSE) { * Unwinds the in-flight transaction after the Shimmer answered a command * with NACK (0xFE) instead of ACK. * - *

The refused instruction is dropped and the stack advances, exactly as - * it would on an ACK, so one refused command no longer stalls everything - * queued behind it. The connection is left up: a refusal means the device - * declined this command, not that the link is gone. + *

The refused instruction is dropped and the stack advances, as it would + * on an ACK, so one refused command no longer stalls everything queued + * behind it. It is dropped only when it is still queued - a GET's + * instruction is already gone by the time its response is awaited. The + * connection is left up: a refusal means the device declined this command, + * not that the link is gone. */ private void processNackFromCommand() { stopTimerCheckForAckOrResp(); //cancel the ack timer @@ -1962,11 +1964,17 @@ private void processNackFromCommand() { byte refusedCommand = mCurrentCommand; + /* Only the ACK-wait state still has the refused instruction queued: a + * GET's instruction is removed as soon as its ACK arrives, so removing + * one here as well would drop whatever was queued behind it and silently + * skip that command. */ + boolean instructionStillQueued = mWaitForAck; + mWaitForAck=false; mWaitForResponse=false; - //Drop the refused instruction, as both ACK paths do for their command - if(getListofInstructions().size()>0){ + //Drop the refused instruction, as the ACK path does for its own command + if(instructionStillQueued && getListofInstructions().size()>0){ removeInstruction(0); } removeAllNulls(); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java index 63ac6f93a..56dddebf3 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java @@ -652,8 +652,16 @@ else if(bytesAvailableToBeRead()){ byteBuffer=readBytes(1); mIamAlive = true; + /* As in the ACK-wait path above, and matching ShimmerBluetooth: a + * NACK can land here instead if the firmware only discovers it + * cannot serve a GET while building the response. Checked before + * isKnownResponseByte() so it is handled as a refusal rather than + * falling through to the ACK/response timeout. */ + if((((int)byteBuffer[0])&0xFF)==NACK_COMMAND_PROCESSED_VALUE){ + processNackFromCommand(); + } //Check to see whether it is a response byte - if(isKnownResponseByte(byteBuffer[0])){ + else if(isKnownResponseByte(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; if(mUseShimmerBluetoothApproach){ @@ -1320,10 +1328,15 @@ private void processNackFromCommand() { int refusedCommand = ((int)mCurrentCommand)&0xFF; + /* Only the ACK-wait state still has the refused instruction queued: a + * GET's instruction is removed as soon as its ACK arrives, so removing + * one here as well would drop whatever was queued behind it. */ + boolean instructionStillQueued = mWaitForAck; + mWaitForAck=false; mWaitForResponse=false; - if(getListofInstructions().size()>0){ + if(instructionStillQueued && getListofInstructions().size()>0){ getListofInstructions().remove(0); } getListofInstructions().removeAll(Collections.singleton(null)); From 8bd5b940deafc08c8bb93cf0ed5d1362370c5047 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Mon, 21 Sep 2026 09:21:08 +0100 Subject: [PATCH 03/11] DEV-982: complete the operation when a command is refused processNackFromCommand() unwound the transaction but sent no progress report, so an operation containing a refused command never reached its end value. BluetoothProgressReportPerDevice.updateProgress() derives the counter from the remaining instruction stack size, and ShimmerDeviceCallbackAdapter only calls finishOperation() when that counter equals mProgressEndValue - so a single NACK left the operation running indefinitely, with mOperationUnderway still true and the application sitting in CONFIGURING/CONNECTING. This matters most at connect time. With SD sync enabled the firmware NACKs every command except SET_SD_SYNC_COMMAND and ACK (ShimBt_isCmdAllowedWhileSdSyncing), which covers the whole driver initialisation sequence. The report is sent before the refused instruction is removed, and only while it is still queued, to match the arithmetic on the ACK path: the response-wait path already reported when its ACK arrived, so reporting again there would skip a count. The three timer-driven commands the ACK path excludes are excluded here too. Known limitation: a refused command still counts as progress and the operation completes as SUCCESS. Reporting a partially-refused operation as FAIL_WITH_WARNING would mean changing the shared OperationState handling in finishOperation(), which is a wider change than this fix; eventCommandRefused() remains the hook for an application that needs to know. Co-Authored-By: Claude Opus 5 --- .../bluetooth/ShimmerBluetooth.java | 18 ++++++++++++++++++ .../comms/radioProtocol/LiteProtocol.java | 13 +++++++++++++ 2 files changed, 31 insertions(+) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 55132210e..ea61763e7 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -1973,6 +1973,24 @@ private void processNackFromCommand() { mWaitForAck=false; mWaitForResponse=false; + /* Mirror the ACK path's progress report so that an operation containing a + * refused command can still reach its end value. + * BluetoothProgressReportPerDevice.updateProgress() derives the counter + * from the remaining stack size, so this has to be sent before the + * instruction is removed, and only while it is still queued - the + * response-wait path already reported when its ACK arrived and reporting + * twice would skip a count. Without it the counter never reaches + * mProgressEndValue, finishOperation() never fires, and the application + * stays in CONFIGURING/CONNECTING indefinitely. The same three + * timer-driven commands are excluded as on the ACK path. */ + if(instructionStillQueued + && mCurrentCommand!=GET_STATUS_COMMAND + && mCurrentCommand!=TEST_CONNECTION_COMMAND + && mCurrentCommand!=SET_BLINK_LED + && mOperationUnderway){ + sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, getComPort())); + } + //Drop the refused instruction, as the ACK path does for its own command if(instructionStillQueued && getListofInstructions().size()>0){ removeInstruction(0); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java index 56dddebf3..1ba5b1668 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java @@ -1336,6 +1336,19 @@ private void processNackFromCommand() { mWaitForAck=false; mWaitForResponse=false; + /* Mirror the ACK path's progress report so that an operation containing a + * refused command can still reach its end value, otherwise the progress + * counter stalls and the operation never completes. Sent before the + * instruction is removed and only while it is still queued, because the + * counter is derived from the remaining stack size. */ + if(instructionStillQueued + && mCurrentCommand!=InstructionsGet.GET_STATUS_COMMAND_VALUE + && mCurrentCommand!=InstructionsSet.TEST_CONNECTION_COMMAND_VALUE + && mCurrentCommand!=InstructionsSet.SET_BLINK_LED_VALUE + && mOperationUnderway){ + sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, mComPort)); + } + if(instructionStillQueued && getListofInstructions().size()>0){ getListofInstructions().remove(0); } From 586c58dba2bb1247015da945a9cdeabd8c300609 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Mon, 21 Sep 2026 09:28:58 +0100 Subject: [PATCH 04/11] DEV-982: add a bench test for the non-streaming NACK path The two earlier harnesses both refused a command while sensing, so both took the mIsStreaming branch of checkForAckOrRespTask - which clears the instruction stack but leaves the connection up. The ~2 s teardown the ticket describes is in the other branch, reached only by a refusal while not streaming, and nothing exercised it. Configuring mid-stream is not a supported operation either, so those runs were testing a path the product does not use. This drives the supported case. With SD sync enabled the firmware refuses every command except SET_SD_SYNC_COMMAND and ACK (ShimBt_isCmdAllowedWhileSdSyncing), so the driver's whole initialisation sequence is NACKed at connect time. On master that ends in connectionLost() about two seconds in; on this branch the refusals are recognised and the link stays up. Nothing is written to the device, so the run is non-destructive - SD sync is set once in Consensys beforehand and cleared afterwards. The test reports INCONCLUSIVE rather than a pass if FULLY_INITIALIZED arrives, which means sync was not actually enabled. Compiled against ShimmerPCBasicExamples with Gradle 8.10, the version CI uses. The checked-in wrapper (6.1) cannot configure ShimmerDriverPC at all - its Shadow plugin requires Gradle 7+ - which is more evidence the stale wrapper deserves its own ticket. Co-Authored-By: Claude Opus 5 --- .../simpleexamples/TestNackNotStreaming.java | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java new file mode 100644 index 000000000..050de7805 --- /dev/null +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java @@ -0,0 +1,196 @@ +package com.shimmerresearch.simpleexamples; + +import java.util.ArrayList; +import java.util.List; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.BasicProcessWithCallBack; +import com.shimmerresearch.driver.CallbackObject; +import com.shimmerresearch.driver.ShimmerMsg; +import com.shimmerresearch.tools.bluetooth.BasicShimmerBluetoothManagerPc; + +/** + * DEV-982 / PR #293 - exercises the NACK path that the earlier streaming tests + * could not reach. + * + *

Why the streaming tests did not show the connection drop

+ * + * {@code checkForAckOrRespTask} in ShimmerBluetooth branches on whether the + * device is streaming: + * + *
+ * if(mIsStreaming){
+ *     ... clearAllInstructions();   // connection stays UP, queue is destroyed
+ * }
+ * else {
+ *     ... connectionLost();         // the ~2 s drop described in the ticket
+ * }
+ * 
+ * + * TestNackWhileStreaming and TestNackQueuedCommand both refuse a command while + * sensing, so both take the first branch - which on master never drops the + * connection. The ~2 s teardown lives only in the second branch, and only a + * refusal while NOT streaming reaches it. That is what this test does. + * + * Configuring a device mid-stream is also not a supported operation, so those + * two tests were exercising a path the product does not use. + * + *

How this test forces a NACK

+ * + * The firmware gates every command before dispatching it + * ({@code ShimBt_processCmd} in log-and-stream-common/Comms/shimmer_bt_uart.c): + * + *
+ * if (storedConfigPtr->syncEnable ^ ShimBt_isCmdAllowedWhileSdSyncing(gAction))
+ *     sendNack = 1;
+ * 
+ * + * and the allow-list is only two entries: + * + *
+ * uint8_t ShimBt_isCmdAllowedWhileSdSyncing(uint8_t command)
+ * {
+ *   return (command == SET_SD_SYNC_COMMAND || command == ACK_COMMAND_PROCESSED);
+ * }
+ * 
+ * + * So with SD sync enabled the device refuses everything else, including + * the whole driver initialisation sequence (GET_FW_VERSION, INQUIRY, + * GET_STATUS ...). Nothing is written to the device to set this up and nothing + * is written by the test, so the run is non-destructive. + * + *

Setup

+ * + *
    + *
  1. In Consensys, enable SD sync on the Shimmer, and write the configuration.
  2. + *
  3. Set {@link #COM_PORT} below.
  4. + *
  5. Run this class on {@code master}, then on the PR #293 branch, unchanged.
  6. + *
  7. Afterwards, disable SD sync again in Consensys.
  8. + *
+ * + *

What to expect

+ * + * + * + * Note that with sync enabled the device cannot finish initialising on either + * branch - every GET it needs is refused. That is expected and is not what is + * being measured here. The difference under test is how it fails: a + * silent link teardown, or a logged refusal with the connection intact. + * + * If FULLY_INITIALIZED arrives, SD sync was not actually enabled and the run + * proves nothing - the test says so rather than reporting a pass. + */ +public class TestNackNotStreaming extends BasicProcessWithCallBack { + + /** TODO set this to your device's COM port */ + private static final String COM_PORT = "COM18"; + + /** + * Comfortably longer than ACK_TIMER_DURATION (2 s) plus the driver's retry + * allowance, so a teardown has every chance to happen before we judge. + */ + private static final long OBSERVATION_WINDOW_MS = 30000; + + private BasicShimmerBluetoothManagerPc mBtManager; + private long mTimeOfConnect; + + private volatile boolean mSawConnectionTeardown = false; + private volatile boolean mSawFullyInitialised = false; + private final List mTransitions = new ArrayList(); + + public static void main(String[] args) throws Exception { + new TestNackNotStreaming().run(); + } + + private void run() throws Exception { + mBtManager = new BasicShimmerBluetoothManagerPc(); + setWaitForData(mBtManager.callBackObject); + + log("Connecting to " + COM_PORT + " - SD sync must be ENABLED on this device"); + mTimeOfConnect = System.currentTimeMillis(); + mBtManager.connectShimmerThroughCommPort(COM_PORT); + + long deadline = mTimeOfConnect + OBSERVATION_WINDOW_MS; + while (System.currentTimeMillis() < deadline && !mSawConnectionTeardown) { + Thread.sleep(250); + } + + report(); + + try { + mBtManager.disconnectAllDevices(); + } catch (Exception e) { + //Nothing useful to do here - the run is over either way + } + System.exit(0); + } + + @Override + protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { + if (!(shimmerMSG.mB instanceof CallbackObject)) { + return; + } + CallbackObject cbo = (CallbackObject) shimmerMSG.mB; + + if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_STATE_CHANGE) { + record("BT_STATE -> " + cbo.mState); + if (cbo.mState == BT_STATE.CONNECTION_LOST + || cbo.mState == BT_STATE.CONNECTION_FAILED + || cbo.mState == BT_STATE.DISCONNECTED) { + mSawConnectionTeardown = true; + } + } + else if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_NOTIFICATION_MESSAGE) { + if (cbo.mIndicator == ShimmerBluetooth.NOTIFICATION_SHIMMER_FULLY_INITIALIZED) { + record("FULLY_INITIALIZED"); + mSawFullyInitialised = true; + } + } + } + + private void report() { + log(""); + log("---------------- observed ----------------"); + for (String t : mTransitions) { + log(t); + } + log("------------------------------------------"); + + if (mSawFullyInitialised) { + log("INCONCLUSIVE - the device initialised, so SD sync was not enabled."); + log(" Enable SD sync in Consensys and run this again."); + } + else if (mSawConnectionTeardown) { + log("MASTER BEHAVIOUR - the link was torn down after the refusal."); + log(" This is the DEV-982 defect: a refused command"); + log(" is indistinguishable from a dead link."); + } + else { + log("PR #293 BEHAVIOUR - the link survived the refusals for " + + (OBSERVATION_WINDOW_MS / 1000) + " s."); + log(" Check the driver log for 'NACK Received for Command:'"); + log(" to confirm the refusals were actually seen."); + } + } + + private void record(String event) { + String line = String.format("t+%5d ms %s", + System.currentTimeMillis() - mTimeOfConnect, event); + mTransitions.add(line); + log(line); + } + + private static void log(String msg) { + System.out.println(msg); + } +} From 4561b05480626dc1bb3bc21cc74092081caa070e Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Tue, 10 Nov 2026 00:53:51 +0000 Subject: [PATCH 05/11] DEV-1431: a log start the device refuses (NACK) ends at once, idle or 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 --- .../bluetooth/ShimmerBluetooth.java | 123 ++++++- .../API_00036_LogStartRefusedTest.java | 242 +++++++++++++ ...PI_00037_StreamingLogStartRefusedTest.java | 334 ++++++++++++++++++ 3 files changed, 685 insertions(+), 14 deletions(-) create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_StreamingLogStartRefusedTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 1c980b362..c343d9eb8 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -304,6 +304,9 @@ public int getNumCrcBytes() { * first. */ private static final byte[] BARE_ACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {ACK_COMMAND_PROCESSED}, 1); + + /** The same for a NACK, the refusal of a command: the CRC of 0xFE is C5 56. */ + private static final byte[] BARE_NACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {NACK_COMMAND_PROCESSED}, 1); public enum SHIMMER_FEATURE { NONE, @@ -1132,23 +1135,42 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR } //Data packet followed by a NACK (a command refused while streaming, e.g. - //any SET blocked by the firmware because it is sensing) + //any SET blocked by the firmware because it is sensing, or a log start the + //device cannot carry out, DEV-1431) else if(bufferTemp[0]==DATA_PACKET && bufferTemp[getPacketSizeWithCrc()+1]==NACK_COMMAND_PROCESSED){ - - if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF && !checkCrc(bufferTemp, getPacketSize() + 1)) { + + //With a link CRC on, the NACK is followed by its own CRC, as a bare ACK + //is, rather than by the next packet + if(!isBareNackCrcSoFar(bufferTemp)){ + printLogDataForDebugging("0xFE after a data packet is not a NACK: its CRC does not match"); discardBufferBytesToNextPacket(); return; } - - //Handle the data packet first, then fail the command in flight - processDataPacket(bufferTemp); - processNackFromCommand(); - - /* clearBuffers() rather than clearSingleDataPacketFromBuffers(), - * because the NACK is a single byte with no payload behind it and that - * helper would push it back as the next packet header. */ - clearBuffers(); + int bareNackEnd = getPacketSizeWithCrc()+2+mBtCommsCrcModeCurrent.getNumCrcBytes(); + if(bufferTemp.lengthA refused log start is also taken for a log that did not start + * ({@link #processLogStartRefused(byte)}). + * + *

Protected because ShimmerAndroidAPI's Shimmer has its own streaming + * parser, which needs to fail the command in flight the same way. */ - private void processNackFromCommand() { + protected void processNackFromCommand() { stopTimerCheckForAckOrResp(); //cancel the ack timer printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); @@ -2222,7 +2267,10 @@ private void processNackFromCommand() { mTransactionCompleted=true; setInstructionStackLock(false); - + + if(refusedCommand==START_LOGGING_ONLY_COMMAND || refusedCommand==START_SDBT_COMMAND){ + processLogStartRefused(refusedCommand); + } eventCommandRefused(refusedCommand); } @@ -3419,6 +3467,53 @@ else if(mCurrentCommand==GET_SHIMMER_VERSION_COMMAND_NEW){ //in case the new com // //NOT USED // } + /** + * A log start the device refused with a NACK (DEV-1431), its transaction already unwound by + * {@link #processNackFromCommand()}. + *

+ * 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, and firmware that refuses + * a start it cannot carry out starts nothing: after START_SDBT the device is not streaming + * either. It refuses START_LOGGING_ONLY in the middle of a stream the same way, the NACK then + * coming between two data packets. Earlier firmware ACKs such a start instead and does + * nothing, so there the status bits are what tell. + *

+ * Without this, a refusal ended as an unanswered start does: the ACK timer's special case + * (checkForAckOrRespTask) took START_LOGGING_ONLY for started. Here the device is left not + * logging, the status reads that startDataLogAndStreaming() stopped start again, and + * {@link #eventLogStartRefused(byte)} says so. + * + * @param refused the start that was refused + */ + private void processLogStartRefused(byte refused) { + printLogDataForDebugging(btCommandToString(refused) + " refused: the device cannot log now"); + setIsSDLogging(false); + if(refused==START_SDBT_COMMAND){ + // After the refused start is retired: the first read is immediate, and skipped while + // any instruction is still queued + startTimerReadStatus(); + } + eventLogStartRefused(refused); + } + + /** What {@link #eventLogStartRefused(byte)} passes to {@link #sendStatusMSGtoUI(String)} by default. */ + public static final String LOG_START_REFUSED_MESSAGE = "The Shimmer refused to start logging to its SD card. " + + "It logs only when undocked, off USB power, with an SD card in and no SD file error, " + + "and with logging turned on in its configuration."; + + /** + * The device refused a log start (START_LOGGING_ONLY_COMMAND or START_SDBT_COMMAND) with a NACK: + * it is not logging. After START_SDBT it is not streaming either; a stream that was running when + * START_LOGGING_ONLY was sent goes on. {@link #eventCommandRefused(byte)} is called for it too, + * after this. By default the reason goes to + * {@link #sendStatusMSGtoUI(String)}; override to tell the user another way. + * + * @param command the start that was refused + */ + protected void eventLogStartRefused(byte command) { + sendStatusMSGtoUI(LOG_START_REFUSED_MESSAGE); + } + private void killConnection(){ printLogDataForDebugging("Killing Connection"); stop(); //If command fail exit device diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java new file mode 100644 index 000000000..305c6ffbc --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java @@ -0,0 +1,242 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.ConcurrentLinkedDeque; + +import org.junit.After; +import org.junit.Test; + +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.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-1431: firmware that cannot start a log (no SD card or a bad one, docked, on USB power, logging + * turned off in its configuration) NACKs START_LOGGING_ONLY_COMMAND and START_SDBT_COMMAND and starts + * nothing. The driver had no NACK handling: it dropped the 0xFE as a stray byte and waited out the ACK + * timer, which then took START_LOGGING_ONLY for started (checkForAckOrRespTask's Consensys special + * case) and dropped the connection for START_SDBT. + *

+ * Now either NACK retires its command at once: the device is left not logging (and not streaming), + * eventLogStartRefused() is called, the connection is kept and the next command goes out. The same + * refusal in the middle of a stream is API_00037_StreamingLogStartRefusedTest. + *

+ * No hardware: the IOThread runs as connect() starts it, over an in-memory radio that answers as the + * firmware does. It lives in this package because mIOThread is a protected member of ShimmerBluetooth. + */ +public class API_00036_LogStartRefusedTest { + + /** Idle on a Shimmer3R: an SD card in, the clock set, not sensing; status byte 1 empty */ + private static final byte[] STATUS_IDLE = {0x24, 0x00}; + + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + /** What a log start gets: an ACK, or a NACK as firmware that refuses it sends */ + volatile byte startReply = ShimmerObject.NACK_COMMAND_PROCESSED; + /** How many bytes of link CRC the firmware appends to every reply */ + volatile int crcBytes = 0; + + void reply(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(bytes, bytes.length); + for(int i=0;i mRefused = Collections.synchronizedList(new ArrayList()); + + @After + public void tearDown() { + if(mDevice!=null){ + mDevice.stopTimerCheckForAckOrResp(); + mDevice.stopTimerReadStatus(); + mDevice.disconnectNoException(); + } + } + + /** An initialised, idle Shimmer3R on LogAndStream, its IOThread running as connect() starts it */ + private AnsweringRadio idleShimmer3r(BT_CRC_MODE crc) { + AnsweringRadio radio = new AnsweringRadio(); + radio.crcBytes = crc.getNumCrcBytes(); + mDevice = new ShimmerPC("COM99") { + @Override + protected void eventLogStartRefused(byte command) { + mRefused.add(command); + super.eventLogStartRefused(command); + } + }; + mDevice.setTestRadio(radio); + mDevice.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25)); + mDevice.setCurrentBtCommsCrcMode(crc); + mDevice.setIsInitialised(true); + mDevice.setBluetoothRadioState(BT_STATE.CONNECTED); + mDevice.mIOThread = mDevice.new IOThread(); + mDevice.mIOThread.start(); + return radio; + } + + private void waitFor(long timeoutMs, java.util.function.BooleanSupplier done) throws InterruptedException { + long end = System.currentTimeMillis()+timeoutMs; + while(!done.getAsBoolean() && System.currentTimeMillis() !mRefused.isEmpty()); + long took = System.currentTimeMillis()-sentAt; + assertEquals("eventLogStartRefused, once, for the start sent", Collections.singletonList(command), mRefused); + assertTrue("refused at once, not after the ACK timer (" + took + " ms)", took < 1500); + assertFalse("the device is not taken to be logging", mDevice.isSDLogging()); + assertFalse("nor streaming", mDevice.isStreaming()); + assertNotEquals("the connection is kept", BT_STATE.CONNECTION_LOST, mDevice.getBluetoothRadioState()); + + // The next command goes out and is answered: nothing is left waiting on the refused start + mDevice.writeAccelRange(1); + waitFor(3000, () -> radio.wrote(ShimmerObject.SET_ACCEL_SENSITIVITY_COMMAND) && mDevice.getListofInstructions().isEmpty()); + assertTrue("the next command was sent", radio.wrote(ShimmerObject.SET_ACCEL_SENSITIVITY_COMMAND)); + assertTrue("and acknowledged", mDevice.getListofInstructions().isEmpty()); + assertNotEquals("the connection is still kept", BT_STATE.CONNECTION_LOST, mDevice.getBluetoothRadioState()); + } + + @Test + public void aRefusedLogOnlyStartLeavesTheDeviceNotLogging() throws Exception { + AnsweringRadio radio = idleShimmer3r(BT_CRC_MODE.OFF); + long sentAt = System.currentTimeMillis(); + mDevice.startSDLogging(); + waitFor(2000, () -> radio.wrote(ShimmerObject.START_LOGGING_ONLY_COMMAND)); + assertTrue("START_LOGGING_ONLY was sent", radio.wrote(ShimmerObject.START_LOGGING_ONLY_COMMAND)); + assertRefusedAtOnce(radio, ShimmerObject.START_LOGGING_ONLY_COMMAND, sentAt); + } + + /** + * The NACK's CRC (C5, or C5 56) is left unread, as an ACK's is when not streaming, and the reply + * to the next command is found past it + */ + private void aRefusedLogOnlyStartWithALinkCrc(BT_CRC_MODE crc) throws Exception { + AnsweringRadio radio = idleShimmer3r(crc); + long sentAt = System.currentTimeMillis(); + mDevice.startSDLogging(); + waitFor(2000, () -> radio.wrote(ShimmerObject.START_LOGGING_ONLY_COMMAND)); + assertRefusedAtOnce(radio, ShimmerObject.START_LOGGING_ONLY_COMMAND, sentAt); + } + + @Test + public void aRefusedLogOnlyStartWithAOneByteCrcLetsTheNextCommandThrough() throws Exception { + aRefusedLogOnlyStartWithALinkCrc(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void aRefusedLogOnlyStartWithATwoByteCrcLetsTheNextCommandThrough() throws Exception { + aRefusedLogOnlyStartWithALinkCrc(BT_CRC_MODE.TWO_BYTE_CRC); + } + + @Test + public void aRefusedStreamAndLogStartStartsNothingAndKeepsTheConnection() throws Exception { + AnsweringRadio radio = idleShimmer3r(BT_CRC_MODE.OFF); + long sentAt = System.currentTimeMillis(); + mDevice.startDataLogAndStreaming(); + waitFor(2000, () -> radio.wrote(ShimmerObject.START_SDBT_COMMAND)); + assertTrue("START_SDBT was sent", radio.wrote(ShimmerObject.START_SDBT_COMMAND)); + assertRefusedAtOnce(radio, ShimmerObject.START_SDBT_COMMAND, sentAt); + // startDataLogAndStreaming() stopped the status reads; the refusal starts them again + waitFor(2000, () -> radio.wrote(ShimmerObject.GET_STATUS_COMMAND)); + assertTrue("the status is read again", radio.wrote(ShimmerObject.GET_STATUS_COMMAND)); + } + + /** An ACKed start is unchanged: the device is taken to be logging, as before */ + @Test + public void anAcknowledgedLogOnlyStartStillLogs() throws Exception { + AnsweringRadio radio = idleShimmer3r(BT_CRC_MODE.OFF); + radio.startReply = ShimmerObject.ACK_COMMAND_PROCESSED; + mDevice.startSDLogging(); + waitFor(2000, () -> mDevice.isSDLogging()); + assertTrue("logging after the ACK", mDevice.isSDLogging()); + assertTrue("no refusal", mRefused.isEmpty()); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_StreamingLogStartRefusedTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_StreamingLogStartRefusedTest.java new file mode 100644 index 000000000..1d5c9f446 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_StreamingLogStartRefusedTest.java @@ -0,0 +1,334 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.io.ByteArrayOutputStream; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.Deque; +import java.util.List; + +import org.junit.After; +import org.junit.Test; + +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; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-1431, while streaming: firmware that cannot start a log refuses START_LOGGING_ONLY_COMMAND in + * the middle of a stream as it does when idle (docked or on USB power, no SD card or a bad one, + * logging turned off in its configuration), and its NACK comes between two data packets, followed + * by its own link CRC when the link has one (C5, or C5 56). + *

+ * On master the NACK was thrown away with the packet in front of it, and 2 s later the ACK timer's + * special case took the device for logging. DEV-982's branch for a data packet followed by a NACK + * did not wait for the NACK's CRC: it cleared the whole buffer at the NACK, so the CRC arrived + * where the next packet's header should be (a parse error, then a resync), and any bytes already + * buffered after the NACK went with it. A data packet whose CRC failed took the NACK with it, a + * 0xFE whose CRC did not match was still taken for one, and a NACK with no command in flight + * refused whichever command had gone last. Nor was a refused log start told apart from any other + * refusal. + *

+ * Now the packet before the NACK is kept, the NACK's CRC is checked and consumed, the refusal + * retires the command, the device is not taken to be logging, the stream goes on, and + * eventLogStartRefused() is called. + *

+ * No hardware: the parser reads from an in-memory byte queue, one byte at a time as the IO thread + * does, as in API_00027_StreamingBareAckCrcTest. + * + * @author Mark Nolan + */ +public class API_00037_StreamingLogStartRefusedTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() mLogStartsRefused = Collections.synchronizedList(new ArrayList()); + private final List mCommandsRefused = Collections.synchronizedList(new ArrayList()); + + @After + public void stopTimers() { + if(mDevice!=null){ + mDevice.stopTimerCheckForAckOrResp(); + mDevice.stopTimerReadStatus(); + } + } + + /** A Shimmer3R on LogAndStream v1.01.025 part way through streaming PACKET_SIZE-byte packets */ + private void streamingShimmer3r(BT_CRC_MODE crcMode) { + mDevice = new ShimmerPC("COM99") { + @Override + protected void eventLogStartRefused(byte command) { + mLogStartsRefused.add(command); + super.eventLogStartRefused(command); + } + + @Override + protected void eventCommandRefused(byte command) { + mCommandsRefused.add(command); + } + }; + mRadio = new QueueRadio(); + mDevice.setTestRadio(mRadio); + mDevice.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25)); + mDevice.setPacketSize(PACKET_SIZE); + mDevice.setCurrentBtCommsCrcMode(crcMode); + mDevice.setIsStreaming(true); + mDevice.setBluetoothRadioState(BT_STATE.STREAMING); + // Queue each parsed packet rather than build an ObjectCluster from it + mDevice.mUseProcessingThread = true; + } + + /** startSDLogging() while streaming, and the IO thread sending its START_LOGGING_ONLY */ + private void startSdLoggingWhileStreaming() { + mDevice.startSDLogging(); + assertEquals("only START_LOGGING_ONLY_COMMAND is queued", 1, mDevice.getListofInstructions().size()); + mDevice.mCurrentCommand = mDevice.getListofInstructions().get(0)[0]; + assertEquals(ShimmerObject.START_LOGGING_ONLY_COMMAND, mDevice.mCurrentCommand); + mDevice.setInstructionStackLock(true); + mDevice.mWaitForAck = true; + mDevice.startTimerCheckForAckOrResp(2); + } + + /** Hands the bytes to the streaming parser one at a time, as the IO thread does */ + private void receive(byte[]... frames) { + for(byte[] frame:frames){ + mRadio.queue(frame); + } + while(!mRadio.rx.isEmpty()){ + mDevice.processWhileStreaming(); + } + } + + /** Has a 0x00, a 0xFE and a 0xFF in it, which a resync would take for the start of a frame */ + private static byte[] payload(int i) { + return new byte[] {(byte) (0x10*i), 0x00, 0x01, (byte) 0xFF, 0x07, (byte) 0xFE, 0x08, 0x3F, 0x09}; + } + + private static byte[] dataPacket(byte[] payload, BT_CRC_MODE crcMode) { + byte[] frame = new byte[1+payload.length]; + frame[0] = ShimmerObject.DATA_PACKET; + System.arraycopy(payload, 0, frame, 1, payload.length); + return withCrc(frame, crcMode); + } + + /** The firmware's refusal, with its link CRC */ + private static byte[] bareNack(BT_CRC_MODE crcMode) { + return withCrc(new byte[] {ShimmerObject.NACK_COMMAND_PROCESSED}, crcMode); + } + + /** The frame followed by the link CRC over all of it, low byte first */ + private static byte[] withCrc(byte[] frame, BT_CRC_MODE crcMode) { + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(frame, frame.length); + byte[] framed = Arrays.copyOf(frame, frame.length+crcMode.getNumCrcBytes()); + System.arraycopy(crc, 0, framed, frame.length, crcMode.getNumCrcBytes()); + return framed; + } + + private static String hex(byte[] bytes) { + return UtilShimmer.bytesToHexStringWithSpacesFormatted(bytes); + } + + private void assertParsed(byte[]... expectedPayloads) { + List expected = new ArrayList(); + for(byte[] payload:expectedPayloads){ + expected.add(hex(payload)); + } + List parsed = new ArrayList(); + // Package-private, so ShimmerPC does not inherit it + ShimmerBluetooth device = mDevice; + for(RawBytePacketWithPCTimeStamp packet:device.mABQPacketByeArray){ + parsed.add(hex(packet.mDataArray)); + } + assertEquals("every good data packet is parsed, once and in order", expected, parsed); + } + + /** What is left in the parser's buffer */ + private void assertBuffered(byte... expected) { + assertEquals(hex(expected), hex(mDevice.mByteArrayOutputStream.toByteArray())); + } + + /** The start retired as refused, the device not logging and still streaming */ + private void assertRefused() { + assertFalse("the NACK is taken", mDevice.mWaitForAck); + assertFalse("the next instruction can be sent", mDevice.isInstructionStackLock()); + assertNull("the ACK timer is cancelled, so its special case cannot take the device for logging", + mDevice.mTimerCheckForAckOrResp); + assertTrue("the refused start is retired", mDevice.getListofInstructions().isEmpty()); + assertFalse("the device is not taken to be logging", mDevice.isSDLogging()); + assertTrue("the stream goes on", mDevice.isStreaming()); + assertEquals(BT_STATE.STREAMING, mDevice.getBluetoothRadioState()); + assertEquals("eventLogStartRefused, once", Collections.singletonList(ShimmerObject.START_LOGGING_ONLY_COMMAND), + mLogStartsRefused); + assertEquals("eventCommandRefused, once", Collections.singletonList(ShimmerObject.START_LOGGING_ONLY_COMMAND), + mCommandsRefused); + } + + private void refusedBetweenTwoPackets(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + receive(dataPacket(payload(1), crcMode), bareNack(crcMode), + dataPacket(payload(2), crcMode), dataPacket(payload(3), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertRefused(); + assertParsed(payload(1), payload(2), payload(3)); + assertBuffered(ShimmerObject.DATA_PACKET); + } + + @Test + public void aLogStartRefusedMidStreamWithoutACrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.OFF); + } + + @Test + public void aLogStartRefusedMidStreamWithAOneByteCrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void aLogStartRefusedMidStreamWithATwoByteCrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** The refusal is not left to the ACK timer, which would take the device for logging 2 s on */ + @Test + public void theAckTimerDoesNotLaterTakeTheDeviceForLogging() throws Exception { + refusedBetweenTwoPackets(BT_CRC_MODE.ONE_BYTE_CRC); + Thread.sleep(2500); + assertFalse("still not logging after the ACK timer would have run out", mDevice.isSDLogging()); + } + + /** + * The NACK's own CRC shows it is a NACK, so a corrupt data packet ahead of it is dropped without + * losing the refusal + */ + private void refusedAfterACorruptPacket(BT_CRC_MODE crcMode, int indexToCorrupt) { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + byte[] corrupt = dataPacket(payload(1), crcMode); + corrupt[indexToCorrupt] ^= 0x01; + receive(corrupt, bareNack(crcMode), dataPacket(payload(2), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertRefused(); + assertParsed(payload(2)); + assertBuffered(ShimmerObject.DATA_PACKET); + } + + @Test + public void aRefusalWithAOneByteCrcAfterACorruptPacket() { + refusedAfterACorruptPacket(BT_CRC_MODE.ONE_BYTE_CRC, 1); + } + + /** Only the packet CRC's second byte is wrong, which is checked separately */ + @Test + public void aRefusalWithATwoByteCrcAfterACorruptPacket() { + refusedAfterACorruptPacket(BT_CRC_MODE.TWO_BYTE_CRC, 1+PACKET_SIZE+1); + } + + /** + * After a resync the buffer can already hold bytes beyond the NACK. Exactly the packet, the + * NACK and its CRC are consumed, and the rest stay as the start of the next frame. + */ + private void refusedWithTheNextFrameAlreadyBuffered(BT_CRC_MODE crcMode) throws Exception { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + byte[] nextFrameStart = Arrays.copyOf(dataPacket(payload(2), crcMode), 4); + ByteArrayOutputStream buffered = new ByteArrayOutputStream(); + buffered.write(dataPacket(payload(1), crcMode)); + buffered.write(bareNack(crcMode)); + buffered.write(nextFrameStart); + mDevice.mByteArrayOutputStream.write(buffered.toByteArray()); + for(long timestamp=0;timestamp Date: Tue, 10 Nov 2026 15:57:53 +0000 Subject: [PATCH 06/11] DEV-982: TestNackNotStreaming gets its NACK from 0x30, not SD sync Review found the bench test could not work: with SD sync enabled the firmware switches Bluetooth off while idle, so the port never opened, and the test still reported "master behaviour" because it took any DISCONNECTED for a teardown. It now refuses a command the firmware always refuses and that changes nothing: 0x30 with one argument byte (the driver's SET_BLINK_LED, the firmware's SET_CHARGE_STATUS_LED_COMMAND, dispatched but never implemented), with GET_SAMPLING_RATE queued straight behind it. It follows those two instructions through the stack and gives a verdict only once the Shimmer has finished connecting, is idle, and has firmware that refuses 0x30 (Shimmer3R LogAndStream v1.01.013+, Shimmer3 v1.01.004+): - PASS: 0x30 retired, the GET answered, the link up 8 s later; - FAIL: the link torn down, or either instruction never completed; - INCONCLUSIVE: otherwise. The window is 8 s because when not streaming the ACK timer gives a SET ACK_TIMER_DURATION + 3 = 5 s, not 2 s. It moves to com.shimmerresearch.bluetooth, since the instruction list and the transaction state are protected, and takes the COM port as its argument. On a Shimmer3R, LogAndStream v1.01.025, over classic Bluetooth, 3 runs each: this branch PASS 3/3 (0x30 retired after 137-224 ms, the GET answered after 241-272 ms); master FAIL 3/3 (the link lost 5.0 s after the refusal, no NACK logged). Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/TestNackNotStreaming.java | 233 ++++++++++++++++++ .../simpleexamples/TestNackNotStreaming.java | 196 --------------- 2 files changed, 233 insertions(+), 196 deletions(-) create mode 100644 ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java delete mode 100644 ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java new file mode 100644 index 000000000..736f0a440 --- /dev/null +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java @@ -0,0 +1,233 @@ +package com.shimmerresearch.bluetooth; + +import java.util.ArrayList; +import java.util.List; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.BasicProcessWithCallBack; +import com.shimmerresearch.driver.CallbackObject; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.ShimmerMsg; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.tools.bluetooth.BasicShimmerBluetoothManagerPc; + +/** + * DEV-982 / PR #293, on hardware: a command refused while NOT streaming. + * + *

Why not streaming

+ * + * {@code checkForAckOrRespTask} in ShimmerBluetooth branches on whether the + * device is streaming. While streaming, an unanswered command calls + * {@code clearAllInstructions()} and the link stays up; otherwise it calls + * {@code connectionLost()}. So a refusal while not streaming is where master + * costs the connection, when the ACK timer runs out about 5 s after the + * command (not streaming, a SET gets {@code ACK_TIMER_DURATION} + 3 s), and it + * is the path this test drives. + * + *

How it gets a NACK

+ * + * It sends 0x30 with one argument byte. The driver calls it + * {@code SET_BLINK_LED} and sends it from {@code writeLEDCommand()}; the + * firmware calls it {@code SET_CHARGE_STATUS_LED_COMMAND}, dispatches it but + * never implemented it, and so always refuses it (log-and-stream-common + * {@code Comms/shimmer_bt_uart.c}). Nothing is written to the device. It queues {@code GET_SAMPLING_RATE_COMMAND} straight + * behind it, to show that the instruction stack moves past the refusal. + *

+ * Firmware has NACKed 0x30 since Shimmer3R LogAndStream v1.01.013 and Shimmer3 + * v1.01.004 (DEV-977). Older firmware ACKs it, so the test refuses to give a + * verdict on it. + *

+ * An earlier version of this test enabled SD sync and relied on the firmware + * refusing every other command. That cannot work: with SD sync enabled the + * firmware switches Bluetooth off while idle, so the port never opens. + *

+ * The test queues the two instructions itself, so that it can follow those + * two through the instruction stack. That is why it lives in the + * {@code com.shimmerresearch.bluetooth} package: the instruction list and the + * transaction state are protected. + * + *

Running it

+ * + * Pass the Shimmer's Bluetooth COM port as the only argument, with the Shimmer + * idle (not streaming or logging), and with SD sync off. Run it on master and + * on the PR branch, unchanged. It takes about 15 s. + * + *
    + *
  • PASS (this PR): the refused command and the GET behind it both + * leave the instruction stack, the GET is answered, and the link is still up 8 + * s later.
  • + *
  • FAIL (master): the NACK is dropped, the GET never goes out, and + * the ACK timer tears the link down about 5 s later.
  • + *
  • INCONCLUSIVE: the Shimmer never finished connecting, is sensing, + * or has firmware too old to refuse 0x30.
  • + *
+ */ +public class TestNackNotStreaming extends BasicProcessWithCallBack { + + private static final long CONNECT_TIMEOUT_MS = 20000; + + /** Past the ACK timer, 5 s for a SET when not streaming, so a teardown has every chance to happen first */ + private static final long OBSERVATION_WINDOW_MS = 8000; + + private BasicShimmerBluetoothManagerPc mBtManager; + private String mComPort; + private long mTimeOfConnect; + + private volatile boolean mSawConnectionTeardown = false; + private volatile boolean mSawFullyInitialised = false; + private final List mTransitions = new ArrayList(); + + public static void main(String[] args) throws Exception { + if (args.length != 1) { + log("Usage: TestNackNotStreaming , e.g. COM18"); + System.exit(2); + } + new TestNackNotStreaming().run(args[0]); + } + + private void run(String comPort) throws Exception { + mComPort = comPort; + mBtManager = new BasicShimmerBluetoothManagerPc(); + setWaitForData(mBtManager.callBackObject); + + log("Connecting to " + comPort); + mTimeOfConnect = System.currentTimeMillis(); + mBtManager.connectShimmerThroughCommPort(comPort); + + long connectDeadline = mTimeOfConnect + CONNECT_TIMEOUT_MS; + while (!mSawFullyInitialised && !mSawConnectionTeardown && System.currentTimeMillis() < connectDeadline) { + Thread.sleep(100); + } + + String verdict = mSawFullyInitialised ? test() : "INCONCLUSIVE - the Shimmer did not finish connecting" + + (mSawConnectionTeardown ? " (the link closed first)" : " within " + (CONNECT_TIMEOUT_MS / 1000) + " s"); + report(verdict); + + try { + mBtManager.disconnectAllDevices(); + } catch (Exception e) { + //Nothing useful to do here - the run is over either way + } + System.exit(0); + } + + /** Sends the refused command and the GET behind it, watches, and gives the verdict */ + private String test() throws InterruptedException { + ShimmerDevice shimmerDevice = mBtManager.getShimmerDeviceBtConnected(mComPort); + if (!(shimmerDevice instanceof ShimmerBluetooth)) { + return "INCONCLUSIVE - no Bluetooth Shimmer found on " + mComPort; + } + ShimmerBluetooth device = (ShimmerBluetooth) shimmerDevice; + String version = device.getHardwareVersionParsed() + " " + device.getFirmwareVersionParsed(); + record("connected: " + version); + + boolean refuses0x30 = device.isThisVerCompatibleWith(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 13) + || (device.getHardwareVersion() == HW_ID.SHIMMER_3 + && device.isThisVerCompatibleWith(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 1, 4)); + if (!refuses0x30) { + return "INCONCLUSIVE - " + version + " ACKs 0x30. It needs Shimmer3R LogAndStream v1.01.013+" + + " or Shimmer3 v1.01.004+."; + } + if (device.isSensing()) { + return "INCONCLUSIVE - the Shimmer is streaming or logging. Stop it and run this again."; + } + + byte[] refused = new byte[] {ShimmerObject.SET_BLINK_LED, 0x00}; + byte[] get = new byte[] {ShimmerObject.GET_SAMPLING_RATE_COMMAND}; + List instructions = device.getListofInstructions(); + synchronized (instructions) { + instructions.add(refused); + instructions.add(get); + } + long sentAt = System.currentTimeMillis(); + record("queued 0x30 00 (SET_BLINK_LED), then GET_SAMPLING_RATE"); + + long refusedRetiredAt = -1; + long getAnsweredAt = -1; + boolean getSent = false; + while (System.currentTimeMillis() - sentAt < OBSERVATION_WINDOW_MS && !mSawConnectionTeardown) { + boolean refusedQueued; + boolean getQueued; + synchronized (instructions) { + refusedQueued = instructions.contains(refused); + getQueued = instructions.contains(get); + } + if (device.mCurrentCommand == ShimmerObject.GET_SAMPLING_RATE_COMMAND) { + getSent = true; + } + long now = System.currentTimeMillis(); + if (refusedRetiredAt < 0 && !refusedQueued) { + refusedRetiredAt = now; + record("0x30 left the instruction stack"); + } + // A GET leaves the stack on its ACK, and is answered when no reply is awaited any more + if (getAnsweredAt < 0 && getSent && !getQueued && !device.mWaitForAck && !device.mWaitForResponse) { + getAnsweredAt = now; + record("GET_SAMPLING_RATE answered"); + } + Thread.sleep(20); + } + + if (mSawConnectionTeardown) { + return "FAIL - the link was torn down after the refusal (master behaviour: a refused command" + + " cannot be told from a dead link)"; + } + if (refusedRetiredAt < 0) { + return "FAIL - the link is up, but the refused 0x30 was never retired"; + } + if (getAnsweredAt < 0) { + return "FAIL - the refusal was retired, but the GET behind it was not answered"; + } + return "PASS - 0x30 refused and retired after " + (refusedRetiredAt - sentAt) + " ms, the GET answered after " + + (getAnsweredAt - sentAt) + " ms, and the link is still up after " + (OBSERVATION_WINDOW_MS / 1000) + " s"; + } + + @Override + protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { + if (!(shimmerMSG.mB instanceof CallbackObject)) { + return; + } + CallbackObject cbo = (CallbackObject) shimmerMSG.mB; + + if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_STATE_CHANGE) { + record("BT_STATE -> " + cbo.mState); + if (cbo.mState == BT_STATE.CONNECTION_LOST + || cbo.mState == BT_STATE.CONNECTION_FAILED + || cbo.mState == BT_STATE.DISCONNECTED) { + mSawConnectionTeardown = true; + } + } + else if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_NOTIFICATION_MESSAGE) { + if (cbo.mIndicator == ShimmerBluetooth.NOTIFICATION_SHIMMER_FULLY_INITIALIZED) { + record("FULLY_INITIALIZED"); + mSawFullyInitialised = true; + } + } + } + + private void report(String verdict) { + log(""); + log("---------------- observed ----------------"); + synchronized (mTransitions) { + for (String t : mTransitions) { + log(t); + } + } + log("------------------------------------------"); + log(verdict); + } + + private void record(String event) { + String line = String.format("t+%5d ms %s", System.currentTimeMillis() - mTimeOfConnect, event); + synchronized (mTransitions) { + mTransitions.add(line); + } + log(line); + } + + private static void log(String msg) { + System.out.println(msg); + } +} diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java deleted file mode 100644 index 050de7805..000000000 --- a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/TestNackNotStreaming.java +++ /dev/null @@ -1,196 +0,0 @@ -package com.shimmerresearch.simpleexamples; - -import java.util.ArrayList; -import java.util.List; - -import com.shimmerresearch.bluetooth.ShimmerBluetooth; -import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; -import com.shimmerresearch.driver.BasicProcessWithCallBack; -import com.shimmerresearch.driver.CallbackObject; -import com.shimmerresearch.driver.ShimmerMsg; -import com.shimmerresearch.tools.bluetooth.BasicShimmerBluetoothManagerPc; - -/** - * DEV-982 / PR #293 - exercises the NACK path that the earlier streaming tests - * could not reach. - * - *

Why the streaming tests did not show the connection drop

- * - * {@code checkForAckOrRespTask} in ShimmerBluetooth branches on whether the - * device is streaming: - * - *
- * if(mIsStreaming){
- *     ... clearAllInstructions();   // connection stays UP, queue is destroyed
- * }
- * else {
- *     ... connectionLost();         // the ~2 s drop described in the ticket
- * }
- * 
- * - * TestNackWhileStreaming and TestNackQueuedCommand both refuse a command while - * sensing, so both take the first branch - which on master never drops the - * connection. The ~2 s teardown lives only in the second branch, and only a - * refusal while NOT streaming reaches it. That is what this test does. - * - * Configuring a device mid-stream is also not a supported operation, so those - * two tests were exercising a path the product does not use. - * - *

How this test forces a NACK

- * - * The firmware gates every command before dispatching it - * ({@code ShimBt_processCmd} in log-and-stream-common/Comms/shimmer_bt_uart.c): - * - *
- * if (storedConfigPtr->syncEnable ^ ShimBt_isCmdAllowedWhileSdSyncing(gAction))
- *     sendNack = 1;
- * 
- * - * and the allow-list is only two entries: - * - *
- * uint8_t ShimBt_isCmdAllowedWhileSdSyncing(uint8_t command)
- * {
- *   return (command == SET_SD_SYNC_COMMAND || command == ACK_COMMAND_PROCESSED);
- * }
- * 
- * - * So with SD sync enabled the device refuses everything else, including - * the whole driver initialisation sequence (GET_FW_VERSION, INQUIRY, - * GET_STATUS ...). Nothing is written to the device to set this up and nothing - * is written by the test, so the run is non-destructive. - * - *

Setup

- * - *
    - *
  1. In Consensys, enable SD sync on the Shimmer, and write the configuration.
  2. - *
  3. Set {@link #COM_PORT} below.
  4. - *
  5. Run this class on {@code master}, then on the PR #293 branch, unchanged.
  6. - *
  7. Afterwards, disable SD sync again in Consensys.
  8. - *
- * - *

What to expect

- * - *
    - *
  • master - the NACK is read and silently discarded, {@code mWaitForAck} - * stays true, the ACK timer expires after {@code ACK_TIMER_DURATION} (2 s) and - * {@code connectionLost()} is called. Expect CONNECTION_LOST / CONNECTION_FAILED - * a couple of seconds after connecting, with nothing in the log explaining why.
  • - * - *
  • PR #293 - the NACK is recognised, the transaction is unwound and the - * link is left up. Expect no teardown inside the observation window, and - * "NACK Received for Command:" lines in the driver log.
  • - *
- * - * Note that with sync enabled the device cannot finish initialising on either - * branch - every GET it needs is refused. That is expected and is not what is - * being measured here. The difference under test is how it fails: a - * silent link teardown, or a logged refusal with the connection intact. - * - * If FULLY_INITIALIZED arrives, SD sync was not actually enabled and the run - * proves nothing - the test says so rather than reporting a pass. - */ -public class TestNackNotStreaming extends BasicProcessWithCallBack { - - /** TODO set this to your device's COM port */ - private static final String COM_PORT = "COM18"; - - /** - * Comfortably longer than ACK_TIMER_DURATION (2 s) plus the driver's retry - * allowance, so a teardown has every chance to happen before we judge. - */ - private static final long OBSERVATION_WINDOW_MS = 30000; - - private BasicShimmerBluetoothManagerPc mBtManager; - private long mTimeOfConnect; - - private volatile boolean mSawConnectionTeardown = false; - private volatile boolean mSawFullyInitialised = false; - private final List mTransitions = new ArrayList(); - - public static void main(String[] args) throws Exception { - new TestNackNotStreaming().run(); - } - - private void run() throws Exception { - mBtManager = new BasicShimmerBluetoothManagerPc(); - setWaitForData(mBtManager.callBackObject); - - log("Connecting to " + COM_PORT + " - SD sync must be ENABLED on this device"); - mTimeOfConnect = System.currentTimeMillis(); - mBtManager.connectShimmerThroughCommPort(COM_PORT); - - long deadline = mTimeOfConnect + OBSERVATION_WINDOW_MS; - while (System.currentTimeMillis() < deadline && !mSawConnectionTeardown) { - Thread.sleep(250); - } - - report(); - - try { - mBtManager.disconnectAllDevices(); - } catch (Exception e) { - //Nothing useful to do here - the run is over either way - } - System.exit(0); - } - - @Override - protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { - if (!(shimmerMSG.mB instanceof CallbackObject)) { - return; - } - CallbackObject cbo = (CallbackObject) shimmerMSG.mB; - - if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_STATE_CHANGE) { - record("BT_STATE -> " + cbo.mState); - if (cbo.mState == BT_STATE.CONNECTION_LOST - || cbo.mState == BT_STATE.CONNECTION_FAILED - || cbo.mState == BT_STATE.DISCONNECTED) { - mSawConnectionTeardown = true; - } - } - else if (shimmerMSG.mIdentifier == ShimmerBluetooth.MSG_IDENTIFIER_NOTIFICATION_MESSAGE) { - if (cbo.mIndicator == ShimmerBluetooth.NOTIFICATION_SHIMMER_FULLY_INITIALIZED) { - record("FULLY_INITIALIZED"); - mSawFullyInitialised = true; - } - } - } - - private void report() { - log(""); - log("---------------- observed ----------------"); - for (String t : mTransitions) { - log(t); - } - log("------------------------------------------"); - - if (mSawFullyInitialised) { - log("INCONCLUSIVE - the device initialised, so SD sync was not enabled."); - log(" Enable SD sync in Consensys and run this again."); - } - else if (mSawConnectionTeardown) { - log("MASTER BEHAVIOUR - the link was torn down after the refusal."); - log(" This is the DEV-982 defect: a refused command"); - log(" is indistinguishable from a dead link."); - } - else { - log("PR #293 BEHAVIOUR - the link survived the refusals for " - + (OBSERVATION_WINDOW_MS / 1000) + " s."); - log(" Check the driver log for 'NACK Received for Command:'"); - log(" to confirm the refusals were actually seen."); - } - } - - private void record(String event) { - String line = String.format("t+%5d ms %s", - System.currentTimeMillis() - mTimeOfConnect, event); - mTransitions.add(line); - log(line); - } - - private static void log(String msg) { - System.out.println(msg); - } -} From 0ef5ddd8637d6cbf6b621b17426f93ee487cd75f Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Wed, 11 Nov 2026 11:33:44 +0000 Subject: [PATCH 07/11] DEV-1413: Shimmer3R sound level channel (0x38), and keep byte 233 on a full write Decode the Shimmer3R sound level channel: ID 0x38, a signed 16-bit little-endian count of 0.01 dB(A), LAeq over the microphone's most recent 128 ms block. 0x8000 means no level and calibrates to NaN. The decoder takes the channel's position from the channel list (inquiry response or SD header), like any other channel. A Shimmer3 never sends 0x38 and keeps the unknown-channel handling. The channel is enabled through configuration byte 233 bit 4, not a sensor bitmap bit. A new SensorSoundLevel (Shimmer3R only) owns the byte: its config hooks take the enable from bit 4 and give back bits 0-3 (the audio mode and gain preset) as read. A full configuration write builds its image from zeros, so until now it wrote 0 to byte 233 and also turned off a Shimmer3R's audio recording. Bit 7 set (erased flash) reads as 0, as the firmware reads it. A Shimmer3's byte 233 stays 0. Tests: API_00040 (ShimmerDriver) covers decoding at the spec position and elsewhere, the no-level value, SD, Shimmer3, and every value of byte 233. API_00041 (ShimmerDriverPC) covers the byte surviving deepClone() and decoding with the arrays data structure. Co-Authored-By: Claude Opus 5.5 --- .../shimmerresearch/driver/Configuration.java | 14 +- .../shimmerresearch/driver/ShimmerObject.java | 35 ++ .../shimmer2r3/ConfigByteLayoutShimmer3.java | 20 ++ .../sensors/AbstractSensor.java | 3 +- .../sensors/soundlevel/SensorSoundLevel.java | 303 ++++++++++++++++ .../API_00040_SoundLevelChannelTest.java | 326 ++++++++++++++++++ .../API_00041_SoundLevelShimmerPCTest.java | 87 +++++ 7 files changed, 786 insertions(+), 2 deletions(-) create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java create mode 100644 ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java index bf813e203..3f416f7ba 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java @@ -94,6 +94,7 @@ import com.shimmerresearch.sensors.adxl371.SensorADXL371; import com.shimmerresearch.sensors.lsm6dsv.SensorLSM6DSV; import com.shimmerresearch.sensors.lis2dw12.SensorLIS2DW12; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; import com.shimmerresearch.verisense.sensors.SensorLSM6DS3; //import com.shimmerresearch.verisense.sensors.SensorLIS2DW12; import com.shimmerresearch.verisense.sensors.SensorBattVoltageVerisense; @@ -158,6 +159,8 @@ public static class CHANNEL_UNITS{ public static final String GRAVITY = "g"; public static final String RPM = "rpm"; public static final String POWER = "dB"; + /** A-weighted sound pressure level, the Shimmer3R sound level channel's unit (DEV-1413) */ + public static final String DECIBELS_A = "dB(A)"; public static final String SCORE = "Score"; public static final String ACCEL_CAL_UNIT = METER_PER_SECOND_SQUARE; @@ -735,6 +738,8 @@ public static class SENSOR_ID{ public static final int SHIMMER_LIS3MDL_MAG_ALT = 41; public static final int SHIMMER_BMP390_PRESSURE = 43; public static final int SHIMMER_BMP581_PRESSURE = 44; + /** Shimmer3R microphone sound level, channel 0x38 (DEV-1413): enabled through configuration byte 233 bit 4, not a sensor bitmap bit */ + public static final int SHIMMER_SOUND_LEVEL = 45; // public static final int SHIMMER_EXG1_24BIT = 3; // public static final int SHIMMER_EXG2_24BIT = 4; @@ -943,7 +948,8 @@ public enum LABEL_SENSOR_TILE{ MPU_OTHER(SensorMPU9X50.LABEL_SENSOR_TILE.MPU_OTHER), GPS("GPS"), STC3100_MONITORING (SensorSTC3100.LABEL_SENSOR_TILE.STC3100_MONITORING), - SWEATCH_ADC ("Sweatch ADC"); + SWEATCH_ADC ("Sweatch ADC"), + SOUND_LEVEL(SensorSoundLevel.LABEL_SENSOR_TILE.SOUND_LEVEL); private String tileText = ""; LABEL_SENSOR_TILE(String text){ @@ -1538,6 +1544,12 @@ public static class CompatibilityInfoForMaps{ svoShimmer3RBrAmpUnifiedLogAndStream, svoShimmer3RProto3DeluxeLogAndStream); + //Shimmer3r sound level (DEV-1413). Every Shimmer3R has the microphone. + //Whether the firmware has the channel is learnt by writing + //configuration byte 233 bit 4 and reading it back, not from here. + public static final List listOfCompatibleVersionInfoSoundLevel = Arrays.asList( + svoShimmer3RLogAndStream); + //TODO need to update this list and remove "any" public static final List listOfCompatibleVersionInfoKionixKXRB52042 = Arrays.asList( svoAnyIntExpBoardAndSdlog, svoAnyIntExpBoardAndBtStream, svoAnyIntExpBoardAndLogAndStream, diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 2679bc312..bf568640c 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -95,6 +95,7 @@ import com.shimmerresearch.sensors.shimmer2.SensorMMA736x; import com.shimmerresearch.sensors.shimmer2.SensorShimmer2Gyro; import com.shimmerresearch.sensors.shimmer2.SensorShimmer2Mag; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; import com.shimmerresearch.algorithms.orientation.GradDes3DOrientation; import com.shimmerresearch.algorithms.orientation.GradDes3DOrientation9DoF; import com.shimmerresearch.algorithms.orientation.Orientation3DObject; @@ -2378,6 +2379,23 @@ else if (isEXGUsingDefaultThreeUnipolarConfiguration()){ calibratedDataUnits[sigIndex]=CHANNEL_UNITS.BEATS_PER_MINUTE; } + // Sound level (DEV-1413, Shimmer3R). Enabled through configuration + // byte 233 bit 4 rather than a sensor bitmap bit, so it is decoded + // whenever the channel list carries it. 0x8000 (no level) is NaN. + int iSoundLevel = getSignalIndex(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL); + if (iSoundLevel!=-1){ + double soundLevelRaw = (double)newPacketInt[iSoundLevel]; + objectCluster.addDataToMap(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL,CHANNEL_TYPE.UNCAL.toString(),CHANNEL_UNITS.NO_UNITS,soundLevelRaw); + uncalibratedData[iSoundLevel]=soundLevelRaw; + uncalibratedDataUnits[iSoundLevel]=CHANNEL_UNITS.NO_UNITS; + if (mEnableCalibration){ + double soundLevelDbA = SensorSoundLevel.calibrateSoundLevel(soundLevelRaw); + objectCluster.addDataToMap(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL,CHANNEL_TYPE.CAL.toString(),CHANNEL_UNITS.DECIBELS_A,soundLevelDbA); + calibratedData[iSoundLevel]=soundLevelDbA; + calibratedDataUnits[iSoundLevel]=CHANNEL_UNITS.DECIBELS_A; + } + } + //Additional Channels Offset int additionalChannelsOffset = calibratedData.length-numAdditionalChannels; if(fwType == COMMUNICATION_TYPE.BLUETOOTH) { @@ -3631,6 +3649,14 @@ else if ((byte)signalId[i-iTS]==(byte)0x28){ enabledSensors |= SENSOR_BRIDGE_AMP; } } + else if ((byte)signalId[i-iTS]==SensorSoundLevel.CHANNEL_ID && getHardwareVersion()==HW_ID.SHIMMER_3R){ + // Sound level (DEV-1413): a signed 16-bit little-endian count of + // 0.01 dB(A). A Shimmer3 never sends 0x38 and keeps the unknown + // channel handling below. + signalNameArray[i+1]=SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL; + signalDataTypeArray[i+1] = "i16"; + packetSize=packetSize+2; + } else{ signalNameArray[i+1]=Byte.toString(signalId[i-iTS]); signalDataTypeArray[i+1] = "u12"; @@ -5605,6 +5631,10 @@ else if(isSupportedNewImuSensors()){ mSensorLIS2MDL = new SensorLIS2MDL(this); addSensorClass(mSensorLIS2MDL); + + // Every Shimmer3R has the microphone; whether its firmware has the + // channel is learnt from configuration byte 233 (DEV-1413) + addSensorClass(new SensorSoundLevel(this)); } } @@ -5858,6 +5888,11 @@ else if(sensorId == Configuration.Shimmer3.SENSOR_ID.HOST_SHIMMER_STREAMING_PROP mSensorMap.get(sensorId).setIsEnabled(true); return true; } + // The sound level (DEV-1413) has no sensor bitmap bit, so the bitmap + // would always turn it off: its state comes from configuration byte 233 + else if(sensorId == Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL){ + return true; + } return false; } diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java index b9d1aa436..5f5b05854 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java @@ -168,6 +168,17 @@ public class ConfigByteLayoutShimmer3 extends ConfigByteLayout implements Serial public int maskLIS2MDLMagRateMSB = 0x07; public int bitShiftLIS2MDLMagRateMSB = 3; + //Config Byte 233, Shimmer3R only (0 where there is none): the microphone. + //Bits 0-1 are the audio mode and bits 2-3 the gain preset (DEV-99), kept as + //read on a configuration write. Bit 4 turns on the sound level channel, + //0x38 (DEV-1413). The firmware clears bits 5-6, and reads the whole byte + //as 0 when bit 7 is set, as it is in erased flash (0xFF). + public int idxAudioConfig = 0; + public int maskAudioModeAndGain = 0x0F; + public int bitShiftSoundLevel = 4; + public int maskSoundLevel = 0x01; + public int maskAudioConfigInvalid = 0x80; + // Derived Channels - used by SW not FW public int maskDerivedChannelsByte = 0xFF; public int byteShiftDerivedSensors0 = 8*0; @@ -395,6 +406,12 @@ public ConfigByteLayoutShimmer3(int firmwareIdentifier, int firmwareVersionMajor maskShowErrorLedsSd = 0x01; } + // Any Shimmer3R firmware: older builds store the byte untouched, so + // writing back what was read is safe on them too + if(mShimmerVerObject.mHardwareVersion == HW_ID.SHIMMER_3R) { + idxAudioConfig = 128+105; + } + if(mShimmerVerObject.mHardwareVersion == HW_ID.SHIMMER_3R || compareVersions(FW_ID.LOGANDSTREAM,0,8,1)) { idxBtFactoryReset = 128+103; @@ -537,6 +554,9 @@ public HashMap getMapOfByteDescriptions(){ mapOfByteDescriptions.put(idxMaxExpLengthLsb, "idxMaxExpLengthLsb"); mapOfByteDescriptions.put(idxMacAddress, "idxMacAddress"); mapOfByteDescriptions.put(idxSDConfigDelayFlag, "idxSDConfigDelayFlag"); + if(idxAudioConfig>0){ + mapOfByteDescriptions.put(idxAudioConfig, "idxAudioConfig"); + } if(idxBtFactoryReset>0){ mapOfByteDescriptions.put(idxBtFactoryReset, "idxBtFactoryReset"); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java index c1049b229..890f78f42 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java @@ -71,7 +71,8 @@ public enum SENSORS{ VD6283("VD6283"), MLX90632("MLX90632"), BMP390("BMP390"), - BMP581("BMP581"); + BMP581("BMP581"), + SOUND_LEVEL("Sound Level"); private final String text; diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java new file mode 100644 index 000000000..d22636d14 --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -0,0 +1,303 @@ +package com.shimmerresearch.sensors.soundlevel; + +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; + +import com.shimmerresearch.driver.ConfigByteLayout; +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.CHANNEL_UNITS; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.Configuration.Shimmer3.CompatibilityInfoForMaps; +import com.shimmerresearch.driver.FormatCluster; +import com.shimmerresearch.driver.ObjectCluster; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; +import com.shimmerresearch.driverUtilities.ChannelDetails; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_DATA_ENDIAN; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_DATA_TYPE; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; +import com.shimmerresearch.driverUtilities.SensorDetails; +import com.shimmerresearch.driverUtilities.SensorDetailsRef; +import com.shimmerresearch.driverUtilities.SensorGroupingDetails; +import com.shimmerresearch.sensors.AbstractSensor; +import com.shimmerresearch.sensors.ActionSetting; + +/** + * The Shimmer3R sound level channel (DEV-1413): the A-weighted sound level + * from the microphone, LAeq over the most recent completed 128 ms block, in + * dB(A) SPL. + *

+ * Nominal. The firmware adds the microphone's datasheet sensitivity and + * nothing more; no unit has been checked against a calibrated sound level + * meter. + *

+ * On the wire. Channel ID 0x38, two bytes, a signed 16-bit + * little-endian count of 0.01 dB(A). 0x8000 (-32768) means there is no level: + * while capture settles (about the first 256 ms), or when it is stopped or + * has failed. {@link #calibrateSoundLevel(double)} makes that NaN, never + * -327.68. A value describes the block that ended 0-128 ms before the + * packet's timestamp, plus the main loop's latency (up to about 0.2 s more + * while an SD card is slow); nothing here corrects for that. The firmware + * places the channel just before the ADS7028 block (GSR, the ADCs and the + * battery), so the battery stays last, but the decoder takes its position + * from the channel list, as for any channel. A Shimmer3 never sends it. + *

+ * Enabling it. Not a sensor bitmap bit: configuration byte 233 bit 4. + * Byte 233 also holds the DEV-99 audio mode (bits 0-1) and gain preset (bits + * 2-3), which this class keeps as read so that a full configuration write, + * which builds its image from zeros, gives the Shimmer back its own. Firmware + * that has the byte but not the channel clears bit 4, so a write and a read + * back says whether a unit has it. Firmware from before the byte (before + * DEV-99) stores it untouched, so there the bit reads back set while no + * channel is sent; the channel list is what the decoder goes by. + *

+ * This class is only created for a Shimmer3R. A Shimmer3's byte 233 stays 0. + */ +public class SensorSoundLevel extends AbstractSensor { + + private static final long serialVersionUID = 6915432740389468093L; + + /** The channel ID in the inquiry response and in the SD header's channel list */ + public static final byte CHANNEL_ID = 0x38; + /** The raw count that means there is no level: 0x8000 as a signed 16-bit value */ + public static final int NO_LEVEL = -32768; + /** Counts per dB(A) */ + public static final double COUNTS_PER_DB = 100.0; + + /** Byte 233's audio mode and gain preset as read (bits 0-3, DEV-99), written back as they are */ + private int mAudioModeAndGain = 0; + + public class GuiLabelSensors{ + public static final String SOUND_LEVEL = "Sound Level"; + } + + public class LABEL_SENSOR_TILE{ + public static final String SOUND_LEVEL = GuiLabelSensors.SOUND_LEVEL; + } + + public static class ObjectClusterSensorName{ + public static final String SOUND_LEVEL = "Sound_Level"; + } + + public static class DatabaseChannelHandles{ + public static final String SOUND_LEVEL = "Sound_Level"; + } + + //--------- Sensor info start -------------- + /** No sensor bitmap bit: enabled through configuration byte 233 bit 4 */ + public static final SensorDetailsRef sensorSoundLevel = new SensorDetailsRef( + 0, + 0, + GuiLabelSensors.SOUND_LEVEL, + CompatibilityInfoForMaps.listOfCompatibleVersionInfoSoundLevel, + null, + Arrays.asList(ObjectClusterSensorName.SOUND_LEVEL)); + + public static final Map mSensorMapRef; + static { + Map aMap = new LinkedHashMap(); + aMap.put(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, SensorSoundLevel.sensorSoundLevel); + mSensorMapRef = Collections.unmodifiableMap(aMap); + } + //--------- Sensor info end -------------- + + //--------- Channel info start -------------- + public static final ChannelDetails channelSoundLevel = new ChannelDetails( + ObjectClusterSensorName.SOUND_LEVEL, + ObjectClusterSensorName.SOUND_LEVEL, + DatabaseChannelHandles.SOUND_LEVEL, + CHANNEL_DATA_TYPE.INT16, 2, CHANNEL_DATA_ENDIAN.LSB, + CHANNEL_UNITS.DECIBELS_A, + Arrays.asList(CHANNEL_TYPE.CAL, CHANNEL_TYPE.UNCAL), + CHANNEL_ID); + + public static final Map mChannelMapRef; + static { + Map aMap = new LinkedHashMap(); + aMap.put(ObjectClusterSensorName.SOUND_LEVEL, SensorSoundLevel.channelSoundLevel); + mChannelMapRef = Collections.unmodifiableMap(aMap); + } + //--------- Channel info end -------------- + + public static final SensorGroupingDetails sensorGroupSoundLevel = new SensorGroupingDetails( + LABEL_SENSOR_TILE.SOUND_LEVEL, + Arrays.asList(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL), + CompatibilityInfoForMaps.listOfCompatibleVersionInfoSoundLevel); + + //--------- Constructors for this class start -------------- + public SensorSoundLevel(ShimmerDevice shimmerDevice) { + super(SENSORS.SOUND_LEVEL, shimmerDevice); + initialise(); + } + //--------- Constructors for this class end -------------- + + /** + * A raw sound level count in nominal dB(A) SPL, or NaN for the no-level + * value (0x8000) and for anything that is not a signed 16-bit count. + */ + public static double calibrateSoundLevel(double rawCount) { + if(Double.isNaN(rawCount) || rawCount<=NO_LEVEL || rawCount>Short.MAX_VALUE) { + return Double.NaN; + } + return rawCount/COUNTS_PER_DB; + } + + @Override + public void generateSensorMap() { + super.createLocalSensorMapWithCustomParser(mSensorMapRef, mChannelMapRef); + } + + @Override + public void generateConfigOptionsMap() { + // No configuration options: the channel is on or off + } + + @Override + public void generateSensorGroupMapping() { + mSensorGroupingMap = new LinkedHashMap(); + mSensorGroupingMap.put(Configuration.Shimmer3.LABEL_SENSOR_TILE.SOUND_LEVEL.ordinal(), sensorGroupSoundLevel); + super.updateSensorGroupingMap(); + } + + /** Used where a device parses through its sensor classes; the Shimmer3R stream and SD paths decode in ShimmerObject.buildMsg() */ + @Override + public ObjectCluster processDataCustom(SensorDetails sensorDetails, byte[] rawData, COMMUNICATION_TYPE commType, + ObjectCluster objectCluster, boolean isTimeSyncEnabled, double pcTimestampMs) { + objectCluster = sensorDetails.processDataCommon(rawData, commType, objectCluster, isTimeSyncEnabled, pcTimestampMs); + + if(mEnableCalibration){ + for(ChannelDetails channelDetails:sensorDetails.mListOfChannels){ + if(channelDetails.mObjectClusterName.equals(ObjectClusterSensorName.SOUND_LEVEL)){ + FormatCluster rawFormatCluster = (FormatCluster) ObjectCluster.returnFormatCluster( + objectCluster.getCollectionOfFormatClusters(channelDetails.mObjectClusterName), + channelDetails.mChannelFormatDerivedFromShimmerDataPacket.toString()); + if(rawFormatCluster!=null){ + objectCluster.addCalData(channelDetails, calibrateSoundLevel(rawFormatCluster.mData), objectCluster.getIndexKeeper()-1); + } + } + } + } + return objectCluster; + } + + @Override + public void checkShimmerConfigBeforeConfiguring() { + // Nothing depends on it + } + + private static ConfigByteLayoutShimmer3 getAudioConfigLayout(ShimmerDevice shimmerDevice, byte[] configBytes) { + ConfigByteLayout configByteLayout = shimmerDevice.getConfigByteLayout(); + if(configByteLayout instanceof ConfigByteLayoutShimmer3){ + ConfigByteLayoutShimmer3 configByteLayoutCast = (ConfigByteLayoutShimmer3) configByteLayout; + if(configByteLayoutCast.idxAudioConfig>0 && configBytes!=null && configBytes.length>configByteLayoutCast.idxAudioConfig){ + return configByteLayoutCast; + } + } + return null; + } + + /** + * Byte 233: bits 0-3 as read (0 if the byte read was not valid) and bit 4 + * from this sensor's state; bits 5-7 are 0, as the firmware wants them. + */ + @Override + public void configBytesGenerate(ShimmerDevice shimmerDevice, byte[] configBytes, COMMUNICATION_TYPE commType) { + ConfigByteLayoutShimmer3 configByteLayoutCast = getAudioConfigLayout(shimmerDevice, configBytes); + if(configByteLayoutCast!=null){ + int value = mAudioModeAndGain & configByteLayoutCast.maskAudioModeAndGain; + if(isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)){ + value |= configByteLayoutCast.maskSoundLevel << configByteLayoutCast.bitShiftSoundLevel; + } + configBytes[configByteLayoutCast.idxAudioConfig] = (byte) value; + } + } + + /** + * Keeps byte 233's bits 0-3 for the next write and takes this sensor's + * state from bit 4. Bit 7 set (erased flash reads 0xFF) makes the firmware + * read the whole byte as 0, and so does this. + */ + @Override + public void configBytesParse(ShimmerDevice shimmerDevice, byte[] configBytes, COMMUNICATION_TYPE commType) { + ConfigByteLayoutShimmer3 configByteLayoutCast = getAudioConfigLayout(shimmerDevice, configBytes); + if(configByteLayoutCast!=null){ + int value = configBytes[configByteLayoutCast.idxAudioConfig] & 0xFF; + if((value & configByteLayoutCast.maskAudioConfigInvalid)!=0){ + value = 0; + } + mAudioModeAndGain = value & configByteLayoutCast.maskAudioModeAndGain; + + SensorDetails sensorDetails = mSensorMap.get(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); + if(sensorDetails!=null){ + sensorDetails.setIsEnabled(((value >> configByteLayoutCast.bitShiftSoundLevel) & configByteLayoutCast.maskSoundLevel)!=0); + } + } + } + + /** + * The sensor bitmap has no bit for this sensor, so the bitmap-driven + * update would always turn it off. Its state comes from byte 233 instead. + */ + @Override + public boolean handleSpecCasesBeforeSensorMapUpdatePerSensor(ShimmerDevice shimmerDevice, Integer sensorId) { + return sensorId!=null && sensorId==Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL; + } + + /** Byte 233's audio mode and gain preset (bits 0-3, DEV-99) as last read, which a configuration write gives back */ + public int getAudioModeAndGain() { + return mAudioModeAndGain; + } + + @Override + public Object setConfigValueUsingConfigLabel(Integer sensorId, String configLabel, Object valueToSet) { + return super.setConfigValueUsingConfigLabelCommon(sensorId, configLabel, valueToSet); + } + + @Override + public Object getConfigValueUsingConfigLabel(Integer sensorId, String configLabel) { + return super.getConfigValueUsingConfigLabelCommon(sensorId, configLabel); + } + + @Override + public void setSensorSamplingRate(double samplingRateHz) { + // One level per 128 ms block whatever the sampling rate + } + + @Override + public boolean setDefaultConfigForSensor(int sensorId, boolean isSensorEnabled) { + return mSensorMap.containsKey(sensorId); + } + + @Override + public boolean checkConfigOptionValues(String stringKey) { + return mConfigOptionsMap.containsKey(stringKey); + } + + @Override + public Object getSettings(String componentName, COMMUNICATION_TYPE commType) { + return null; + } + + @Override + public ActionSetting setSettings(String componentName, Object valueToSet, COMMUNICATION_TYPE commType) { + return new ActionSetting(commType); + } + + @Override + public boolean processResponse(int responseCommand, Object parsedResponse, COMMUNICATION_TYPE commType) { + return false; + } + + @Override + public LinkedHashMap generateConfigMap() { + return new LinkedHashMap(); + } + + @Override + public void parseConfigMap(LinkedHashMap mapOfConfigPerShimmer) { + // Nothing beyond the enabled state, which the sensor map carries + } + +} diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java new file mode 100644 index 000000000..e06f0d5df --- /dev/null +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java @@ -0,0 +1,326 @@ +package com.shimmerresearch.driver; + +import static org.junit.Assert.*; + +import java.util.Arrays; + +import org.junit.Test; + +import com.shimmerresearch.driver.Configuration.CHANNEL_UNITS; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.driverUtilities.UtilParseData; +import com.shimmerresearch.sensors.AbstractSensor.SENSORS; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; + +/** + * DEV-1413: the Shimmer3R sound level channel, 0x38. Its decoding from a data + * packet, wherever the channel list puts it, and configuration byte 233, + * whose bit 4 turns it on. A full configuration write builds its image from + * zeros, so before DEV-1413 it wrote 0 to byte 233 and turned off a + * Shimmer3R's audio recording (DEV-99) as well; it now gives back bits 0-3 as + * read. A Shimmer3 has no microphone: it never sends 0x38 and its byte 233 + * stays 0. + *

+ * No hardware. + * + * @author Mark Nolan + */ +public class API_00040_SoundLevelChannelTest { + + private static final int IDX_AUDIO_CONFIG = 233; + + /** Shimmer3R LogAndStream: every one has the microphone */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + private static final ShimmerVerObject S3 = new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17); + + private static final byte LN_ACCEL_X = 0x00; + private static final byte LN_ACCEL_Y = 0x01; + private static final byte LN_ACCEL_Z = 0x02; + private static final byte VBATT = 0x03; + private static final byte GSR = 0x1C; + private static final byte SOUND_LEVEL = 0x38; + + /** The smallest concrete ShimmerObject: decoding and configuration, no connection */ + private static class TestShimmer extends ShimmerObject { + private static final long serialVersionUID = 1L; + + TestShimmer(ShimmerVerObject svo) { + setShimmerVersionObjectAndCreateSensorMap(svo); + setSamplingRateShimmer(128); + updateTimestampByteLength(); + } + + @Override + public void createConfigBytesLayout() { + mConfigByteLayout = new ConfigByteLayoutShimmer3(getFirmwareIdentifier(), getFirmwareVersionMajor(), getFirmwareVersionMinor(), getFirmwareVersionInternal(), mShimmerVerObject.mHardwareVersion); + } + + @Override + protected void checkBattery() { + } + + @Override + public ShimmerDevice deepClone() { + return null; + } + + @Override + protected void interpretDataPacketFormat(Object object, COMMUNICATION_TYPE commType) { + } + + @Override + protected void dataHandler(ObjectCluster ojc) { + } + + @Override + protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { + } + + byte[] written() { + return generateConfigBytesForWritingToShimmer().clone(); + } + + boolean isSoundLevelEnabled() { + return isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); + } + + void setSoundLevelEnabled(boolean state) { + assertTrue(setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, state)); + } + + /** Takes the channel list as an inquiry response or an SD header gives it */ + void channels(byte... channelIds) { + mNChannels = channelIds.length; + interpretDataPacketFormat(channelIds.length, channelIds); + } + } + + /** A configuration as a Shimmer on that firmware would answer it, with the given byte 233 */ + private static byte[] configFromShimmer(ShimmerVerObject svo, int audioConfig) { + byte[] config = new TestShimmer(svo).written(); + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + return config; + } + + private static TestShimmer readFrom(ShimmerVerObject svo, int audioConfig) { + TestShimmer shimmer = new TestShimmer(svo); + shimmer.configBytesParse(configFromShimmer(svo, audioConfig), COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int writtenAudioConfig(TestShimmer shimmer) { + return shimmer.written()[IDX_AUDIO_CONFIG] & 0xFF; + } + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + /** A data packet as buildMsg gets it: the timestamp, then two bytes little-endian per channel */ + private static byte[] packet(TestShimmer shimmer, int... channelValues) { + byte[] packet = new byte[shimmer.mTimeStampPacketByteSize + 2*channelValues.length]; + packet[0] = 0x10; + int index = shimmer.mTimeStampPacketByteSize; + for(int value:channelValues){ + packet[index++] = (byte) (value & 0xFF); + packet[index++] = (byte) ((value >> 8) & 0xFF); + } + return packet; + } + + private static FormatCluster soundLevel(ObjectCluster objectCluster, CHANNEL_TYPE channelType) { + return objectCluster.getLastFormatCluster(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, channelType.toString()); + } + + // ---------- Decoding ---------- + + /** Just before the ADS7028 block (GSR, then the battery last), as the firmware sends it */ + @Test + public void decodedAtTheSpecPosition() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, LN_ACCEL_Y, LN_ACCEL_Z, SOUND_LEVEL, GSR, VBATT); + + assertEquals(shimmer.mTimeStampPacketByteSize + 12, shimmer.mPacketSize); + assertSame(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, shimmer.mSignalNameArray[4]); + assertEquals("i16", shimmer.mSignalDataTypeArray[4]); + + byte[] packet = packet(shimmer, 0x0101, 0x0202, 0x0303, 6543, 0x0456, 0x0123); + ObjectCluster objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + + assertEquals(6543, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + FormatCluster cal = soundLevel(objectCluster, CHANNEL_TYPE.CAL); + assertEquals(65.43, cal.mData, 1e-9); + assertEquals(CHANNEL_UNITS.DECIBELS_A, cal.mUnits); + + // The channels after it are still where the channel list says + long[] parsed = UtilParseData.parseData(packet, shimmer.mSignalDataTypeArray); + assertEquals(0x0303, parsed[3]); + assertEquals(6543, parsed[4]); + assertEquals(0x0456, parsed[5]); + assertEquals(0x0123, parsed[6]); + } + + /** The decoder goes by the channel list, not by a fixed position */ + @Test + public void decodedWhereverTheChannelListPutsIt() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(SOUND_LEVEL, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 4012, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(40.12, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + + shimmer = new TestShimmer(S3R); + shimmer.channels(VBATT, SOUND_LEVEL); + objectCluster = shimmer.buildMsg(packet(shimmer, 0x0123, 4012), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(40.12, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + /** 0x8000 says there is no level: NaN, never -327.68 */ + @Test + public void noLevelIsNaN() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 0x8000, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + + assertEquals(SensorSoundLevel.NO_LEVEL, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + assertTrue(Double.isNaN(soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData)); + } + + /** Signed: a level below 0 dB(A) is a level, not a wrap */ + @Test + public void signedLittleEndian() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(SOUND_LEVEL); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0xFF9C), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(-100, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + assertEquals(-1.0, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + + objectCluster = shimmer.buildMsg(packet(shimmer, 0x7FFF), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(327.67, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + /** Shimmer3R SD files carry the channel list in their header, decoded the same way */ + @Test + public void decodedFromAnSdFile() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, GSR, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 7210, 0x0456, 0x0123), COMMUNICATION_TYPE.SD, false, 0); + assertEquals(72.10, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + @Test + public void calibration() { + assertEquals(65.43, SensorSoundLevel.calibrateSoundLevel(6543), 1e-12); + assertEquals(0.0, SensorSoundLevel.calibrateSoundLevel(0), 0); + assertEquals(-327.67, SensorSoundLevel.calibrateSoundLevel(-32767), 1e-12); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(-32768))); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(32768))); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(Double.NaN))); + } + + /** A Shimmer3 never sends 0x38: if one did, it would stay an unknown channel, as before */ + @Test + public void shimmer3KeepsTheUnknownChannelHandling() { + TestShimmer shimmer = new TestShimmer(S3); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, VBATT); + assertEquals(Byte.toString(SOUND_LEVEL), shimmer.mSignalNameArray[2]); + assertEquals("u12", shimmer.mSignalDataTypeArray[2]); + + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 6543, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertNull(soundLevel(objectCluster, CHANNEL_TYPE.CAL)); + assertNull(soundLevel(objectCluster, CHANNEL_TYPE.UNCAL)); + } + + // ---------- Configuration byte 233 ---------- + + @Test + public void onlyAShimmer3RHasTheSensor() { + TestShimmer s3r = new TestShimmer(S3R); + assertNotNull(s3r.getSensorClass(SENSORS.SOUND_LEVEL)); + assertNotNull(s3r.getSensorDetails(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + assertFalse("off until the Shimmer says otherwise", s3r.isSoundLevelEnabled()); + + TestShimmer s3 = new TestShimmer(S3); + assertNull(s3.getSensorClass(SENSORS.SOUND_LEVEL)); + assertNull(s3.getSensorDetails(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + } + + /** The DEV-99 audio mode went to 0 on every full write before DEV-1413 */ + @Test + public void theAudioModeReadGoesBackOnAFullWrite() { + for(int audioMode=0;audioMode<4;audioMode++){ + TestShimmer shimmer = readFrom(S3R, audioMode); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals("mode " + audioMode, audioMode, writtenAudioConfig(shimmer)); + } + } + + /** + * Every value of the byte: bits 0-4 go back as read, bits 5-6 are cleared + * as the firmware clears them, and bit 7 set (erased flash) reads as 0 + */ + @Test + public void everyByteGoesBackAsTheFirmwareKeepsIt() { + for(int value=0;value<256;value++){ + TestShimmer shimmer = readFrom(S3R, value); + boolean valid = (value & 0x80)==0; + assertEquals(hex(value), valid && (value & 0x10)!=0, shimmer.isSoundLevelEnabled()); + assertEquals(hex(value), valid ? value & 0x1F : 0, writtenAudioConfig(shimmer)); + } + } + + /** Enabling the sensor sets byte 233 bit 4 and changes nothing else in the image */ + @Test + public void enablingSetsBit4AndNothingElse() { + TestShimmer shimmer = readFrom(S3R, 0x02); + byte[] off = shimmer.written(); + + shimmer.setSoundLevelEnabled(true); + byte[] on = shimmer.written(); + assertEquals(0x12, on[IDX_AUDIO_CONFIG] & 0xFF); + byte[] onWithByte233Off = on.clone(); + onWithByte233Off[IDX_AUDIO_CONFIG] = off[IDX_AUDIO_CONFIG]; + assertArrayEquals("no sensor bitmap bit, so no other byte moves", off, onWithByte233Off); + + shimmer.setSoundLevelEnabled(false); + assertTrue(Arrays.equals(off, shimmer.written())); + } + + /** A Shimmer3R never read writes 0, as the driver always did */ + @Test + public void unreadShimmer3RWritesZero() { + TestShimmer shimmer = new TestShimmer(S3R); + assertEquals(0, writtenAudioConfig(shimmer)); + shimmer.setSoundLevelEnabled(true); + assertEquals(0x10, writtenAudioConfig(shimmer)); + } + + /** The bitmap has no bit for it, so updating the sensor map from the bitmap must leave it alone */ + @Test + public void theSensorBitmapDoesNotTurnItOff() { + TestShimmer shimmer = readFrom(S3R, 0x11); + assertTrue(shimmer.isSoundLevelEnabled()); + long enabledSensors = shimmer.getEnabledSensors(); + + shimmer.setEnabledAndDerivedSensorsAndUpdateMaps(shimmer.getEnabledSensors(), shimmer.getDerivedSensors()); + assertTrue(shimmer.isSoundLevelEnabled()); + + shimmer.refreshEnabledSensorsFromSensorMap(); + assertEquals("adds no bitmap bit (0x4000 would read as ECG-to-HR on SD)", enabledSensors, shimmer.getEnabledSensors()); + assertEquals(0x11, writtenAudioConfig(shimmer)); + } + + /** A Shimmer3 has no microphone: byte 233 stays 0 whatever was read */ + @Test + public void shimmer3WritesZero() { + TestShimmer shimmer = readFrom(S3, 0x13); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals(0, writtenAudioConfig(shimmer)); + assertFalse(shimmer.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, true)); + assertEquals(0, writtenAudioConfig(shimmer)); + } +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java new file mode 100644 index 000000000..bbf8d83e2 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java @@ -0,0 +1,87 @@ +package com.shimmerresearch.pcDriver; + +import static org.junit.Assert.*; + +import org.junit.Test; + +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.ObjectCluster; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; + +/** + * DEV-1413: the Shimmer3R sound level channel through ShimmerPC, the class + * Consensys configures. Consensys edits a copy made by serialisation + * (deepClone()) and writes the configuration from it, so byte 233 as read has + * to survive the copy. API_00040 in ShimmerDriver covers the decoding and the + * byte itself. + *

+ * No hardware. + * + * @author Mark Nolan + */ +public class API_00041_SoundLevelShimmerPCTest { + + private static final int IDX_AUDIO_CONFIG = 233; + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + + private static ShimmerPC shimmer() { + ShimmerPC shimmer = new ShimmerPC("COM99"); + shimmer.setShimmerVersionObjectAndCreateSensorMap(S3R); + return shimmer; + } + + private static ShimmerPC readFrom(int audioConfig) { + byte[] config = shimmer().generateConfigBytesForWritingToShimmer().clone(); + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + ShimmerPC shimmer = shimmer(); + shimmer.configBytesParse(config, COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int writtenAudioConfig(ShimmerPC shimmer) { + return shimmer.generateConfigBytesForWritingToShimmer()[IDX_AUDIO_CONFIG] & 0xFF; + } + + @Test + public void byte233SurvivesTheCopyConsensysWritesFrom() { + ShimmerPC shimmer = readFrom(0x13); + assertTrue(shimmer.isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + + ShimmerPC clone = shimmer.deepClone(); + assertNotNull(clone); + assertTrue(clone.isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + assertEquals(0x13, writtenAudioConfig(clone)); + + assertTrue(clone.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, false)); + assertEquals("the audio mode stays", 0x03, writtenAudioConfig(clone)); + assertEquals("the original is untouched", 0x13, writtenAudioConfig(shimmer)); + } + + /** Consensys streams with the arrays data structure on */ + @Test + public void decodedWithTheArraysDataStructure() { + ShimmerPC shimmer = shimmer(); + shimmer.mNChannels = 2; + shimmer.interpretDataPacketFormat(2, new byte[] {SensorSoundLevel.CHANNEL_ID, 0x03}); + shimmer.enableArraysDataStructure(true); + + byte[] packet = new byte[shimmer.getPacketSize()]; + int iSoundLevel = packet.length - 4; + packet[iSoundLevel] = (byte) 0x8F; // 6543 = 0x198F + packet[iSoundLevel + 1] = (byte) 0x19; + ObjectCluster objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(65.43, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.CAL.toString()), 1e-9); + assertEquals(6543, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.UNCAL.toString()), 0); + + packet[iSoundLevel] = 0x00; // 0x8000, no level + packet[iSoundLevel + 1] = (byte) 0x80; + objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertTrue(Double.isNaN(objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.CAL.toString()))); + assertEquals(-32768, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.UNCAL.toString()), 0); + } +} From e1804c0abe0db356334d25dda327c740ce5699e5 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Wed, 11 Nov 2026 17:17:01 +0000 Subject: [PATCH 08/11] DEV-1413: name v1.01.026, the first firmware release with the sound level SensorSoundLevel's javadoc names LogAndStream_Shimmer3R v1.01.026, and the firmware without byte 233 as the releases before it. Co-Authored-By: Claude Opus 5.5 --- .../sensors/soundlevel/SensorSoundLevel.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java index d22636d14..01abf2252 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -27,7 +27,7 @@ /** * The Shimmer3R sound level channel (DEV-1413): the A-weighted sound level * from the microphone, LAeq over the most recent completed 128 ms block, in - * dB(A) SPL. + * dB(A) SPL. LogAndStream_Shimmer3R v1.01.026 is the first release with it. *

* Nominal. The firmware adds the microphone's datasheet sensitivity and * nothing more; no unit has been checked against a calibrated sound level @@ -49,9 +49,9 @@ * 2-3), which this class keeps as read so that a full configuration write, * which builds its image from zeros, gives the Shimmer back its own. Firmware * that has the byte but not the channel clears bit 4, so a write and a read - * back says whether a unit has it. Firmware from before the byte (before - * DEV-99) stores it untouched, so there the bit reads back set while no - * channel is sent; the channel list is what the decoder goes by. + * back says whether a unit has it. Firmware from before the byte (releases + * before v1.01.026, DEV-99) stores it untouched, so there the bit reads back + * set while no channel is sent; the channel list is what the decoder goes by. *

* This class is only created for a Shimmer3R. A Shimmer3's byte 233 stays 0. */ From a09a0d45a523878b4bf8832a9775906d335668a1 Mon Sep 17 00:00:00 2001 From: JongChern Date: Fri, 13 Nov 2026 11:35:07 +0800 Subject: [PATCH 09/11] DEV-1413: offer the sound level only from LogAndStream_Shimmer3R v1.01.026 Releases before v1.01.026 store configuration byte 233 untouched, so on them bit 4 read back set while no channel was sent: the Sound Level tile showed on, and nothing arrived. The bit also stayed in the unit, so a later firmware update would turn the channel on unasked. The sensor's compatibility list is now Shimmer3R LogAndStream v1.01.026 and later, so the tile is offered only there. On older firmware a bit 4 already set reads as off and the next configuration write clears it. Bits 0-3, the audio mode the full write used to wipe, are kept on every Shimmer3R firmware as before. API_00040 runs at v1.01.026 and adds three tests at v1.01.025: the tile is not offered, a stored bit 4 reads off and is cleared on write, and enabling sets nothing. Without the gate all three fail. ShimmerDriver 195/195, ShimmerDriverPC 105/105, on JDK 11. Co-Authored-By: Claude Opus 5.5 --- .../shimmerresearch/driver/Configuration.java | 11 +++--- .../sensors/soundlevel/SensorSoundLevel.java | 34 ++++++++++++------ .../API_00040_SoundLevelChannelTest.java | 35 +++++++++++++++++-- .../API_00041_SoundLevelShimmerPCTest.java | 3 +- 4 files changed, 66 insertions(+), 17 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java index 3f416f7ba..0f2f44607 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java @@ -1337,6 +1337,8 @@ public static class CompatibilityInfoForMaps{ private static final ShimmerVerObject svoShimmer3RImuAnyExpBrdLogAndStream = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,0,1,0,ShimmerVerDetails.ANY_VERSION, ShimmerVerDetails.ANY_VERSION, NEW_IMU_EXP_REV.IMU); public static final ShimmerVerObject svoShimmer3RLogAndStream = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION); + /** LogAndStream_Shimmer3R v1.01.026 and later: the first release with the sound level channel (DEV-1413) */ + public static final ShimmerVerObject svoShimmer3RLogAndStreamSoundLevel = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,1,1,26,ShimmerVerDetails.ANY_VERSION); public static final ShimmerVerObject svoShimmer3LogAndStreamWithSDLogSyncSupport = new ShimmerVerObject(HW_ID.SHIMMER_3,FW_ID.LOGANDSTREAM,0,16,11,ShimmerVerDetails.ANY_VERSION); public static final ShimmerVerObject svoShimmer3RLogAndStreamWithSDLogSyncSupport = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION); @@ -1544,11 +1546,12 @@ public static class CompatibilityInfoForMaps{ svoShimmer3RBrAmpUnifiedLogAndStream, svoShimmer3RProto3DeluxeLogAndStream); - //Shimmer3r sound level (DEV-1413). Every Shimmer3R has the microphone. - //Whether the firmware has the channel is learnt by writing - //configuration byte 233 bit 4 and reading it back, not from here. + //Shimmer3r sound level (DEV-1413), from LogAndStream_Shimmer3R v1.01.026, + //the first release with the channel. Earlier releases store + //configuration byte 233 untouched, so bit 4 would read back set there + //with no channel behind it: the tile is not offered on them. public static final List listOfCompatibleVersionInfoSoundLevel = Arrays.asList( - svoShimmer3RLogAndStream); + svoShimmer3RLogAndStreamSoundLevel); //TODO need to update this list and remove "any" public static final List listOfCompatibleVersionInfoKionixKXRB52042 = Arrays.asList( diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java index 01abf2252..8365b00c3 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -47,11 +47,17 @@ * Enabling it. Not a sensor bitmap bit: configuration byte 233 bit 4. * Byte 233 also holds the DEV-99 audio mode (bits 0-1) and gain preset (bits * 2-3), which this class keeps as read so that a full configuration write, - * which builds its image from zeros, gives the Shimmer back its own. Firmware - * that has the byte but not the channel clears bit 4, so a write and a read - * back says whether a unit has it. Firmware from before the byte (releases - * before v1.01.026, DEV-99) stores it untouched, so there the bit reads back - * set while no channel is sent; the channel list is what the decoder goes by. + * which builds its image from zeros, gives the Shimmer back its own, on any + * Shimmer3R firmware. + *

+ * Offered from v1.01.026. The sensor and its tile are only offered on + * LogAndStream_Shimmer3R v1.01.026 and later + * ({@link CompatibilityInfoForMaps#listOfCompatibleVersionInfoSoundLevel}). + * Releases before it (DEV-99) store byte 233 untouched, so there bit 4 would + * read back set while no channel is sent. On them, a bit 4 that is already + * set reads as off, and the next configuration write clears it, so a later + * firmware update does not turn the channel on unasked. The channel list, + * not the bit, is still what the decoder goes by. *

* This class is only created for a Shimmer3R. A Shimmer3's byte 233 stays 0. */ @@ -198,16 +204,22 @@ private static ConfigByteLayoutShimmer3 getAudioConfigLayout(ShimmerDevice shimm return null; } + /** Whether this firmware has the channel: LogAndStream_Shimmer3R v1.01.026 or later */ + private static boolean isChannelSupported(ShimmerDevice shimmerDevice) { + return shimmerDevice.isVerCompatibleWithAnyOf(CompatibilityInfoForMaps.listOfCompatibleVersionInfoSoundLevel); + } + /** * Byte 233: bits 0-3 as read (0 if the byte read was not valid) and bit 4 - * from this sensor's state; bits 5-7 are 0, as the firmware wants them. + * from this sensor's state, on firmware that has the channel; bits 5-7 are + * 0, as the firmware wants them. */ @Override public void configBytesGenerate(ShimmerDevice shimmerDevice, byte[] configBytes, COMMUNICATION_TYPE commType) { ConfigByteLayoutShimmer3 configByteLayoutCast = getAudioConfigLayout(shimmerDevice, configBytes); if(configByteLayoutCast!=null){ int value = mAudioModeAndGain & configByteLayoutCast.maskAudioModeAndGain; - if(isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)){ + if(isChannelSupported(shimmerDevice) && isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)){ value |= configByteLayoutCast.maskSoundLevel << configByteLayoutCast.bitShiftSoundLevel; } configBytes[configByteLayoutCast.idxAudioConfig] = (byte) value; @@ -216,8 +228,9 @@ public void configBytesGenerate(ShimmerDevice shimmerDevice, byte[] configBytes, /** * Keeps byte 233's bits 0-3 for the next write and takes this sensor's - * state from bit 4. Bit 7 set (erased flash reads 0xFF) makes the firmware - * read the whole byte as 0, and so does this. + * state from bit 4, on firmware that has the channel; before v1.01.026 the + * sensor reads as off whatever bit 4 holds. Bit 7 set (erased flash reads + * 0xFF) makes the firmware read the whole byte as 0, and so does this. */ @Override public void configBytesParse(ShimmerDevice shimmerDevice, byte[] configBytes, COMMUNICATION_TYPE commType) { @@ -231,7 +244,8 @@ public void configBytesParse(ShimmerDevice shimmerDevice, byte[] configBytes, CO SensorDetails sensorDetails = mSensorMap.get(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); if(sensorDetails!=null){ - sensorDetails.setIsEnabled(((value >> configByteLayoutCast.bitShiftSoundLevel) & configByteLayoutCast.maskSoundLevel)!=0); + sensorDetails.setIsEnabled(isChannelSupported(shimmerDevice) + && ((value >> configByteLayoutCast.bitShiftSoundLevel) & configByteLayoutCast.maskSoundLevel)!=0); } } } diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java index e06f0d5df..9e170d146 100644 --- a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00040_SoundLevelChannelTest.java @@ -34,8 +34,10 @@ public class API_00040_SoundLevelChannelTest { private static final int IDX_AUDIO_CONFIG = 233; - /** Shimmer3R LogAndStream: every one has the microphone */ - private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + /** Shimmer3R LogAndStream v1.01.026, the first release with the channel: every Shimmer3R has the microphone */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 26); + /** The release before it, which stores byte 233 untouched */ + private static final ShimmerVerObject S3R_BEFORE_CHANNEL = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); private static final ShimmerVerObject S3 = new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17); private static final byte LN_ACCEL_X = 0x00; @@ -249,6 +251,35 @@ public void onlyAShimmer3RHasTheSensor() { assertNull(s3.getSensorDetails(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); } + /** The tile is offered from v1.01.026, the first release with the channel, and not before */ + @Test + public void theTileIsOfferedFromV1_01_026() { + int tile = Configuration.Shimmer3.LABEL_SENSOR_TILE.SOUND_LEVEL.ordinal(); + assertTrue(new TestShimmer(S3R).getSensorGroupingMap().containsKey(tile)); + assertTrue(new TestShimmer(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 2, 0)).getSensorGroupingMap().containsKey(tile)); + assertFalse(new TestShimmer(S3R_BEFORE_CHANNEL).getSensorGroupingMap().containsKey(tile)); + } + + /** + * Before v1.01.026 the firmware stores byte 233 untouched, so a bit 4 read back + * there has no channel behind it: it reads as off, and the next write clears it, + * keeping the audio mode, so a later firmware update does not turn the channel on + */ + @Test + public void beforeTheChannelBit4ReadsOffAndIsClearedOnWrite() { + TestShimmer shimmer = readFrom(S3R_BEFORE_CHANNEL, 0x12); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals("the audio mode kept, bit 4 cleared", 0x02, writtenAudioConfig(shimmer)); + } + + /** Before v1.01.026 enabling it writes nothing: the firmware would only store the bit */ + @Test + public void beforeTheChannelEnablingDoesNotSetBit4() { + TestShimmer shimmer = readFrom(S3R_BEFORE_CHANNEL, 0x01); + shimmer.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, true); + assertEquals("the audio mode kept, bit 4 not set", 0x01, writtenAudioConfig(shimmer)); + } + /** The DEV-99 audio mode went to 0 on every full write before DEV-1413 */ @Test public void theAudioModeReadGoesBackOnAFullWrite() { diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java index bbf8d83e2..9e6040c77 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00041_SoundLevelShimmerPCTest.java @@ -27,7 +27,8 @@ public class API_00041_SoundLevelShimmerPCTest { private static final int IDX_AUDIO_CONFIG = 233; - private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + /** v1.01.026, the first release with the channel */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 26); private static ShimmerPC shimmer() { ShimmerPC shimmer = new ShimmerPC("COM99"); From 1893a0efa735e3f72fa5d984bfcddc88a659f63b Mon Sep 17 00:00:00 2001 From: JongChern Date: Fri, 13 Nov 2026 12:41:29 +0800 Subject: [PATCH 10/11] DEV-971: read event files, take live event records, ask the event channel status The Java driver now does the host side of the event channel that the web SDK does (log-and-stream-common docs/SHIMMER3_EVENT_CHANNEL.md and SHIMMER3_BT_COMMUNICATION_PROTOCOL.md section 7.15): - EventFile, EventRecord: the SD card's events/ files, a 64-byte header and 16-byte records, with pairing to the data file by its initial timestamp. - writeEventStream(boolean): SET_FEATURE / FEATURE_EVENT_STREAM. Each record frame, [0x8A][0xBB][0x10][record][CRC-16], reaches EventChannelListener. Frames are taken between data packets (any link CRC mode), straight after the opt-in's ACK, at the start of the buffer, and when idle, including before a command's ACK or reply. They are only parsed after an opt-in, and only once their own CRC checks out. - readEventChannelStatus(): GET_EVENT_CHANNEL_STATUS_COMMAND (0xB9). Not streaming only: its reply is not wrapped in 0x8A, so the streaming parser could not tell it from a packet. Tests port the web SDK's tests/events/record.test.ts inputs and results, and run the IO thread over an in-memory radio for the streaming and idle paths. Android's Shimmer.java overrides the streaming parser and does not know the frame, so it must not opt in until ported. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 327 +++++++++++- .../shimmerresearch/driver/ShimmerObject.java | 5 + .../driver/shimmer2r3/EventChannelStatus.java | 110 ++++ .../driver/shimmer2r3/EventFile.java | 238 +++++++++ .../driver/shimmer2r3/EventFrame.java | 93 ++++ .../driver/shimmer2r3/EventRecord.java | 218 ++++++++ .../API_00042_EventRecordFileTest.java | 253 +++++++++ .../bluetooth/API_00043_EventStreamTest.java | 492 ++++++++++++++++++ 8 files changed, 1729 insertions(+), 7 deletions(-) create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventChannelStatus.java create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventFile.java create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventFrame.java create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventRecord.java create mode 100644 ShimmerDriver/src/test/java/com/shimmerresearch/driver/shimmer2r3/API_00042_EventRecordFileTest.java create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 134f22883..e2df1cef4 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -91,6 +91,7 @@ import java.util.Timer; import java.util.TimerTask; import java.util.concurrent.ArrayBlockingQueue; +import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.TimeUnit; import org.apache.commons.lang3.ArrayUtils; @@ -107,6 +108,9 @@ import com.shimmerresearch.driver.Configuration.Shimmer3; import com.shimmerresearch.driver.calibration.CalibDetails.CALIB_READ_SOURCE; import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; +import com.shimmerresearch.driver.shimmer2r3.EventChannelStatus; +import com.shimmerresearch.driver.shimmer2r3.EventFrame; +import com.shimmerresearch.driver.shimmer2r3.EventRecord; import com.shimmerresearch.driver.ShimmerObject; import com.shimmerresearch.driverUtilities.AssembleShimmerConfig; import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; @@ -270,7 +274,35 @@ public String toString() { //endregion --------- TIMERS --------- protected transient ByteArrayOutputStream mByteArrayOutputStream = new ByteArrayOutputStream(); - + + //region --------- EVENT CHANNEL (DEV-971) --------- + /** + * Told of the event channel's records as they arrive, and of its status + * (DEV-971). Called on the driver's IO thread: hand the work to your own + * thread rather than block it. + */ + public interface EventChannelListener { + /** A record from a connection that opted in with {@link ShimmerBluetooth#writeEventStream(boolean)} */ + void onEventRecord(ShimmerBluetooth shimmer, EventRecord record); + /** The answer to {@link ShimmerBluetooth#readEventChannelStatus()} */ + void onEventChannelStatus(ShimmerBluetooth shimmer, EventChannelStatus status); + } + + private transient List mEventChannelListeners = new CopyOnWriteArrayList(); + /** + * Whether record frames may arrive on this connection: set when the opt-in + * is sent, since the firmware sends the first record straight after its + * ACK, and kept until the next connection, since frames sent before an + * opt-out took effect can still be on their way. The protocol says never to + * parse them without opting in. + */ + private volatile boolean mEventFramesPossible = false; + private volatile boolean mEventStreamRequested = false; + private volatile EventChannelStatus mEventChannelStatus = null; + private volatile int mEventFramesReceived = 0; + private volatile int mEventFramesBadCrc = 0; + //endregion --------- EVENT CHANNEL --------- + // private boolean mVerboseMode = true; // private String mParentClassName = "ShimmerBluetooth"; @@ -384,7 +416,8 @@ public enum SHIMMER_FEATURE { aMap.put(GET_RWC_COMMAND, new BtCommandDetails(GET_RWC_COMMAND, "GET_RWC_COMMAND", RWC_RESPONSE)); aMap.put(GET_VBATT_COMMAND, new BtCommandDetails(GET_VBATT_COMMAND, "GET_VBATT_COMMAND", VBATT_RESPONSE)); aMap.put(GET_BT_FW_VERSION_STR_COMMAND, new BtCommandDetails(GET_BT_FW_VERSION_STR_COMMAND, "GET_BT_FW_VERSION_STR_COMMAND", BT_FW_VERSION_STR_RESPONSE)); - + aMap.put(GET_EVENT_CHANNEL_STATUS_COMMAND, new BtCommandDetails(GET_EVENT_CHANNEL_STATUS_COMMAND, "GET_EVENT_CHANNEL_STATUS_COMMAND", EVENT_CHANNEL_STATUS_RESPONSE)); + mBtGetCommandMap = Collections.unmodifiableMap(aMap); } @@ -505,7 +538,8 @@ public enum SHIMMER_FEATURE { aMap.put(RWC_RESPONSE, new BtCommandDetails(RWC_RESPONSE, "RWC_RESPONSE", 8)); aMap.put(VBATT_RESPONSE, new BtCommandDetails(VBATT_RESPONSE, "VBATT_RESPONSE", 3)); aMap.put(BT_FW_VERSION_STR_RESPONSE, new BtCommandDetails(BT_FW_VERSION_STR_RESPONSE, "BT_FW_VERSION_STR_RESPONSE", -1)); - + aMap.put(EVENT_CHANNEL_STATUS_RESPONSE, new BtCommandDetails(EVENT_CHANNEL_STATUS_RESPONSE, "EVENT_CHANNEL_STATUS_RESPONSE", EventChannelStatus.LENGTH)); + mBtResponseMap = Collections.unmodifiableMap(aMap); } @@ -854,7 +888,18 @@ private void processNotStreamingWaitForAck() { if(byteBuffer!=null){ mNumberofTXRetriesCount = 0; setIamAlive(true); - + + /* An event record frame sent before the ACK: take it and keep + * waiting. The firmware never holds a reply back for one, but a + * frame already queued can go out first (DEV-971). */ + if(byteBuffer[0]==INSTREAM_CMD_RESPONSE && mEventFramesPossible) { + byte[] subtype = readBytes(1, INSTREAM_CMD_RESPONSE); + if(subtype!=null && subtype[0]==EVENT_RECORD_RESPONSE) { + readEventFrameRestFromPort(); + } + return; + } + //TODO: ACK is probably now working for STOP_STREAMING_COMMAND so merge in with others? if(mCurrentCommand==STOP_STREAMING_COMMAND || mCurrentCommand==STOP_SDBT_COMMAND) { //due to not receiving the ack from stop streaming command we will skip looking for it. @@ -977,8 +1022,27 @@ private void processNotStreamingWaitForResp() { //Check to see whether it is a response byte else if(isKnownResponse(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; - - processResponseCommand(responseCommand); + + if(responseCommand==INSTREAM_CMD_RESPONSE && mEventFramesPossible) { + /* 0x8A can be the reply (a wrapped one such as the status) + * or an event record frame sent before it, which is taken + * and the reply still waited for (DEV-971) */ + byte[] subtype = readBytes(1, INSTREAM_CMD_RESPONSE); + if(subtype==null) { + return; + } + if(subtype[0]==EVENT_RECORD_RESPONSE) { + readEventFrameRestFromPort(); + return; + } + processInstreamResponse(subtype[0], false); + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF) { + clearCrcBytesFromBuffer(responseCommand); + } + } + else { + processResponseCommand(responseCommand); + } //JD: only stop timer after process because there are readbyte opeartions in the processresponsecommand stopTimerCheckForAckOrResp(); //cancel the ack timer mWaitForResponse=false; @@ -1022,6 +1086,16 @@ && bytesAvailableToBeRead()) { if(byteBuffer[0]==NACK_COMMAND_PROCESSED) { printLogDataForDebugging("NACK received with no command awaiting a reply - ignored"); } + /* An event record frame, which comes with no ACK (DEV-971). The + * serial buffer is not cleared after it, since another frame may + * already be behind it. */ + else if(byteBuffer[0]==INSTREAM_CMD_RESPONSE && mEventFramesPossible) { + byte[] subtype = readBytes(1, INSTREAM_CMD_RESPONSE); + if(subtype!=null && subtype[0]==EVENT_RECORD_RESPONSE) { + readEventFrameRestFromPort(); + return; + } + } else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { printLogDataForDebugging("ACK RECEIVED , Connected State!!"); byteBuffer = readBytes(1, INSTREAM_CMD_RESPONSE); @@ -1106,6 +1180,19 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR // undock, the user button, a low-battery stop), so this completes the // command in flight only if the response is that command's reply byte[] inStreamResponseCommand = readBytes(1, INSTREAM_CMD_RESPONSE); + + // An event record frame has no ACK of its own, so this ACK is a bare + // one: the reply to the SET command in flight, such as the opt-in, + // which the firmware follows at once with its first record (DEV-971) + if(mEventFramesPossible && inStreamResponseCommand!=null + && inStreamResponseCommand[0]==EVENT_RECORD_RESPONSE){ + processDataPacket(bufferTemp); + processAckWhileStreaming(); + readEventFrameRestFromPort(); + clearBuffers(); + return; + } + boolean isReplyToCommandInFlight = inStreamResponseCommand!=null && isReplyToCommandInFlight(inStreamResponseCommand[0]); if(isReplyToCommandInFlight){ @@ -1145,6 +1232,19 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR } } + //Data packet followed by an event record frame, which has no ACK before it + //(DEV-971). The packet is taken and the frame left at the start of the + //buffer for processEventFrameAtStartOfBuffer(). + else if(mEventFramesPossible + && bufferTemp[0]==DATA_PACKET + && bufferTemp[getPacketSizeWithCrc()+1]==INSTREAM_CMD_RESPONSE){ + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF && !checkCrc(bufferTemp, getPacketSize() + 1)) { + discardBufferBytesToNextPacket(); + return; + } + processDataPacket(bufferTemp); + clearBytesFromStartOfBuffers(bufferTemp, getPacketSizeWithCrc()+1); + } //Data packet followed by a NACK (a command refused while streaming, e.g. //any SET blocked by the firmware because it is sensing, or a log start the //device cannot carry out, DEV-1431) @@ -1207,6 +1307,10 @@ protected void processWhileStreaming() { printLogDataForDebugging("readbyte null"); } + if(processEventFrameAtStartOfBuffer()){ + return; + } + if(processAckAtStartOfBuffer()){ return; } @@ -1254,6 +1358,14 @@ private boolean processAckAtStartOfBuffer() { if(bufferTemp.length==2){ return true; //wait for the response opcode } + //Or a bare ACK to the SET command in flight, followed by an event record + //frame, which has no ACK of its own (DEV-971) + if(mEventFramesPossible && bufferTemp[2]==EVENT_RECORD_RESPONSE + && isKnownSetCommand(mCurrentCommand) && mBtCommsCrcModeCurrent==BT_CRC_MODE.OFF){ + clearBytesFromStartOfBuffers(bufferTemp, 1); + processAckWhileStreaming(); + return true; + } if(bufferTemp.length>3 || !isReplyToCommandInFlight(bufferTemp[2])){ return false; } @@ -1476,6 +1588,11 @@ else if(inStreamResponseCommand==VBATT_RESPONSE) { + "\tBatt %=" + battStatusDetails.getEstimatedChargePercentageParsed()); } } + else if(inStreamResponseCommand==EVENT_RECORD_RESPONSE && mEventFramesPossible){ + // Carries its own CRC and never the link CRC, so nothing more to clear + readEventFrameRestFromPort(); + responseWasParsed = false; + } else { responseWasParsed = false; @@ -2206,7 +2323,23 @@ else if(responseCommand==BT_FW_VERSION_STR_RESPONSE) { } } } - + + else if(responseCommand==EVENT_CHANNEL_STATUS_RESPONSE) { + byte[] responseData = readBytes(EventChannelStatus.LENGTH, responseCommand); + if(responseData!=null){ + EventChannelStatus status = EventChannelStatus.parse(responseData, 0); + mEventChannelStatus = status; + printLogDataForDebugging("Event channel status:\t" + status); + for(EventChannelListener listener:getEventChannelListeners()){ + try { + listener.onEventChannelStatus(this, status); + } catch (RuntimeException e) { + printLogDataForDebugging("Event channel listener threw: " + e); + } + } + } + } + else { consolePrintLn("Unhandled BT response: " + responseCommand); responseWasParsed = false; @@ -3057,6 +3190,7 @@ private void initializeShimmer3or3R(int hardwareVersion){ // The firmware may have changed since the last connection setEventChannelSupported(null); + resetEventChannelConnectionState(); readEventChannelSupport(); if (isSetupDeviceWhileConnecting()){ @@ -5325,6 +5459,185 @@ private void processEventChannelProbeNack() { setInstructionStackLock(false); } + /** + * Opts this connection in to, or out of, the event channel's records + * (DEV-971): SET_FEATURE with FEATURE_EVENT_STREAM. Once in, every button and + * TTL record reaches each {@link EventChannelListener}, starting with the + * inputs' state at the opt-in, whether or not the Shimmer is streaming or + * logging. + *

+ * It lasts for this connection only: the firmware clears it on connect and + * on disconnect, so call it again after every reconnection. It enables no + * input, since configuration byte 232 decides which are recorded, but it + * does arm an enabled TTL input outside a logging session. + *

+ * Android's {@code Shimmer.java} has its own streaming parser, which does + * not know the record frame: don't opt in there until it is ported. + * + * @return false, and nothing is sent, when the firmware is older than + * SET_FEATURE or is known not to have the event channel + */ + public boolean writeEventStream(boolean enable) { + if(!getShimmerVerObject().isSupportedSetFeature() || Boolean.FALSE.equals(isEventChannelSupported())) { + return false; + } + /* Before the write, not after the ACK: the firmware sends the first + * record straight after its ACK */ + if(enable) { + mEventFramesPossible = true; + } + mEventStreamRequested = enable; + writeSetFeatureCommand(SHIMMER_FEATURE.EVENT_STREAM.ordinal(), enable? 1:0); + return true; + } + + /** Whether this connection asked for the event channel's records with {@link #writeEventStream(boolean)} */ + public boolean isEventStreamRequested() { + return mEventStreamRequested; + } + + /** + * Asks for the event channel's status, GET_EVENT_CHANNEL_STATUS_COMMAND + * (0xB9). The answer goes to each {@link EventChannelListener} and to + * {@link #getEventChannelStatus()}. + *

+ * Only sent to a Shimmer known to have the event channel, since firmware + * without it does not answer, and only while it is not streaming: the reply, + * {@code [ACK][0xBA][status x 9]}, is not wrapped in 0x8A as replies sent + * between data packets are, so the streaming parser could not tell it from + * a packet. + * + * @return whether it was sent + */ + public boolean readEventChannelStatus() { + if(!Boolean.TRUE.equals(isEventChannelSupported()) || isStreaming()) { + return false; + } + writeInstruction(new byte[]{GET_EVENT_CHANNEL_STATUS_COMMAND}); + return true; + } + + /** The last answer to {@link #readEventChannelStatus()}, or null */ + public EventChannelStatus getEventChannelStatus() { + return mEventChannelStatus; + } + + /** Event record frames taken on this connection */ + public int getEventFramesReceived() { + return mEventFramesReceived; + } + + /** Event record frames dropped on this connection because their CRC did not check out */ + public int getEventFramesBadCrc() { + return mEventFramesBadCrc; + } + + public void addEventChannelListener(EventChannelListener listener) { + if(listener!=null && !getEventChannelListeners().contains(listener)) { + getEventChannelListeners().add(listener); + } + } + + public void removeEventChannelListener(EventChannelListener listener) { + getEventChannelListeners().remove(listener); + } + + private List getEventChannelListeners() { + if(mEventChannelListeners==null) { + // null after deserialisation, since the list is transient + mEventChannelListeners = new CopyOnWriteArrayList(); + } + return mEventChannelListeners; + } + + /** Clears the event channel's per-connection state: the firmware clears the opt-in on every connect */ + protected void resetEventChannelConnectionState() { + mEventFramesPossible = false; + mEventStreamRequested = false; + mEventChannelStatus = null; + mEventFramesReceived = 0; + mEventFramesBadCrc = 0; + } + + /** + * While streaming: takes an event record frame at the start of the buffer, + * {@code [0x8A][0xBB][len][record][CRC-16]} with no ACK before it. A frame + * is only taken once its own CRC checks out. + * + * @return true while the bytes so far are taken, or may still turn out to be + * a frame + */ + private boolean processEventFrameAtStartOfBuffer() { + if(!mEventFramesPossible || mByteArrayOutputStream.size()==0) { + return false; + } + byte[] bufferTemp = mByteArrayOutputStream.toByteArray(); + if(bufferTemp[0]!=INSTREAM_CMD_RESPONSE) { + return false; + } + int frameLength = EventFrame.getFrameLength(bufferTemp, 0, bufferTemp.length); + if(frameLength==EventFrame.NEED_MORE) { + return true; + } + if(frameLength==EventFrame.NOT_A_FRAME) { + if(bufferTemp.length>=EventFrame.HEAD_LENGTH && bufferTemp[1]==EVENT_RECORD_RESPONSE) { + mEventFramesBadCrc++; + printLogDataForDebugging("Event record frame discarded, its CRC does not check out: " + + UtilShimmer.bytesToHexStringWithSpacesFormatted(bufferTemp)); + } + return false; + } + dispatchEventRecord(EventRecord.parse(bufferTemp, EventFrame.HEAD_LENGTH)); + clearBytesFromStartOfBuffers(bufferTemp, frameLength); + return true; + } + + /** + * Reads the rest of an event record frame off the port, once its 0x8A and + * 0xBB have been read, and hands the record on if its CRC checks out. + */ + private void readEventFrameRestFromPort() { + byte[] lengthByte = readBytes(1, EVENT_RECORD_RESPONSE); + if(lengthByte==null) { + return; + } + int recordLength = lengthByte[0]&0xFF; + if(recordLengthEventFrame.MAX_RECORD_LENGTH) { + mEventFramesBadCrc++; + printLogDataForDebugging("0x8A 0xBB with a record length of " + recordLength + " is not an event record frame"); + return; + } + byte[] rest = readBytes(recordLength+EventFrame.CRC_LENGTH, EVENT_RECORD_RESPONSE); + if(rest==null) { + return; + } + byte[] frame = new byte[EventFrame.HEAD_LENGTH+rest.length]; + frame[0] = INSTREAM_CMD_RESPONSE; + frame[1] = EVENT_RECORD_RESPONSE; + frame[2] = lengthByte[0]; + System.arraycopy(rest, 0, frame, EventFrame.HEAD_LENGTH, rest.length); + EventRecord record = EventFrame.parse(frame, 0); + if(record==null) { + mEventFramesBadCrc++; + printLogDataForDebugging("Event record frame discarded, its CRC does not check out: " + + UtilShimmer.bytesToHexStringWithSpacesFormatted(frame)); + return; + } + dispatchEventRecord(record); + } + + private void dispatchEventRecord(EventRecord record) { + mEventFramesReceived++; + printLogDataForDebugging("Event record:\t" + record); + for(EventChannelListener listener:getEventChannelListeners()) { + try { + listener.onEventRecord(this, record); + } catch (RuntimeException e) { + printLogDataForDebugging("Event channel listener threw: " + e); + } + } + } + //endregion --------- READ/WRITE FUNCTIONS --------- diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index b4f7da309..52f084551 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -506,6 +506,11 @@ public static final class PRESSURE_SENSOR_ID { public static final byte SET_TEST = (byte) 0xA8; public static final byte SET_FEATURE = (byte) 0xB7; + /** Event channel status (DEV-971): [0xB9] answered by [ACK][0xBA][status x 9] */ + public static final byte GET_EVENT_CHANNEL_STATUS_COMMAND = (byte) 0xB9; + public static final byte EVENT_CHANNEL_STATUS_RESPONSE = (byte) 0xBA; + /** An event channel record, [0x8A][0xBB][len][record][CRC-16], sent only to a host that opted in (DEV-971) */ + public static final byte EVENT_RECORD_RESPONSE = (byte) 0xBB; public static final int MAX_NUMBER_OF_SIGNALS = 77;//50; //used to be 11 but now 13 because of the SR30 + 8 for 3d orientation public static final int MAX_INQUIRY_PACKET_SIZE = 47; diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventChannelStatus.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventChannelStatus.java new file mode 100644 index 000000000..8f8b58122 --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventChannelStatus.java @@ -0,0 +1,110 @@ +package com.shimmerresearch.driver.shimmer2r3; + +import java.io.Serializable; + +/** + * The answer to GET_EVENT_CHANNEL_STATUS_COMMAND (0xB9), which is + * {@code [ACK][0xBA][status x 9]} (DEV-971; log-and-stream-common + * {@code docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md} §7.15). + * + *

+ * 0     inputs the configuration enables: bit 0 button markers, bit 1 TTL
+ * 1     bit 0 the event stream is on for this connection, bit 1 an event file
+ *       is open, bit 2 the event file was stopped by an error, bit 3 the TTL
+ *       input is armed, bit 4 the TTL input is off for a second after a flood
+ * 2     each input's state now: bit 0 button, bit 1 TTL
+ * 3..4  the link's next sequence number
+ * 5..6  edges lost this session, the event file's dropped count
+ * 7..8  records the link lost since the opt-in, because its queue was full
+ * 
+ */ +public class EventChannelStatus implements Serializable { + + private static final long serialVersionUID = 1L; + + /** Length of the status after the 0xBA opcode */ + public static final int LENGTH = 9; + + private final int mInputsEnabled; + private final int mFlags; + private final int mState; + private final int mNextSequenceNumber; + private final int mSessionDropped; + private final int mLinkLost; + + private EventChannelStatus(byte[] b, int at) { + mInputsEnabled = b[at]&0xFF; + mFlags = b[at+1]&0xFF; + mState = b[at+2]&0xFF; + mNextSequenceNumber = EventRecord.uint16(b, at+3); + mSessionDropped = EventRecord.uint16(b, at+5); + mLinkLost = EventRecord.uint16(b, at+7); + } + + /** + * Decodes the 9 status bytes at {@code bytes[offset]}. + * + * @throws IllegalArgumentException when fewer than 9 remain + */ + public static EventChannelStatus parse(byte[] bytes, int offset) { + if(bytes==null || offset<0 || bytes.length//} on the SD card, the companion of + * the data file {@code data///}. It holds the user + * button's and the TTL input's records for that data file. + *

+ * Format: log-and-stream-common {@code docs/SHIMMER3_EVENT_CHANNEL.md} §4: a + * 64-byte header, then 16-byte {@link EventRecord}s, all little-endian. The + * header's own lengths are honoured, so a later format with a longer header or + * longer records still decodes, its extra bytes skipped. + * + *

+ * 0      magic "SEVT"            24  config time, Unix seconds
+ * 4      format version, 1       28  firmware ID
+ * 5      header length, 64       30  firmware major
+ * 6      record length, 16       32  firmware minor
+ * 7      hardware ID             33  firmware internal
+ * 8..15  file-open time, ticks   34  first record's sequence number
+ * 16..23 Shimmer3 RTC offset     36  open reason: 1 session start, 2 split
+ *                                37  inputs recorded: bit 0 button, bit 1 TTL
+ * 
+ */ +public class EventFile implements Serializable { + + private static final long serialVersionUID = 1L; + + public static final String MAGIC = "SEVT"; + public static final int FORMAT_VERSION = 1; + public static final int HEADER_LENGTH = 64; + + public static final int OPEN_REASON_SESSION_START = 1; + public static final int OPEN_REASON_SPLIT = 2; + + /** Thrown for bytes that are not an event file this decoder can read */ + public static class FormatException extends IOException { + private static final long serialVersionUID = 1L; + public FormatException(String message) { + super(message); + } + } + + private int mVersion; + private int mHeaderLength; + private int mRecordLength; + private int mHardwareId; + private long mFileOpenTicks; + private long mRtcOffsetTicks; + private long mConfigTime; + private int mFirmwareId; + private int mFirmwareMajor; + private int mFirmwareMinor; + private int mFirmwareInternal; + private int mFirstSequenceNumber; + private int mOpenReason; + private int mInputs; + private List mRecords = new ArrayList(); + private int mTrailingBytes; + + private EventFile() { + } + + public static EventFile parse(File file) throws IOException { + return parse(Files.readAllBytes(file.toPath())); + } + + /** + * Decodes an event file's bytes. + * + * @throws FormatException when the magic, version or lengths are wrong + */ + public static EventFile parse(byte[] bytes) throws FormatException { + if(bytes==null || bytes.length<8) { + throw new FormatException("Too short to be an event file."); + } + String magic = new String(bytes, 0, 4, StandardCharsets.ISO_8859_1); + if(!MAGIC.equals(magic)) { + throw new FormatException("Not an event file: starts \"" + magic + "\", not \"" + MAGIC + "\"."); + } + EventFile f = new EventFile(); + f.mVersion = bytes[4]&0xFF; + if(f.mVersion!=FORMAT_VERSION) { + throw new FormatException("Event file format version " + f.mVersion + " is not supported."); + } + f.mHeaderLength = bytes[5]&0xFF; + f.mRecordLength = bytes[6]&0xFF; + if(f.mHeaderLength getRecords() { + return Collections.unmodifiableList(mRecords); + } + + /** Bytes after the last whole record, from a file cut short mid-write */ + public int getTrailingBytes() { + return mTrailingBytes; + } + + /** Whether the file ends with a final record. Without one it was cut short, by a flat battery say. */ + public boolean isComplete() { + return !mRecords.isEmpty() && mRecords.get(mRecords.size()-1).isFinal(); + } + + /** A record's real-world time in Unix milliseconds: its ticks plus, on a Shimmer3, the file's RTC offset */ + public double getUnixMs(EventRecord record) { + return (double)(record.getTicks()+mRtcOffsetTicks)*1000.0/EventRecord.TICKS_PER_SECOND; + } + + /** + * Whether this event file belongs with the SD data file whose header gives + * {@code dataFileInitialTimestampTicks}: the two carry the same initial + * timestamp, so a copied or renamed file can still be paired. + */ + public boolean belongsWithDataFile(long dataFileInitialTimestampTicks) { + return mFileOpenTicks==dataFileInitialTimestampTicks; + } + + /** + * The companion event file of an SD data file, by the card's layout: + * {@code data/X/NNN} pairs with {@code events/X/NNN}. Returns null when the + * data file is not under a {@code data} folder. + */ + public static File getCompanionFile(File dataFile) { + File session = dataFile.getParentFile(); + File experiment = session==null? null:session.getParentFile(); + File dataRoot = experiment==null? null:experiment.getParentFile(); + if(dataRoot==null || !"data".equalsIgnoreCase(dataRoot.getName())) { + return null; + } + File eventsRoot = new File(dataRoot.getParentFile(), "events"); + return new File(new File(new File(eventsRoot, experiment.getName()), session.getName()), dataFile.getName()); + } + +} diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventFrame.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventFrame.java new file mode 100644 index 000000000..9eb49cc12 --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/EventFrame.java @@ -0,0 +1,93 @@ +package com.shimmerresearch.driver.shimmer2r3; + +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; + +/** + * The Bluetooth frame that carries one event channel record to a host that + * opted in (DEV-971): {@code [0x8A][0xBB][len][record][CRC-16]}, 21 bytes with + * the firmware's 16-byte record. + *

+ * Format: log-and-stream-common {@code docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md} + * §7.15. The frame has no leading ACK, and carries its own CRC-16 (seed 0xB0CA, + * an odd length padded with one 0x00, as the link CRC) whatever CRC mode the + * link is in, never the link CRC on top. A frame is only taken once that CRC + * checks out, which is what lets a parser find one between data packets with + * confidence. + */ +public class EventFrame { + + public static final byte INSTREAM_CMD_RESPONSE = (byte) 0x8A; + /** The frame's subtype after {@link #INSTREAM_CMD_RESPONSE} */ + public static final byte EVENT_RECORD_RESPONSE = (byte) 0xBB; + /** Prefix, subtype and length byte */ + public static final int HEAD_LENGTH = 3; + public static final int CRC_LENGTH = 2; + /** A frame with the firmware's 16-byte record */ + public static final int LENGTH = HEAD_LENGTH+EventRecord.LENGTH+CRC_LENGTH; + /** + * The longest record a frame is believed to carry. The firmware sends 16; a + * later one may send more, which a host skips. Anything longer is taken for + * a stray 0x8A rather than a giant frame. + */ + public static final int MAX_RECORD_LENGTH = 64; + + /** {@link #getFrameLength} result: the bytes so far could still be a frame */ + public static final int NEED_MORE = -1; + /** {@link #getFrameLength} result: they are not a frame */ + public static final int NOT_A_FRAME = 0; + + private EventFrame() { + } + + /** + * The length of the frame at {@code buf[at]}, of the first {@code available} + * bytes there: {@link #NEED_MORE} when they end before that can be told, or + * {@link #NOT_A_FRAME} when they are not a frame whose CRC checks out. + */ + public static int getFrameLength(byte[] buf, int at, int available) { + if(available<1) { + return NEED_MORE; + } + if(buf[at]!=INSTREAM_CMD_RESPONSE) { + return NOT_A_FRAME; + } + if(available<2) { + return NEED_MORE; + } + if(buf[at+1]!=EVENT_RECORD_RESPONSE) { + return NOT_A_FRAME; + } + if(availableMAX_RECORD_LENGTH) { + return NOT_A_FRAME; + } + int total = HEAD_LENGTH+recordLength+CRC_LENGTH; + if(available + * Format: log-and-stream-common {@code docs/SHIMMER3_EVENT_CHANNEL.md} §4.2. + * All fields are little-endian. + * + *

+ * 0      type        1 edge, 2 initial state, 3 heartbeat, 4 overflow
+ * 1      flags       bit 0 timer-latched, 1 synthesized, 2 late, 3 stale, 7 final
+ * 2..3   sequence    in a file it continues across a split; over Bluetooth it is
+ *                    the link's own, from 0 at the opt-in
+ * 4..11  time        RTC ticks, 32768 a second, all 64 bits
+ * 12     channel     0 button, 1 TTL, 0xFF none
+ * 13     state       every input after this record: bit 0 button, bit 1 TTL
+ * 14..15 dropped     edges lost so far (this session in a file, since the
+ *                    opt-in over Bluetooth), stopping at 0xFFFF
+ * 
+ */ +public class EventRecord implements Serializable { + + private static final long serialVersionUID = 1L; + + /** The RTC the records are timed by */ + public static final int TICKS_PER_SECOND = 32768; + public static final int LENGTH = 16; + + public static final int TYPE_EDGE = 0x01; + public static final int TYPE_INITIAL_STATE = 0x02; + public static final int TYPE_HEARTBEAT = 0x03; + public static final int TYPE_OVERFLOW = 0x04; + + /** The time was latched by a timer (TTL edges) */ + public static final int FLAG_HW_CAPTURE = 0x01; + /** An edge the debounce first took as bounce, put back at its own time */ + public static final int FLAG_SYNTHESIZED = 0x02; + /** A TTL capture read more than 32.768 ms after it happened */ + public static final int FLAG_LATE = 0x04; + /** Reserved */ + public static final int FLAG_STATE_STALE = 0x08; + /** The last record of a file */ + public static final int FLAG_FINAL = 0x80; + + public static final int CHANNEL_BUTTON = 0x00; + public static final int CHANNEL_TTL = 0x01; + /** Records that describe no one input: initial state, heartbeat */ + public static final int CHANNEL_NONE = 0xFF; + + /** Bits of a record's state, and of a file header's or status's inputs */ + public static final int INPUT_BUTTON = 0x01; + public static final int INPUT_TTL = 0x02; + + private final int mType; + private final int mFlags; + private final int mSequenceNumber; + private final long mTicks; + private final int mChannel; + private final int mState; + private final int mDropped; + + public EventRecord(int type, int flags, int sequenceNumber, long ticks, int channel, int state, int dropped) { + mType = type; + mFlags = flags; + mSequenceNumber = sequenceNumber; + mTicks = ticks; + mChannel = channel; + mState = state; + mDropped = dropped; + } + + /** + * Decodes the 16-byte record at {@code bytes[offset]}. + * + * @throws IllegalArgumentException when fewer than 16 bytes remain + */ + public static EventRecord parse(byte[] bytes, int offset) { + if(bytes==null || offset<0 || bytes.lengthwrap/2) { + candidate += wrap; + } + return candidate; + } + + /** A short description, such as "Button pressed" or "TTL low" */ + public String getDescription() { + switch(mType) { + case TYPE_EDGE: + if(mChannel==CHANNEL_BUTTON) { + return isButtonDown()? "Button pressed":"Button released"; + } + if(mChannel==CHANNEL_TTL) { + return isTtlHigh()? "TTL high":"TTL low"; + } + return "Edge on channel " + mChannel; + case TYPE_INITIAL_STATE: + return "Initial state"; + case TYPE_HEARTBEAT: + return isFinal()? "End of file":"Heartbeat"; + case TYPE_OVERFLOW: + return "Edges lost"; + default: + return String.format("Record type 0x%02X", mType); + } + } + + @Override + public String toString() { + return "EventRecord[seq=" + mSequenceNumber + ", " + getDescription() + + ", ticks=0x" + Long.toHexString(mTicks) + + ", flags=0x" + Integer.toHexString(mFlags) + + ", state=" + mState + ", dropped=" + mDropped + "]"; + } + + static int uint16(byte[] b, int at) { + return (b[at]&0xFF) | ((b[at+1]&0xFF)<<8); + } + + static long int64(byte[] b, int at) { + long v = 0; + for(int i=7;i>=0;i--) { + v = (v<<8) | (b[at+i]&0xFF); + } + return v; + } + +} diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/shimmer2r3/API_00042_EventRecordFileTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/shimmer2r3/API_00042_EventRecordFileTest.java new file mode 100644 index 000000000..ed282c304 --- /dev/null +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/shimmer2r3/API_00042_EventRecordFileTest.java @@ -0,0 +1,253 @@ +package com.shimmerresearch.driver.shimmer2r3; + +import static org.junit.Assert.*; + +import java.io.File; +import java.util.Arrays; +import java.util.List; + +import org.junit.Test; + +/** + * DEV-971: the event channel's records, event files, Bluetooth record frames + * and status, decoded from the bytes in log-and-stream-common + * docs/SHIMMER3_EVENT_CHANNEL.md §5 and docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md + * §7.15, which the firmware's Test/host/test_event_record.c pins its encoder + * to. The same inputs and results as the web SDK's tests/events/record.test.ts. + */ +public class API_00042_EventRecordFileTest { + + private static byte[] hex(String s) { + String[] parts = s.trim().split("\\s+"); + byte[] out = new byte[parts.length]; + for(int i=0;i records = file.getRecords(); + assertEquals(17, records.size()); + assertEquals(0, file.getTrailingBytes()); + assertTrue(file.isComplete()); + for(int i=0;i r = file.getRecords(); + assertEquals(-0.619995, r.get(0).getSecondsFrom(open), 1e-5); + assertEquals(0.0, r.get(4).getSecondsFrom(open), 0.0); + assertEquals(12.399994, r.get(5).getSecondsFrom(open), 1e-5); + assertEquals(30.000122, r.get(7).getSecondsFrom(open), 1e-5); + assertEquals(150.809998, r.get(16).getSecondsFrom(open), 1e-5); + } + + @Test + public void readsTheRecordFields() throws Exception { + List r = EventFile.parse(WORKED_FILE).getRecords(); + EventRecord press = r.get(0); + assertEquals(EventRecord.TYPE_EDGE, press.getType()); + assertEquals(EventRecord.CHANNEL_BUTTON, press.getChannel()); + assertTrue(press.isButtonDown()); + assertFalse(press.isTtlHigh()); + assertEquals(0, press.getDropped()); + assertEquals("Button pressed", press.getDescription()); + assertEquals("Button released", r.get(1).getDescription()); + + EventRecord init = r.get(4); + assertEquals(EventRecord.TYPE_INITIAL_STATE, init.getType()); + assertEquals(EventRecord.CHANNEL_NONE, init.getChannel()); + assertEquals("Initial state", init.getDescription()); + + EventRecord ttlRise = r.get(7); + assertTrue(ttlRise.isTimerLatched()); + assertEquals("TTL high", ttlRise.getDescription()); + assertEquals("TTL low", r.get(8).getDescription()); + assertEquals("Heartbeat", r.get(11).getDescription()); + assertEquals("End of file", r.get(16).getDescription()); + assertTrue(r.get(16).isFinal()); + } + + @Test + public void keepsAFileCutShortAndSaysSo() throws Exception { + EventFile cut = EventFile.parse(Arrays.copyOf(WORKED_FILE, 64+16*5+7)); + assertEquals(5, cut.getRecords().size()); + assertEquals(7, cut.getTrailingBytes()); + assertFalse(cut.isComplete()); + } + + @Test + public void skipsHeaderAndRecordBytesBeyondThoseItKnows() throws Exception { + byte[] longer = new byte[80+20]; + System.arraycopy(WORKED_FILE, 0, longer, 0, 64); + longer[5] = 80; + longer[6] = 20; + System.arraycopy(WORKED_FILE, 64, longer, 80, 16); + EventFile f = EventFile.parse(longer); + assertEquals(1, f.getRecords().size()); + assertEquals(0x35723711D0A4L, f.getRecords().get(0).getTicks()); + } + + @Test + public void refusesWhatIsNotAnEventFile() { + try { + EventFile.parse(hex("00 01 02 03 04 05 06 07")); + fail("not SEVT"); + } catch (EventFile.FormatException e) { + // expected + } + byte[] v2 = WORKED_FILE.clone(); + v2[4] = 2; + try { + EventFile.parse(v2); + fail("version 2"); + } catch (EventFile.FormatException e) { + assertTrue(e.getMessage(), e.getMessage().contains("version 2")); + } + } + + @Test + public void findsTheCompanionOfADataFile() { + File data = new File(new File(new File(new File("card", "data"), "Trial_1730283600"), "Shimmer_A1B2-007"), "000"); + File events = EventFile.getCompanionFile(data); + assertEquals(new File(new File(new File(new File("card", "events"), "Trial_1730283600"), "Shimmer_A1B2-007"), "000"), events); + assertNull(EventFile.getCompanionFile(new File("000"))); + } + + @Test + public void decodesTheProtocolDocFrameCrcIncluded() { + assertEquals(21, EventFrame.getFrameLength(WORKED_FRAME, 0)); + EventRecord rec = EventFrame.parse(WORKED_FRAME, 0); + assertNotNull(rec); + assertEquals(EventRecord.TYPE_EDGE, rec.getType()); + assertEquals(1, rec.getSequenceNumber()); + assertEquals(0x357237185333L, rec.getTicks()); + assertEquals(EventRecord.CHANNEL_BUTTON, rec.getChannel()); + assertTrue(rec.isButtonDown()); + } + + @Test + public void rejectsAFrameWhoseCrcDoesNotCheckOut() { + byte[] bad = WORKED_FRAME.clone(); + bad[10] ^= 0x01; + assertEquals(EventFrame.NOT_A_FRAME, EventFrame.getFrameLength(bad, 0)); + assertNull(EventFrame.parse(bad, 0)); + } + + @Test + public void asksForMoreUntilTheFrameIsWhole() { + for(int n=1;n<21;n++) { + assertEquals("after " + n + " bytes", EventFrame.NEED_MORE, EventFrame.getFrameLength(WORKED_FRAME, 0, n)); + } + } + + @Test + public void isNotFooledByOther0x8AMessages() { + assertEquals(EventFrame.NOT_A_FRAME, EventFrame.getFrameLength(hex("8A 71 00 01"), 0)); + assertEquals("shorter than a record", EventFrame.NOT_A_FRAME, EventFrame.getFrameLength(hex("8A BB 05"), 0)); + } + + @Test + public void measuresAFrameAtAnOffset() { + byte[] buf = new byte[25]; + System.arraycopy(WORKED_FRAME, 0, buf, 4, WORKED_FRAME.length); + assertEquals(21, EventFrame.getFrameLength(buf, 4)); + } + + @Test + public void decodesTheNineStatusBytes() { + EventChannelStatus s = EventChannelStatus.parse(hex("03 0B 02 05 00 02 00 01 00"), 0); + assertEquals(3, s.getInputsEnabled()); + assertTrue(s.isStreaming()); + assertTrue(s.isFileOpen()); + assertFalse(s.isFileError()); + assertTrue(s.isTtlArmed()); + assertFalse(s.isTtlThrottled()); + assertEquals(EventRecord.INPUT_TTL, s.getState()); + assertEquals(5, s.getNextSequenceNumber()); + assertEquals(2, s.getSessionDropped()); + assertEquals(1, s.getLinkLost()); + } + + @Test(expected=IllegalArgumentException.class) + public void theStatusNeedsAllNine() { + EventChannelStatus.parse(hex("03 0B"), 0); + } + + /** A data packet's 24-bit timestamp, unwrapped from the stream's start, and the record's 64-bit time */ + @Test + public void placesARecordOnTheStreamsUnwrappedTimeline() { + final long wrap = 1L<<24; + long ticks = 0x357237185333L; + EventRecord rec = new EventRecord(EventRecord.TYPE_EDGE, 0, 0, ticks, 0, 1, 0); + long low24 = ticks&(wrap-1); + // A stream that began in an earlier cycle, three wraps ago + double reference = 3*wrap+low24+1000; + assertEquals(3*wrap+low24, rec.getTicksOnStreamTimeline(reference), 0.0); + // The latest sample a little before the edge + assertEquals(3*wrap+low24, rec.getTicksOnStreamTimeline(3*wrap+low24-500), 0.0); + // Across a wrap: the edge just after it, the sample just before + EventRecord justAfterWrap = new EventRecord(EventRecord.TYPE_EDGE, 0, 0, 0x3572380000A0L, 0, 1, 0); + assertEquals(5*wrap+0xA0, justAfterWrap.getTicksOnStreamTimeline(5*wrap-200), 0.0); + } + +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java new file mode 100644 index 000000000..80bdb05ac --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java @@ -0,0 +1,492 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.Deque; +import java.util.List; +import java.util.concurrent.ConcurrentLinkedDeque; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.EventChannelListener; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.SHIMMER_FEATURE; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driver.shimmer2r3.EventChannelStatus; +import com.shimmerresearch.driver.shimmer2r3.EventRecord; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.driverUtilities.UtilShimmer; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-971: a host that opts in with SET_FEATURE / FEATURE_EVENT_STREAM gets + * every button and TTL record as a frame, {@code [0x8A][0xBB][0x10][record][CRC-16]}, + * with no ACK before it and its own CRC whatever the link's CRC mode + * (log-and-stream-common docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md §7.15). + * Frames come between data packets while streaming, straight after the opt-in's + * ACK, and when the Shimmer is idle, including before a command's ACK or reply. + *

+ * Before this the driver knew no 0x8A subtype 0xBB: between data packets it took + * the frame for a parse error and threw it away with whatever followed it until + * the next packet boundary, and when idle it cleared the serial buffer. + *

+ * No hardware. The streaming tests hand the parser one byte at a time, as in + * API_00037_StreamingLogStartRefusedTest; the idle tests run the IOThread over a + * radio that answers as the firmware does, as in API_00038_EventChannelProbeTest. + */ +public class API_00043_EventStreamTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + private static final ShimmerVerObject S3R_V1_1_25 = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + + private static byte[] hex(String s) { + String[] parts = s.trim().split("\\s+"); + byte[] out = new byte[parts.length]; + for(int i=0;i>8); + for(int i=0;i<8;i++) { + f[7+i] = (byte) (ticks>>(8*i)); + } + f[15] = (byte) channel; + f[16] = (byte) state; + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(f, 19); + f[19] = crc[0]; + f[20] = crc[1]; + return f; + } + + /** The first record after an opt-in: the inputs' state then */ + private static final byte[] INITIAL_STATE = frame(EventRecord.TYPE_INITIAL_STATE, 0, 0x357237100000L, EventRecord.CHANNEL_NONE, 0); + private static final byte[] TTL_RISE = frame(EventRecord.TYPE_EDGE, 2, 0x357237200000L, EventRecord.CHANNEL_TTL, EventRecord.INPUT_TTL); + + private static class Collected implements EventChannelListener { + final List records = Collections.synchronizedList(new ArrayList()); + final List statuses = Collections.synchronizedList(new ArrayList()); + + @Override + public void onEventRecord(ShimmerBluetooth shimmer, EventRecord record) { + records.add(record); + } + + @Override + public void onEventChannelStatus(ShimmerBluetooth shimmer, EventChannelStatus status) { + statuses.add(status); + } + + List sequenceNumbers() { + List seqs = new ArrayList(); + synchronized(records) { + for(EventRecord r:records) { + seqs.add(r.getSequenceNumber()); + } + } + return seqs; + } + } + + private final Collected mCollected = new Collected(); + + // ------------------------------------------------------------------ + // While streaming + // ------------------------------------------------------------------ + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() expected = new ArrayList(); + for(byte[] payload:expectedPayloads){ + expected.add(hexOf(payload)); + } + List parsed = new ArrayList(); + ShimmerBluetooth device = mStreamingDevice; + for(RawBytePacketWithPCTimeStamp packet:device.mABQPacketByeArray){ + parsed.add(hexOf(packet.mDataArray)); + } + assertEquals("every data packet is parsed, once and in order", expected, parsed); + } + + private void assertOptInAcked() { + assertFalse("the opt-in's ACK is taken", mStreamingDevice.mWaitForAck); + assertFalse(mStreamingDevice.isInstructionStackLock()); + assertTrue(mStreamingDevice.getListofInstructions().isEmpty()); + assertNull("the ACK timer is cancelled", mStreamingDevice.mTimerCheckForAckOrResp); + assertTrue(mStreamingDevice.isStreaming()); + } + + /** The opt-in's ACK between two packets, then its first record, then more packets and records */ + private void optInMidStream(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + optInWhileStreaming(); + receive(dataPacket(payload(1), crcMode), bareAck(crcMode), INITIAL_STATE, + dataPacket(payload(2), crcMode), MARKER_PRESS, + dataPacket(payload(3), crcMode), TTL_RISE, MARKER_PRESS, + dataPacket(payload(4), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertOptInAcked(); + assertParsed(payload(1), payload(2), payload(3), payload(4)); + assertEquals(Arrays.asList(0, 1, 2, 1), mCollected.sequenceNumbers()); + EventRecord press = mCollected.records.get(1); + assertEquals(0x357237185333L, press.getTicks()); + assertTrue(press.isButtonDown()); + assertEquals(4, mStreamingDevice.getEventFramesReceived()); + assertEquals(0, mStreamingDevice.getEventFramesBadCrc()); + assertArrayEquals(new byte[] {ShimmerObject.DATA_PACKET}, mStreamingDevice.mByteArrayOutputStream.toByteArray()); + } + + @After + public void stopStreamingTimers() { + if(mStreamingDevice!=null){ + mStreamingDevice.stopTimerCheckForAckOrResp(); + mStreamingDevice.stopTimerReadStatus(); + } + } + + @Test + public void framesBetweenPacketsWithoutALinkCrc() { + optInMidStream(BT_CRC_MODE.OFF); + } + + @Test + public void framesBetweenPacketsWithAOneByteLinkCrc() { + optInMidStream(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void framesBetweenPacketsWithATwoByteLinkCrc() { + optInMidStream(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** Data packets paused (the unit closing its SD file, say): the opt-in's ACK and its record at the start of the buffer */ + @Test + public void theOptInsAckAndRecordWithNoPacketBeforeThem() { + streamingShimmer3r(BT_CRC_MODE.OFF); + optInWhileStreaming(); + receive(bareAck(BT_CRC_MODE.OFF), INITIAL_STATE, dataPacket(payload(1), BT_CRC_MODE.OFF), + dataPacket(payload(2), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + assertOptInAcked(); + assertParsed(payload(1), payload(2)); + assertEquals(Arrays.asList(0), mCollected.sequenceNumbers()); + } + + @Test + public void aFrameWhoseCrcFailsIsDroppedAndTheStreamGoesOn() { + BT_CRC_MODE crcMode = BT_CRC_MODE.TWO_BYTE_CRC; + streamingShimmer3r(crcMode); + optInWhileStreaming(); + byte[] corrupt = MARKER_PRESS.clone(); + corrupt[10] ^= 0x01; + receive(dataPacket(payload(1), crcMode), bareAck(crcMode), INITIAL_STATE, + dataPacket(payload(2), crcMode), corrupt, + dataPacket(payload(3), crcMode), dataPacket(payload(4), crcMode), TTL_RISE, + dataPacket(payload(5), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertEquals("the corrupt frame is not taken", Arrays.asList(0, 2), mCollected.sequenceNumbers()); + assertEquals(1, mStreamingDevice.getEventFramesBadCrc()); + List parsed = new ArrayList(); + ShimmerBluetooth device = mStreamingDevice; + for(RawBytePacketWithPCTimeStamp packet:device.mABQPacketByeArray){ + parsed.add(hexOf(packet.mDataArray)); + } + assertTrue(parsed.contains(hexOf(payload(1)))); + assertTrue(parsed.contains(hexOf(payload(2)))); + assertTrue("the parser resyncs after it", parsed.contains(hexOf(payload(4)))); + assertTrue(parsed.contains(hexOf(payload(5)))); + assertFalse("no packet is made up from the frame's bytes", parsed.size()>5); + } + + /** The protocol says never to parse these frames without opting in, and the driver doesn't */ + @Test + public void framesAreNotParsedWithoutAnOptIn() { + streamingShimmer3r(BT_CRC_MODE.TWO_BYTE_CRC); + receive(dataPacket(payload(1), BT_CRC_MODE.TWO_BYTE_CRC), MARKER_PRESS, + dataPacket(payload(2), BT_CRC_MODE.TWO_BYTE_CRC), new byte[] {ShimmerObject.DATA_PACKET}); + assertTrue(mCollected.records.isEmpty()); + assertEquals(0, mStreamingDevice.getEventFramesReceived()); + } + + // ------------------------------------------------------------------ + // Not streaming, with the IOThread running + // ------------------------------------------------------------------ + + /** Answers as LogAndStream_Shimmer3R v1.01.026 does */ + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + /** Sent ahead of the next command's ACK, as a record already queued would be */ + volatile byte[] beforeNextAck = null; + /** Sent between the next status command's ACK and its reply */ + volatile byte[] betweenAckAndReply = null; + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + byte[] early = beforeNextAck; + if(early!=null) { + beforeNextAck = null; + queue(early); + } + if(buffer[0]==ShimmerObject.SET_FEATURE && buffer[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal()){ + queue(ShimmerObject.ACK_COMMAND_PROCESSED); + if(buffer[2]!=0) { + // The first record at the opt-in, then one already made + queue(INITIAL_STATE); + queue(MARKER_PRESS); + } + } + else if(buffer[0]==ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND){ + queue(ShimmerObject.ACK_COMMAND_PROCESSED); + byte[] between = betweenAckAndReply; + if(between!=null) { + betweenAckAndReply = null; + queue(between); + } + queue(ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE); + queue(hex("03 0B 02 05 00 02 00 01 00")); + } + else { + queue(ShimmerObject.ACK_COMMAND_PROCESSED); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() Date: Fri, 13 Nov 2026 12:46:07 +0800 Subject: [PATCH 11/11] DEV-971: Event markers window in SensorMapsExample, to bench the Java event channel Tools > Event markers (Shimmer3R), or the EVENT MARKERS button, opens a window that does with the Java driver what Shimmer Capture web does with the web SDK: - whether the unit has the event channel, and asking again; - configuration byte 232 (button mode, what starts logging, TTL input), written with the whole configuration and read back; - opt in / opt out, the live records with sequence gaps flagged, and the frame and bad-CRC counters; - the event channel status (not while streaming); - an event file from a card: its header, completeness, the data file it pairs with, and its records timed from the file open. Each live edge is also marked on the main plot as a red vertical bar, placed by the latest data packet's Shimmer clock against the plot's PC-time axis. CI does not build ShimmerPCBasicExamples; built locally. Co-Authored-By: Claude Opus 5.5 --- .../simpleexamples/EventMarkersFrame.java | 540 ++++++++++++++++++ .../simpleexamples/SensorMapsExample.java | 115 +++- 2 files changed, 652 insertions(+), 3 deletions(-) create mode 100644 ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/EventMarkersFrame.java diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/EventMarkersFrame.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/EventMarkersFrame.java new file mode 100644 index 000000000..535ba750e --- /dev/null +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/EventMarkersFrame.java @@ -0,0 +1,540 @@ +package com.shimmerresearch.simpleexamples; + +import java.awt.BorderLayout; +import java.awt.Dimension; +import java.awt.FlowLayout; +import java.awt.GridBagConstraints; +import java.awt.GridBagLayout; +import java.awt.Insets; +import java.awt.event.ActionEvent; +import java.awt.event.ActionListener; +import java.awt.event.WindowAdapter; +import java.awt.event.WindowEvent; +import java.io.File; +import java.text.SimpleDateFormat; +import java.util.Date; +import java.util.TimeZone; + +import javax.swing.BorderFactory; +import javax.swing.BoxLayout; +import javax.swing.JButton; +import javax.swing.JCheckBox; +import javax.swing.JComboBox; +import javax.swing.JFileChooser; +import javax.swing.JFrame; +import javax.swing.JLabel; +import javax.swing.JOptionPane; +import javax.swing.JPanel; +import javax.swing.JScrollPane; +import javax.swing.JTabbedPane; +import javax.swing.JTable; +import javax.swing.JTextArea; +import javax.swing.SwingUtilities; +import javax.swing.table.DefaultTableModel; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.EventChannelListener; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; +import com.shimmerresearch.driver.shimmer2r3.EventChannelStatus; +import com.shimmerresearch.driver.shimmer2r3.EventFile; +import com.shimmerresearch.driver.shimmer2r3.EventRecord; + +/** + * A bench window for the Shimmer3 / Shimmer3R event channel (DEV-971), to test + * the Java driver's support against a unit, as Shimmer Capture web does for the + * web SDK: + *

    + *
  • whether the unit has the event channel;
  • + *
  • configuration byte 232: the button mode, what starts logging, the TTL + * input, written and read back;
  • + *
  • the live records after an opt-in, with sequence gaps flagged, and each + * one marked on the main window's plot;
  • + *
  • the event channel status;
  • + *
  • an event file from a card, its header and records.
  • + *
+ */ +public class EventMarkersFrame extends JFrame implements EventChannelListener { + + private static final long serialVersionUID = 1L; + + /** Supplies the connected device, and marks a record on the plot */ + public interface Host { + ShimmerDevice getConnectedDevice(); + void plotEventRecord(ShimmerBluetooth shimmer, EventRecord record); + } + + private static final String[] BUTTON_MODES = { + "0 As before (User Button setting decides)", + "1 Disabled", + "2 Single press starts / stops logging", + "3 Double press starts / stops logging", + "4 Double press starts / stops, every press recorded", + "5 Every press recorded, logging untouched", + }; + private static final String[] LOG_TRIGGERS = { + "0 A host command only", + "1 A host command or an undock", + "2 Nothing: logging off", + }; + + private final Host mHost; + private ShimmerBluetooth mAttachedTo = null; + + private final JLabel mLblSupport = new JLabel(" "); + private final JComboBox mComboButtonMode = new JComboBox(BUTTON_MODES); + private final JComboBox mComboLogTriggers = new JComboBox(LOG_TRIGGERS); + private final JCheckBox mChkTtl = new JCheckBox("Record TTL input"); + private final JLabel mLblConfig = new JLabel(" "); + private final JLabel mLblCounters = new JLabel(" "); + private final JTextArea mTxtStatus = new JTextArea(5, 40); + private final JTextArea mTxtFile = new JTextArea(6, 40); + + private static final String[] LIVE_COLUMNS = {"#", "Received", "Seq", "Shimmer time (UTC)", "Record", "Flags", "State", "Dropped", "Note"}; + private static final String[] FILE_COLUMNS = {"#", "Seq", "From file open (s)", "Shimmer time (UTC)", "Record", "Flags", "State", "Dropped"}; + private final DefaultTableModel mLiveModel = new DefaultTableModel(LIVE_COLUMNS, 0) { + private static final long serialVersionUID = 1L; + @Override public boolean isCellEditable(int r, int c) { return false; } + }; + private final DefaultTableModel mFileModel = new DefaultTableModel(FILE_COLUMNS, 0) { + private static final long serialVersionUID = 1L; + @Override public boolean isCellEditable(int r, int c) { return false; } + }; + + private Integer mLastSeq = null; + private int mGaps = 0; + + private final SimpleDateFormat mUtc = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS"); + private final SimpleDateFormat mLocal = new SimpleDateFormat("HH:mm:ss.SSS"); + + public EventMarkersFrame(Host host) { + super("Event markers (DEV-971)"); + mHost = host; + mUtc.setTimeZone(TimeZone.getTimeZone("UTC")); + setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE); + setSize(new Dimension(1000, 720)); + addWindowListener(new WindowAdapter() { + @Override + public void windowClosed(WindowEvent e) { + detach(); + } + }); + buildUi(); + refresh(); + } + + private void buildUi() { + JPanel top = new JPanel(); + top.setLayout(new BoxLayout(top, BoxLayout.Y_AXIS)); + + // --- Device + JPanel device = new JPanel(new FlowLayout(FlowLayout.LEFT)); + device.setBorder(BorderFactory.createTitledBorder("Device")); + JButton btnRefresh = button("Refresh", new ActionListener() { + public void actionPerformed(ActionEvent e) { + refresh(); + } + }); + JButton btnProbe = button("Ask again", new ActionListener() { + public void actionPerformed(ActionEvent e) { + ShimmerBluetooth sb = shimmer(); + if(sb==null) { + return; + } + if(sb.isStreaming()) { + warn("Stop streaming first: the driver does not ask a streaming Shimmer."); + return; + } + sb.readEventChannelSupport(); + refreshLater(); + } + }); + device.add(mLblSupport); + device.add(btnRefresh); + device.add(btnProbe); + top.add(device); + + // --- Configuration byte 232 + JPanel config = new JPanel(new GridBagLayout()); + config.setBorder(BorderFactory.createTitledBorder("Configuration byte 232 (written with the whole configuration)")); + GridBagConstraints c = new GridBagConstraints(); + c.insets = new Insets(2, 4, 2, 4); + c.anchor = GridBagConstraints.WEST; + c.gridx = 0; c.gridy = 0; + config.add(new JLabel("Button"), c); + c.gridx = 1; + config.add(mComboButtonMode, c); + c.gridx = 0; c.gridy = 1; + config.add(new JLabel("Logging starts on"), c); + c.gridx = 1; + config.add(mComboLogTriggers, c); + c.gridx = 0; c.gridy = 2; + config.add(mChkTtl, c); + JPanel configButtons = new JPanel(new FlowLayout(FlowLayout.LEFT, 4, 0)); + configButtons.add(button("Write", new ActionListener() { + public void actionPerformed(ActionEvent e) { + writeButtonLogMode(); + } + })); + configButtons.add(button("Read back", new ActionListener() { + public void actionPerformed(ActionEvent e) { + ShimmerBluetooth sb = shimmer(); + if(sb==null) { + return; + } + if(sb.isStreaming() || sb.isSDLogging()) { + warn("Stop streaming and logging first: the firmware refuses configuration reads and writes while sensing."); + return; + } + sb.readConfigBytes(); + refreshLater(); + } + })); + c.gridx = 1; + config.add(configButtons, c); + c.gridx = 0; c.gridy = 3; c.gridwidth = 2; + config.add(mLblConfig, c); + top.add(config); + + // --- Live records + JPanel live = new JPanel(new FlowLayout(FlowLayout.LEFT)); + live.setBorder(BorderFactory.createTitledBorder("Live records over Bluetooth (this connection only)")); + live.add(button("Opt in", new ActionListener() { + public void actionPerformed(ActionEvent e) { + optIn(true); + } + })); + live.add(button("Opt out", new ActionListener() { + public void actionPerformed(ActionEvent e) { + optIn(false); + } + })); + live.add(button("Get status", new ActionListener() { + public void actionPerformed(ActionEvent e) { + ShimmerBluetooth sb = shimmer(); + if(sb==null) { + return; + } + attach(sb); + if(!sb.readEventChannelStatus()) { + warn(sb.isStreaming() + ? "Not while streaming: the status reply is not wrapped as replies between data packets are." + : "Not sent: this unit is not known to have the event channel."); + } + } + })); + live.add(button("Clear list", new ActionListener() { + public void actionPerformed(ActionEvent e) { + mLiveModel.setRowCount(0); + mLastSeq = null; + mGaps = 0; + updateCounters(); + } + })); + live.add(mLblCounters); + top.add(live); + + JPanel north = new JPanel(new BorderLayout()); + north.add(top, BorderLayout.CENTER); + mTxtStatus.setEditable(false); + JScrollPane statusScroll = new JScrollPane(mTxtStatus); + statusScroll.setBorder(BorderFactory.createTitledBorder("Event channel status")); + statusScroll.setPreferredSize(new Dimension(320, 100)); + north.add(statusScroll, BorderLayout.EAST); + + // --- Tables + JTabbedPane tabs = new JTabbedPane(); + tabs.addTab("Live records", new JScrollPane(new JTable(mLiveModel))); + + JPanel filePanel = new JPanel(new BorderLayout()); + JPanel fileButtons = new JPanel(new FlowLayout(FlowLayout.LEFT)); + fileButtons.add(button("Open event file...", new ActionListener() { + public void actionPerformed(ActionEvent e) { + openEventFile(); + } + })); + fileButtons.add(new JLabel("events/// on the card, beside data///")); + filePanel.add(fileButtons, BorderLayout.NORTH); + mTxtFile.setEditable(false); + JPanel fileCentre = new JPanel(new BorderLayout()); + fileCentre.add(new JScrollPane(mTxtFile), BorderLayout.NORTH); + fileCentre.add(new JScrollPane(new JTable(mFileModel)), BorderLayout.CENTER); + filePanel.add(fileCentre, BorderLayout.CENTER); + tabs.addTab("Event file", filePanel); + + getContentPane().setLayout(new BorderLayout()); + getContentPane().add(north, BorderLayout.NORTH); + getContentPane().add(tabs, BorderLayout.CENTER); + } + + private static JButton button(String text, ActionListener l) { + JButton b = new JButton(text); + b.addActionListener(l); + return b; + } + + private void warn(String message) { + JOptionPane.showMessageDialog(this, message, "Event markers", JOptionPane.WARNING_MESSAGE); + } + + /** The connected Shimmer3 / Shimmer3R, or null with a message */ + private ShimmerBluetooth shimmer() { + ShimmerDevice device = mHost.getConnectedDevice(); + if(!(device instanceof ShimmerBluetooth)) { + warn("Connect a Shimmer3 or Shimmer3R first."); + return null; + } + ShimmerBluetooth sb = (ShimmerBluetooth) device; + BT_STATE state = sb.getBluetoothRadioState(); + if(state==null || state==BT_STATE.DISCONNECTED || state==BT_STATE.CONNECTION_LOST || state==BT_STATE.CONNECTING) { + warn("The Shimmer is not connected."); + return null; + } + return sb; + } + + private void attach(ShimmerBluetooth sb) { + if(mAttachedTo!=sb) { + detach(); + sb.addEventChannelListener(this); + mAttachedTo = sb; + } + } + + private void detach() { + if(mAttachedTo!=null) { + mAttachedTo.removeEventChannelListener(this); + mAttachedTo = null; + } + } + + /** Re-reads what the driver knows of the connected unit */ + public void refresh() { + ShimmerDevice device = mHost.getConnectedDevice(); + if(!(device instanceof ShimmerBluetooth)) { + mLblSupport.setText("No Shimmer3 / Shimmer3R connected"); + mLblConfig.setText(" "); + return; + } + ShimmerBluetooth sb = (ShimmerBluetooth) device; + attach(sb); + Boolean supported = sb.isEventChannelSupported(); + mLblSupport.setText(sb.getFirmwareVersionParsed() + " - event channel: " + + (supported==null? "not asked yet" : (supported? "yes" : "no"))); + if(sb.isButtonLogModeKnown()) { + int buttonMode = sb.getButtonMode(); + int logTriggers = sb.getLogTriggers(); + if(buttonMode//)"); + if(chooser.showOpenDialog(this)!=JFileChooser.APPROVE_OPTION) { + return; + } + File f = chooser.getSelectedFile(); + EventFile ef; + try { + ef = EventFile.parse(f); + } catch (Exception e) { + warn("Could not read " + f.getName() + ": " + e.getMessage()); + return; + } + File data = companionDataFile(f); + StringBuilder sb = new StringBuilder(); + sb.append(f.getAbsolutePath()).append("\n"); + sb.append("Hardware ID ").append(ef.getHardwareId()) + .append(ef.getHardwareId()==10? " (Shimmer3R)" : ef.getHardwareId()==3? " (Shimmer3)" : "") + .append(", firmware ").append(ef.getFirmwareId()).append(" v").append(ef.getFirmwareMajor()) + .append(".").append(ef.getFirmwareMinor()).append(".").append(ef.getFirmwareInternal()).append("\n"); + sb.append("Opened ").append(ef.getOpenReason()==EventFile.OPEN_REASON_SPLIT? "at an hourly split" : "at the session start") + .append(" at ").append(mUtc.format(new Date(Math.round(ef.getUnixMs(new EventRecord(0, 0, 0, ef.getFileOpenTicks(), 0, 0, 0)))))) + .append(" UTC (file-open ticks 0x").append(Long.toHexString(ef.getFileOpenTicks())).append(")\n"); + sb.append("Records: ").append(ef.getRecords().size()) + .append(", inputs: ").append((ef.getInputs()&EventRecord.INPUT_BUTTON)!=0? "button " : "") + .append((ef.getInputs()&EventRecord.INPUT_TTL)!=0? "TTL" : "") + .append(", ").append(ef.isComplete()? "complete (ends with a final record)" : "NOT complete: no final record, cut short") + .append(ef.getTrailingBytes()>0? ", " + ef.getTrailingBytes() + " trailing bytes" : "").append("\n"); + sb.append("Data file: ").append(data==null? "not found by the card layout" : data.getPath() + (data.exists()? "" : " (not present)")); + mTxtFile.setText(sb.toString()); + + mFileModel.setRowCount(0); + int i = 0; + for(EventRecord r:ef.getRecords()) { + mFileModel.addRow(new Object[] { + i++, + r.getSequenceNumber(), + String.format("%+.6f", r.getSecondsFrom(ef.getFileOpenTicks())), + mUtc.format(new Date(Math.round(ef.getUnixMs(r)))), + r.getDescription(), + flags(r), + state(r), + r.getDropped()}); + } + } + + /** events/X/NNN pairs with data/X/NNN */ + private static File companionDataFile(File eventFile) { + File session = eventFile.getParentFile(); + File experiment = session==null? null : session.getParentFile(); + File eventsRoot = experiment==null? null : experiment.getParentFile(); + if(eventsRoot==null || !"events".equalsIgnoreCase(eventsRoot.getName())) { + return null; + } + return new File(new File(new File(new File(eventsRoot.getParentFile(), "data"), experiment.getName()), session.getName()), eventFile.getName()); + } + +} diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/SensorMapsExample.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/SensorMapsExample.java index a9666ee87..77df9aacb 100644 --- a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/SensorMapsExample.java +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/simpleexamples/SensorMapsExample.java @@ -34,7 +34,14 @@ import com.shimmerresearch.verisense.communication.SyncProgressDetails; import com.shimmerresearch.verisense.communication.VerisenseProtocolByteCommunication; import com.shimmerresearch.bluetooth.ShimmerBluetooth; +import com.shimmerresearch.driver.FormatCluster; +import com.shimmerresearch.driver.shimmer2r3.EventRecord; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; import info.monitorenter.gui.chart.Chart2D; +import info.monitorenter.gui.chart.ITrace2D; +import info.monitorenter.gui.chart.traces.Trace2DLtd; +import info.monitorenter.gui.chart.traces.painters.TracePainterVerticalBar; +import java.awt.Color; import javax.swing.JLabel; import javax.swing.JPanel; @@ -89,6 +96,13 @@ public class SensorMapsExample extends BasicProcessWithCallBack { LoggingPC lpc; JCheckBox chckbxWriteDataToFile; String[] options = {"Shimmer3", "Verisense"}; + + //Event markers (DEV-971) + EventMarkersFrame eventMarkersFrame; + /** The latest data packet's Shimmer clock (unwrapped, ms) and its plot x value (PC time, ms), to place event records on the plot */ + volatile double lastPacketShimmerMs = Double.NaN; + volatile double lastPacketPlotMs = Double.NaN; + ITrace2D eventMarkerTrace; /** * Initialize the contents of the frame * @wbp.parser.entryPoint @@ -296,7 +310,15 @@ public void actionPerformed(ActionEvent e) { } }); mnTools.add(mntmLowPowerMode); - + + JMenuItem mntmEventMarkers = new JMenuItem("Event markers (Shimmer3R)"); + mntmEventMarkers.addActionListener(new ActionListener() { + public void actionPerformed(ActionEvent e) { + openEventMarkers(); + } + }); + mnTools.add(mntmEventMarkers); + JButton btnStartStreaming = new JButton("START STREAMING"); btnStartStreaming.addActionListener(new ActionListener() { public void actionPerformed(ActionEvent arg0) { @@ -506,8 +528,91 @@ public void actionPerformed(ActionEvent e) { }); btnStopSd.setBounds(1075, 181, 107, 31); frame.getContentPane().add(btnStopSd); - - plotManager.setTitle("Plot"); + + JButton btnEventMarkers = new JButton("EVENT MARKERS"); + btnEventMarkers.setToolTipText("Button and TTL event markers (Shimmer3R, LogAndStream v1.01.026 and later)"); + btnEventMarkers.addActionListener(new ActionListener() { + public void actionPerformed(ActionEvent e) { + openEventMarkers(); + } + }); + btnEventMarkers.setBounds(625, 225, 187, 31); + frame.getContentPane().add(btnEventMarkers); + + plotManager.setTitle("Plot"); + } + + /** The connected device, looked up the way the other buttons do */ + ShimmerDevice getConnectedDevice() { + if (btComport==null || btComport.isEmpty()) { + return null; + } + if (btComport.contains(PREFIX_COM) || btComport.contains(PREFIX_DEV)) { + return btManager.getShimmerDeviceBtConnected(btComport); + } + return btManager.getShimmerDeviceBtConnectedFromMac(btComport); + } + + void openEventMarkers() { + if (eventMarkersFrame==null || !eventMarkersFrame.isDisplayable()) { + eventMarkersFrame = new EventMarkersFrame(new EventMarkersFrame.Host() { + @Override + public ShimmerDevice getConnectedDevice() { + return SensorMapsExample.this.getConnectedDevice(); + } + + @Override + public void plotEventRecord(ShimmerBluetooth shimmer, EventRecord record) { + SensorMapsExample.this.plotEventRecord(record); + } + }); + eventMarkersFrame.setLocationRelativeTo(frame); + } + eventMarkersFrame.refresh(); + eventMarkersFrame.setVisible(true); + eventMarkersFrame.toFront(); + } + + /** + * Marks an edge on the plot as a vertical bar. The plot's x axis is PC time, + * so the record's Shimmer clock is placed against the latest data packet's: + * a packet carries the low 24 bits of the same clock, which the driver + * unwraps from wherever the stream began. Called on the Swing thread. + */ + void plotEventRecord(EventRecord record) { + if (!record.isEdge() || Double.isNaN(lastPacketShimmerMs) || Double.isNaN(lastPacketPlotMs)) { + return; // nothing streaming to place it against + } + double packetTicks = lastPacketShimmerMs*EventRecord.TICKS_PER_SECOND/1000.0; + double eventTicks = record.getTicksOnStreamTimeline(packetTicks); + double x = lastPacketPlotMs+(eventTicks-packetTicks)*1000.0/EventRecord.TICKS_PER_SECOND; + + if (eventMarkerTrace==null || !mChart.getTraces().contains(eventMarkerTrace)) { + eventMarkerTrace = new Trace2DLtd(200); + eventMarkerTrace.setName("Event markers"); + eventMarkerTrace.setColor(Color.RED); + eventMarkerTrace.setTracePainter(new TracePainterVerticalBar(mChart)); + mChart.addTrace(eventMarkerTrace); + } + double top = 1; + try { + top = mChart.getAxisY().getMax(); + } catch (Exception e) { + // no range yet + } + eventMarkerTrace.addPoint(x, top); + } + + /** Keeps the latest packet's Shimmer clock and plot x value, for plotEventRecord() */ + void notePacketTimes(ObjectCluster objc) { + FormatCluster shimmerTs = ObjectCluster.returnFormatCluster( + objc.getCollectionOfFormatClusters(Configuration.Shimmer3.ObjectClusterSensorName.TIMESTAMP), CHANNEL_TYPE.CAL.toString()); + FormatCluster plotTs = ObjectCluster.returnFormatCluster( + objc.getCollectionOfFormatClusters(Configuration.Shimmer3.ObjectClusterSensorName.SYSTEM_TIMESTAMP_PLOT), CHANNEL_TYPE.CAL.toString()); + if (shimmerTs!=null && plotTs!=null) { + lastPacketShimmerMs = shimmerTs.mData; + lastPacketPlotMs = plotTs.mData; + } } public static void main(String args[]) { @@ -604,6 +709,9 @@ protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { } textPaneStatus.setText("connected"); updateDeviceSpec(); + if (eventMarkersFrame!=null && eventMarkersFrame.isDisplayable()) { + eventMarkersFrame.refresh(); + } //shimmer = (ShimmerPC) btManager.getShimmerDeviceBtConnected(btComport); // shimmerDevice = btManager.getShimmerDeviceBtConnected(btComport); @@ -667,6 +775,7 @@ protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { } else if (ind == ShimmerPC.MSG_IDENTIFIER_DATA_PACKET) { System.out.println("Shimmer MSG_IDENTIFIER_DATA_PACKET"); ObjectCluster objc = (ObjectCluster) shimmerMSG.mB; + notePacketTimes(objc); if (lpc!=null) { lpc.logData(objc); }