diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index d23354449..1c980b362 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java @@ -317,6 +317,7 @@ public enum SHIMMER_FEATURE { aMap.put(DATA_PACKET, new BtCommandDetails(DATA_PACKET, "DATA_PACKET")); aMap.put(ROUTINE_COMMUNICATION, new BtCommandDetails(ROUTINE_COMMUNICATION, "ROUTINE_COMMUNICATION")); aMap.put(ACK_COMMAND_PROCESSED, new BtCommandDetails(ACK_COMMAND_PROCESSED, "ACK_COMMAND_PROCESSED")); + aMap.put(NACK_COMMAND_PROCESSED, new BtCommandDetails(NACK_COMMAND_PROCESSED, "NACK_COMMAND_PROCESSED")); mBtCommandMapOther = Collections.unmodifiableMap(aMap); } @@ -933,6 +934,14 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } + /* The Shimmer refused the command. Without this branch the NACK + * was discarded, mWaitForAck stayed true and the instruction stack + * stayed locked until the ACK timer expired and tore the + * connection down - a refusal was indistinguishable from a dead + * link. */ + else if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED) { + processNackFromCommand(); + } } } } @@ -944,8 +953,15 @@ private void processNotStreamingWaitForResp() { if(byteBuffer!=null){ setIamAlive(true); + /* A NACK can arrive here rather than in the ACK state if the + * firmware decides it cannot serve a GET only while building the + * response. Checked before isKnownResponse() so it is handled as a + * refusal rather than falling through to the ACK timeout. */ + if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED){ + processNackFromCommand(); + } //Check to see whether it is a response byte - if(isKnownResponse(byteBuffer[0])){ + else if(isKnownResponse(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; processResponseCommand(responseCommand); @@ -985,7 +1001,14 @@ && bytesAvailableToBeRead()) { byteBuffer=readBytes(1); if(byteBuffer!=null){ - if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { + /* Deliberately log-only: this path runs with no command in + * flight (!mWaitForAck && !mWaitForResponse), so there is no + * transaction to fail and a stray 0xFE must not be turned into a + * refusal. The buffer is cleared below either way. */ + if(byteBuffer[0]==NACK_COMMAND_PROCESSED) { + printLogDataForDebugging("NACK received with no command awaiting a reply - ignored"); + } + else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { printLogDataForDebugging("ACK RECEIVED , Connected State!!"); byteBuffer = readBytes(1, INSTREAM_CMD_RESPONSE); if(byteBuffer!=null && byteBuffer[0]==ACK_COMMAND_PROCESSED){ //an android fix.. not fully investigated (JC) @@ -1108,6 +1131,25 @@ else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTR } } + //Data packet followed by a NACK (a command refused while streaming, e.g. + //any SET blocked by the firmware because it is sensing) + else if(bufferTemp[0]==DATA_PACKET + && bufferTemp[getPacketSizeWithCrc()+1]==NACK_COMMAND_PROCESSED){ + + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF && !checkCrc(bufferTemp, getPacketSize() + 1)) { + discardBufferBytesToNextPacket(); + return; + } + + //Handle the data packet first, then fail the command in flight + processDataPacket(bufferTemp); + processNackFromCommand(); + + /* clearBuffers() rather than clearSingleDataPacketFromBuffers(), + * because the NACK is a single byte with no payload behind it and that + * helper would push it back as the next packet header. */ + clearBuffers(); + } //TODO: ACK in bufferTemp[0] not handled //else if else { @@ -1545,13 +1587,14 @@ protected void clearBuffers() { } /** - * Next packet start should begin with DATA_PACKET or ACK_COMMAND_PROCESSED byte so skip to that point + * Next packet start should begin with DATA_PACKET, ACK_COMMAND_PROCESSED or + * NACK_COMMAND_PROCESSED byte so skip to that point */ protected void discardBufferBytesToNextPacket(){ byte[] bTemp = mByteArrayOutputStream.toByteArray(); - //Find index of first DATA_PACKET or ACK byte within the buffer - int offset = findOffsetOfNextZeroOrFF(bTemp); + //Find index of first DATA_PACKET, ACK or NACK byte within the buffer + int offset = findOffsetOfNextPacketBoundary(bTemp); //If not found, just skip one byte offset = (offset == -1) ? 1 : offset; @@ -1565,15 +1608,16 @@ protected void discardBufferBytesToNextPacket(){ } /** - * Finds the offset/index of the next DATA_PACKET (0x00) or ACK_COMMAND_PROCESSED (0xFF) byte. + * Finds the offset/index of the next DATA_PACKET (0x00), ACK_COMMAND_PROCESSED + * (0xFF) or NACK_COMMAND_PROCESSED (0xFE) byte. * * @param buffer a byte array to search within - * @return index of the first 0x00 or 0xFF byte found after position 0, or -1 if not found + * @return index of the first 0x00, 0xFF or 0xFE byte found after position 0, or -1 if not found */ - private static int findOffsetOfNextZeroOrFF(byte[] buffer) { + private static int findOffsetOfNextPacketBoundary(byte[] buffer) { for (int i = 1; i < buffer.length; i++) { byte b = buffer[i]; - if (b == 0 || b == (byte) 0xFF) + if (b == DATA_PACKET || b == ACK_COMMAND_PROCESSED || b == NACK_COMMAND_PROCESSED) return i; } return -1; @@ -2126,6 +2170,78 @@ else if(responseCommand==BT_FW_VERSION_STR_RESPONSE) { } } + /** + * Unwinds the in-flight transaction after the Shimmer answered a command + * with NACK (0xFE) instead of ACK. + * + *

The refused instruction is dropped and the stack advances, as it would + * on an ACK, so one refused command no longer stalls everything queued + * behind it. It is dropped only when it is still queued - a GET's + * instruction is already gone by the time its response is awaited. The + * connection is left up: a refusal means the device declined this command, + * not that the link is gone. + */ + private void processNackFromCommand() { + stopTimerCheckForAckOrResp(); //cancel the ack timer + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); + + byte refusedCommand = mCurrentCommand; + + /* Only the ACK-wait state still has the refused instruction queued: a + * GET's instruction is removed as soon as its ACK arrives, so removing + * one here as well would drop whatever was queued behind it and silently + * skip that command. */ + boolean instructionStillQueued = mWaitForAck; + + mWaitForAck=false; + mWaitForResponse=false; + + /* Mirror the ACK path's progress report so that an operation containing a + * refused command can still reach its end value. + * BluetoothProgressReportPerDevice.updateProgress() derives the counter + * from the remaining stack size, so this has to be sent before the + * instruction is removed, and only while it is still queued - the + * response-wait path already reported when its ACK arrived and reporting + * twice would skip a count. Without it the counter never reaches + * mProgressEndValue, finishOperation() never fires, and the application + * stays in CONFIGURING/CONNECTING indefinitely. The same three + * timer-driven commands are excluded as on the ACK path. */ + if(instructionStillQueued + && mCurrentCommand!=GET_STATUS_COMMAND + && mCurrentCommand!=TEST_CONNECTION_COMMAND + && mCurrentCommand!=SET_BLINK_LED + && mOperationUnderway){ + sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, getComPort())); + } + + //Drop the refused instruction, as the ACK path does for its own command + if(instructionStillQueued && getListofInstructions().size()>0){ + removeInstruction(0); + } + removeAllNulls(); + + mTransactionCompleted=true; + setInstructionStackLock(false); + + eventCommandRefused(refusedCommand); + } + + /** + * Called when the Shimmer refused a command with a NACK. The transaction has + * already been unwound and the connection is still up. + * + *

