From cb89d5d883a54d0da465c24b793c228b1a8272a6 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Mon, 2 Nov 2026 14:58:17 +0000 Subject: [PATCH 01/10] DEV-971: keep configuration byte 232, and probe for the event channel Byte 232 holds the button mode, the log triggers and the TTL input enable on LogAndStream firmware with the event channel. The full configuration write built its image from zeros, so every configure from Consensys or the Android config dialog put 0 there and turned the button back to legacy. - ButtonLogMode: the byte's fields and the firmware's correction rules (log-and-stream-common shimmer_button_log_mode.c, via the web SDK's buttonLogMode.ts), including press recording and the TTL input taken out on SR48-6-0. - ShimmerObject: the parse keeps the byte as read, 0xFF included, and the generator writes it back (corrected where it can be trusted). Before packing bytes 217 and 218 it holds userButtonEnable at the button mode's nearest equivalent and clears singleTouchStart where no press can start logging, as the firmware does. Getters and setters for the three fields, and config labels for them. - The byte is trusted only when the Shimmer ACKed the probe, or the value read is one the firmware keeps: firmware without it leaves 0xFF, and the dock cannot probe. - ShimmerVerObject.isSupportedSetFeature(): SET_FEATURE arrived with log-and-stream-common, in LogAndStream_Shimmer3R v1.0.52 and LogAndStream_Shimmer3 v1.0.20. Older firmware discards 0xB7 and runs the two bytes after it as commands (03 is GET_SAMPLING_RATE, which is ACKed), so it is never sent there. The layout places byte 232 from those releases on; the event channel's builds report the release before them, so the version cannot say more. - ShimmerBluetooth.readEventChannelSupport(): SET_FEATURE with FEATURE_EVENT_STREAM and 0, sent on connect. ACK means the event channel is there; the NACK is handled without dropping the link, and still counts towards the operation's progress. - writeConfigBytes(): when the byte was never read nor set, as when a configuration is written on connect before the read, the chunk at 128 is sent either side of byte 232, so the Shimmer keeps its own. Not benched. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 123 ++++++- .../shimmerresearch/driver/Configuration.java | 6 + .../shimmerresearch/driver/ShimmerObject.java | 191 ++++++++++ .../driver/shimmer2r3/ButtonLogMode.java | 283 +++++++++++++++ .../shimmer2r3/ConfigByteLayoutShimmer3.java | 13 + .../driverUtilities/ShimmerVerObject.java | 18 + .../driver/API_00036_ButtonLogModeTest.java | 209 +++++++++++ ...PI_00037_ButtonLogModeConfigWriteTest.java | 332 ++++++++++++++++++ .../API_00038_EventChannelProbeTest.java | 226 ++++++++++++ 9 files changed, 1396 insertions(+), 5 deletions(-) create mode 100644 ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java create mode 100644 ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index d23354449..d0fffc9ab 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -106,6 +106,7 @@ import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; 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.ShimmerObject; import com.shimmerresearch.driverUtilities.AssembleShimmerConfig; import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; @@ -305,9 +306,13 @@ public int getNumCrcBytes() { */ private static final byte[] BARE_ACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {ACK_COMMAND_PROCESSED}, 1); + /** SET_FEATURE's feature ids, by ordinal */ public enum SHIMMER_FEATURE { NONE, RN4678_ERROR_DETECTION, + REBOOT_ON_DISCONNECT, + /** The event channel's records, sent to a host that opts in (DEV-971). Firmware without the event channel NACKs it. */ + EVENT_STREAM, } public static final Map mBtCommandMapOther; @@ -933,6 +938,12 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } + /* Firmware without the event channel NACKs its probe. Without + * this the NACK was discarded and the ACK timer then dropped the + * connection. Other NACKs are left as they were. */ + else if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED && isEventChannelProbeInFlight()) { + processEventChannelProbeNack(); + } } } } @@ -2533,7 +2544,10 @@ else if(currentCommand==SET_TEST){ InShimmerTest = true; } else if (currentCommand == SET_FEATURE) { - // TODO: do something? + if(isEventChannelProbeInFlight()) { + // Only firmware with the event channel ACKs FEATURE_EVENT_STREAM + setEventChannelSupported(true); + } } else { //unhandled set command @@ -2877,6 +2891,10 @@ private void initializeShimmer3or3R(int hardwareVersion){ writeSetFeatureCommand(SHIMMER_FEATURE.RN4678_ERROR_DETECTION.ordinal(), 1); } + // The firmware may have changed since the last connection + setEventChannelSupported(null); + readEventChannelSupport(); + if (isSetupDeviceWhileConnecting()){ if(mFixedShimmerConfigMode!=null && mFixedShimmerConfigMode!=FIXED_SHIMMER_CONFIG_MODE.NONE){ boolean triggerConfig = setFixedConfigWhenConnecting(); @@ -4901,7 +4919,20 @@ public void writeConfigBytes(){ public void writeConfigBytes(boolean readBackAfter){ if(this.getFirmwareVersionCode()>=6){ - writeConfigBytes(mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, generateConfigBytesForWritingToShimmer(), mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, readBackAfter); + byte[] configBytes = generateConfigBytesForWritingToShimmer(); + int idxButtonLogMode = (mConfigByteLayout instanceof ConfigByteLayoutShimmer3) ? ((ConfigByteLayoutShimmer3) mConfigByteLayout).idxButtonLogMode : 0; + if(idxButtonLogMode>0 && !isButtonLogModeKnown()){ + // Byte 232 (DEV-971) was never read from this Shimmer nor set, + // as when a configuration is written on connect before it is + // read. Skip it, so that the Shimmer keeps its own. + writeMem(SET_INFOMEM_COMMAND, mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, idxButtonLogMode); + if(readBackAfter){ + readConfigBytes(); + } + } + else { + writeConfigBytes(mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, readBackAfter); + } } } @@ -4922,6 +4953,19 @@ public void writeConfigBytes(int startAddress, byte[] buf, int maxMemAddress, bo } public void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress){ + writeMem(command, startAddress, buf, maxMemAddress, -1); + } + + /** + * Writes buf in chunks of up to 128 bytes, as {@link #writeMem(int, int, byte[], int)} + * does, but leaves out the byte at skipIndex: the chunk holding it goes as + * the bytes before it and the bytes after it. Every other chunk starts + * where it would have, which matters to the firmware for the chunks at 0 + * and 128. + * + * @param skipIndex the index into buf of the byte not to write, or -1 to write them all + */ + private void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress, int skipIndex){ this.mNumOfMemSetCmds = 0; if(this.getFirmwareVersionCode()>=6){ @@ -4945,10 +4989,23 @@ public void writeMem(int command, int startAddress, byte[] buf, int maxMemAddres currentPacketNumBytes = numBytesRemaining; } - byte[] infoSegBuf = Arrays.copyOfRange(buf, currentBytePointer, currentBytePointer + currentPacketNumBytes); + int chunkEnd = currentBytePointer + currentPacketNumBytes; + if(skipIndex>=currentBytePointer && skipIndexcurrentBytePointer){ + writeMemCommand(command, currentStartAddr, Arrays.copyOfRange(buf, currentBytePointer, skipIndex)); + mNumOfMemSetCmds += 1; + } + if(skipIndex+1 + * Firmware older than SET_FEATURE is not asked, and has no event channel. + * Nor is a Shimmer that is streaming, where a NACK is not yet handled. + */ + public void readEventChannelSupport() { + if(!getShimmerVerObject().isSupportedSetFeature()) { + setEventChannelSupported(false); + } + else if(!isStreaming()) { + writeSetFeatureCommand(SHIMMER_FEATURE.EVENT_STREAM.ordinal(), 0); + } + } + + /** Whether the command awaiting its ACK is SET_FEATURE for FEATURE_EVENT_STREAM, which tells whether the event channel is there */ + private boolean isEventChannelProbeInFlight() { + if(mCurrentCommand!=SET_FEATURE) { + return false; + } + List instructions = getListofInstructions(); + if(instructions.isEmpty()) { + return false; + } + byte[] instruction = instructions.get(0); + return instruction!=null && instruction.length>1 + && instruction[0]==SET_FEATURE + && instruction[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal(); + } + + /** + * The firmware NACKed FEATURE_EVENT_STREAM, so it has no event channel. + * Completes the command as an ACK does, the progress report included, so + * that the connection stays up and the operation it is part of finishes. + */ + private void processEventChannelProbeNack() { + stopTimerCheckForAckOrResp(); //cancel the ack timer + mWaitForAck=false; + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand) + ", no event channel"); + + setEventChannelSupported(false); + + if(mOperationUnderway){ + sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, getComPort())); + } + removeInstruction(0); + + mTransactionCompleted = true; + setInstructionStackLock(false); + } + //endregion --------- READ/WRITE FUNCTIONS --------- diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java index bf813e203..ba89b5a06 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java @@ -902,6 +902,12 @@ public class GuiLabelConfig{ public static final String ENABLE_ERROR_LEDS_RTC = "RTC Error LEDs"; public static final String ENABLE_ERROR_LEDS_SD = "SD Error LEDs"; public static final String LOW_POWER_AUTOSTOP = "Low-power Autostop"; + /** Configuration byte 232 bits 0-2 (DEV-971), an Integer, see ButtonLogMode.BUTTON_MODE_* */ + public static final String BUTTON_MODE = "Button Mode"; + /** Configuration byte 232 bits 3-4 (DEV-971), an Integer, see ButtonLogMode.LOG_TRIGGERS_* */ + public static final String LOG_TRIGGERS = "Log Triggers"; + /** Configuration byte 232 bit 5 (DEV-971), a Boolean */ + public static final String TTL_INPUT = "TTL Input"; public static final String KINEMATIC_LPM = "Kinematic Sensors Low-Power Mode";//XXX-RS-LSM-SensorClass? What about HighResolutionMode?! public static final String CALIBRATION_ALL = AbstractSensor.GuiLabelConfigCommon.CALIBRATION_ALL; diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 2679bc312..ecaca1026 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -36,6 +36,7 @@ import com.shimmerresearch.driver.calibration.UtilCalibration; import com.shimmerresearch.driver.calibration.CalibDetails.CALIB_READ_SOURCE; import com.shimmerresearch.driver.shimmer2r3.BluetoothModuleVersionDetails; +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; import com.shimmerresearch.driver.shimmerGq.ConfigByteLayoutShimmerGq802154; import com.shimmerresearch.driverUtilities.ChannelDetails; @@ -460,6 +461,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; @@ -575,6 +577,13 @@ public String toString() { private int mShowErrorLedsSd = 0; private boolean mLowBattAutoStop = false; + /** Configuration byte 232 as read from the Shimmer or set by the host (DEV-971), see {@link ButtonLogMode} */ + private int mButtonLogMode = 0; + /** Whether mButtonLogMode is the Shimmer's own: read from it, or set by the host */ + private boolean mIsButtonLogModeKnown = false; + /** The Shimmer's answer to the event channel probe (SET_FEATURE): null until it has answered */ + private Boolean mIsEventChannelSupported = null; + protected int mTrialId = 0; protected int mTrialNumberOfShimmers = 0; protected int mTrialDurationEstimatedInSecs = 0; @@ -4977,6 +4986,10 @@ public void setDefaultShimmerConfiguration() { setButtonStart(true); setShowErrorLedsRtc(true); setShowErrorLedsSd(true); + // Byte 232's own default, legacy. Whether it is the Shimmer's is + // left as it was: a default the Shimmer was never read for is not + // written to it over Bluetooth. + mButtonLogMode = 0; setBluetoothBaudRate(9); //460800 @@ -5160,6 +5173,13 @@ public void configBytesParse(byte[] configBytes, COMMUNICATION_TYPE commType) { if(isVerCompatibleWithAnyOf(Configuration.Shimmer3.configOptionLowPowerAutoStop.mListOfCompatibleVersionInfo)) { setLowBattAutoStop((configBytes[configByteLayoutCast.idxSDExperimentConfig1] >> configByteLayoutCast.bitShiftLowBattStop) & configByteLayoutCast.maskLowBattStop); } + + // Kept as read, 0xFF included, so that a full configuration + // write gives the Shimmer back its own byte + if(configByteLayoutCast.idxButtonLogMode>0 && configBytes.length>configByteLayoutCast.idxButtonLogMode) { + mButtonLogMode = configBytes[configByteLayoutCast.idxButtonLogMode] & 0xFF; + mIsButtonLogModeKnown = true; + } byte[] macIdBytes = new byte[configByteLayoutCast.lengthMacIdBytes]; System.arraycopy(configBytes, configByteLayoutCast.idxMacAddress, macIdBytes, 0 , configByteLayoutCast.lengthMacIdBytes); @@ -5376,6 +5396,15 @@ public byte[] configBytesGenerate(boolean generateForWritingToShimmer, COMMUNICA mConfigBytes[configByteLayoutCast.idxSDNumOfShimmers] = (byte) (mTrialNumberOfShimmers & 0xFF); } + + // Byte 232 (DEV-971). The image starts from zeros, so without + // this a full write turned the button mode back to legacy. The + // rules go first: they hold userButtonEnable and singleTouchStart, + // packed into bytes 217 and 218 below, as the firmware will. + if(configByteLayoutCast.idxButtonLogMode>0) { + applyButtonLogModeRules(); + mConfigBytes[configByteLayoutCast.idxButtonLogMode] = (byte) getButtonLogModeToWrite(); + } if(getFirmwareIdentifier()==FW_ID.SDLOG || getFirmwareIdentifier()==FW_ID.LOGANDSTREAM || getFirmwareIdentifier()==FW_ID.STROKARE) { mConfigBytes[configByteLayoutCast.idxSDExperimentConfig0] = (byte) ((mButtonStart & configByteLayoutCast.maskButtonStart) << configByteLayoutCast.bitShiftButtonStart); @@ -6616,6 +6645,150 @@ public void setDisableBluetooth(boolean state) { public void setButtonStart(int state) { this.mButtonStart = state; } + + /** + * Configuration byte 232 (DEV-971) as the driver holds it: as read from the + * Shimmer, 0xFF included, or as set. {@link #getButtonLogModeCorrected()} + * is what the firmware acts on. + */ + public int getButtonLogMode() { + return mButtonLogMode; + } + + /** + * Sets configuration byte 232 (DEV-971) whole. The firmware corrects a + * value it cannot act on to 0 (see {@link ButtonLogMode#correct(int)}). + * Like the field setters, it holds userButtonEnable and singleTouchStart + * where the button mode decides them. + */ + public void setButtonLogMode(int value) { + mButtonLogMode = value & 0xFF; + mIsButtonLogModeKnown = true; + applyButtonLogModeRules(); + } + + /** + * Sets the three fields of configuration byte 232 (DEV-971) at once. + * + * @param buttonMode one of ButtonLogMode.BUTTON_MODE_* + * @param logTriggers one of ButtonLogMode.LOG_TRIGGERS_*, read only when buttonMode is not legacy + * @param ttlInputEnabled whether the TTL input's edges are recorded + */ + public void setButtonLogMode(int buttonMode, int logTriggers, boolean ttlInputEnabled) { + setButtonLogMode(ButtonLogMode.compose(0, buttonMode, logTriggers, ttlInputEnabled)); + } + + /** What the user button does: one of ButtonLogMode.BUTTON_MODE_*, as the firmware will act on it */ + public int getButtonMode() { + return getButtonLogModeCorrected() & ButtonLogMode.MASK_BUTTON_MODE; + } + + /** + * Sets what the user button does (byte 232 bits 0-2). The other two fields + * keep the values last set, so they can be set in any order. Not + * BUTTON_MODE_LEGACY, it holds userButtonEnable at the mode's nearest + * equivalent and clears singleTouchStart where no press can start logging, + * as the firmware does. + * + * @param buttonMode one of ButtonLogMode.BUTTON_MODE_* + */ + public void setButtonMode(int buttonMode) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, buttonMode, ButtonLogMode.getRawLogTriggers(mButtonLogMode), ButtonLogMode.isRawTtlInputEnabled(mButtonLogMode))); + } + + /** + * What else starts SD logging: one of ButtonLogMode.LOG_TRIGGERS_*, as the + * firmware will act on it. Always LOG_TRIGGERS_HOST while the button mode + * is legacy, which does not read them. + */ + public int getLogTriggers() { + return (getButtonLogModeCorrected() & ButtonLogMode.MASK_LOG_TRIGGERS) >> ButtonLogMode.BIT_SHIFT_LOG_TRIGGERS; + } + + /** + * Sets what else starts SD logging (byte 232 bits 3-4). Read only when the + * button mode is not legacy, but kept for when it is set. + * + * @param logTriggers one of ButtonLogMode.LOG_TRIGGERS_* + */ + public void setLogTriggers(int logTriggers) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, ButtonLogMode.getRawButtonMode(mButtonLogMode), logTriggers, ButtonLogMode.isRawTtlInputEnabled(mButtonLogMode))); + } + + /** Whether the TTL input's edges are recorded, as the firmware will act on it */ + public boolean isTtlInputEnabled() { + return (getButtonLogModeCorrected() & ButtonLogMode.MASK_TTL_INPUT)!=0; + } + + /** Sets whether the TTL input's edges are recorded (byte 232 bit 5), whatever the button mode */ + public void setTtlInputEnabled(boolean ttlInputEnabled) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, ButtonLogMode.getRawButtonMode(mButtonLogMode), ButtonLogMode.getRawLogTriggers(mButtonLogMode), ttlInputEnabled)); + } + + /** + * Whether the driver has the Shimmer's own byte 232: read from it, or set + * here. When it has neither, a full configuration write over Bluetooth + * leaves the Shimmer's byte as it is. + */ + public boolean isButtonLogModeKnown() { + return mIsButtonLogModeKnown; + } + + /** + * Whether byte 232 can be taken at its word: the Shimmer answered the event + * channel probe, or the byte holds a value the firmware keeps. Firmware + * without the byte leaves it 0xFF, which is not one, and the dock cannot + * probe. + */ + public boolean isButtonLogModeMeaningful() { + return (mIsEventChannelSupported!=null && mIsEventChannelSupported) || ButtonLogMode.isValid(mButtonLogMode); + } + + /** + * Byte 232 as this Shimmer's firmware will act on it, corrected for its + * board; 0, legacy, where the byte cannot be taken at its word + * ({@link #isButtonLogModeMeaningful()}). + */ + public int getButtonLogModeCorrected() { + if(!isButtonLogModeMeaningful()) { + return 0; + } + return ButtonLogMode.correctForBoard(mButtonLogMode, getHardwareVersion(), getExpansionBoardDetails()); + } + + /** The byte a full configuration write puts at 232: corrected where meaningful, otherwise as read */ + protected int getButtonLogModeToWrite() { + return isButtonLogModeMeaningful() ? getButtonLogModeCorrected() : mButtonLogMode; + } + + /** + * Holds userButtonEnable (byte 217 bit 5) at byte 232's button mode's + * nearest equivalent, and clears singleTouchStart (byte 218 bit 7) where no + * press can start logging, as the firmware does when it takes a + * configuration (ShimConfig_checkAndCorrectConfig). Byte 232 in the legacy + * mode changes neither. + */ + protected void applyButtonLogModeRules() { + int value = getButtonLogModeCorrected(); + if(!ButtonLogMode.isSingleTouchAllowed(value)) { + setSingleTouch(false); + } + setButtonStart(ButtonLogMode.getNearestUserButtonEnable(value, isButtonStart())); + } + + /** + * The Shimmer's answer to the event channel probe (DEV-971): true if it + * ACKed SET_FEATURE's FEATURE_EVENT_STREAM, false if it NACKed it or its + * firmware is older than SET_FEATURE, null until asked. Not version-based: + * the event channel's builds report the release before them. + */ + public Boolean isEventChannelSupported() { + return mIsEventChannelSupported; + } + + protected void setEventChannelSupported(Boolean isEventChannelSupported) { + mIsEventChannelSupported = isEventChannelSupported; + } protected void setDisableBluetooth(int state) { this.mDisableBluetooth = state; @@ -9716,6 +9889,15 @@ public Object getConfigValueUsingConfigLabel(String identifier, String configLab case(Configuration.Shimmer3.GuiLabelConfig.EXPERIMENT_SYNC_WHEN_LOGGING): returnValue = isSyncWhenLogging(); break; + case(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE): + returnValue = getButtonMode(); + break; + case(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS): + returnValue = getLogTriggers(); + break; + case(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT): + returnValue = isTtlInputEnabled(); + break; case(Configuration.Shimmer3.GuiLabelConfig.KINEMATIC_LPM): if(isLSM303DigitalAccelLPM()&&checkLowPowerGyro()&&checkLowPowerMag()) { @@ -9886,6 +10068,15 @@ public Object setConfigValueUsingConfigLabel(String identifier, String configLab setDisableBluetooth(!(boolean)valueToSet); setSyncWhenLogging((boolean)valueToSet); break; + case(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE): + setButtonMode((int)valueToSet); + break; + case(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS): + setLogTriggers((int)valueToSet); + break; + case(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT): + setTtlInputEnabled((boolean)valueToSet); + break; case(Configuration.Shimmer3.GuiLabelConfig.KINEMATIC_LPM): setLowPowerAccelWR((boolean)valueToSet); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java new file mode 100644 index 000000000..53c8f14aa --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java @@ -0,0 +1,283 @@ +package com.shimmerresearch.driver.shimmer2r3; + +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID_SR_CODES; + +/** + * Configuration byte 232 (NV_BUTTON_LOG_MODE) on a Shimmer3 or Shimmer3R + * running LogAndStream with the event channel (DEV-971): what the user button + * does, what else may start SD logging, and whether the TTL input is recorded. + * + *
+ *    bits 0-2  button mode   BUTTON_MODE_*
+ *    bits 3-4  log triggers  LOG_TRIGGERS_*, read only when the button mode is not legacy
+ *    bit 5     TTL input recorded, whatever the button mode
+ *    bit 6     unused, cleared
+ *    bit 7     must be 0
+ * 
+ * + * 0 means "as before": userButtonEnable (byte 217 bit 5) decides both what a + * press does and whether leaving the dock starts logging. Anything the + * firmware cannot act on reads as 0 too: bit 7 set (erased memory, and + * firmware before the byte, is 0xFF), a reserved value, or log triggers under + * the legacy button mode. + * + * A port of log-and-stream-common Configuration/shimmer_button_log_mode.c, + * through the web SDK's devices/events/buttonLogMode.ts, kept rule for rule so + * the driver reads every one of the 256 values as the firmware does. The table + * and the reasons behind each rule are in log-and-stream-common + * docs/SHIMMER3_CONFIGURATION_INFOMEM.md section 8.3. + * + * @author Mark Nolan + */ +public class ButtonLogMode { + + /** Offset of the byte in the configuration bytes (128 + 104) */ + public static final int CONFIG_BYTE_INDEX = 232; + + public static final int MASK_BUTTON_MODE = 0x07; + public static final int BIT_SHIFT_LOG_TRIGGERS = 3; + public static final int MASK_LOG_TRIGGERS = 0x18; + public static final int MASK_TTL_INPUT = 0x20; + public static final int MASK_INVALID = 0x80; + + /** userButtonEnable decides, as before the byte existed */ + public static final int BUTTON_MODE_LEGACY = 0; + /** A press does nothing, and the LED shows nothing while it is held */ + public static final int BUTTON_MODE_DISABLED = 1; + /** A press starts and stops logging */ + public static final int BUTTON_MODE_SINGLE_PRESS = 2; + /** A double press starts and stops logging */ + public static final int BUTTON_MODE_DOUBLE_PRESS = 3; + /** A double press starts and stops logging, and every press and release is recorded */ + public static final int BUTTON_MODE_DOUBLE_PRESS_RECORDED = 4; + /** Every press and release is recorded, and a press never starts or stops logging */ + public static final int BUTTON_MODE_RECORDED = 5; + + /** A host command only */ + public static final int LOG_TRIGGERS_HOST = 0; + /** A host command, or leaving the dock (on Shimmer3R, unplugging USB-C) */ + public static final int LOG_TRIGGERS_HOST_OR_UNDOCK = 1; + /** Nothing: SD logging is off */ + public static final int LOG_TRIGGERS_NONE = 2; + + private static boolean isButtonModeBuilt(int buttonMode) { + return buttonMode>=BUTTON_MODE_DISABLED && buttonMode<=BUTTON_MODE_RECORDED; + } + + private static boolean canPressStartLogging(int buttonMode) { + return buttonMode==BUTTON_MODE_SINGLE_PRESS + || buttonMode==BUTTON_MODE_DOUBLE_PRESS + || buttonMode==BUTTON_MODE_DOUBLE_PRESS_RECORDED; + } + + /** + * The byte the firmware acts on, and writes back after a configuration + * write: raw itself when it is valid, 0 when bit 7 is set, and otherwise the + * button mode and log triggers cleared when either is not valid (a legacy + * byte's log triggers are not read, so they are cleared too). Bit 5 stands on + * its own unless bit 7 is set. Bit 6 is cleared. + */ + public static int correct(int raw) { + int value = raw & 0xFF; + if((value & MASK_INVALID)!=0){ + return 0; + } + int buttonMode = value & MASK_BUTTON_MODE; + int logTriggers = (value & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + int ttlInput = value & MASK_TTL_INPUT; + if(!isButtonModeBuilt(buttonMode) || logTriggers>LOG_TRIGGERS_NONE){ + return ttlInput; + } + return value & (MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + } + + /** Whether the firmware keeps the value as it is */ + public static boolean isValid(int raw) { + return correct(raw)==(raw & 0xFF); + } + + /** The button mode the firmware acts on (bits 0-2 of the corrected byte) */ + public static int getButtonMode(int raw) { + return correct(raw) & MASK_BUTTON_MODE; + } + + /** The log triggers the firmware acts on: 0 whenever the button mode is legacy */ + public static int getLogTriggers(int raw) { + return (correct(raw) & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + } + + /** Whether the TTL input's edges are recorded */ + public static boolean isTtlInputEnabled(int raw) { + return (correct(raw) & MASK_TTL_INPUT)!=0; + } + + /** Whether every press and release goes to the event channel (modes 4 and 5) */ + public static boolean isRecordingButtonPresses(int raw) { + int buttonMode = getButtonMode(raw); + return buttonMode==BUTTON_MODE_DOUBLE_PRESS_RECORDED || buttonMode==BUTTON_MODE_RECORDED; + } + + /** Whether SD logging is off: log triggers 2, which only a non-legacy mode reads */ + public static boolean isLoggingDisabled(int raw) { + return getLogTriggers(raw)==LOG_TRIGGERS_NONE; + } + + /** + * Whether a press (or, in the double-press modes, a double press) starts + * and stops logging. Logging off wins over a mode whose press would: the + * LED still shows the press, and nothing starts. + */ + public static boolean isPressStartingLogging(int raw, boolean userButtonEnable) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return userButtonEnable; + } + return canPressStartLogging(buttonMode) && !isLoggingDisabled(raw); + } + + /** + * Whether leaving the dock, or on Shimmer3R unplugging USB-C, starts + * logging. Never with single touch, where the sync centre's press starts + * every node. + */ + public static boolean isUndockStartingLogging(int raw, boolean userButtonEnable, boolean singleTouchStart) { + if(singleTouchStart){ + return false; + } + if(getButtonMode(raw)==BUTTON_MODE_LEGACY){ + return !userButtonEnable; + } + return getLogTriggers(raw)==LOG_TRIGGERS_HOST_OR_UNDOCK; + } + + /** + * The userButtonEnable the firmware holds byte 217 at for this byte, so a + * host or firmware that knows only byte 217 never falls back to an undock + * start. False only where a press cannot start logging and leaving the dock + * does; otherwise true. A legacy byte leaves userButtonEnable as it is. + */ + public static boolean getNearestUserButtonEnable(int raw, boolean userButtonEnable) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return userButtonEnable; + } + return !(!canPressStartLogging(buttonMode) && getLogTriggers(raw)==LOG_TRIGGERS_HOST_OR_UNDOCK); + } + + /** + * Whether single touch can work: it needs a press that can start logging. + * The firmware clears singleTouchStart when this is false. + */ + public static boolean isSingleTouchAllowed(int raw) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return true; + } + return canPressStartLogging(buttonMode) && !isLoggingDisabled(raw); + } + + /** + * The corrected byte with press recording taken out, as the firmware does + * on a board with no button edges to record (SR48-6-0): a recorded double + * press becomes a plain double press, and recording alone becomes disabled. + */ + public static int withoutPressRecording(int raw) { + int fixed = correct(raw); + int rest = fixed & ~MASK_BUTTON_MODE & 0xFF; + switch(fixed & MASK_BUTTON_MODE){ + case BUTTON_MODE_DOUBLE_PRESS_RECORDED: + return rest | BUTTON_MODE_DOUBLE_PRESS; + case BUTTON_MODE_RECORDED: + return rest | BUTTON_MODE_DISABLED; + default: + return fixed; + } + } + + /** + * The byte for a set of settings, corrected the way the firmware will + * correct it, so what a host writes is what it reads back. A legacy button + * mode drops the log triggers, and an out-of-range value makes the button + * mode and log triggers read as legacy while the TTL bit stands. + */ + public static int encode(int buttonMode, int logTriggers, boolean ttlInputEnabled) { + return correct(compose(0, buttonMode, logTriggers, ttlInputEnabled)); + } + + /** + * The byte with its three fields replaced, before correction, so fields can + * be set one at a time in any order: log triggers set while the button mode + * is still legacy survive until the mode is set. Bits 6 and 7 come out + * clear; an out-of-range button mode or log triggers leaves that field 0. + */ + public static int compose(int raw, int buttonMode, int logTriggers, boolean ttlInputEnabled) { + int value = (raw & MASK_INVALID)!=0 ? 0 : raw & (MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + value &= ~(MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + if(buttonMode>=0 && buttonMode<=MASK_BUTTON_MODE){ + value |= buttonMode; + } + if(logTriggers>=0 && logTriggers<=(MASK_LOG_TRIGGERS >> BIT_SHIFT_LOG_TRIGGERS)){ + value |= logTriggers << BIT_SHIFT_LOG_TRIGGERS; + } + if(ttlInputEnabled){ + value |= MASK_TTL_INPUT; + } + return value; + } + + /** The raw fields of a byte, bit 7 making all of them 0, as a setter starts from them */ + public static int getRawButtonMode(int raw) { + return (raw & MASK_INVALID)!=0 ? 0 : raw & MASK_BUTTON_MODE; + } + + public static int getRawLogTriggers(int raw) { + return (raw & MASK_INVALID)!=0 ? 0 : (raw & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + } + + public static boolean isRawTtlInputEnabled(int raw) { + return (raw & MASK_INVALID)==0 && (raw & MASK_TTL_INPUT)!=0; + } + + /** + * Whether a board's button edges reach the firmware. Not on SR48-6-0, a + * Shimmer3R whose button is wired to BOOT0, whose interrupt is used for dock + * detection (ShimBrd_isBoardSr48_6_0, log-and-stream-common + * Boards/shimmer_boards.c). A board whose identity is unknown gets it. + */ + public static boolean isButtonEdgeRecordingSupported(int hardwareVersion, ExpansionBoardDetails board) { + return !isSr48_6_0(hardwareVersion, board); + } + + /** Whether a board has the TTL input. Not on SR48-6-0 (ShimBrd_isTtlInputSupported). */ + public static boolean isTtlInputSupported(int hardwareVersion, ExpansionBoardDetails board) { + return !isSr48_6_0(hardwareVersion, board); + } + + private static boolean isSr48_6_0(int hardwareVersion, ExpansionBoardDetails board) { + return hardwareVersion==HW_ID.SHIMMER_3R + && board!=null + && board.getExpansionBoardId()==HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED + && board.getExpansionBoardRev()==6 + && board.getExpansionBoardRevSpecial()==0; + } + + /** + * The byte the firmware keeps on a board: corrected, with press recording + * and the TTL input taken out where the board has neither + * (ShimConfig_checkAndCorrectConfig, log-and-stream-common + * Configuration/shimmer_config.c). + */ + public static int correctForBoard(int raw, int hardwareVersion, ExpansionBoardDetails board) { + int value = correct(raw); + if(!isButtonEdgeRecordingSupported(hardwareVersion, board)){ + value = withoutPressRecording(value); + } + if(!isTtlInputSupported(hardwareVersion, board)){ + value &= ~MASK_TTL_INPUT & 0xFF; + } + return value; + } + +} 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..ee647dd0c 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java @@ -105,6 +105,8 @@ public class ConfigByteLayoutShimmer3 extends ConfigByteLayout implements Serial public int idxMacAddress = 128+96; // 6bytes public int idxSDConfigDelayFlag = 128+102; public int idxBtFactoryReset = 0; + /** Button mode, log triggers and TTL input (DEV-971), see {@link ButtonLogMode}. 0 where the firmware cannot have it. */ + public int idxButtonLogMode = 0; public int idxNode0 = 128+128+0; @@ -400,6 +402,14 @@ public ConfigByteLayoutShimmer3(int firmwareIdentifier, int firmwareVersionMajor idxBtFactoryReset = 128+103; } + // The event channel's builds report the release before them, so only + // the earliest firmware that can carry it is known from the version. + // Whether it is really there is the SET_FEATURE probe's answer + // (ShimmerBluetooth.readEventChannelSupport()) or a valid byte read back. + if(mShimmerVerObject.isSupportedSetFeature()) { + idxButtonLogMode = ButtonLogMode.CONFIG_BYTE_INDEX; + } + // if(mShimmerVerObject.isVerCompatibleWithAnyOf(Configuration.Shimmer3.configOptionLowPowerAutoStop.mListOfCompatibleVersionInfo)) { // maskLowBattStop = 0; // bitShiftLowBattStop = 0; @@ -541,6 +551,9 @@ public HashMap getMapOfByteDescriptions(){ if(idxBtFactoryReset>0){ mapOfByteDescriptions.put(idxBtFactoryReset, "idxBtFactoryReset"); } + if(idxButtonLogMode>0){ + mapOfByteDescriptions.put(idxButtonLogMode, "idxButtonLogMode"); + } mapOfByteDescriptions.put(idxNode0, "Node0"); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java index 05c046afd..c8db3ba62 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java @@ -748,4 +748,22 @@ public boolean isSupportedBtBatteryRequest() { || compareVersions(HW_ID.SHIMMER_3, FW_ID.BTSTREAM, 0, 8, 1)); } + /** + * Whether the firmware has SET_FEATURE (0xB7), with its feature id and + * value, and NACKs a feature id it does not know. It came with + * log-and-stream-common: LogAndStream_Shimmer3R v1.0.52 and + * LogAndStream_Shimmer3 v1.0.20. Older firmware discards the 0xB7 byte + * unanswered and takes the two bytes after it as commands, so a feature id + * of 3 there is GET_SAMPLING_RATE_COMMAND, which is ACKed. SET_FEATURE must + * not be sent to it. + *

+ * This is also the earliest firmware whose builds can carry the DEV-971 + * event channel and configuration byte 232: those builds report the release + * before them, so the version alone cannot say whether they do. + */ + public boolean isSupportedSetFeature() { + return compareVersions(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 52) + || compareVersions(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 20); + } + } diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java new file mode 100644 index 000000000..ec895edf9 --- /dev/null +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java @@ -0,0 +1,209 @@ +package com.shimmerresearch.driver; + +import static org.junit.Assert.*; + +import java.util.Set; +import java.util.TreeSet; + +import org.junit.Test; + +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID_SR_CODES; + +/** + * DEV-971: configuration byte 232, the button mode, log triggers and TTL + * input. The driver has to read every value as the firmware does + * (log-and-stream-common Configuration/shimmer_button_log_mode.c), so the + * cases below are the table in that repo's + * docs/SHIMMER3_CONFIGURATION_INFOMEM.md section 8.3, row for row: the 16 + * values the firmware keeps, what a press does, what starts logging, and the + * userButtonEnable the firmware holds byte 217 at. + * + * @author Mark Nolan + */ +public class API_00036_ButtonLogModeTest { + + /** What a press does, in the table's words */ + private enum PRESS { + /** As userButtonEnable says: the legacy mode */ + LEGACY, + NOTHING, + /** Nothing starts, but the LED shows the press: logging is off */ + LED_ONLY, + STARTS_STOPS, + DOUBLE_STARTS_STOPS, + } + + /** One row of the table */ + private static class Row { + final int value; + final PRESS press; + final boolean recorded; + final boolean undockStarts; + final boolean loggingOff; + /** null: unchanged, the legacy mode */ + final Boolean userButtonEnableHeldAt; + + Row(int value, PRESS press, boolean recorded, boolean undockStarts, boolean loggingOff, Boolean userButtonEnableHeldAt) { + this.value = value; + this.press = press; + this.recorded = recorded; + this.undockStarts = undockStarts; + this.loggingOff = loggingOff; + this.userButtonEnableHeldAt = userButtonEnableHeldAt; + } + } + + private static final Row[] TABLE = { + new Row(0x00, PRESS.LEGACY, false, false, false, null), + new Row(0x01, PRESS.NOTHING, false, false, false, true), + new Row(0x09, PRESS.NOTHING, false, true, false, false), + new Row(0x11, PRESS.NOTHING, false, false, true, true), + new Row(0x02, PRESS.STARTS_STOPS, false, false, false, true), + new Row(0x0A, PRESS.STARTS_STOPS, false, true, false, true), + new Row(0x12, PRESS.LED_ONLY, false, false, true, true), + new Row(0x03, PRESS.DOUBLE_STARTS_STOPS, false, false, false, true), + new Row(0x0B, PRESS.DOUBLE_STARTS_STOPS, false, true, false, true), + new Row(0x13, PRESS.LED_ONLY, false, false, true, true), + new Row(0x04, PRESS.DOUBLE_STARTS_STOPS, true, false, false, true), + new Row(0x0C, PRESS.DOUBLE_STARTS_STOPS, true, true, false, true), + new Row(0x14, PRESS.NOTHING, true, false, true, true), + new Row(0x05, PRESS.NOTHING, true, false, false, true), + new Row(0x0D, PRESS.NOTHING, true, true, false, false), + new Row(0x15, PRESS.NOTHING, true, false, true, true), + }; + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + /** Each row stands with bit 5 set too, which only turns the TTL input on */ + private static void checkRow(Row row, int value) { + String name = hex(value); + assertEquals(name + " is kept as it is", value, ButtonLogMode.correct(value)); + assertTrue(name + " is valid", ButtonLogMode.isValid(value)); + assertEquals(name + " TTL input", (value & 0x20)!=0, ButtonLogMode.isTtlInputEnabled(value)); + assertEquals(name + " presses recorded", row.recorded, ButtonLogMode.isRecordingButtonPresses(value)); + assertEquals(name + " logging off", row.loggingOff, ButtonLogMode.isLoggingDisabled(value)); + + for(boolean userButtonEnable:new boolean[] {false, true}){ + String state = name + " with userButtonEnable " + userButtonEnable; + boolean held = row.userButtonEnableHeldAt==null ? userButtonEnable : row.userButtonEnableHeldAt; + assertEquals(state + ": the userButtonEnable held", held, ButtonLogMode.getNearestUserButtonEnable(value, userButtonEnable)); + + boolean pressStarts = row.press==PRESS.STARTS_STOPS || row.press==PRESS.DOUBLE_STARTS_STOPS + || (row.press==PRESS.LEGACY && userButtonEnable); + // The firmware acts on the userButtonEnable it holds + assertEquals(state + ": a press starts logging", pressStarts, ButtonLogMode.isPressStartingLogging(value, held)); + + boolean undockStarts = row.press==PRESS.LEGACY ? !userButtonEnable : row.undockStarts; + assertEquals(state + ": leaving the dock starts logging", undockStarts, ButtonLogMode.isUndockStartingLogging(value, held, false)); + assertFalse(state + ": single touch suppresses the undock start", ButtonLogMode.isUndockStartingLogging(value, held, true)); + } + + // Single touch needs a press that can start logging + boolean singleTouch = row.press==PRESS.LEGACY || row.press==PRESS.STARTS_STOPS || row.press==PRESS.DOUBLE_STARTS_STOPS; + assertEquals(name + " single touch allowed", singleTouch, ButtonLogMode.isSingleTouchAllowed(value)); + } + + @Test + public void theSixteenValuesTheFirmwareKeeps() { + for(Row row:TABLE){ + checkRow(row, row.value); + } + } + + @Test + public void eachWithTheTtlInputOn() { + for(Row row:TABLE){ + checkRow(row, row.value | ButtonLogMode.MASK_TTL_INPUT); + } + } + + @Test + public void theTableIsEveryValueTheFirmwareKeeps() { + Set valid = new TreeSet(); + for(int value=0;value<256;value++){ + if(ButtonLogMode.isValid(value)){ + valid.add(value); + } + } + Set expected = new TreeSet(); + for(Row row:TABLE){ + expected.add(row.value); + expected.add(row.value | ButtonLogMode.MASK_TTL_INPUT); + } + assertEquals(expected, valid); + } + + /** Restates the section 8.3 correction independently of ButtonLogMode, for all 256 values */ + @Test + public void everyOtherValueIsCorrectedAsTheFirmwareDoes() { + for(int value=0;value<256;value++){ + int expected; + int buttonMode = value & 0x07; + int logTriggers = (value >> 3) & 0x03; + if((value & 0x80)!=0){ + expected = 0; // bit 7 set: the whole byte reads as 0, TTL input off + } + else if(buttonMode==0 || buttonMode>5 || logTriggers==3){ + expected = value & 0x20; // legacy, reserved: bits 0-4 cleared, TTL input as it is + } + else { + expected = value & 0x3F; // bit 6 is unused and cleared + } + assertEquals(hex(value), expected, ButtonLogMode.correct(value)); + assertEquals(hex(value) + " button mode", expected & 0x07, ButtonLogMode.getButtonMode(value)); + assertEquals(hex(value) + " log triggers", (expected >> 3) & 0x03, ButtonLogMode.getLogTriggers(value)); + } + } + + @Test + public void erasedMemoryReadsAsLegacy() { + assertEquals(0, ButtonLogMode.correct(0xFF)); + assertFalse(ButtonLogMode.isValid(0xFF)); + assertEquals("bit 7 takes the TTL input with it", 0, ButtonLogMode.correct(0xA0)); + assertEquals("a byte read from a Java byte[]", 0, ButtonLogMode.correct((byte) 0xFF)); + } + + @Test + public void encodeIsWhatTheFirmwareKeeps() { + assertEquals("the button off", 0x01, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_HOST, false)); + assertEquals("the button off and logging off", 0x11, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + assertEquals("legacy drops the log triggers", 0x00, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + assertEquals("the TTL input alone", 0x20, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_HOST, true)); + assertEquals("a reserved mode reads as legacy", 0x20, ButtonLogMode.encode(6, ButtonLogMode.LOG_TRIGGERS_HOST_OR_UNDOCK, true)); + assertEquals("reserved log triggers read as legacy", 0x00, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, 3, false)); + assertEquals("an out-of-range mode is left 0", 0x00, ButtonLogMode.encode(9, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + } + + @Test + public void fieldsSetOneAtATimeInEitherOrder() { + int triggersFirst = ButtonLogMode.compose(0, ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_NONE, false); + triggersFirst = ButtonLogMode.compose(triggersFirst, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.getRawLogTriggers(triggersFirst), false); + assertEquals(0x11, triggersFirst); + + int modeFirst = ButtonLogMode.compose(0, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_HOST, false); + modeFirst = ButtonLogMode.compose(modeFirst, ButtonLogMode.getRawButtonMode(modeFirst), ButtonLogMode.LOG_TRIGGERS_NONE, false); + assertEquals(0x11, modeFirst); + + assertEquals("erased memory gives nothing to keep", 0x01, ButtonLogMode.compose(0xFF, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.getRawLogTriggers(0xFF), ButtonLogMode.isRawTtlInputEnabled(0xFF))); + } + + @Test + public void sr48_6_0HasNoButtonEdgesAndNoTtlInput() { + ExpansionBoardDetails sr48_6_0 = new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 6, 0); + assertEquals("recorded double press becomes double press", 0x03, ButtonLogMode.correctForBoard(0x04, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("recorded alone becomes disabled", 0x11, ButtonLogMode.correctForBoard(0x15, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("the TTL input goes", 0x0B, ButtonLogMode.correctForBoard(0x2C, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("a mode without recording stays", 0x02, ButtonLogMode.correctForBoard(0x02, HW_ID.SHIMMER_3R, sr48_6_0)); + + ExpansionBoardDetails sr48_7_0 = new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 7, 0); + assertEquals("a later SR48 has both", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3R, sr48_7_0)); + assertEquals("the rule is Shimmer3R's", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3, sr48_6_0)); + assertEquals("an unknown board has both", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3R, null)); + } + +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java new file mode 100644 index 000000000..b007053b8 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java @@ -0,0 +1,332 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import org.junit.Test; + +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID_SR_CODES; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** + * DEV-971: configuration byte 232, the button mode, log triggers and TTL + * input, through a full configuration write. The write builds its image from + * zeros, so before DEV-971 every configure from Consensys or Android put 0 + * there and turned a Shimmer's button back on. It now carries the byte read + * from the Shimmer, or the one set, and holds userButtonEnable and + * singleTouchStart where the button mode decides them, as the firmware does. + * Before anything is read, a Bluetooth write leaves the byte out, so the + * Shimmer keeps its own. + *

+ * No hardware. It lives in this package because the instruction list is a + * protected member of ShimmerBluetooth. + * + * @author Mark Nolan + */ +public class API_00037_ButtonLogModeConfigWriteTest { + + private static final int IDX_BUTTON_LOG_MODE = 232; + private static final int IDX_TRIAL_CONFIG0 = 217; + private static final int IDX_TRIAL_CONFIG1 = 218; + private static final int USER_BUTTON_ENABLE = 0x20; + private static final int SINGLE_TOUCH_START = 0x80; + + /** A Shimmer3R on a release whose builds can carry the event channel */ + private static final ShimmerVerObject S3R_EVENT_CHANNEL_CAPABLE = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + + /** Lets a test give the probe's answer */ + private static class ProbedShimmer extends ShimmerPC { + private static final long serialVersionUID = 1L; + ProbedShimmer() { + super("COM99"); + } + void probeAnswered(Boolean isEventChannelSupported) { + setEventChannelSupported(isEventChannelSupported); + } + } + + private static ProbedShimmer shimmer(ShimmerVerObject svo) { + ProbedShimmer shimmer = new ProbedShimmer(); + shimmer.setShimmerVersionObjectAndCreateSensorMap(svo); + return shimmer; + } + + /** + * A configuration as a Shimmer on that firmware would answer it, with the + * given bytes 232, 217 and 218: the image a second, unread Shimmer makes + */ + private static byte[] configFromShimmer(ShimmerVerObject svo, int buttonLogMode, int trialConfig0, int trialConfig1) { + ShimmerPC source = new ShimmerPC("COM98"); + source.setShimmerVersionObjectAndCreateSensorMap(svo); + byte[] config = source.generateConfigBytesForWritingToShimmer().clone(); + config[IDX_BUTTON_LOG_MODE] = (byte) buttonLogMode; + config[IDX_TRIAL_CONFIG0] = (byte) trialConfig0; + config[IDX_TRIAL_CONFIG1] = (byte) trialConfig1; + return config; + } + + private static ProbedShimmer readFrom(ShimmerVerObject svo, int buttonLogMode, int trialConfig0, int trialConfig1) { + ProbedShimmer shimmer = shimmer(svo); + shimmer.configBytesParse(configFromShimmer(svo, buttonLogMode, trialConfig0, trialConfig1), COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int written(ShimmerPC shimmer, int idx) { + return shimmer.generateConfigBytesForWritingToShimmer()[idx] & 0xFF; + } + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + @Test + public void theByteReadGoesBackOnAFullWrite() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + assertTrue(shimmer.isButtonLogModeKnown()); + assertEquals(ButtonLogMode.BUTTON_MODE_DISABLED, shimmer.getButtonMode()); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, shimmer.getLogTriggers()); + assertEquals("before DEV-971 this was 0", 0x11, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void everyValueTheFirmwareKeepsGoesBack() { + for(int value=0;value<256;value++){ + if(!ButtonLogMode.isValid(value)){ + continue; + } + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, value, USER_BUTTON_ENABLE, 0); + assertEquals(hex(value), value, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + } + + @Test + public void userButtonEnableIsHeldAtTheModesEquivalent() { + ProbedShimmer undockStart = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x09, USER_BUTTON_ENABLE, 0); + undockStart.setButtonStart(true); + assertEquals("0x09: nothing on a press, logging on an undock", 0, written(undockStart, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertFalse(undockStart.isButtonStart()); + + ProbedShimmer disabled = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x01, 0, 0); + assertEquals("0x01: held at 1, so firmware without the byte never adds an undock start", USER_BUTTON_ENABLE, written(disabled, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertTrue(disabled.isButtonStart()); + + ProbedShimmer legacy = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, 0, 0); + assertEquals("legacy leaves it as it is", 0, written(legacy, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + } + + @Test + public void singleTouchIsClearedWhereNoPressCanStartLogging() { + ProbedShimmer disabled = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x01, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); + disabled.setSingleTouch(true); + assertEquals(0, written(disabled, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + assertFalse(disabled.isSingleTouch()); + + ProbedShimmer loggingOff = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x12, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); + loggingOff.setSingleTouch(true); + assertEquals("a press that could, but logging is off", 0, written(loggingOff, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + + ProbedShimmer singlePress = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x02, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); + singlePress.setSingleTouch(true); + assertEquals(SINGLE_TOUCH_START, written(singlePress, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + } + + @Test + public void aValueSetIsWrittenWhateverTheOrderOfTheFields() { + ProbedShimmer modeFirst = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + modeFirst.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + modeFirst.setLogTriggers(ButtonLogMode.LOG_TRIGGERS_NONE); + assertEquals(0x11, written(modeFirst, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer triggersFirst = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + triggersFirst.setLogTriggers(ButtonLogMode.LOG_TRIGGERS_NONE); + assertEquals("legacy does not read them yet", ButtonLogMode.LOG_TRIGGERS_HOST, triggersFirst.getLogTriggers()); + triggersFirst.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, triggersFirst.getLogTriggers()); + assertEquals(0x11, written(triggersFirst, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer ttl = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + ttl.setTtlInputEnabled(true); + assertEquals("the other fields stay", 0x31, written(ttl, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void theConfigLabelsSetAndGetTheFields() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS, ButtonLogMode.LOG_TRIGGERS_NONE); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE, ButtonLogMode.BUTTON_MODE_RECORDED); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT, true); + assertEquals(0x35, written(shimmer, IDX_BUTTON_LOG_MODE)); + assertEquals(ButtonLogMode.BUTTON_MODE_RECORDED, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE)); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS)); + assertEquals(true, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT)); + } + + @Test + public void erasedMemoryIsKeptAsReadAndReadsAsLegacy() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0xFF, 0, SINGLE_TOUCH_START); + assertFalse(shimmer.isButtonLogModeMeaningful()); + assertEquals(ButtonLogMode.BUTTON_MODE_LEGACY, shimmer.getButtonMode()); + assertEquals(0xFF, written(shimmer, IDX_BUTTON_LOG_MODE)); + assertEquals("legacy changes neither", 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertEquals(SINGLE_TOUCH_START, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + } + + @Test + public void aByteTheFirmwareWouldCorrectIsTrustedOnlyAfterTheProbe() { + // Reserved button mode 7 with the TTL input on: no firmware writes it + ProbedShimmer unprobed = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x27, USER_BUTTON_ENABLE, 0); + assertFalse(unprobed.isTtlInputEnabled()); + assertEquals("kept as read", 0x27, written(unprobed, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer probed = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x27, USER_BUTTON_ENABLE, 0); + probed.probeAnswered(true); + assertTrue(probed.isTtlInputEnabled()); + assertEquals("as the firmware corrects it", 0x20, written(probed, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void sr48_6_0HasNeitherInput() { + ProbedShimmer shimmer = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + shimmer.setExpansionBoardDetails(new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 6, 0)); + shimmer.configBytesParse(configFromShimmer(S3R_EVENT_CHANNEL_CAPABLE, 0x24, USER_BUTTON_ENABLE, 0), COMMUNICATION_TYPE.BLUETOOTH); + assertEquals(0x03, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void firmwareThatCannotHaveTheByteIsWrittenAsBefore() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 19), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = readFrom(svo, 0x11, USER_BUTTON_ENABLE, 0); + assertFalse(svo.getFirmwareVersionParsed(), shimmer.isButtonLogModeKnown()); + assertEquals(svo.getFirmwareVersionParsed(), 0, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + ProbedShimmer s3 = readFrom(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 1, 9), 0x11, USER_BUTTON_ENABLE, 0); + assertEquals("a Shimmer3 release that can", 0x11, written(s3, IDX_BUTTON_LOG_MODE)); + } + + // ---- The Bluetooth write's SET_INFOMEM chunks + + /** [address, length] of each SET_INFOMEM queued: [0x8C, length, address LSB, address MSB, data...] */ + private static List infoMemChunks(ShimmerBluetooth shimmer) { + List chunks = new ArrayList(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + chunks.add(new int[] {(instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8), instruction[1]&0xFF}); + } + } + return chunks; + } + + private static byte[] infoMemChunkAt(ShimmerBluetooth shimmer, int address) { + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND + && ((instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8))==address){ + return instruction; + } + } + fail("no SET_INFOMEM at " + address); + return null; + } + + private static void assertChunks(String message, int[][] expected, ShimmerBluetooth shimmer) { + List chunks = infoMemChunks(shimmer); + List actual = new ArrayList(); + for(int[] chunk:chunks){ + actual.add(Arrays.toString(chunk)); + } + List wanted = new ArrayList(); + for(int[] chunk:expected){ + wanted.add(Arrays.toString(chunk)); + } + assertEquals(message, wanted, actual); + } + + /** The 128-byte chunks of the Shimmer's image, as the write has always sent them */ + private static int[][] allChunks(ShimmerBluetooth shimmer) { + int length = shimmer.generateConfigBytesForWritingToShimmer().length; + int[][] chunks = new int[length/128][]; + for(int i=0;i chunks = new ArrayList(); + for(int[] chunk:allChunks(shimmer)){ + if(chunk[0]==128){ + chunks.add(new int[] {128, 104}); + chunks.add(new int[] {233, 23}); + } + else { + chunks.add(chunk); + } + } + return chunks.toArray(new int[0][]); + } + + @Test + public void beforeAReadTheBluetoothWriteLeavesTheShimmersByte() { + ProbedShimmer shimmer = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + assertFalse(shimmer.isButtonLogModeKnown()); + shimmer.writeConfigBytes(false); + assertChunks("a configuration written on connect, before the read", chunksWithout232(shimmer), shimmer); + + // The bytes either side of 232 are the image's + byte[] image = shimmer.generateConfigBytesForWritingToShimmer(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + int address = (instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8); + int length = instruction[1]&0xFF; + assertArrayEquals("chunk at " + address, Arrays.copyOfRange(image, address, address+length), Arrays.copyOfRange(instruction, 4, 4+length)); + } + } + + ProbedShimmer s3 = shimmer(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 20)); + s3.writeConfigBytes(false); + assertChunks("the first Shimmer3 release that can", chunksWithout232(s3), s3); + } + + @Test + public void onceReadOrSetTheBluetoothWriteHasTheByte() { + ProbedShimmer read = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + read.writeConfigBytes(false); + assertChunks("read", allChunks(read), read); + + ProbedShimmer set = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + set.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + set.writeConfigBytes(false); + assertChunks("set", allChunks(set), set); + byte[] chunk = infoMemChunkAt(set, 128); + assertEquals("set, before anything was read", 0x01, chunk[4 + IDX_BUTTON_LOG_MODE - 128] & 0xFF); + } + + @Test + public void olderFirmwareIsWrittenInWholeChunksAsBefore() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 19), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = shimmer(svo); + shimmer.writeConfigBytes(false); + assertChunks(svo.getFirmwareVersionParsed(), allChunks(shimmer), shimmer); + } + } + +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java new file mode 100644 index 000000000..7b3d977b4 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java @@ -0,0 +1,226 @@ +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_STATE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.SHIMMER_FEATURE; +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-971: whether a Shimmer has the event channel, and with it configuration + * byte 232, is asked rather than read off its version, because the event + * channel's builds report the release before them. The question is SET_FEATURE + * with FEATURE_EVENT_STREAM and 0: firmware with the event channel ACKs it and + * firmware without NACKs it. + *

+ * The driver did not handle a NACK: it discarded it, kept waiting for the ACK, + * and its ACK timer then dropped the connection. So the probe's NACK is now + * handled. Firmware older than SET_FEATURE answers nothing at all and takes the + * two bytes after 0xB7 as commands, so it is never asked. + *

+ * 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. + * + * @author Mark Nolan + */ +public class API_00038_EventChannelProbeTest { + + private static final byte FEATURE_EVENT_STREAM = (byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal(); + + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + /** How the firmware answers FEATURE_EVENT_STREAM */ + final byte eventStreamAnswer; + + AnsweringRadio(byte eventStreamAnswer) { + this.eventStreamAnswer = eventStreamAnswer; + } + + int countWritten(byte command) { + int count = 0; + synchronized(written){ + for(byte[] w:written){ + if(w[0]==command){ + count++; + } + } + } + return count; + } + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + if(buffer[0]==ShimmerObject.SET_FEATURE && buffer[1]==FEATURE_EVENT_STREAM){ + rx.add(eventStreamAnswer); + } + else { + // Every other command here is a SET, which the firmware acknowledges + rx.add(ShimmerObject.ACK_COMMAND_PROCESSED); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() progressReports = Collections.synchronizedList(new ArrayList()); + volatile boolean connectionLost = false; + + WatchedShimmer() { + super("COM99"); + } + + @Override + protected void sendProgressReport(BluetoothProgressReportPerCmd pRPC) { + progressReports.add((byte) pRPC.mCommandCompleted); + super.sendProgressReport(pRPC); + } + + @Override + protected void connectionLost() { + connectionLost = true; + super.connectionLost(); + } + } + + private WatchedShimmer mDevice; + + @After + public void tearDown() { + if(mDevice!=null){ + mDevice.stopTimerCheckForAckOrResp(); + mDevice.disconnectNoException(); + } + } + + /** A connected Shimmer, not streaming, with its IOThread running as connect() starts it */ + private AnsweringRadio connectedShimmer(ShimmerVerObject svo, byte eventStreamAnswer) { + AnsweringRadio radio = new AnsweringRadio(eventStreamAnswer); + mDevice = new WatchedShimmer(); + mDevice.setTestRadio(radio); + mDevice.setShimmerVersionObjectAndCreateSensorMap(svo); + mDevice.setIsInitialised(true); + mDevice.mIOThread = mDevice.new IOThread(); + mDevice.mIOThread.start(); + return radio; + } + + /** Waits for the instruction list to empty, well inside the 5 s ACK timer that drops the connection */ + private void waitForInstructionsDone(long timeoutMs) throws InterruptedException { + long end = System.currentTimeMillis()+timeoutMs; + while((!mDevice.getListofInstructions().isEmpty() || mDevice.isInstructionStackLock()) && System.currentTimeMillis() Date: Mon, 2 Nov 2026 15:19:41 +0000 Subject: [PATCH 02/10] DEV-971: SET_FEATURE reached Shimmer3 in v1.0.17, not v1.0.20 LogAndStream_Shimmer3 v1.00.017 is the first release whose log-and-stream-common pin has SET_FEATURE (df58877, with the two-byte argument fix e5ea88c). From v1.00.017 to v1.00.019 the module sat at LogAndStream/log-and-stream-common, and v1.00.017 builds its Bluetooth handler from there. The earlier check looked only at the path v1.00.020 moved it to. The gate moves to v1.0.17, the same release isSupportedRn4678ErrorDetection() already uses. Those releases NACK FEATURE_EVENT_STREAM, so they read as having no event channel, and their SET_INFOMEM handler is the same one that takes the split write around byte 232. Co-Authored-By: Claude Opus 5.5 --- .../shimmerresearch/driverUtilities/ShimmerVerObject.java | 4 ++-- .../bluetooth/API_00037_ButtonLogModeConfigWriteTest.java | 6 +++--- .../bluetooth/API_00038_EventChannelProbeTest.java | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java index c8db3ba62..c22e31888 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java @@ -752,7 +752,7 @@ public boolean isSupportedBtBatteryRequest() { * Whether the firmware has SET_FEATURE (0xB7), with its feature id and * value, and NACKs a feature id it does not know. It came with * log-and-stream-common: LogAndStream_Shimmer3R v1.0.52 and - * LogAndStream_Shimmer3 v1.0.20. Older firmware discards the 0xB7 byte + * LogAndStream_Shimmer3 v1.0.17. Older firmware discards the 0xB7 byte * unanswered and takes the two bytes after it as commands, so a feature id * of 3 there is GET_SAMPLING_RATE_COMMAND, which is ACKed. SET_FEATURE must * not be sent to it. @@ -763,7 +763,7 @@ public boolean isSupportedBtBatteryRequest() { */ public boolean isSupportedSetFeature() { return compareVersions(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 52) - || compareVersions(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 20); + || compareVersions(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17); } } diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java index b007053b8..e60dbbd10 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java @@ -207,7 +207,7 @@ public void sr48_6_0HasNeitherInput() { public void firmwareThatCannotHaveTheByteIsWrittenAsBefore() { ShimmerVerObject[] older = { new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), - new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 19), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), }; for(ShimmerVerObject svo:older){ ProbedShimmer shimmer = readFrom(svo, 0x11, USER_BUTTON_ENABLE, 0); @@ -297,7 +297,7 @@ public void beforeAReadTheBluetoothWriteLeavesTheShimmersByte() { } } - ProbedShimmer s3 = shimmer(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 20)); + ProbedShimmer s3 = shimmer(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17)); s3.writeConfigBytes(false); assertChunks("the first Shimmer3 release that can", chunksWithout232(s3), s3); } @@ -320,7 +320,7 @@ public void onceReadOrSetTheBluetoothWriteHasTheByte() { public void olderFirmwareIsWrittenInWholeChunksAsBefore() { ShimmerVerObject[] older = { new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), - new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 19), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), }; for(ShimmerVerObject svo:older){ ProbedShimmer shimmer = shimmer(svo); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java index 7b3d977b4..58e7a74c7 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java @@ -195,7 +195,7 @@ public void aNackStillCountsTowardsTheOperation() throws Exception { public void firmwareOlderThanSetFeatureIsNotAsked() throws Exception { ShimmerVerObject[] older = { new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), - new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 19), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.BTSTREAM, 0, 8, 1), }; for(ShimmerVerObject svo:older){ @@ -207,7 +207,7 @@ public void firmwareOlderThanSetFeatureIsNotAsked() throws Exception { } WatchedShimmer s3 = new WatchedShimmer(); - s3.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 20)); + s3.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17)); s3.readEventChannelSupport(); assertNull("the first Shimmer3 release with SET_FEATURE is asked", s3.isEventChannelSupported()); assertEquals(1, s3.getListofInstructions().size()); From 3606c9511779636c7779438c73920c1a6841396a Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Tue, 3 Nov 2026 22:18:57 +0000 Subject: [PATCH 03/10] DEV-971: clear single touch on firmware with byte 232, as it does applyButtonLogModeRules() kept singleTouchStart wherever byte 232 left a press that can start logging. That rule exists only in a firmware build with IS_SUPPORTED_SINGLE_TOUCH, and no LogAndStream release has it: every one clears the bit on each configuration it takes, whatever byte 232 holds. So a full write sent a bit the Shimmer drops, and the driver showed single touch on where it never acts. - The rules now clear singleTouchStart on firmware that has byte 232 (LogAndStream from the release that brought SET_FEATURE, the same gate the layout uses), and keep userButtonEnable at the button mode's nearest equivalent there as before. - On other firmware they change nothing. A byte 232 setter called for an SDLog Shimmer, or LogAndStream before the byte, used to move userButtonEnable and clear single touch on firmware that has neither rule, and SDLog is the one firmware the driver offers Single Touch Start for. - API_00037: single touch is cleared in every mode, 0xFF included, and firmware without the byte keeps bytes 217 and 218. All three tests fail on the old rule. Not benched. Co-Authored-By: Claude Opus 5.5 --- .../shimmerresearch/driver/ShimmerObject.java | 23 +++++---- .../driver/shimmer2r3/ButtonLogMode.java | 4 +- ...PI_00037_ButtonLogModeConfigWriteTest.java | 51 ++++++++++++------- 3 files changed, 50 insertions(+), 28 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index ecaca1026..0f4018c50 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -6659,7 +6659,7 @@ public int getButtonLogMode() { * Sets configuration byte 232 (DEV-971) whole. The firmware corrects a * value it cannot act on to 0 (see {@link ButtonLogMode#correct(int)}). * Like the field setters, it holds userButtonEnable and singleTouchStart - * where the button mode decides them. + * as that firmware will ({@link #applyButtonLogModeRules()}). */ public void setButtonLogMode(int value) { mButtonLogMode = value & 0xFF; @@ -6762,18 +6762,21 @@ protected int getButtonLogModeToWrite() { } /** - * Holds userButtonEnable (byte 217 bit 5) at byte 232's button mode's - * nearest equivalent, and clears singleTouchStart (byte 218 bit 7) where no - * press can start logging, as the firmware does when it takes a - * configuration (ShimConfig_checkAndCorrectConfig). Byte 232 in the legacy - * mode changes neither. + * On firmware that has byte 232, does what it does when it takes a + * configuration (ShimConfig_checkAndCorrectConfig): holds userButtonEnable + * (byte 217 bit 5) at the button mode's nearest equivalent, which the legacy + * mode leaves as it is, and clears singleTouchStart (byte 218 bit 7). That + * firmware is LogAndStream from the release that brought SET_FEATURE, none + * of it built with single touch (IS_SUPPORTED_SINGLE_TOUCH is 0 in + * log-and-stream-common), so it clears the bit whatever byte 232 holds. + * Other firmware changes neither here. */ protected void applyButtonLogModeRules() { - int value = getButtonLogModeCorrected(); - if(!ButtonLogMode.isSingleTouchAllowed(value)) { - setSingleTouch(false); + if(!mShimmerVerObject.isSupportedSetFeature()) { + return; } - setButtonStart(ButtonLogMode.getNearestUserButtonEnable(value, isButtonStart())); + setSingleTouch(false); + setButtonStart(ButtonLogMode.getNearestUserButtonEnable(getButtonLogModeCorrected(), isButtonStart())); } /** diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java index 53c8f14aa..d27b0dd87 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java @@ -168,7 +168,9 @@ public static boolean getNearestUserButtonEnable(int raw, boolean userButtonEnab /** * Whether single touch can work: it needs a press that can start logging. - * The firmware clears singleTouchStart when this is false. + * Firmware built with single touch clears singleTouchStart when this is + * false. No LogAndStream release is built with it, and each clears + * singleTouchStart whatever this byte holds. */ public static boolean isSingleTouchAllowed(int raw) { int buttonMode = getButtonMode(raw); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java index e60dbbd10..1ad040e28 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java @@ -24,8 +24,8 @@ * input, through a full configuration write. The write builds its image from * zeros, so before DEV-971 every configure from Consensys or Android put 0 * there and turned a Shimmer's button back on. It now carries the byte read - * from the Shimmer, or the one set, and holds userButtonEnable and - * singleTouchStart where the button mode decides them, as the firmware does. + * from the Shimmer, or the one set, holds userButtonEnable at the button + * mode's nearest equivalent and clears singleTouchStart, as the firmware does. * Before anything is read, a Bluetooth write leaves the byte out, so the * Shimmer keeps its own. *

@@ -125,20 +125,22 @@ public void userButtonEnableIsHeldAtTheModesEquivalent() { assertEquals("legacy leaves it as it is", 0, written(legacy, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); } + /** LogAndStream is built without single touch, and clears it whatever byte 232 holds */ @Test - public void singleTouchIsClearedWhereNoPressCanStartLogging() { - ProbedShimmer disabled = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x01, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); - disabled.setSingleTouch(true); - assertEquals(0, written(disabled, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); - assertFalse(disabled.isSingleTouch()); - - ProbedShimmer loggingOff = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x12, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); - loggingOff.setSingleTouch(true); - assertEquals("a press that could, but logging is off", 0, written(loggingOff, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); - - ProbedShimmer singlePress = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x02, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); - singlePress.setSingleTouch(true); - assertEquals(SINGLE_TOUCH_START, written(singlePress, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + public void singleTouchIsClearedInEveryMode() { + int[] values = { + 0x00, // legacy + 0x01, // no press can start logging + 0x12, // a press that could, but logging is off + 0x02, // a press that starts logging + 0x03, // a double press that does + }; + for(int value:values){ + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, value, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); + shimmer.setSingleTouch(true); + assertEquals(hex(value), 0, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + assertFalse(hex(value), shimmer.isSingleTouch()); + } } @Test @@ -178,8 +180,8 @@ public void erasedMemoryIsKeptAsReadAndReadsAsLegacy() { assertFalse(shimmer.isButtonLogModeMeaningful()); assertEquals(ButtonLogMode.BUTTON_MODE_LEGACY, shimmer.getButtonMode()); assertEquals(0xFF, written(shimmer, IDX_BUTTON_LOG_MODE)); - assertEquals("legacy changes neither", 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); - assertEquals(SINGLE_TOUCH_START, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + assertEquals("legacy leaves userButtonEnable", 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertEquals("the firmware clears single touch all the same", 0, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); } @Test @@ -218,6 +220,21 @@ public void firmwareThatCannotHaveTheByteIsWrittenAsBefore() { assertEquals("a Shimmer3 release that can", 0x11, written(s3, IDX_BUTTON_LOG_MODE)); } + @Test + public void firmwareThatCannotHaveTheByteKeepsBytes217And218() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.SDLOG, 0, 19, 0), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = readFrom(svo, 0x00, 0, SINGLE_TOUCH_START); + shimmer.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + assertEquals(svo.getFirmwareVersionParsed(), 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertEquals(svo.getFirmwareVersionParsed(), SINGLE_TOUCH_START, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + } + } + // ---- The Bluetooth write's SET_INFOMEM chunks /** [address, length] of each SET_INFOMEM queued: [0x8C, length, address LSB, address MSB, data...] */ From a3b5cba5a922fe163fbbe9d53e4b2daed7ef8e63 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Wed, 11 Nov 2026 17:17:06 +0000 Subject: [PATCH 04/10] DEV-971: name v1.01.026, the first Shimmer3R release with the event channel readEventChannelSupport()'s javadoc: no Shimmer3 release has it yet, and the builds before a release report the release before them, so the driver still asks rather than going by the version. Co-Authored-By: Claude Opus 5.5 --- .../com/shimmerresearch/bluetooth/ShimmerBluetooth.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index d0fffc9ab..6d2de43d3 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -5061,8 +5061,10 @@ public void writeSetFeatureCommand(int feature, int setting){ * configuration byte 232 (DEV-971): SET_FEATURE with FEATURE_EVENT_STREAM * and 0, which changes nothing, since a connection starts opted out. * Firmware with the event channel ACKs it and firmware without NACKs it; - * {@link #isEventChannelSupported()} has the answer. There is no version to - * go by: the event channel's builds report the release before them. + * {@link #isEventChannelSupported()} has the answer. LogAndStream_Shimmer3R + * v1.01.026 is the first Shimmer3R release with the event channel, and no + * Shimmer3 release has it yet. The builds before a release report the + * release before them, so the driver asks rather than going by the version. *

* Firmware older than SET_FEATURE is not asked, and has no event channel. * Nor is a Shimmer that is streaming, where a NACK is not yet handled. From 1893a0efa735e3f72fa5d984bfcddc88a659f63b Mon Sep 17 00:00:00 2001 From: JongChern Date: Fri, 13 Nov 2026 12:41:29 +0800 Subject: [PATCH 05/10] 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 06/10] 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); } From 3de20a7cd69d70f12ec6af09f166eb213440d4c1 Mon Sep 17 00:00:00 2001 From: JongChern Date: Fri, 13 Nov 2026 15:11:43 +0800 Subject: [PATCH 07/10] DEV-971: fix four parser defects in the event channel found in review Each was first reproduced by a test that failed on the unchanged code (API_00044_EventStreamReviewReproTest), then fixed: 1. Idle: event records right behind an in-stream reply were lost. After an unsolicited status push ([ACK][0x8A][0x71]), sent on a dock, an undock or a press that starts logging, clearSerialBuffer() wiped the records queued behind it (0 of 2 arrived). With the event channel on, the bytes after the reply are now left for the next pass. A record frame after a stray ACK no longer has link-CRC bytes cleared after it either: it carries its own CRC. 2. Streaming: an ACK nobody waited for, before a record frame, re-ran the ACK handling of the SET that went last. It is now taken only while an ACK is awaited. 3. Streaming with no link CRC: the packet before a 0x8A was taken as a packet even when the 0x8A was a data byte after a lost byte, so misframed bytes reached the app as a sample. It is now taken only once the frame after it passes its own CRC; otherwise the bytes are discarded as before. 4. readEventChannelStatus() could be queued behind a start of streaming not yet acknowledged, and its unwrapped reply, [ACK][0xBA][9], was then not taken between data packets and the command timed out. It is now refused while a start of streaming is queued, and a reply that still arrives between packets is taken. ShimmerDriver 219/219 and ShimmerDriverPC 154/154 pass; the Java 8 MATLAB jar builds. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 124 ++++++- .../API_00044_EventStreamReviewReproTest.java | 339 ++++++++++++++++++ 2 files changed, 444 insertions(+), 19 deletions(-) create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00044_EventStreamReviewReproTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index e2df1cef4..ffad2b160 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -1104,10 +1104,17 @@ else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { } if(byteBuffer!=null && byteBuffer[0]==INSTREAM_CMD_RESPONSE){ processResponseCommand(INSTREAM_CMD_RESPONSE); + /* The reply was read whole. With the event channel on, records + * may already be queued behind it (a status push when a press + * starts logging, say), so they are left for the next pass + * rather than cleared (DEV-971). */ + if(mEventFramesPossible) { + return; + } } } } - + clearSerialBuffer(); } } @@ -1170,7 +1177,32 @@ else if(bufferTemp[0]==DATA_PACKET //Then handle the ACK from the last SET command processAckWhileStreaming(); } - + + //The event channel status, [ACK][0xBA][9], which is not wrapped in 0x8A: + //readEventChannelStatus() is not sent while streaming, but one sent just + //before a stream started is answered once packets flow (DEV-971) + else if(bufferTemp[getPacketSizeWithCrc()+2]==EVENT_CHANNEL_STATUS_RESPONSE + && mWaitForAck && mCurrentCommand==GET_EVENT_CHANNEL_STATUS_COMMAND){ + byte[] responseData = readBytes(EventChannelStatus.LENGTH, EVENT_CHANNEL_STATUS_RESPONSE); + stopTimerCheckForAckOrResp(); //cancel the ack timer + mWaitForAck=false; + mWaitForResponse=false; + if(responseData!=null){ + if(mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF){ + clearCrcBytesFromBuffer(EVENT_CHANNEL_STATUS_RESPONSE); + } + takeEventChannelStatus(responseData); + } + processDataPacket(bufferTemp); + if(getListofInstructions().size()>0){ + removeInstruction(0); + } + mTransactionCompleted=true; + setInstructionStackLock(false); + clearBuffers(); + return; + } + //this is for LogAndStream support, command is transmitted and ack received else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTREAM_CMD_RESPONSE){ printLogDataForDebugging("COMMAND TXed and ACK RECEIVED IN STREAM"); @@ -1187,7 +1219,13 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR if(mEventFramesPossible && inStreamResponseCommand!=null && inStreamResponseCommand[0]==EVENT_RECORD_RESPONSE){ processDataPacket(bufferTemp); - processAckWhileStreaming(); + if(mWaitForAck){ + processAckWhileStreaming(); + } + else { + // Nothing waits for an ACK, so the SET that went last must not be acknowledged again + printLogDataForDebugging("ACK with no command awaiting it, before an event record - ignored"); + } readEventFrameRestFromPort(); clearBuffers(); return; @@ -1238,12 +1276,30 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR 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; + int packetEnd = getPacketSizeWithCrc()+1; + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF) { + //The packet's own CRC confirms it + if (!checkCrc(bufferTemp, getPacketSize() + 1)) { + discardBufferBytesToNextPacket(); + return; + } + } + else { + //With no link CRC, a 0x8A where the next packet should start is + //only a frame, and the packet before it only a packet, once the + //frame's own CRC checks out. Otherwise the boundary is wrong (a + //byte lost, say), and the bytes are discarded as before. + int frameLength = EventFrame.getFrameLength(bufferTemp, packetEnd, bufferTemp.length-packetEnd); + if (frameLength==EventFrame.NEED_MORE) { + return; //wait for the rest of the frame + } + if (frameLength==EventFrame.NOT_A_FRAME) { + discardBufferBytesToNextPacket(); + return; + } } processDataPacket(bufferTemp); - clearBytesFromStartOfBuffers(bufferTemp, getPacketSizeWithCrc()+1); + clearBytesFromStartOfBuffers(bufferTemp, packetEnd); } //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 @@ -2164,7 +2220,14 @@ else if(responseCommand==RWC_RESPONSE) { } } else if(responseCommand==INSTREAM_CMD_RESPONSE) { - processInstreamResponse(false); + byte[] inStreamResponseCommand = readBytes(1, INSTREAM_CMD_RESPONSE); + if(inStreamResponseCommand!=null){ + processInstreamResponse(inStreamResponseCommand[0], false); + if(inStreamResponseCommand[0]==EVENT_RECORD_RESPONSE && mEventFramesPossible){ + // An event record frame carries its own CRC and never the link CRC (DEV-971) + responseWasParsed = false; + } + } } else if(responseCommand==LSM303DLHC_ACCEL_LPMODE_RESPONSE) { byte[] responseData = readBytes(1, responseCommand); @@ -2327,16 +2390,7 @@ 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); - } - } + takeEventChannelStatus(responseData); } } @@ -5510,13 +5564,31 @@ public boolean isEventStreamRequested() { * @return whether it was sent */ public boolean readEventChannelStatus() { - if(!Boolean.TRUE.equals(isEventChannelSupported()) || isStreaming()) { + if(!Boolean.TRUE.equals(isEventChannelSupported()) || isStreaming() || isStreamStartQueued()) { return false; } writeInstruction(new byte[]{GET_EVENT_CHANNEL_STATUS_COMMAND}); return true; } + /** + * Whether a start of streaming is queued or in flight: the instruction list + * keeps a command until it is answered, and isStreaming() turns true only + * then. A status read queued behind it would be answered between data packets. + */ + private boolean isStreamStartQueued() { + List instructions = getListofInstructions(); + synchronized(instructions){ + for(byte[] instruction:instructions){ + if(instruction!=null && instruction.length>0 + && (instruction[0]==START_STREAMING_COMMAND || instruction[0]==START_SDBT_COMMAND)){ + return true; + } + } + } + return false; + } + /** The last answer to {@link #readEventChannelStatus()}, or null */ public EventChannelStatus getEventChannelStatus() { return mEventChannelStatus; @@ -5626,6 +5698,20 @@ private void readEventFrameRestFromPort() { dispatchEventRecord(record); } + /** Keeps the event channel status's 9 bytes and hands them to each listener */ + private void takeEventChannelStatus(byte[] responseData) { + 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); + } + } + } + private void dispatchEventRecord(EventRecord record) { mEventFramesReceived++; printLogDataForDebugging("Event record:\t" + record); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00044_EventStreamReviewReproTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00044_EventStreamReviewReproTest.java new file mode 100644 index 000000000..f1272c148 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00044_EventStreamReviewReproTest.java @@ -0,0 +1,339 @@ +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; + +/** + * Repro tests for the review findings on #348, written before any fix. Each + * asserts the behaviour the protocol needs; a failure here confirms the + * finding on the unchanged code. + */ +public class API_00044_EventStreamReviewReproTest { + + private static final int PACKET_SIZE = 9; + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + + private static byte[] frame(int type, int seq, long ticks, int channel, int state) { + byte[] f = new byte[21]; + f[0] = (byte) 0x8A; + f[1] = (byte) 0xBB; + f[2] = 16; + f[3] = (byte) type; + f[5] = (byte) seq; + f[6] = (byte) (seq>>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; + } + + private static final byte[] PRESS = frame(EventRecord.TYPE_EDGE, 1, 0x357237185333L, EventRecord.CHANNEL_BUTTON, 1); + private static final byte[] RELEASE = frame(EventRecord.TYPE_EDGE, 2, 0x357237186333L, EventRecord.CHANNEL_BUTTON, 0); + + 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); } + } + + private final Collected mCollected = new Collected(); + private final List mAcksProcessed = Collections.synchronizedList(new ArrayList()); + + // ------------------------------------------------------------------ + // Streaming parser, fed one byte at a time + // ------------------------------------------------------------------ + + 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 n, int timeout) throws SerialPortTimeoutException { + if(rx.size() parsed() { + List out = new ArrayList(); + ShimmerBluetooth d = mStreaming; + for(RawBytePacketWithPCTimeStamp p:d.mABQPacketByeArray) out.add(UtilShimmer.bytesToHexStringWithSpacesFormatted(p.mDataArray)); + return out; + } + + @After + public void stopTimers() { + if(mStreaming!=null) { + mStreaming.stopTimerCheckForAckOrResp(); + mStreaming.stopTimerReadStatus(); + } + if(mIdle!=null) { + mIdle.stopTimerCheckForAckOrResp(); + mIdle.disconnectNoException(); + } + } + + /** + * Finding 2: an ACK with no command waiting for it, then a frame. The SET + * that went last must not have its ACK handling run a second time. + */ + @Test + public void finding2_anAckNobodyWaitsForBeforeAFrameDoesNotReRunTheLastSetsAck() { + streamingShimmer3r(BT_CRC_MODE.OFF); + alreadyOptedIn(); + // The last command was a SET that completed long ago + mStreaming.mCurrentCommand = ShimmerObject.SET_SAMPLING_RATE_COMMAND; + receive(dataPacket(payload(1), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED}, PRESS, + dataPacket(payload(2), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + assertEquals("the record is taken", 1, mCollected.records.size()); + assertEquals("no SET's ACK is processed: none was in flight", Collections.emptyList(), mAcksProcessed); + } + + /** + * Finding 3: no link CRC, opted in, and a byte lost from a packet, so the + * parser's boundary falls one byte late and lands on a data byte of 0x8A. + * The misframed bytes must not be handed on as a packet; before #348 they + * were discarded to the next packet boundary. + */ + @Test + public void finding3_withoutACrcAMisframedPacketBeforeA0x8ADataByteIsNotTakenAsAPacket() { + streamingShimmer3r(BT_CRC_MODE.OFF); + alreadyOptedIn(); + byte[] good = dataPacket(payload(1), BT_CRC_MODE.OFF); + // Packet 2 loses its 4th byte on the link, and its 2nd byte happens to be 0x8A + byte[] p2 = new byte[] {0x20, (byte) 0x8A, 0x01, 0x02, 0x07, 0x05, 0x08, 0x3F, 0x09}; + byte[] p2Lost = new byte[1+p2.length-1]; + p2Lost[0] = ShimmerObject.DATA_PACKET; + System.arraycopy(p2, 0, p2Lost, 1, 3); + System.arraycopy(p2, 4, p2Lost, 4, p2.length-4); + byte[] p3 = dataPacket(new byte[] {(byte) 0x8A, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x00}, BT_CRC_MODE.OFF); + receive(good, p2Lost, p3, dataPacket(payload(4), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + List got = parsed(); + // The bytes the parser framed as packet 2: 8 of p2's and the next packet's 0x00 header + byte[] misframed = new byte[PACKET_SIZE]; + System.arraycopy(p2Lost, 1, misframed, 0, p2Lost.length-1); + misframed[PACKET_SIZE-1] = ShimmerObject.DATA_PACKET; + assertFalse("misframed bytes " + UtilShimmer.bytesToHexStringWithSpacesFormatted(misframed) + " were taken as a packet: " + got, + got.contains(UtilShimmer.bytesToHexStringWithSpacesFormatted(misframed))); + } + + /** + * Finding 5, the consequence: a status reply, [ACK][0xBA][9], arriving + * between data packets is not taken, so the command never completes. + */ + @Test + public void finding5_aStatusReplyBetweenDataPacketsIsTaken() { + streamingShimmer3r(BT_CRC_MODE.OFF); + mStreaming.mCurrentCommand = ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND; + mStreaming.getListofInstructions().add(new byte[] {ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND}); + mStreaming.setInstructionStackLock(true); + mStreaming.mWaitForAck = true; + byte[] reply = new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED, ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE, + 0x03, 0x0B, 0x02, 0x05, 0x00, 0x02, 0x00, 0x01, 0x00}; + receive(dataPacket(payload(1), BT_CRC_MODE.OFF), reply, dataPacket(payload(2), BT_CRC_MODE.OFF), + dataPacket(payload(3), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + assertEquals("the status reply is taken", 1, mCollected.statuses.size()); + assertFalse("the command completes", mStreaming.mWaitForAck); + } + + /** + * Finding 5, the precondition: readEventChannelStatus() is queued behind a + * start of streaming that has not been acknowledged yet, so its reply comes + * once packets flow. + */ + @Test + public void finding5_theStatusIsNotQueuedBehindAStartOfStreaming() throws Exception { + ShimmerPC s = new ShimmerPC("COM98"); + s.setShimmerVersionObjectAndCreateSensorMap(S3R); + // As the probe leaves it on a unit with the event channel + java.lang.reflect.Method m = com.shimmerresearch.driver.ShimmerObject.class.getDeclaredMethod("setEventChannelSupported", Boolean.class); + m.setAccessible(true); + m.invoke(s, Boolean.TRUE); + s.startStreaming(); + boolean sent = s.readEventChannelStatus(); + boolean queuedAfterStart = false; + boolean startSeen = false; + for(byte[] ins:s.getListofInstructions()) { + if(ins[0]==ShimmerObject.START_STREAMING_COMMAND) startSeen = true; + if(startSeen && ins[0]==ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND) queuedAfterStart = true; + } + s.stopTimerCheckForAckOrResp(); + s.stopTimerReadStatus(); + assertFalse("the status is queued after a start of streaming (sent=" + sent + ")", queuedAfterStart); + } + + // ------------------------------------------------------------------ + // Idle, with the IOThread running + // ------------------------------------------------------------------ + + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + void queue(byte... bytes) { for(byte b:bytes) rx.add(b); } + @Override public boolean writeBytes(byte[] buffer) { queue(ShimmerObject.ACK_COMMAND_PROCESSED); return true; } + @Override public byte[] readBytes(int n, int timeout) throws SerialPortTimeoutException { + if(rx.size() Date: Fri, 13 Nov 2026 15:29:39 +0800 Subject: [PATCH 08/10] DEV-971: tests with a link CRC, race-free idle radios; keep records behind a bare ACK's CRC From the review of #349: - The idle tests' radios now take each burst whole and let reads wait for their bytes, as a serial port does (WaitingTestRadio), so the IOThread can no longer race the test's writes. API_00043's idle tests use it too. - The status-push, frame-after-ACK and status-reply tests now run with no link CRC, a 1-byte and a 2-byte one. - The misframing test checks that the good packets after the damaged one still arrive; the status-reply test that the command is retired, the lock released, the timer cancelled and the packets either side parsed. The CRC runs reproduced one more defect, which is fixed here: with a link CRC on (the driver turns it on at connect where the firmware has it), the records sent in the same burst as the opt-in's ACK were lost, 0 of 2. The bare ACK's link CRC is left after the ACK is taken; the idle path read it as an unknown byte and cleared the whole serial buffer, records included. With the event channel on, the idle path now drops only the bytes it read. All 7 tests in API_00044 fail on #348's code and pass here. ShimmerDriver 219/219, ShimmerDriverPC 155/155; the Java 8 MATLAB jar builds. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 18 +- .../bluetooth/API_00043_EventStreamTest.java | 58 ++--- .../API_00044_EventStreamReviewReproTest.java | 218 +++++++++++------- .../bluetooth/WaitingTestRadio.java | 114 +++++++++ 4 files changed, 279 insertions(+), 129 deletions(-) create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/WaitingTestRadio.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index ffad2b160..befd46761 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -1104,18 +1104,20 @@ else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { } if(byteBuffer!=null && byteBuffer[0]==INSTREAM_CMD_RESPONSE){ processResponseCommand(INSTREAM_CMD_RESPONSE); - /* The reply was read whole. With the event channel on, records - * may already be queued behind it (a status push when a press - * starts logging, say), so they are left for the next pass - * rather than cleared (DEV-971). */ - if(mEventFramesPossible) { - return; - } } } } - clearSerialBuffer(); + /* With the event channel on, records can be queued behind + * anything read here: behind a status push (when a press starts + * logging, say), or behind the link CRC a bare ACK leaves (the + * opt-in's ACK, whose first record follows at once). So only the + * bytes just read are dropped, and the rest are left for the next + * pass; clearing the buffer would wipe the records with them + * (DEV-971). */ + if(!mEventFramesPossible) { + clearSerialBuffer(); + } } } 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 index 80bdb05ac..455613db1 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00043_EventStreamTest.java @@ -331,73 +331,45 @@ public void framesAreNotParsedWithoutAnOptIn() { // 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()); + /** Answers as LogAndStream_Shimmer3R v1.01.026 does, each reply one burst */ + private static class AnsweringRadio extends WaitingTestRadio { /** 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[] answer(byte[] buffer) { + java.io.ByteArrayOutputStream reply = new java.io.ByteArrayOutputStream(); byte[] early = beforeNextAck; if(early!=null) { beforeNextAck = null; - queue(early); + reply.write(early, 0, early.length); } if(buffer[0]==ShimmerObject.SET_FEATURE && buffer[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal()){ - queue(ShimmerObject.ACK_COMMAND_PROCESSED); + reply.write(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); + reply.write(INITIAL_STATE, 0, INITIAL_STATE.length); + reply.write(MARKER_PRESS, 0, MARKER_PRESS.length); } } else if(buffer[0]==ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND){ - queue(ShimmerObject.ACK_COMMAND_PROCESSED); + reply.write(ShimmerObject.ACK_COMMAND_PROCESSED); byte[] between = betweenAckAndReply; if(between!=null) { betweenAckAndReply = null; - queue(between); + reply.write(between, 0, between.length); } - queue(ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE); - queue(hex("03 0B 02 05 00 02 00 01 00")); + reply.write(ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE); + byte[] status = hex("03 0B 02 05 00 02 00 01 00"); + reply.write(status, 0, status.length); } else { - queue(ShimmerObject.ACK_COMMAND_PROCESSED); + reply.write(ShimmerObject.ACK_COMMAND_PROCESSED); } - return true; + return reply.toByteArray(); } - - @Override - public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { - if(rx.size() + * The streaming tests hand the parser one byte at a time on the test's thread. + * The idle tests run the IOThread over {@link WaitingTestRadio}, whose bursts + * arrive whole and whose reads wait, so the driver's reads cannot race the + * test's writes. */ public class API_00044_EventStreamReviewReproTest { private static final int PACKET_SIZE = 9; private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + private static final BT_CRC_MODE[] CRC_MODES = {BT_CRC_MODE.OFF, BT_CRC_MODE.ONE_BYTE_CRC, BT_CRC_MODE.TWO_BYTE_CRC}; private static byte[] frame(int type, int seq, long ticks, int channel, int state) { byte[] f = new byte[21]; @@ -60,14 +66,24 @@ private static byte[] frame(int type, int seq, long ticks, int channel, int stat return f; } + private static final byte[] INITIAL_STATE = frame(EventRecord.TYPE_INITIAL_STATE, 0, 0x357237100000L, EventRecord.CHANNEL_NONE, 0); private static final byte[] PRESS = frame(EventRecord.TYPE_EDGE, 1, 0x357237185333L, EventRecord.CHANNEL_BUTTON, 1); private static final byte[] RELEASE = frame(EventRecord.TYPE_EDGE, 2, 0x357237186333L, EventRecord.CHANNEL_BUTTON, 0); + /** A reply as the firmware frames it on a link with {@code crcMode}: its bytes, then the link CRC over them */ + private static byte[] withLinkCrc(byte[] bytes, BT_CRC_MODE crcMode) { + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(bytes, bytes.length); + byte[] out = Arrays.copyOf(bytes, bytes.length+crcMode.getNumCrcBytes()); + System.arraycopy(crc, 0, out, bytes.length, crcMode.getNumCrcBytes()); + return out; + } + 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); } + void clear() { records.clear(); statuses.clear(); } } private final Collected mCollected = new Collected(); @@ -101,6 +117,12 @@ private static class QueueRadio implements ByteCommunication { private QueueRadio mQueue; private void streamingShimmer3r(BT_CRC_MODE crcMode) { + if(mStreaming!=null) { + mStreaming.stopTimerCheckForAckOrResp(); + mStreaming.stopTimerReadStatus(); + } + mCollected.clear(); + mAcksProcessed.clear(); mStreaming = new ShimmerPC("COM99") { private static final long serialVersionUID = 1L; @Override @@ -142,16 +164,17 @@ private static byte[] dataPacket(byte[] payload, BT_CRC_MODE crcMode) { byte[] f = new byte[1+payload.length]; f[0] = ShimmerObject.DATA_PACKET; System.arraycopy(payload, 0, f, 1, payload.length); - byte[] crc = ShimmerCrc.shimmerUartCrcCalc(f, f.length); - byte[] out = Arrays.copyOf(f, f.length+crcMode.getNumCrcBytes()); - System.arraycopy(crc, 0, out, f.length, crcMode.getNumCrcBytes()); - return out; + return withLinkCrc(f, crcMode); + } + + private static String hex(byte[] b) { + return UtilShimmer.bytesToHexStringWithSpacesFormatted(b); } private List parsed() { List out = new ArrayList(); ShimmerBluetooth d = mStreaming; - for(RawBytePacketWithPCTimeStamp p:d.mABQPacketByeArray) out.add(UtilShimmer.bytesToHexStringWithSpacesFormatted(p.mDataArray)); + for(RawBytePacketWithPCTimeStamp p:d.mABQPacketByeArray) out.add(hex(p.mDataArray)); return out; } @@ -169,7 +192,9 @@ public void stopTimers() { /** * Finding 2: an ACK with no command waiting for it, then a frame. The SET - * that went last must not have its ACK handling run a second time. + * that went last must not have its ACK handling run a second time. No link + * CRC: with one, a bare ACK goes through the older bare-ACK branch, which + * acknowledges unguarded for a data packet too (not changed here). */ @Test public void finding2_anAckNobodyWaitsForBeforeAFrameDoesNotReRunTheLastSetsAck() { @@ -181,59 +206,72 @@ public void finding2_anAckNobodyWaitsForBeforeAFrameDoesNotReRunTheLastSetsAck() dataPacket(payload(2), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); assertEquals("the record is taken", 1, mCollected.records.size()); assertEquals("no SET's ACK is processed: none was in flight", Collections.emptyList(), mAcksProcessed); + assertEquals(Arrays.asList(hex(payload(1)), hex(payload(2))), parsed()); } /** * Finding 3: no link CRC, opted in, and a byte lost from a packet, so the * parser's boundary falls one byte late and lands on a data byte of 0x8A. - * The misframed bytes must not be handed on as a packet; before #348 they - * were discarded to the next packet boundary. + * The misframed bytes must not be handed on as a packet, and the parser must + * resync so that the good packets after them still arrive. */ @Test public void finding3_withoutACrcAMisframedPacketBeforeA0x8ADataByteIsNotTakenAsAPacket() { streamingShimmer3r(BT_CRC_MODE.OFF); alreadyOptedIn(); byte[] good = dataPacket(payload(1), BT_CRC_MODE.OFF); - // Packet 2 loses its 4th byte on the link, and its 2nd byte happens to be 0x8A + // Packet 2 loses its 4th byte on the link byte[] p2 = new byte[] {0x20, (byte) 0x8A, 0x01, 0x02, 0x07, 0x05, 0x08, 0x3F, 0x09}; byte[] p2Lost = new byte[1+p2.length-1]; p2Lost[0] = ShimmerObject.DATA_PACKET; System.arraycopy(p2, 0, p2Lost, 1, 3); System.arraycopy(p2, 4, p2Lost, 4, p2.length-4); - byte[] p3 = dataPacket(new byte[] {(byte) 0x8A, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x00}, BT_CRC_MODE.OFF); - receive(good, p2Lost, p3, dataPacket(payload(4), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); - List got = parsed(); - // The bytes the parser framed as packet 2: 8 of p2's and the next packet's 0x00 header + // Packet 3's first data byte is 0x8A, where the late boundary lands + byte[] p3Payload = new byte[] {(byte) 0x8A, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x01}; + receive(good, p2Lost, dataPacket(p3Payload, BT_CRC_MODE.OFF), dataPacket(payload(4), BT_CRC_MODE.OFF), + dataPacket(payload(5), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); byte[] misframed = new byte[PACKET_SIZE]; System.arraycopy(p2Lost, 1, misframed, 0, p2Lost.length-1); misframed[PACKET_SIZE-1] = ShimmerObject.DATA_PACKET; - assertFalse("misframed bytes " + UtilShimmer.bytesToHexStringWithSpacesFormatted(misframed) + " were taken as a packet: " + got, - got.contains(UtilShimmer.bytesToHexStringWithSpacesFormatted(misframed))); + List got = parsed(); + assertFalse("misframed bytes " + hex(misframed) + " were taken as a packet: " + got, got.contains(hex(misframed))); + assertEquals("the good packets either side arrive, the damaged one does not", + Arrays.asList(hex(payload(1)), hex(p3Payload), hex(payload(4)), hex(payload(5))), got); } /** - * Finding 5, the consequence: a status reply, [ACK][0xBA][9], arriving - * between data packets is not taken, so the command never completes. + * Finding 5, the consequence, with each link CRC: a status reply, + * [ACK][0xBA][9], between data packets is taken, the command retired, the + * lock released and the packets either side parsed. */ @Test public void finding5_aStatusReplyBetweenDataPacketsIsTaken() { - streamingShimmer3r(BT_CRC_MODE.OFF); - mStreaming.mCurrentCommand = ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND; - mStreaming.getListofInstructions().add(new byte[] {ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND}); - mStreaming.setInstructionStackLock(true); - mStreaming.mWaitForAck = true; - byte[] reply = new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED, ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE, - 0x03, 0x0B, 0x02, 0x05, 0x00, 0x02, 0x00, 0x01, 0x00}; - receive(dataPacket(payload(1), BT_CRC_MODE.OFF), reply, dataPacket(payload(2), BT_CRC_MODE.OFF), - dataPacket(payload(3), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); - assertEquals("the status reply is taken", 1, mCollected.statuses.size()); - assertFalse("the command completes", mStreaming.mWaitForAck); + for(BT_CRC_MODE crcMode:CRC_MODES) { + streamingShimmer3r(crcMode); + mStreaming.mCurrentCommand = ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND; + mStreaming.getListofInstructions().add(new byte[] {ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND}); + mStreaming.setInstructionStackLock(true); + mStreaming.mWaitForAck = true; + mStreaming.startTimerCheckForAckOrResp(2); + byte[] reply = withLinkCrc(new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED, ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE, + 0x03, 0x0B, 0x02, 0x05, 0x00, 0x02, 0x00, 0x01, 0x00}, crcMode); + receive(dataPacket(payload(1), crcMode), reply, dataPacket(payload(2), crcMode), + dataPacket(payload(3), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + String m = crcMode + ": "; + assertEquals(m + "the status reply is taken", 1, mCollected.statuses.size()); + assertEquals(m + "its values", 5, mCollected.statuses.get(0).getNextSequenceNumber()); + assertFalse(m + "no longer waits for the ACK", mStreaming.mWaitForAck); + assertTrue(m + "the command is retired", mStreaming.getListofInstructions().isEmpty()); + assertFalse(m + "the next instruction can be sent", mStreaming.isInstructionStackLock()); + assertNull(m + "the ACK timer is cancelled", mStreaming.mTimerCheckForAckOrResp); + assertEquals(m + "the packets either side are parsed", + Arrays.asList(hex(payload(1)), hex(payload(2)), hex(payload(3))), parsed()); + } } /** - * Finding 5, the precondition: readEventChannelStatus() is queued behind a - * start of streaming that has not been acknowledged yet, so its reply comes - * once packets flow. + * Finding 5, the precondition: readEventChannelStatus() is not queued + * behind a start of streaming that has not been acknowledged yet. */ @Test public void finding5_theStatusIsNotQueuedBehindAStartOfStreaming() throws Exception { @@ -253,41 +291,46 @@ public void finding5_theStatusIsNotQueuedBehindAStartOfStreaming() throws Except } s.stopTimerCheckForAckOrResp(); s.stopTimerReadStatus(); - assertFalse("the status is queued after a start of streaming (sent=" + sent + ")", queuedAfterStart); + assertFalse("refused", sent); + assertFalse("the status is queued after a start of streaming", queuedAfterStart); } // ------------------------------------------------------------------ // Idle, with the IOThread running // ------------------------------------------------------------------ - private static class AnsweringRadio implements ByteCommunication { - final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); - void queue(byte... bytes) { for(byte b:bytes) rx.add(b); } - @Override public boolean writeBytes(byte[] buffer) { queue(ShimmerObject.ACK_COMMAND_PROCESSED); return true; } - @Override public byte[] readBytes(int n, int timeout) throws SerialPortTimeoutException { - if(rx.size() + *
  • {@link #queue(byte[]...)} adds a burst whole, under the same lock reads + * take, so the IOThread never sees half of it;
  • + *
  • a read waits up to its timeout for the bytes it asks for, as a serial + * port does, rather than failing the moment they are short.
  • + * + * Subclasses answer what the driver writes by overriding {@link #answer(byte[])}. + */ +abstract class WaitingTestRadio implements ByteCommunication { + + private final Deque mRx = new ArrayDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + + /** Adds the chunks as one burst: a read sees all of it or none of it */ + void queue(byte[]... chunks) { + synchronized(mRx) { + for(byte[] chunk:chunks) { + for(byte b:chunk) { + mRx.add(b); + } + } + } + } + + /** Adds single bytes as one burst */ + void queueBytes(byte... bytes) { + queue(bytes); + } + + /** The reply to one command the driver wrote, as one burst; empty for none */ + abstract byte[] answer(byte[] command); + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + byte[] reply = answer(buffer.clone()); + if(reply!=null && reply.length>0) { + queue(reply); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + long end = System.currentTimeMillis()+Math.max(timeout, 1); + while(true) { + synchronized(mRx) { + if(mRx.size()>=byteCount) { + byte[] out = new byte[byteCount]; + for(int i=0;i=end) { + throw new SerialPortTimeoutException("TEST", "readBytes", timeout); + } + try { + Thread.sleep(2); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw new SerialPortTimeoutException("TEST", "readBytes", timeout); + } + } + } + + @Override + public int getInputBufferBytesCount() { + synchronized(mRx) { + return mRx.size(); + } + } + + @Override public boolean isOpened() { return true; } + @Override public boolean closePort() { return true; } + @Override public boolean openPort() { return true; } + @Override public boolean setParams(int i, int j, int k, int l) { return true; } + @Override public boolean purgePort(int i) { return true; } + @Override public void setByteCommunicationListener(ByteCommunicationListener byteCommListener) { } + @Override public void removeRadioListenerList() { } + + /** The bytes of several chunks, in order */ + static byte[] concat(byte[]... chunks) { + int n = 0; + for(byte[] c:chunks) { + n += c.length; + } + byte[] out = new byte[n]; + int at = 0; + for(byte[] c:chunks) { + System.arraycopy(c, 0, out, at, c.length); + at += c.length; + } + return out; + } + +} From d7d7fd80ad58c381c570e357a45a95e32408454a Mon Sep 17 00:00:00 2001 From: JongChern Date: Fri, 13 Nov 2026 16:16:21 +0800 Subject: [PATCH 09/10] DEV-971: leave byte 233 out before a read; one NACK handler; renumber tests From the review of #343: - A Bluetooth configuration write before any read sent a Shimmer3R's byte 233 (DEV-99 audio mode and gain, DEV-1413 sound level) as 0, which turned the unit's audio mode off. It is now left out as byte 232 is, unless it was read or the sound level is turned on, on the same firmware. writeMem() takes a list of bytes to leave out. 3 of the 5 tests in API_00047_AudioConfigWriteTest fail without it. - The event channel probe's NACK now goes through processNackFromCommand(), which marks the event channel unsupported and does not report the NACK as a refused command. processEventChannelProbeNack() is gone. - API_00036_ButtonLogModeTest and API_00037_ButtonLogModeConfigWriteTest are now API_00045 and API_00046: master's log-start-refused tests have those numbers. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 111 +++++++------ .../shimmerresearch/driver/ShimmerObject.java | 10 ++ .../sensors/soundlevel/SensorSoundLevel.java | 15 ++ ....java => API_00045_ButtonLogModeTest.java} | 2 +- .../API_00038_EventChannelProbeTest.java | 16 ++ ...I_00046_ButtonLogModeConfigWriteTest.java} | 31 +++- .../API_00047_AudioConfigWriteTest.java | 150 ++++++++++++++++++ 7 files changed, 270 insertions(+), 65 deletions(-) rename ShimmerDriver/src/test/java/com/shimmerresearch/driver/{API_00036_ButtonLogModeTest.java => API_00045_ButtonLogModeTest.java} (99%) rename ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/{API_00037_ButtonLogModeConfigWriteTest.java => API_00046_ButtonLogModeConfigWriteTest.java} (93%) create mode 100644 ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index befd46761..32c08f967 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -987,12 +987,6 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } - /* Firmware without the event channel NACKs its probe. That NACK - * is an answer, not a failure, so it is taken here before the - * general refusal below. */ - else if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED && isEventChannelProbeInFlight()) { - processEventChannelProbeNack(); - } /* 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 @@ -2423,12 +2417,16 @@ else if(responseCommand==EVENT_CHANNEL_STATUS_RESPONSE) { *

    A refused log start is also taken for a log that did not start * ({@link #processLogStartRefused(byte)}). * + *

    A NACK of the event channel's probe ({@link #readEventChannelSupport()}) + * is an answer, not a failure: the firmware has no event channel. It is + * unwound the same way, but the application is not told that a command + * was refused. + * *

    Protected because ShimmerAndroidAPI's Shimmer has its own streaming * parser, which needs to fail the command in flight the same way. */ protected void processNackFromCommand() { stopTimerCheckForAckOrResp(); //cancel the ack timer - printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); byte refusedCommand = mCurrentCommand; @@ -2438,9 +2436,18 @@ protected void processNackFromCommand() { * skip that command. */ boolean instructionStillQueued = mWaitForAck; + //Asked before the instruction is removed, since it looks at it + boolean eventChannelProbe = instructionStillQueued && isEventChannelProbeInFlight(); + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand) + + (eventChannelProbe ? ", no event channel" : "")); + mWaitForAck=false; mWaitForResponse=false; + if(eventChannelProbe){ + setEventChannelSupported(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 @@ -2471,7 +2478,9 @@ protected void processNackFromCommand() { if(refusedCommand==START_LOGGING_ONLY_COMMAND || refusedCommand==START_SDBT_COMMAND){ processLogStartRefused(refusedCommand); } - eventCommandRefused(refusedCommand); + if(!eventChannelProbe){ + eventCommandRefused(refusedCommand); + } } /** @@ -5321,12 +5330,28 @@ public void writeConfigBytes(){ public void writeConfigBytes(boolean readBackAfter){ if(this.getFirmwareVersionCode()>=6){ byte[] configBytes = generateConfigBytesForWritingToShimmer(); - int idxButtonLogMode = (mConfigByteLayout instanceof ConfigByteLayoutShimmer3) ? ((ConfigByteLayoutShimmer3) mConfigByteLayout).idxButtonLogMode : 0; - if(idxButtonLogMode>0 && !isButtonLogModeKnown()){ - // Byte 232 (DEV-971) was never read from this Shimmer nor set, - // as when a configuration is written on connect before it is - // read. Skip it, so that the Shimmer keeps its own. - writeMem(SET_INFOMEM_COMMAND, mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, idxButtonLogMode); + // Bytes the driver does not have from this Shimmer, as when a + // configuration is written on connect before it is read. They + // are skipped, so that the Shimmer keeps its own. Only on + // firmware that can have byte 232: older firmware is still + // written in whole chunks. + List skipIndexes = new ArrayList(); + if(mConfigByteLayout instanceof ConfigByteLayoutShimmer3){ + ConfigByteLayoutShimmer3 configByteLayoutCast = (ConfigByteLayoutShimmer3) mConfigByteLayout; + if(configByteLayoutCast.idxButtonLogMode>0){ + // Byte 232 (DEV-971), neither read nor set + if(!isButtonLogModeKnown()){ + skipIndexes.add(configByteLayoutCast.idxButtonLogMode); + } + // Byte 233 (DEV-99, DEV-1413) on a Shimmer3R, not read + // and the sound level not turned on + if(configByteLayoutCast.idxAudioConfig>0 && !isAudioConfigKnown()){ + skipIndexes.add(configByteLayoutCast.idxAudioConfig); + } + } + } + if(!skipIndexes.isEmpty()){ + writeMem(SET_INFOMEM_COMMAND, mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, skipIndexes); if(readBackAfter){ readConfigBytes(); } @@ -5354,19 +5379,19 @@ public void writeConfigBytes(int startAddress, byte[] buf, int maxMemAddress, bo } public void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress){ - writeMem(command, startAddress, buf, maxMemAddress, -1); + writeMem(command, startAddress, buf, maxMemAddress, Collections.emptyList()); } /** * Writes buf in chunks of up to 128 bytes, as {@link #writeMem(int, int, byte[], int)} - * does, but leaves out the byte at skipIndex: the chunk holding it goes as - * the bytes before it and the bytes after it. Every other chunk starts - * where it would have, which matters to the firmware for the chunks at 0 - * and 128. + * does, but leaves out the bytes at skipIndexes: a chunk holding any goes + * as the runs of bytes between them, each at its own address. Every other + * chunk starts where it would have, which matters to the firmware for the + * chunks at 0 and 128. * - * @param skipIndex the index into buf of the byte not to write, or -1 to write them all + * @param skipIndexes the indexes into buf of the bytes not to write, empty to write them all */ - private void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress, int skipIndex){ + private void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress, List skipIndexes){ this.mNumOfMemSetCmds = 0; if(this.getFirmwareVersionCode()>=6){ @@ -5390,23 +5415,18 @@ private void writeMem(int command, int startAddress, byte[] buf, int maxMemAddre currentPacketNumBytes = numBytesRemaining; } + // The chunk, or its runs between the bytes skipped int chunkEnd = currentBytePointer + currentPacketNumBytes; - if(skipIndex>=currentBytePointer && skipIndexcurrentBytePointer){ - writeMemCommand(command, currentStartAddr, Arrays.copyOfRange(buf, currentBytePointer, skipIndex)); - mNumOfMemSetCmds += 1; - } - if(skipIndex+1runStart){ + writeMemCommand(command, currentStartAddr + (runStart-currentBytePointer), Arrays.copyOfRange(buf, runStart, i)); + mNumOfMemSetCmds += 1; + } + runStart = i+1; } } - else { - byte[] infoSegBuf = Arrays.copyOfRange(buf, currentBytePointer, chunkEnd); - - writeMemCommand(command, currentStartAddr, infoSegBuf); - mNumOfMemSetCmds += 1; - } currentStartAddr += currentPacketNumBytes; numBytesRemaining -= currentPacketNumBytes; @@ -5494,27 +5514,6 @@ private boolean isEventChannelProbeInFlight() { && instruction[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal(); } - /** - * The firmware NACKed FEATURE_EVENT_STREAM, so it has no event channel. - * Completes the command as an ACK does, the progress report included, so - * that the connection stays up and the operation it is part of finishes. - */ - private void processEventChannelProbeNack() { - stopTimerCheckForAckOrResp(); //cancel the ack timer - mWaitForAck=false; - printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand) + ", no event channel"); - - setEventChannelSupported(false); - - if(mOperationUnderway){ - sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, getComPort())); - } - removeInstruction(0); - - mTransactionCompleted = true; - 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 diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 52f084551..dcf10063e 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -6774,6 +6774,16 @@ public boolean isButtonLogModeKnown() { return mIsButtonLogModeKnown; } + /** + * Whether the driver has the Shimmer3R's own byte 233, the microphone's + * configuration ({@link SensorSoundLevel#isAudioConfigKnown()}). True + * where there is no such byte. + */ + public boolean isAudioConfigKnown() { + AbstractSensor abstractSensor = getSensorClass(AbstractSensor.SENSORS.SOUND_LEVEL); + return !(abstractSensor instanceof SensorSoundLevel) || ((SensorSoundLevel) abstractSensor).isAudioConfigKnown(); + } + /** * Whether byte 232 can be taken at its word: the Shimmer answered the event * channel probe, or the byte holds a value the firmware keeps. Firmware 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 8365b00c3..092877676 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -74,6 +74,8 @@ public class SensorSoundLevel extends AbstractSensor { /** Byte 233's audio mode and gain preset as read (bits 0-3, DEV-99), written back as they are */ private int mAudioModeAndGain = 0; + /** Whether byte 233 has been read from the Shimmer, and so mAudioModeAndGain is its own */ + private boolean mIsAudioConfigRead = false; public class GuiLabelSensors{ public static final String SOUND_LEVEL = "Sound Level"; @@ -241,6 +243,7 @@ public void configBytesParse(ShimmerDevice shimmerDevice, byte[] configBytes, CO value = 0; } mAudioModeAndGain = value & configByteLayoutCast.maskAudioModeAndGain; + mIsAudioConfigRead = true; SensorDetails sensorDetails = mSensorMap.get(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); if(sensorDetails!=null){ @@ -264,6 +267,18 @@ public int getAudioModeAndGain() { return mAudioModeAndGain; } + /** + * Whether a configuration write has a byte 233 to give: it was read from + * the Shimmer, or the sound level is on, the one part of it set here. + * Before a read, bits 0-3 are not known, and writing them as 0 would turn + * the Shimmer's audio mode off. With the sound level turned on before a + * read they are written as 0 all the same, since one bit cannot be written + * on its own. + */ + public boolean isAudioConfigKnown() { + return mIsAudioConfigRead || isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); + } + @Override public Object setConfigValueUsingConfigLabel(Integer sensorId, String configLabel, Object valueToSet) { return super.setConfigValueUsingConfigLabelCommon(sensorId, configLabel, valueToSet); diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java similarity index 99% rename from ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java rename to ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java index ec895edf9..647205381 100644 --- a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00036_ButtonLogModeTest.java +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java @@ -23,7 +23,7 @@ * * @author Mark Nolan */ -public class API_00036_ButtonLogModeTest { +public class API_00045_ButtonLogModeTest { /** What a press does, in the table's words */ private enum PRESS { diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java index 58e7a74c7..2990a817f 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java @@ -105,12 +105,19 @@ public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutExce private static class WatchedShimmer extends ShimmerPC { private static final long serialVersionUID = 1L; final List progressReports = Collections.synchronizedList(new ArrayList()); + final List commandsRefused = Collections.synchronizedList(new ArrayList()); volatile boolean connectionLost = false; WatchedShimmer() { super("COM99"); } + @Override + protected void eventCommandRefused(byte command) { + commandsRefused.add(command); + super.eventCommandRefused(command); + } + @Override protected void sendProgressReport(BluetoothProgressReportPerCmd pRPC) { progressReports.add((byte) pRPC.mCommandCompleted); @@ -180,6 +187,15 @@ public void aNackMeansItIsNotAndTheConnectionStaysUp() throws Exception { assertFalse(mDevice.connectionLost); } + @Test + public void theProbesNackIsAnAnswerNotARefusal() throws Exception { + connectedShimmer(S3R_V1_1_25, ShimmerObject.NACK_COMMAND_PROCESSED); + mDevice.readEventChannelSupport(); + waitForInstructionsDone(2000); + assertEquals(Boolean.FALSE, mDevice.isEventChannelSupported()); + assertTrue("the application is not told a command was refused", mDevice.commandsRefused.isEmpty()); + } + @Test public void aNackStillCountsTowardsTheOperation() throws Exception { connectedShimmer(S3R_V1_1_25, ShimmerObject.NACK_COMMAND_PROCESSED); diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00046_ButtonLogModeConfigWriteTest.java similarity index 93% rename from ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java rename to ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00046_ButtonLogModeConfigWriteTest.java index 1ad040e28..a974f217e 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00037_ButtonLogModeConfigWriteTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00046_ButtonLogModeConfigWriteTest.java @@ -34,7 +34,7 @@ * * @author Mark Nolan */ -public class API_00037_ButtonLogModeConfigWriteTest { +public class API_00046_ButtonLogModeConfigWriteTest { private static final int IDX_BUTTON_LOG_MODE = 232; private static final int IDX_TRIAL_CONFIG0 = 217; @@ -282,13 +282,12 @@ private static int[][] allChunks(ShimmerBluetooth shimmer) { return chunks; } - /** The same, with the chunk at 128 sent either side of byte 232 */ - private static int[][] chunksWithout232(ShimmerBluetooth shimmer) { + /** The same, with the chunk at 128 sent as the parts given */ + private static int[][] chunk128As(ShimmerBluetooth shimmer, int[]... parts) { List chunks = new ArrayList(); for(int[] chunk:allChunks(shimmer)){ if(chunk[0]==128){ - chunks.add(new int[] {128, 104}); - chunks.add(new int[] {233, 23}); + chunks.addAll(Arrays.asList(parts)); } else { chunks.add(chunk); @@ -297,14 +296,30 @@ private static int[][] chunksWithout232(ShimmerBluetooth shimmer) { return chunks.toArray(new int[0][]); } + /** Either side of byte 232 */ + private static int[][] chunksWithout232(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 104}, new int[] {233, 23}); + } + + /** Either side of bytes 232 and 233: a Shimmer3R's, before a read (API_00047) */ + private static int[][] chunksWithout232And233(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 104}, new int[] {234, 22}); + } + + /** Either side of byte 233 */ + private static int[][] chunksWithout233(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 105}, new int[] {234, 22}); + } + @Test public void beforeAReadTheBluetoothWriteLeavesTheShimmersByte() { ProbedShimmer shimmer = shimmer(S3R_EVENT_CHANNEL_CAPABLE); assertFalse(shimmer.isButtonLogModeKnown()); shimmer.writeConfigBytes(false); - assertChunks("a configuration written on connect, before the read", chunksWithout232(shimmer), shimmer); + assertChunks("a configuration written on connect, before the read; a Shimmer3R's byte 233 is left out too", + chunksWithout232And233(shimmer), shimmer); - // The bytes either side of 232 are the image's + // The bytes either side of 232 and 233 are the image's byte[] image = shimmer.generateConfigBytesForWritingToShimmer(); for(byte[] instruction:shimmer.getListofInstructions()){ if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ @@ -328,7 +343,7 @@ public void onceReadOrSetTheBluetoothWriteHasTheByte() { ProbedShimmer set = shimmer(S3R_EVENT_CHANNEL_CAPABLE); set.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); set.writeConfigBytes(false); - assertChunks("set", allChunks(set), set); + assertChunks("set, with byte 233 still unread", chunksWithout233(set), set); byte[] chunk = infoMemChunkAt(set, 128); assertEquals("set, before anything was read", 0x01, chunk[4 + IDX_BUTTON_LOG_MODE - 128] & 0xFF); } diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java new file mode 100644 index 000000000..caa774473 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java @@ -0,0 +1,150 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import org.junit.Test; + +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +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; + +/** + * Configuration byte 233 on a Shimmer3R (DEV-99 audio mode and gain in bits + * 0-3, DEV-1413 sound level in bit 4) through a Bluetooth configuration write. + * The host can set bit 4 but never bits 0-3, which it only gives back as read. + * So before a read, the write leaves the byte out, as it does byte 232 + * (API_00046), and the Shimmer keeps its own. The one exception is the sound + * level turned on before a read: the byte is then written with bits 0-3 at 0, + * since a SET_INFOMEM cannot write one bit. + *

    + * No hardware. It lives in this package because the instruction list is a + * protected member of ShimmerBluetooth. + */ +public class API_00047_AudioConfigWriteTest { + + private static final int IDX_BUTTON_LOG_MODE = 232; + private static final int IDX_AUDIO_CONFIG = 233; + private static final int SOUND_LEVEL_BIT = 0x10; + + /** v1.01.026, the first release with the sound level */ + 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"); + shimmer.setShimmerVersionObjectAndCreateSensorMap(S3R); + return shimmer; + } + + private static ShimmerPC readFrom(int buttonLogMode, int audioConfig) { + byte[] config = shimmer().generateConfigBytesForWritingToShimmer().clone(); + config[IDX_BUTTON_LOG_MODE] = (byte) buttonLogMode; + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + ShimmerPC shimmer = shimmer(); + shimmer.configBytesParse(config, COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + /** Each SET_INFOMEM queued: [0x8C, length, address LSB, address MSB, data...] */ + private static List infoMemWrites(ShimmerBluetooth shimmer) { + List writes = new ArrayList(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + writes.add(instruction); + } + } + return writes; + } + + private static int address(byte[] write) { + return (write[2]&0xFF) | ((write[3]&0xFF)<<8); + } + + private static int length(byte[] write) { + return write[1]&0xFF; + } + + /** The value written at idx, or -1 if no SET_INFOMEM covers it */ + private static int writtenAt(ShimmerBluetooth shimmer, int idx) { + for(byte[] write:infoMemWrites(shimmer)){ + if(idx>=address(write) && idx chunks(ShimmerBluetooth shimmer) { + List chunks = new ArrayList(); + for(byte[] write:infoMemWrites(shimmer)){ + chunks.add(Arrays.toString(new int[] {address(write), length(write)})); + } + return chunks; + } + + @Test + public void beforeAReadTheBluetoothWriteLeavesTheShimmersAudioByte() { + ShimmerPC shimmer = shimmer(); + shimmer.writeConfigBytes(false); + assertEquals("a configuration written on connect, before the read, would turn the Shimmer's audio mode and sound level off", + -1, writtenAt(shimmer, IDX_AUDIO_CONFIG)); + } + + @Test + public void beforeAReadBytes232And233AreBothLeftOut() { + ShimmerPC shimmer = shimmer(); + shimmer.writeConfigBytes(false); + int length = shimmer.generateConfigBytesForWritingToShimmer().length; + List wanted = new ArrayList(); + for(int address=0;address Date: Fri, 13 Nov 2026 17:24:19 +0800 Subject: [PATCH 10/10] DEV-1459: an audio mode set before a read is written; renumber a test - Master's byte 233 rule (#351) leaves the byte out of a configuration written before it is read, unless it was read or the sound level is on. An audio mode set here before a read was therefore not written. SensorSoundLevel.isAudioConfigKnown() now takes the device and also counts an audio mode that differs from the one read, the same test configBytesGenerate() uses to write it. Off set before a read still leaves the Shimmer's own. API_00047 gains two tests; the first failed on the merged code. - API_00042_Shimmer3rAudioStatusTest is now API_00048: master's API_00042_EventRecordFileTest has that number. Co-Authored-By: Claude Opus 5.5 --- .../bluetooth/ShimmerBluetooth.java | 4 +-- .../shimmerresearch/driver/ShimmerObject.java | 6 ++-- .../sensors/soundlevel/SensorSoundLevel.java | 22 ++++++++++----- .../API_00047_AudioConfigWriteTest.java | 28 +++++++++++++++---- ...> API_00048_Shimmer3rAudioStatusTest.java} | 2 +- 5 files changed, 44 insertions(+), 18 deletions(-) rename ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/{API_00042_Shimmer3rAudioStatusTest.java => API_00048_Shimmer3rAudioStatusTest.java} (98%) diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 027829602..e0f241f43 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -5402,8 +5402,8 @@ public void writeConfigBytes(boolean readBackAfter){ if(!isButtonLogModeKnown()){ skipIndexes.add(configByteLayoutCast.idxButtonLogMode); } - // Byte 233 (DEV-99, DEV-1413) on a Shimmer3R, not read - // and the sound level not turned on + // Byte 233 (DEV-99, DEV-1413) on a Shimmer3R, neither read + // nor set (the sound level or the audio mode) if(configByteLayoutCast.idxAudioConfig>0 && !isAudioConfigKnown()){ skipIndexes.add(configByteLayoutCast.idxAudioConfig); } diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 65ceee4b2..8d450164b 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -6812,12 +6812,12 @@ public boolean isButtonLogModeKnown() { /** * Whether the driver has the Shimmer3R's own byte 233, the microphone's - * configuration ({@link SensorSoundLevel#isAudioConfigKnown()}). True - * where there is no such byte. + * configuration ({@link SensorSoundLevel#isAudioConfigKnown(ShimmerDevice)}). + * True where there is no such byte. */ public boolean isAudioConfigKnown() { AbstractSensor abstractSensor = getSensorClass(AbstractSensor.SENSORS.SOUND_LEVEL); - return !(abstractSensor instanceof SensorSoundLevel) || ((SensorSoundLevel) abstractSensor).isAudioConfigKnown(); + return !(abstractSensor instanceof SensorSoundLevel) || ((SensorSoundLevel) abstractSensor).isAudioConfigKnown(this); } /** 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 bbf606eee..7dbb508b8 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -283,14 +283,22 @@ public int getAudioModeAndGain() { /** * Whether a configuration write has a byte 233 to give: it was read from - * the Shimmer, or the sound level is on, the one part of it set here. - * Before a read, bits 0-3 are not known, and writing them as 0 would turn - * the Shimmer's audio mode off. With the sound level turned on before a - * read they are written as 0 all the same, since one bit cannot be written - * on its own. + * the Shimmer, or a part of it was set here, the sound level turned on or + * the audio mode (DEV-1459) changed from the one read. Before a read, bits + * 0-3 are not known, and writing them as 0 would turn the Shimmer's audio + * mode off. With the sound level or an audio mode set before a read, the + * rest of bits 0-3 are written as 0 all the same, since one bit cannot be + * written on its own. An audio mode set back to Off before a read looks + * like one never set, so the Shimmer keeps its own. */ - public boolean isAudioConfigKnown() { - return mIsAudioConfigRead || isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); + public boolean isAudioConfigKnown(ShimmerDevice shimmerDevice) { + if(mIsAudioConfigRead || isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)){ + return true; + } + // As configBytesGenerate() decides whether to write the mode set here + ConfigByteLayout configByteLayout = shimmerDevice.getConfigByteLayout(); + return isAudioModeSupported(shimmerDevice) && configByteLayout instanceof ConfigByteLayoutShimmer3 + && ((ShimmerObject) shimmerDevice).getAudioMode()!=(mAudioModeAndGain & ((ConfigByteLayoutShimmer3) configByteLayout).maskAudioMode); } @Override diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java index caa774473..4e23f4b04 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java @@ -19,11 +19,12 @@ /** * Configuration byte 233 on a Shimmer3R (DEV-99 audio mode and gain in bits * 0-3, DEV-1413 sound level in bit 4) through a Bluetooth configuration write. - * The host can set bit 4 but never bits 0-3, which it only gives back as read. - * So before a read, the write leaves the byte out, as it does byte 232 - * (API_00046), and the Shimmer keeps its own. The one exception is the sound - * level turned on before a read: the byte is then written with bits 0-3 at 0, - * since a SET_INFOMEM cannot write one bit. + * The host can set bit 4 and the audio mode (bits 0-1, DEV-1459), but not the + * gain preset (bits 2-3), which it only gives back as read. So before a read, + * the write leaves the byte out, as it does byte 232 (API_00046), and the + * Shimmer keeps its own. The exceptions are the sound level turned on, or an + * audio mode set, before a read: the byte is then written with the rest of + * bits 0-3 at 0, since a SET_INFOMEM cannot write one bit. *

    * No hardware. It lives in this package because the instruction list is a * protected member of ShimmerBluetooth. @@ -147,4 +148,21 @@ public void byte232SetBeforeAReadIsWrittenWithout233() { assertEquals(0x01, writtenAt(shimmer, IDX_BUTTON_LOG_MODE)); assertEquals(-1, writtenAt(shimmer, IDX_AUDIO_CONFIG)); } + + /** DEV-1459: the audio mode, bits 0-1, can be set here too */ + @Test + public void anAudioModeSetBeforeAReadIsWritten() { + ShimmerPC shimmer = shimmer(); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.AUDIO_MODE, Configuration.Shimmer3.AUDIO_MODE_FINGERPRINT); + shimmer.writeConfigBytes(false); + assertEquals("the mode set, with the rest of the byte at 0", Configuration.Shimmer3.AUDIO_MODE_FINGERPRINT, writtenAt(shimmer, IDX_AUDIO_CONFIG)); + } + + @Test + public void anAudioModeLeftAsItIsBeforeAReadIsLeftOut() { + ShimmerPC shimmer = shimmer(); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.AUDIO_MODE, Configuration.Shimmer3.AUDIO_MODE_OFF); + shimmer.writeConfigBytes(false); + assertEquals("Off is the default, so it says nothing about the Shimmer's own", -1, writtenAt(shimmer, IDX_AUDIO_CONFIG)); + } } diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java similarity index 98% rename from ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java rename to ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java index a6dffd464..9aff543cb 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java @@ -12,7 +12,7 @@ * DEV-1459: status byte 1 bits 1-2, audio recording and audio fault * (log-and-stream-common SHIMMER3R_AUDIO.md ยง5). No hardware. */ -public class API_00042_Shimmer3rAudioStatusTest { +public class API_00048_Shimmer3rAudioStatusTest { /** Reaches the status parser, which the driver calls on each status frame */ private static class StatusShimmer extends ShimmerPC {