diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 3129b2721..423ae2357 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -2625,7 +2625,7 @@ private void initializeShimmer3or3R(int hardwareVersion){ //readExpansionBoardID(); if (isBtCrcModeSupported()) { - writeBtCommsCrcMode(DEFAULT_BT_CRC_MODE_IF_SUPPORTED); + writeBtCommsCrcMode(getBtCrcModeToUseOnConnect()); } else if (DEFAULT_BT_CRC_MODE_IF_SUPPORTED!=BT_CRC_MODE.OFF && isBtCrcClearedWhenSensingStops()) { printLogDataForDebugging("Link CRC left off: " + getFirmwareVersionParsed() + " on a Shimmer3R drops it whenever sensing stops; v1.0.11 and later keep it"); @@ -5028,13 +5028,17 @@ public boolean enableBtCommsTwoByteCrc() { /** * Queues SET_CRC_COMMAND. Turning a CRC on is refused wherever - * {@link #isBtCrcModeSupported()} is false. Turning it off is refused only by - * firmware without the command. + * {@link #isBtCrcModeSupported()} is false, and a 2-byte CRC also wherever + * {@link #isTwoByteCrcOverrunningStatusPush()} is true. Turning it off is + * refused only by firmware without the command. * * @param btCrcMode * @return false if nothing was queued */ public boolean writeBtCommsCrcMode(BT_CRC_MODE btCrcMode) { + if (btCrcMode==BT_CRC_MODE.TWO_BYTE_CRC && isTwoByteCrcOverrunningStatusPush()) { + return false; + } boolean isAllowed = btCrcMode==BT_CRC_MODE.OFF ? getFirmwareVersionCode() >= 8 : isBtCrcModeSupported(); if (isAllowed) { writeInstruction(new byte[] { SET_CRC_COMMAND, (byte) (btCrcMode.ordinal()) }); @@ -5047,7 +5051,8 @@ public boolean writeBtCommsCrcMode(BT_CRC_MODE btCrcMode) { * Sets the default mode that should be used when establishing a connection to * the Shimmer if the current firmware version supports the CRC feature. * Shimmer3R LogAndStream before v1.00.011 counts as not supporting it; see - * {@link #isBtCrcModeSupported()}. + * {@link #isBtCrcModeSupported()}. A 2-byte CRC falls back to 1 byte where + * the firmware cannot take 2; see {@link #isTwoByteCrcOverrunningStatusPush()}. * * @param btCommsCrcMode */ @@ -5057,9 +5062,9 @@ public static void setDefaultBtCrcModeToUseIfFwSupported(BT_CRC_MODE btCommsCrcM /** * Gets the default CRC mode that will attempted to be used when establishing a - * connection to the Shimmer. If a connection has already been established and - * the firmware version has been read, this function will return the actual CRC - * mode that's in use. + * connection to the Shimmer. This is the setting, not necessarily what a + * connected Shimmer uses, which {@link #getCurrentBtCommsCrcMode()} returns: on + * some firmware the driver leaves the CRC off, or uses 1 byte in place of 2. * * @return */ @@ -5132,6 +5137,50 @@ && getFirmwareIdentifier()==FW_ID.LOGANDSTREAM && !isThisVerCompatibleWith(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 11); } + /** + * True for Shimmer3R LogAndStream v1.00.024 to v1.00.049, where a 2-byte link + * CRC overruns the unsolicited status push. Those releases build the push in a + * six-byte buffer, uint8_t selfcmd[6] (ShimBt_instreamStatusRespSend, + * log-and-stream-common Comms/shimmer_bt_uart.c:2262 at f39be8c1f). The push is + * the ACK prefix, 0x8A 0x71 and two status bytes, so a 2-byte CRC makes seven + * bytes and the seventh lands past the end of the buffer: the sensor hardfaults + * (DEV-621). v1.00.050 sized the buffer for it. The firmware pushes on docking + * and undocking, the user button, a trial-duration expiry and a low-battery + * stop, so the fault can come at any point in a session. + *

+ * A 1-byte CRC, one status byte (v1.00.023 and earlier, and every Shimmer3) or + * the ACK prefix turned off (SET_INSTREAM_RESPONSE_ACK_PREFIX_STATE, 0xA3) each + * make the push six bytes, which fits. This driver keeps the prefix, because its + * in-stream parsers expect it, so the 2-byte CRC is what has to go. + *

+ * Derived from the firmware source; not yet run against a Shimmer3R on + * v1.00.024 to v1.00.049. + * + * @return + */ + public boolean isTwoByteCrcOverrunningStatusPush() { + // Two status bytes: Shimmer3R LogAndStream v1.00.024 and later + return isSupportedUSBPluggedInStatus() + && !isThisVerCompatibleWith(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 50); + } + + /** + * The CRC mode to ask for when connecting: the default, except that a 2-byte + * default falls back to 1 byte wherever + * {@link #isTwoByteCrcOverrunningStatusPush()} is true. One byte is the low + * byte of the same CRC, so the link keeps its check. + * + * @return + */ + protected BT_CRC_MODE getBtCrcModeToUseOnConnect() { + if (DEFAULT_BT_CRC_MODE_IF_SUPPORTED==BT_CRC_MODE.TWO_BYTE_CRC && isTwoByteCrcOverrunningStatusPush()) { + printLogDataForDebugging("Link CRC cut to 1 byte: " + getFirmwareVersionParsed() + + " on a Shimmer3R overruns its status push with 2; v1.0.50 and later take 2"); + return BT_CRC_MODE.ONE_BYTE_CRC; + } + return DEFAULT_BT_CRC_MODE_IF_SUPPORTED; + } + /**** DISABLE FUNCTIONS *****/ private long disableBit(long number,long disablebitvalue){ diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00026_Shimmer3rTwoByteCrcGateTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00026_Shimmer3rTwoByteCrcGateTest.java new file mode 100644 index 000000000..4aa59dee0 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00026_Shimmer3rTwoByteCrcGateTest.java @@ -0,0 +1,139 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +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; + +/** + * DEV-1143: Shimmer3R LogAndStream v1.00.024 to v1.00.049 build the unsolicited + * status push in a six-byte buffer. With a 2-byte link CRC the push is seven + * bytes, so the sensor hardfaults the next time it pushes: on docking or + * undocking, the user button, a trial-duration expiry or a low battery (DEV-621, + * fixed in v1.00.050). The driver must never send those releases a 2-byte + * SET_CRC_COMMAND: a 2-byte default falls back to 1 byte when connecting, and + * asking for 2 bytes is refused. + *

+ * The overrun needs two status bytes, which start at v1.00.024 and which no + * Shimmer3 sends, so a Shimmer3 with the same version numbers keeps 2 bytes. + *

+ * No hardware: the connect path writes getBtCrcModeToUseOnConnect(), so that + * and the instruction stack are what these check. It lives in this package + * because both are protected members of ShimmerBluetooth. + * + * @author Mark Nolan + */ +public class API_00026_Shimmer3rTwoByteCrcGateTest { + + private final BT_CRC_MODE mDefaultBtCrcMode = ShimmerBluetooth.getDefaultBtCrcModeIfFwSupported(); + + @After + public void restoreDefaultBtCrcMode() { + // The default is static, so one set here would carry into later tests + ShimmerBluetooth.setDefaultBtCrcModeToUseIfFwSupported(mDefaultBtCrcMode); + } + + private static ShimmerPC device(int hardwareVersion, int fwMajor, int fwMinor, int fwInternal) { + ShimmerPC device = new ShimmerPC("COM99"); + device.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(hardwareVersion, FW_ID.LOGANDSTREAM, fwMajor, fwMinor, fwInternal)); + return device; + } + + private static String describe(ShimmerPC device) { + return device.getHardwareVersionParsed() + " " + device.getFirmwareVersionParsed(); + } + + /** The argument of every SET_CRC_COMMAND on the instruction stack, in order */ + private static List queuedCrcModes(ShimmerPC device) { + List modes = new ArrayList(); + for(byte[] instruction:device.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_CRC_COMMAND){ + modes.add((int) instruction[1]); + } + } + return modes; + } + + private static ShimmerPC[] overrunning() { + return new ShimmerPC[] { + device(HW_ID.SHIMMER_3R, 1, 0, 24), // the first with two status bytes + device(HW_ID.SHIMMER_3R, 1, 0, 49) // the last with selfcmd[6] + }; + } + + private static ShimmerPC[] withRoom() { + return new ShimmerPC[] { + device(HW_ID.SHIMMER_3R, 1, 0, 23), // one status byte + device(HW_ID.SHIMMER_3R, 1, 0, 50), // the buffer fix + // The internal number restarts at each minor release, so it cannot + // decide on its own + device(HW_ID.SHIMMER_3R, 1, 1, 0), + device(HW_ID.SHIMMER_3, 1, 0, 30) // one status byte + }; + } + + @Test + public void twoByteCrcIsRefusedWhereItOverrunsThePush() { + for(ShimmerPC device:overrunning()){ + String label = describe(device); + assertTrue(label, device.isTwoByteCrcOverrunningStatusPush()); + assertFalse(label, device.enableBtCommsTwoByteCrc()); + assertFalse(label, device.writeBtCommsCrcMode(BT_CRC_MODE.TWO_BYTE_CRC)); + assertEquals(label + ": nothing is sent", Arrays.asList(), queuedCrcModes(device)); + } + } + + @Test + public void oneByteCrcAndOffAreStillSentWhereTwoBytesOverrun() { + for(ShimmerPC device:overrunning()){ + String label = describe(device); + assertTrue(label, device.enableBtCommsOneByteCrc()); + assertTrue(label, device.disableBtCommsCrc()); + assertEquals(label, Arrays.asList(BT_CRC_MODE.ONE_BYTE_CRC.ordinal(), BT_CRC_MODE.OFF.ordinal()), queuedCrcModes(device)); + } + } + + @Test + public void twoByteCrcIsSentWhereThePushHasRoom() { + for(ShimmerPC device:withRoom()){ + String label = describe(device); + assertFalse(label, device.isTwoByteCrcOverrunningStatusPush()); + assertTrue(label, device.enableBtCommsTwoByteCrc()); + assertEquals(label, Arrays.asList(BT_CRC_MODE.TWO_BYTE_CRC.ordinal()), queuedCrcModes(device)); + } + } + + @Test + public void twoByteDefaultFallsBackToOneByteWhenConnecting() { + ShimmerBluetooth.setDefaultBtCrcModeToUseIfFwSupported(BT_CRC_MODE.TWO_BYTE_CRC); + for(ShimmerPC device:overrunning()){ + assertEquals(describe(device), BT_CRC_MODE.ONE_BYTE_CRC, device.getBtCrcModeToUseOnConnect()); + } + // Only that connection falls back: the setting stands for the next device + assertEquals(BT_CRC_MODE.TWO_BYTE_CRC, ShimmerBluetooth.getDefaultBtCrcModeIfFwSupported()); + for(ShimmerPC device:withRoom()){ + assertEquals(describe(device), BT_CRC_MODE.TWO_BYTE_CRC, device.getBtCrcModeToUseOnConnect()); + } + } + + @Test + public void otherDefaultsAreUnchangedWhenConnecting() { + for(BT_CRC_MODE btCrcMode:new BT_CRC_MODE[] {BT_CRC_MODE.OFF, BT_CRC_MODE.ONE_BYTE_CRC}){ + ShimmerBluetooth.setDefaultBtCrcModeToUseIfFwSupported(btCrcMode); + for(ShimmerPC device:overrunning()){ + assertEquals(describe(device), btCrcMode, device.getBtCrcModeToUseOnConnect()); + } + } + } +}