Deliberately concrete rather than abstract so that existing subclasses + * keep compiling; override to surface the refusal to the application. A + * refusal is expected in normal use - most SET commands are rejected while + * the device is sensing, and some GETs are rejected for hardware that does + * not have the feature. + * + * @param command the command byte that was refused + */ + protected void eventCommandRefused(byte command) { + //Default: no application-level notification, the log line above stands + } + // TODO: Consider removing this, replace by SET then GET and let the // RESPONSE update the variables in ShimmerObject - removes duplication of // code and ensure ShimmerObject it up-to-date with exactly what is on diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java index 8ab6f3a79..558e47bbc 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/comms/radioProtocol/LiteProtocol.java @@ -126,6 +126,12 @@ public class InstructionsGet{ protected String mDirectoryName; protected int numBytesToReadFromExpBoard=0; private static final int MAX_CALIB_DUMP_MAX = 4096; + /* The generated LiteProtocolInstructionSet has no NACK entry, so the value + * is declared here rather than read from InstructionsSet. Adding it to + * grpcprotosrc/src/LiteProtocolInstructionSet.proto and regenerating would + * be tidier, but that rewrites a large generated file committed in two + * places for the sake of one constant. */ + private static final int NACK_COMMAND_PROCESSED_VALUE = 0xFE; /** @@ -678,6 +684,12 @@ else if(isKnownGetCommand(mCurrentCommand)){ } } + /* The Shimmer refused the command. Without this branch the NACK + * was discarded and the transaction stalled until the ACK timer + * expired, which is treated as a lost connection. */ + else if((((int)byteBuffer[0])&0xFF)==NACK_COMMAND_PROCESSED_VALUE) { + processNackFromCommand(); + } } } } @@ -712,8 +724,16 @@ else if(bytesAvailableToBeRead()){ byteBuffer=readBytes(1); mIamAlive = true; + /* As in the ACK-wait path above, and matching ShimmerBluetooth: a + * NACK can land here instead if the firmware only discovers it + * cannot serve a GET while building the response. Checked before + * isKnownResponseByte() so it is handled as a refusal rather than + * falling through to the ACK/response timeout. */ + if((((int)byteBuffer[0])&0xFF)==NACK_COMMAND_PROCESSED_VALUE){ + processNackFromCommand(); + } //Check to see whether it is a response byte - if(isKnownResponseByte(byteBuffer[0])){ + else if(isKnownResponseByte(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; if(mUseShimmerBluetoothApproach){ @@ -1367,6 +1387,62 @@ private int availableBytes() throws ShimmerException { public void eventLogAndStreamStatusChanged(int currentCommand){ mProtocolListener.eventLogAndStreamStatusChangedCallback(currentCommand); } + + /** + * Unwinds the in-flight transaction after the Shimmer answered a command + * with NACK (0xFE) instead of ACK. The refused instruction is dropped so the + * stack advances, and the connection is left up - a refusal means the device + * declined this command, not that the link is gone. + */ + private void processNackFromCommand() { + stopTimerCheckForAckOrResp(); //cancel the ack timer + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); + + int refusedCommand = ((int)mCurrentCommand)&0xFF; + + /* Only the ACK-wait state still has the refused instruction queued: a + * GET's instruction is removed as soon as its ACK arrives, so removing + * one here as well would drop whatever was queued behind it. */ + boolean instructionStillQueued = mWaitForAck; + + mWaitForAck=false; + mWaitForResponse=false; + + /* Mirror the ACK path's progress report so that an operation containing a + * refused command can still reach its end value, otherwise the progress + * counter stalls and the operation never completes. Sent before the + * instruction is removed and only while it is still queued, because the + * counter is derived from the remaining stack size. */ + if(instructionStillQueued + && mCurrentCommand!=InstructionsGet.GET_STATUS_COMMAND_VALUE + && mCurrentCommand!=InstructionsSet.TEST_CONNECTION_COMMAND_VALUE + && mCurrentCommand!=InstructionsSet.SET_BLINK_LED_VALUE + && mOperationUnderway){ + sendProgressReport(new BluetoothProgressReportPerCmd(mCurrentCommand, getListofInstructions().size(), mMyBluetoothAddress, mComPort)); + } + + if(instructionStillQueued && getListofInstructions().size()>0){ + getListofInstructions().remove(0); + } + getListofInstructions().removeAll(Collections.singleton(null)); + + mTransactionCompleted=true; + setInstructionStackLock(false); + + eventCommandRefused(refusedCommand); + } + + /** + * Called when the Shimmer refused a command with a NACK. The transaction has + * already been unwound and the connection is still up. Concrete rather than + * a new ProtocolListener callback so that existing implementers keep + * compiling; override to surface the refusal to the application. + * + * @param command the command value that was refused + */ + protected void eventCommandRefused(int command) { + //Default: no application-level notification, the log line above stands + } private void isNowStreaming() { mProtocolListener.isNowStreaming(); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 2679bc312..177ae34bd 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -460,6 +460,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; diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java new file mode 100644 index 000000000..736f0a440 --- /dev/null +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java @@ -0,0 +1,233 @@ +package com.shimmerresearch.bluetooth; + +import java.util.ArrayList; +import java.util.List; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.BasicProcessWithCallBack; +import com.shimmerresearch.driver.CallbackObject; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.ShimmerMsg; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.tools.bluetooth.BasicShimmerBluetoothManagerPc; + +/** + * DEV-982 / PR #293, on hardware: a command refused while NOT streaming. + * + *

Why not streaming

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

How it gets a NACK

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

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

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

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

Running it

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