diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 6d2de43d3..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"; @@ -305,6 +337,9 @@ public int getNumCrcBytes() { * first. */ private static final byte[] BARE_ACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {ACK_COMMAND_PROCESSED}, 1); + + /** The same for a NACK, the refusal of a command: the CRC of 0xFE is C5 56. */ + private static final byte[] BARE_NACK_CRC = ShimmerCrc.shimmerUartCrcCalc(new byte[] {NACK_COMMAND_PROCESSED}, 1); /** SET_FEATURE's feature ids, by ordinal */ public enum SHIMMER_FEATURE { @@ -322,6 +357,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); } @@ -380,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); } @@ -501,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); } @@ -850,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. @@ -938,12 +987,20 @@ 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. */ + /* 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 + * connection down - a refusal was indistinguishable from a dead + * link. */ + else if((byte)byteBuffer[0]==NACK_COMMAND_PROCESSED) { + processNackFromCommand(); + } } } } @@ -955,11 +1012,37 @@ 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); + + 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; @@ -996,7 +1079,24 @@ && 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"); + } + /* 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); if(byteBuffer!=null && byteBuffer[0]==ACK_COMMAND_PROCESSED){ //an android fix.. not fully investigated (JC) @@ -1080,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){ @@ -1119,6 +1232,57 @@ 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) + else if(bufferTemp[0]==DATA_PACKET + && bufferTemp[getPacketSizeWithCrc()+1]==NACK_COMMAND_PROCESSED){ + + //With a link CRC on, the NACK is followed by its own CRC, as a bare ACK + //is, rather than by the next packet + if(!isBareNackCrcSoFar(bufferTemp)){ + printLogDataForDebugging("0xFE after a data packet is not a NACK: its CRC does not match"); + discardBufferBytesToNextPacket(); + return; + } + int bareNackEnd = getPacketSizeWithCrc()+2+mBtCommsCrcModeCurrent.getNumCrcBytes(); + if(bufferTemp.length3 || !isReplyToCommandInFlight(bufferTemp[2])){ return false; } @@ -1274,6 +1450,23 @@ private boolean isBareAckCrcSoFar(byte[] bufferTemp) { return true; } + /** + * Whether the bytes received so far after the NACK that follows a data packet + * agree with the CRC on a bare NACK, none of it having arrived counting as + * agreeing. With no link CRC there is nothing to check: a data packet can + * only be followed by another packet's 0x00, an ACK or a NACK. + */ + private boolean isBareNackCrcSoFar(byte[] bufferTemp) { + int crcStart = getPacketSizeWithCrc()+2; + int numCrcBytesReceived = Math.min(bufferTemp.length-crcStart, mBtCommsCrcModeCurrent.getNumCrcBytes()); + for(int i=0;iThe 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. + * + *

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

Protected because ShimmerAndroidAPI's Shimmer has its own streaming + * parser, which needs to fail the command in flight the same way. + */ + protected 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); + + if(refusedCommand==START_LOGGING_ONLY_COMMAND || refusedCommand==START_SDBT_COMMAND){ + processLogStartRefused(refusedCommand); + } + 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 @@ -2893,6 +3190,7 @@ private void initializeShimmer3or3R(int hardwareVersion){ // The firmware may have changed since the last connection setEventChannelSupported(null); + resetEventChannelConnectionState(); readEventChannelSupport(); if (isSetupDeviceWhileConnecting()){ @@ -3321,6 +3619,53 @@ else if(mCurrentCommand==GET_SHIMMER_VERSION_COMMAND_NEW){ //in case the new com // //NOT USED // } + /** + * A log start the device refused with a NACK (DEV-1431), its transaction already unwound by + * {@link #processNackFromCommand()}. + *

+ * The firmware starts a log only when the device is undocked, off USB power, has an SD card in + * with no file error and has logging turned on in its configuration, and firmware that refuses + * a start it cannot carry out starts nothing: after START_SDBT the device is not streaming + * either. It refuses START_LOGGING_ONLY in the middle of a stream the same way, the NACK then + * coming between two data packets. Earlier firmware ACKs such a start instead and does + * nothing, so there the status bits are what tell. + *

+ * Without this, a refusal ended as an unanswered start does: the ACK timer's special case + * (checkForAckOrRespTask) took START_LOGGING_ONLY for started. Here the device is left not + * logging, the status reads that startDataLogAndStreaming() stopped start again, and + * {@link #eventLogStartRefused(byte)} says so. + * + * @param refused the start that was refused + */ + private void processLogStartRefused(byte refused) { + printLogDataForDebugging(btCommandToString(refused) + " refused: the device cannot log now"); + setIsSDLogging(false); + if(refused==START_SDBT_COMMAND){ + // After the refused start is retired: the first read is immediate, and skipped while + // any instruction is still queued + startTimerReadStatus(); + } + eventLogStartRefused(refused); + } + + /** What {@link #eventLogStartRefused(byte)} passes to {@link #sendStatusMSGtoUI(String)} by default. */ + public static final String LOG_START_REFUSED_MESSAGE = "The Shimmer refused to start logging to its SD card. " + + "It logs only when undocked, off USB power, with an SD card in and no SD file error, " + + "and with logging turned on in its configuration."; + + /** + * The device refused a log start (START_LOGGING_ONLY_COMMAND or START_SDBT_COMMAND) with a NACK: + * it is not logging. After START_SDBT it is not streaming either; a stream that was running when + * START_LOGGING_ONLY was sent goes on. {@link #eventCommandRefused(byte)} is called for it too, + * after this. By default the reason goes to + * {@link #sendStatusMSGtoUI(String)}; override to tell the user another way. + * + * @param command the start that was refused + */ + protected void eventLogStartRefused(byte command) { + sendStatusMSGtoUI(LOG_START_REFUSED_MESSAGE); + } + private void killConnection(){ printLogDataForDebugging("Killing Connection"); stop(); //If command fail exit device @@ -5114,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/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/Configuration.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java index ba89b5a06..a09bb6b68 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java @@ -94,6 +94,7 @@ import com.shimmerresearch.sensors.adxl371.SensorADXL371; import com.shimmerresearch.sensors.lsm6dsv.SensorLSM6DSV; import com.shimmerresearch.sensors.lis2dw12.SensorLIS2DW12; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; import com.shimmerresearch.verisense.sensors.SensorLSM6DS3; //import com.shimmerresearch.verisense.sensors.SensorLIS2DW12; import com.shimmerresearch.verisense.sensors.SensorBattVoltageVerisense; @@ -158,6 +159,8 @@ public static class CHANNEL_UNITS{ public static final String GRAVITY = "g"; public static final String RPM = "rpm"; public static final String POWER = "dB"; + /** A-weighted sound pressure level, the Shimmer3R sound level channel's unit (DEV-1413) */ + public static final String DECIBELS_A = "dB(A)"; public static final String SCORE = "Score"; public static final String ACCEL_CAL_UNIT = METER_PER_SECOND_SQUARE; @@ -735,6 +738,8 @@ public static class SENSOR_ID{ public static final int SHIMMER_LIS3MDL_MAG_ALT = 41; public static final int SHIMMER_BMP390_PRESSURE = 43; public static final int SHIMMER_BMP581_PRESSURE = 44; + /** Shimmer3R microphone sound level, channel 0x38 (DEV-1413): enabled through configuration byte 233 bit 4, not a sensor bitmap bit */ + public static final int SHIMMER_SOUND_LEVEL = 45; // public static final int SHIMMER_EXG1_24BIT = 3; // public static final int SHIMMER_EXG2_24BIT = 4; @@ -949,7 +954,8 @@ public enum LABEL_SENSOR_TILE{ MPU_OTHER(SensorMPU9X50.LABEL_SENSOR_TILE.MPU_OTHER), GPS("GPS"), STC3100_MONITORING (SensorSTC3100.LABEL_SENSOR_TILE.STC3100_MONITORING), - SWEATCH_ADC ("Sweatch ADC"); + SWEATCH_ADC ("Sweatch ADC"), + SOUND_LEVEL(SensorSoundLevel.LABEL_SENSOR_TILE.SOUND_LEVEL); private String tileText = ""; LABEL_SENSOR_TILE(String text){ @@ -1337,6 +1343,8 @@ public static class CompatibilityInfoForMaps{ private static final ShimmerVerObject svoShimmer3RImuAnyExpBrdLogAndStream = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,0,1,0,ShimmerVerDetails.ANY_VERSION, ShimmerVerDetails.ANY_VERSION, NEW_IMU_EXP_REV.IMU); public static final ShimmerVerObject svoShimmer3RLogAndStream = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION); + /** LogAndStream_Shimmer3R v1.01.026 and later: the first release with the sound level channel (DEV-1413) */ + public static final ShimmerVerObject svoShimmer3RLogAndStreamSoundLevel = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,1,1,26,ShimmerVerDetails.ANY_VERSION); public static final ShimmerVerObject svoShimmer3LogAndStreamWithSDLogSyncSupport = new ShimmerVerObject(HW_ID.SHIMMER_3,FW_ID.LOGANDSTREAM,0,16,11,ShimmerVerDetails.ANY_VERSION); public static final ShimmerVerObject svoShimmer3RLogAndStreamWithSDLogSyncSupport = new ShimmerVerObject(HW_ID.SHIMMER_3R,FW_ID.LOGANDSTREAM,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION,ShimmerVerDetails.ANY_VERSION); @@ -1544,6 +1552,13 @@ public static class CompatibilityInfoForMaps{ svoShimmer3RBrAmpUnifiedLogAndStream, svoShimmer3RProto3DeluxeLogAndStream); + //Shimmer3r sound level (DEV-1413), from LogAndStream_Shimmer3R v1.01.026, + //the first release with the channel. Earlier releases store + //configuration byte 233 untouched, so bit 4 would read back set there + //with no channel behind it: the tile is not offered on them. + public static final List listOfCompatibleVersionInfoSoundLevel = Arrays.asList( + svoShimmer3RLogAndStreamSoundLevel); + //TODO need to update this list and remove "any" public static final List listOfCompatibleVersionInfoKionixKXRB52042 = Arrays.asList( svoAnyIntExpBoardAndSdlog, svoAnyIntExpBoardAndBtStream, svoAnyIntExpBoardAndLogAndStream, diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index 0f4018c50..52f084551 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -96,6 +96,7 @@ import com.shimmerresearch.sensors.shimmer2.SensorMMA736x; import com.shimmerresearch.sensors.shimmer2.SensorShimmer2Gyro; import com.shimmerresearch.sensors.shimmer2.SensorShimmer2Mag; +import com.shimmerresearch.sensors.soundlevel.SensorSoundLevel; import com.shimmerresearch.algorithms.orientation.GradDes3DOrientation; import com.shimmerresearch.algorithms.orientation.GradDes3DOrientation9DoF; import com.shimmerresearch.algorithms.orientation.Orientation3DObject; @@ -505,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; @@ -2387,6 +2393,23 @@ else if (isEXGUsingDefaultThreeUnipolarConfiguration()){ calibratedDataUnits[sigIndex]=CHANNEL_UNITS.BEATS_PER_MINUTE; } + // Sound level (DEV-1413, Shimmer3R). Enabled through configuration + // byte 233 bit 4 rather than a sensor bitmap bit, so it is decoded + // whenever the channel list carries it. 0x8000 (no level) is NaN. + int iSoundLevel = getSignalIndex(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL); + if (iSoundLevel!=-1){ + double soundLevelRaw = (double)newPacketInt[iSoundLevel]; + objectCluster.addDataToMap(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL,CHANNEL_TYPE.UNCAL.toString(),CHANNEL_UNITS.NO_UNITS,soundLevelRaw); + uncalibratedData[iSoundLevel]=soundLevelRaw; + uncalibratedDataUnits[iSoundLevel]=CHANNEL_UNITS.NO_UNITS; + if (mEnableCalibration){ + double soundLevelDbA = SensorSoundLevel.calibrateSoundLevel(soundLevelRaw); + objectCluster.addDataToMap(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL,CHANNEL_TYPE.CAL.toString(),CHANNEL_UNITS.DECIBELS_A,soundLevelDbA); + calibratedData[iSoundLevel]=soundLevelDbA; + calibratedDataUnits[iSoundLevel]=CHANNEL_UNITS.DECIBELS_A; + } + } + //Additional Channels Offset int additionalChannelsOffset = calibratedData.length-numAdditionalChannels; if(fwType == COMMUNICATION_TYPE.BLUETOOTH) { @@ -3640,6 +3663,14 @@ else if ((byte)signalId[i-iTS]==(byte)0x28){ enabledSensors |= SENSOR_BRIDGE_AMP; } } + else if ((byte)signalId[i-iTS]==SensorSoundLevel.CHANNEL_ID && getHardwareVersion()==HW_ID.SHIMMER_3R){ + // Sound level (DEV-1413): a signed 16-bit little-endian count of + // 0.01 dB(A). A Shimmer3 never sends 0x38 and keeps the unknown + // channel handling below. + signalNameArray[i+1]=SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL; + signalDataTypeArray[i+1] = "i16"; + packetSize=packetSize+2; + } else{ signalNameArray[i+1]=Byte.toString(signalId[i-iTS]); signalDataTypeArray[i+1] = "u12"; @@ -5634,6 +5665,10 @@ else if(isSupportedNewImuSensors()){ mSensorLIS2MDL = new SensorLIS2MDL(this); addSensorClass(mSensorLIS2MDL); + + // Every Shimmer3R has the microphone; whether its firmware has the + // channel is learnt from configuration byte 233 (DEV-1413) + addSensorClass(new SensorSoundLevel(this)); } } @@ -5887,6 +5922,11 @@ else if(sensorId == Configuration.Shimmer3.SENSOR_ID.HOST_SHIMMER_STREAMING_PROP mSensorMap.get(sensorId).setIsEnabled(true); return true; } + // The sound level (DEV-1413) has no sensor bitmap bit, so the bitmap + // would always turn it off: its state comes from configuration byte 233 + else if(sensorId == Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL){ + return true; + } return false; } diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java index ee647dd0c..0e0cb2f2c 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java @@ -170,6 +170,17 @@ public class ConfigByteLayoutShimmer3 extends ConfigByteLayout implements Serial public int maskLIS2MDLMagRateMSB = 0x07; public int bitShiftLIS2MDLMagRateMSB = 3; + //Config Byte 233, Shimmer3R only (0 where there is none): the microphone. + //Bits 0-1 are the audio mode and bits 2-3 the gain preset (DEV-99), kept as + //read on a configuration write. Bit 4 turns on the sound level channel, + //0x38 (DEV-1413). The firmware clears bits 5-6, and reads the whole byte + //as 0 when bit 7 is set, as it is in erased flash (0xFF). + public int idxAudioConfig = 0; + public int maskAudioModeAndGain = 0x0F; + public int bitShiftSoundLevel = 4; + public int maskSoundLevel = 0x01; + public int maskAudioConfigInvalid = 0x80; + // Derived Channels - used by SW not FW public int maskDerivedChannelsByte = 0xFF; public int byteShiftDerivedSensors0 = 8*0; @@ -397,6 +408,12 @@ public ConfigByteLayoutShimmer3(int firmwareIdentifier, int firmwareVersionMajor maskShowErrorLedsSd = 0x01; } + // Any Shimmer3R firmware: older builds store the byte untouched, so + // writing back what was read is safe on them too + if(mShimmerVerObject.mHardwareVersion == HW_ID.SHIMMER_3R) { + idxAudioConfig = 128+105; + } + if(mShimmerVerObject.mHardwareVersion == HW_ID.SHIMMER_3R || compareVersions(FW_ID.LOGANDSTREAM,0,8,1)) { idxBtFactoryReset = 128+103; @@ -547,6 +564,9 @@ public HashMap getMapOfByteDescriptions(){ mapOfByteDescriptions.put(idxMaxExpLengthLsb, "idxMaxExpLengthLsb"); mapOfByteDescriptions.put(idxMacAddress, "idxMacAddress"); mapOfByteDescriptions.put(idxSDConfigDelayFlag, "idxSDConfigDelayFlag"); + if(idxAudioConfig>0){ + mapOfByteDescriptions.put(idxAudioConfig, "idxAudioConfig"); + } if(idxBtFactoryReset>0){ mapOfByteDescriptions.put(idxBtFactoryReset, "idxBtFactoryReset"); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/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/main/java/com/shimmerresearch/sensors/AbstractSensor.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java index c1049b229..890f78f42 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java @@ -71,7 +71,8 @@ public enum SENSORS{ VD6283("VD6283"), MLX90632("MLX90632"), BMP390("BMP390"), - BMP581("BMP581"); + BMP581("BMP581"), + SOUND_LEVEL("Sound Level"); private final String text; diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java new file mode 100644 index 000000000..8365b00c3 --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -0,0 +1,317 @@ +package com.shimmerresearch.sensors.soundlevel; + +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; + +import com.shimmerresearch.driver.ConfigByteLayout; +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.CHANNEL_UNITS; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.Configuration.Shimmer3.CompatibilityInfoForMaps; +import com.shimmerresearch.driver.FormatCluster; +import com.shimmerresearch.driver.ObjectCluster; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; +import com.shimmerresearch.driverUtilities.ChannelDetails; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_DATA_ENDIAN; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_DATA_TYPE; +import com.shimmerresearch.driverUtilities.ChannelDetails.CHANNEL_TYPE; +import com.shimmerresearch.driverUtilities.SensorDetails; +import com.shimmerresearch.driverUtilities.SensorDetailsRef; +import com.shimmerresearch.driverUtilities.SensorGroupingDetails; +import com.shimmerresearch.sensors.AbstractSensor; +import com.shimmerresearch.sensors.ActionSetting; + +/** + * The Shimmer3R sound level channel (DEV-1413): the A-weighted sound level + * from the microphone, LAeq over the most recent completed 128 ms block, in + * dB(A) SPL. LogAndStream_Shimmer3R v1.01.026 is the first release with it. + *

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

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

+ * Enabling it. Not a sensor bitmap bit: configuration byte 233 bit 4. + * Byte 233 also holds the DEV-99 audio mode (bits 0-1) and gain preset (bits + * 2-3), which this class keeps as read so that a full configuration write, + * which builds its image from zeros, gives the Shimmer back its own, on any + * Shimmer3R firmware. + *

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

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

+ * No hardware. + * + * @author Mark Nolan + */ +public class API_00040_SoundLevelChannelTest { + + private static final int IDX_AUDIO_CONFIG = 233; + + /** Shimmer3R LogAndStream v1.01.026, the first release with the channel: every Shimmer3R has the microphone */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 26); + /** The release before it, which stores byte 233 untouched */ + private static final ShimmerVerObject S3R_BEFORE_CHANNEL = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + private static final ShimmerVerObject S3 = new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17); + + private static final byte LN_ACCEL_X = 0x00; + private static final byte LN_ACCEL_Y = 0x01; + private static final byte LN_ACCEL_Z = 0x02; + private static final byte VBATT = 0x03; + private static final byte GSR = 0x1C; + private static final byte SOUND_LEVEL = 0x38; + + /** The smallest concrete ShimmerObject: decoding and configuration, no connection */ + private static class TestShimmer extends ShimmerObject { + private static final long serialVersionUID = 1L; + + TestShimmer(ShimmerVerObject svo) { + setShimmerVersionObjectAndCreateSensorMap(svo); + setSamplingRateShimmer(128); + updateTimestampByteLength(); + } + + @Override + public void createConfigBytesLayout() { + mConfigByteLayout = new ConfigByteLayoutShimmer3(getFirmwareIdentifier(), getFirmwareVersionMajor(), getFirmwareVersionMinor(), getFirmwareVersionInternal(), mShimmerVerObject.mHardwareVersion); + } + + @Override + protected void checkBattery() { + } + + @Override + public ShimmerDevice deepClone() { + return null; + } + + @Override + protected void interpretDataPacketFormat(Object object, COMMUNICATION_TYPE commType) { + } + + @Override + protected void dataHandler(ObjectCluster ojc) { + } + + @Override + protected void processMsgFromCallback(ShimmerMsg shimmerMSG) { + } + + byte[] written() { + return generateConfigBytesForWritingToShimmer().clone(); + } + + boolean isSoundLevelEnabled() { + return isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); + } + + void setSoundLevelEnabled(boolean state) { + assertTrue(setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, state)); + } + + /** Takes the channel list as an inquiry response or an SD header gives it */ + void channels(byte... channelIds) { + mNChannels = channelIds.length; + interpretDataPacketFormat(channelIds.length, channelIds); + } + } + + /** A configuration as a Shimmer on that firmware would answer it, with the given byte 233 */ + private static byte[] configFromShimmer(ShimmerVerObject svo, int audioConfig) { + byte[] config = new TestShimmer(svo).written(); + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + return config; + } + + private static TestShimmer readFrom(ShimmerVerObject svo, int audioConfig) { + TestShimmer shimmer = new TestShimmer(svo); + shimmer.configBytesParse(configFromShimmer(svo, audioConfig), COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int writtenAudioConfig(TestShimmer shimmer) { + return shimmer.written()[IDX_AUDIO_CONFIG] & 0xFF; + } + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + /** A data packet as buildMsg gets it: the timestamp, then two bytes little-endian per channel */ + private static byte[] packet(TestShimmer shimmer, int... channelValues) { + byte[] packet = new byte[shimmer.mTimeStampPacketByteSize + 2*channelValues.length]; + packet[0] = 0x10; + int index = shimmer.mTimeStampPacketByteSize; + for(int value:channelValues){ + packet[index++] = (byte) (value & 0xFF); + packet[index++] = (byte) ((value >> 8) & 0xFF); + } + return packet; + } + + private static FormatCluster soundLevel(ObjectCluster objectCluster, CHANNEL_TYPE channelType) { + return objectCluster.getLastFormatCluster(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, channelType.toString()); + } + + // ---------- Decoding ---------- + + /** Just before the ADS7028 block (GSR, then the battery last), as the firmware sends it */ + @Test + public void decodedAtTheSpecPosition() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, LN_ACCEL_Y, LN_ACCEL_Z, SOUND_LEVEL, GSR, VBATT); + + assertEquals(shimmer.mTimeStampPacketByteSize + 12, shimmer.mPacketSize); + assertSame(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, shimmer.mSignalNameArray[4]); + assertEquals("i16", shimmer.mSignalDataTypeArray[4]); + + byte[] packet = packet(shimmer, 0x0101, 0x0202, 0x0303, 6543, 0x0456, 0x0123); + ObjectCluster objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + + assertEquals(6543, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + FormatCluster cal = soundLevel(objectCluster, CHANNEL_TYPE.CAL); + assertEquals(65.43, cal.mData, 1e-9); + assertEquals(CHANNEL_UNITS.DECIBELS_A, cal.mUnits); + + // The channels after it are still where the channel list says + long[] parsed = UtilParseData.parseData(packet, shimmer.mSignalDataTypeArray); + assertEquals(0x0303, parsed[3]); + assertEquals(6543, parsed[4]); + assertEquals(0x0456, parsed[5]); + assertEquals(0x0123, parsed[6]); + } + + /** The decoder goes by the channel list, not by a fixed position */ + @Test + public void decodedWhereverTheChannelListPutsIt() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(SOUND_LEVEL, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 4012, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(40.12, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + + shimmer = new TestShimmer(S3R); + shimmer.channels(VBATT, SOUND_LEVEL); + objectCluster = shimmer.buildMsg(packet(shimmer, 0x0123, 4012), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(40.12, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + /** 0x8000 says there is no level: NaN, never -327.68 */ + @Test + public void noLevelIsNaN() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 0x8000, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + + assertEquals(SensorSoundLevel.NO_LEVEL, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + assertTrue(Double.isNaN(soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData)); + } + + /** Signed: a level below 0 dB(A) is a level, not a wrap */ + @Test + public void signedLittleEndian() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(SOUND_LEVEL); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0xFF9C), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(-100, soundLevel(objectCluster, CHANNEL_TYPE.UNCAL).mData, 0); + assertEquals(-1.0, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + + objectCluster = shimmer.buildMsg(packet(shimmer, 0x7FFF), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(327.67, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + /** Shimmer3R SD files carry the channel list in their header, decoded the same way */ + @Test + public void decodedFromAnSdFile() { + TestShimmer shimmer = new TestShimmer(S3R); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, GSR, VBATT); + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 7210, 0x0456, 0x0123), COMMUNICATION_TYPE.SD, false, 0); + assertEquals(72.10, soundLevel(objectCluster, CHANNEL_TYPE.CAL).mData, 1e-9); + } + + @Test + public void calibration() { + assertEquals(65.43, SensorSoundLevel.calibrateSoundLevel(6543), 1e-12); + assertEquals(0.0, SensorSoundLevel.calibrateSoundLevel(0), 0); + assertEquals(-327.67, SensorSoundLevel.calibrateSoundLevel(-32767), 1e-12); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(-32768))); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(32768))); + assertTrue(Double.isNaN(SensorSoundLevel.calibrateSoundLevel(Double.NaN))); + } + + /** A Shimmer3 never sends 0x38: if one did, it would stay an unknown channel, as before */ + @Test + public void shimmer3KeepsTheUnknownChannelHandling() { + TestShimmer shimmer = new TestShimmer(S3); + shimmer.channels(LN_ACCEL_X, SOUND_LEVEL, VBATT); + assertEquals(Byte.toString(SOUND_LEVEL), shimmer.mSignalNameArray[2]); + assertEquals("u12", shimmer.mSignalDataTypeArray[2]); + + ObjectCluster objectCluster = shimmer.buildMsg(packet(shimmer, 0, 6543, 0x0123), COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertNull(soundLevel(objectCluster, CHANNEL_TYPE.CAL)); + assertNull(soundLevel(objectCluster, CHANNEL_TYPE.UNCAL)); + } + + // ---------- Configuration byte 233 ---------- + + @Test + public void onlyAShimmer3RHasTheSensor() { + TestShimmer s3r = new TestShimmer(S3R); + assertNotNull(s3r.getSensorClass(SENSORS.SOUND_LEVEL)); + assertNotNull(s3r.getSensorDetails(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + assertFalse("off until the Shimmer says otherwise", s3r.isSoundLevelEnabled()); + + TestShimmer s3 = new TestShimmer(S3); + assertNull(s3.getSensorClass(SENSORS.SOUND_LEVEL)); + assertNull(s3.getSensorDetails(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + } + + /** The tile is offered from v1.01.026, the first release with the channel, and not before */ + @Test + public void theTileIsOfferedFromV1_01_026() { + int tile = Configuration.Shimmer3.LABEL_SENSOR_TILE.SOUND_LEVEL.ordinal(); + assertTrue(new TestShimmer(S3R).getSensorGroupingMap().containsKey(tile)); + assertTrue(new TestShimmer(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 2, 0)).getSensorGroupingMap().containsKey(tile)); + assertFalse(new TestShimmer(S3R_BEFORE_CHANNEL).getSensorGroupingMap().containsKey(tile)); + } + + /** + * Before v1.01.026 the firmware stores byte 233 untouched, so a bit 4 read back + * there has no channel behind it: it reads as off, and the next write clears it, + * keeping the audio mode, so a later firmware update does not turn the channel on + */ + @Test + public void beforeTheChannelBit4ReadsOffAndIsClearedOnWrite() { + TestShimmer shimmer = readFrom(S3R_BEFORE_CHANNEL, 0x12); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals("the audio mode kept, bit 4 cleared", 0x02, writtenAudioConfig(shimmer)); + } + + /** Before v1.01.026 enabling it writes nothing: the firmware would only store the bit */ + @Test + public void beforeTheChannelEnablingDoesNotSetBit4() { + TestShimmer shimmer = readFrom(S3R_BEFORE_CHANNEL, 0x01); + shimmer.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, true); + assertEquals("the audio mode kept, bit 4 not set", 0x01, writtenAudioConfig(shimmer)); + } + + /** The DEV-99 audio mode went to 0 on every full write before DEV-1413 */ + @Test + public void theAudioModeReadGoesBackOnAFullWrite() { + for(int audioMode=0;audioMode<4;audioMode++){ + TestShimmer shimmer = readFrom(S3R, audioMode); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals("mode " + audioMode, audioMode, writtenAudioConfig(shimmer)); + } + } + + /** + * Every value of the byte: bits 0-4 go back as read, bits 5-6 are cleared + * as the firmware clears them, and bit 7 set (erased flash) reads as 0 + */ + @Test + public void everyByteGoesBackAsTheFirmwareKeepsIt() { + for(int value=0;value<256;value++){ + TestShimmer shimmer = readFrom(S3R, value); + boolean valid = (value & 0x80)==0; + assertEquals(hex(value), valid && (value & 0x10)!=0, shimmer.isSoundLevelEnabled()); + assertEquals(hex(value), valid ? value & 0x1F : 0, writtenAudioConfig(shimmer)); + } + } + + /** Enabling the sensor sets byte 233 bit 4 and changes nothing else in the image */ + @Test + public void enablingSetsBit4AndNothingElse() { + TestShimmer shimmer = readFrom(S3R, 0x02); + byte[] off = shimmer.written(); + + shimmer.setSoundLevelEnabled(true); + byte[] on = shimmer.written(); + assertEquals(0x12, on[IDX_AUDIO_CONFIG] & 0xFF); + byte[] onWithByte233Off = on.clone(); + onWithByte233Off[IDX_AUDIO_CONFIG] = off[IDX_AUDIO_CONFIG]; + assertArrayEquals("no sensor bitmap bit, so no other byte moves", off, onWithByte233Off); + + shimmer.setSoundLevelEnabled(false); + assertTrue(Arrays.equals(off, shimmer.written())); + } + + /** A Shimmer3R never read writes 0, as the driver always did */ + @Test + public void unreadShimmer3RWritesZero() { + TestShimmer shimmer = new TestShimmer(S3R); + assertEquals(0, writtenAudioConfig(shimmer)); + shimmer.setSoundLevelEnabled(true); + assertEquals(0x10, writtenAudioConfig(shimmer)); + } + + /** The bitmap has no bit for it, so updating the sensor map from the bitmap must leave it alone */ + @Test + public void theSensorBitmapDoesNotTurnItOff() { + TestShimmer shimmer = readFrom(S3R, 0x11); + assertTrue(shimmer.isSoundLevelEnabled()); + long enabledSensors = shimmer.getEnabledSensors(); + + shimmer.setEnabledAndDerivedSensorsAndUpdateMaps(shimmer.getEnabledSensors(), shimmer.getDerivedSensors()); + assertTrue(shimmer.isSoundLevelEnabled()); + + shimmer.refreshEnabledSensorsFromSensorMap(); + assertEquals("adds no bitmap bit (0x4000 would read as ECG-to-HR on SD)", enabledSensors, shimmer.getEnabledSensors()); + assertEquals(0x11, writtenAudioConfig(shimmer)); + } + + /** A Shimmer3 has no microphone: byte 233 stays 0 whatever was read */ + @Test + public void shimmer3WritesZero() { + TestShimmer shimmer = readFrom(S3, 0x13); + assertFalse(shimmer.isSoundLevelEnabled()); + assertEquals(0, writtenAudioConfig(shimmer)); + assertFalse(shimmer.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, true)); + assertEquals(0, writtenAudioConfig(shimmer)); + } +} diff --git a/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_00036_LogStartRefusedTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java new file mode 100644 index 000000000..305c6ffbc --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00036_LogStartRefusedTest.java @@ -0,0 +1,242 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.concurrent.ConcurrentLinkedDeque; + +import org.junit.After; +import org.junit.Test; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_CRC_MODE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.comms.wiredProtocol.ShimmerCrc; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-1431: firmware that cannot start a log (no SD card or a bad one, docked, on USB power, logging + * turned off in its configuration) NACKs START_LOGGING_ONLY_COMMAND and START_SDBT_COMMAND and starts + * nothing. The driver had no NACK handling: it dropped the 0xFE as a stray byte and waited out the ACK + * timer, which then took START_LOGGING_ONLY for started (checkForAckOrRespTask's Consensys special + * case) and dropped the connection for START_SDBT. + *

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

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

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

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

+ * No hardware: the parser reads from an in-memory byte queue, one byte at a time as the IO thread + * does, as in API_00027_StreamingBareAckCrcTest. + * + * @author Mark Nolan + */ +public class API_00037_StreamingLogStartRefusedTest { + + /** Bytes after the DATA_PACKET byte: a 3-byte timestamp and three 2-byte channels */ + private static final int PACKET_SIZE = 9; + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + + void queue(byte... bytes) { + for(byte b:bytes){ + rx.add(b); + } + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() mLogStartsRefused = Collections.synchronizedList(new ArrayList()); + private final List mCommandsRefused = Collections.synchronizedList(new ArrayList()); + + @After + public void stopTimers() { + if(mDevice!=null){ + mDevice.stopTimerCheckForAckOrResp(); + mDevice.stopTimerReadStatus(); + } + } + + /** A Shimmer3R on LogAndStream v1.01.025 part way through streaming PACKET_SIZE-byte packets */ + private void streamingShimmer3r(BT_CRC_MODE crcMode) { + mDevice = new ShimmerPC("COM99") { + @Override + protected void eventLogStartRefused(byte command) { + mLogStartsRefused.add(command); + super.eventLogStartRefused(command); + } + + @Override + protected void eventCommandRefused(byte command) { + mCommandsRefused.add(command); + } + }; + mRadio = new QueueRadio(); + mDevice.setTestRadio(mRadio); + mDevice.setShimmerVersionObjectAndCreateSensorMap(new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25)); + mDevice.setPacketSize(PACKET_SIZE); + mDevice.setCurrentBtCommsCrcMode(crcMode); + mDevice.setIsStreaming(true); + mDevice.setBluetoothRadioState(BT_STATE.STREAMING); + // Queue each parsed packet rather than build an ObjectCluster from it + mDevice.mUseProcessingThread = true; + } + + /** startSDLogging() while streaming, and the IO thread sending its START_LOGGING_ONLY */ + private void startSdLoggingWhileStreaming() { + mDevice.startSDLogging(); + assertEquals("only START_LOGGING_ONLY_COMMAND is queued", 1, mDevice.getListofInstructions().size()); + mDevice.mCurrentCommand = mDevice.getListofInstructions().get(0)[0]; + assertEquals(ShimmerObject.START_LOGGING_ONLY_COMMAND, mDevice.mCurrentCommand); + mDevice.setInstructionStackLock(true); + mDevice.mWaitForAck = true; + mDevice.startTimerCheckForAckOrResp(2); + } + + /** Hands the bytes to the streaming parser one at a time, as the IO thread does */ + private void receive(byte[]... frames) { + for(byte[] frame:frames){ + mRadio.queue(frame); + } + while(!mRadio.rx.isEmpty()){ + mDevice.processWhileStreaming(); + } + } + + /** Has a 0x00, a 0xFE and a 0xFF in it, which a resync would take for the start of a frame */ + private static byte[] payload(int i) { + return new byte[] {(byte) (0x10*i), 0x00, 0x01, (byte) 0xFF, 0x07, (byte) 0xFE, 0x08, 0x3F, 0x09}; + } + + private static byte[] dataPacket(byte[] payload, BT_CRC_MODE crcMode) { + byte[] frame = new byte[1+payload.length]; + frame[0] = ShimmerObject.DATA_PACKET; + System.arraycopy(payload, 0, frame, 1, payload.length); + return withCrc(frame, crcMode); + } + + /** The firmware's refusal, with its link CRC */ + private static byte[] bareNack(BT_CRC_MODE crcMode) { + return withCrc(new byte[] {ShimmerObject.NACK_COMMAND_PROCESSED}, crcMode); + } + + /** The frame followed by the link CRC over all of it, low byte first */ + private static byte[] withCrc(byte[] frame, BT_CRC_MODE crcMode) { + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(frame, frame.length); + byte[] framed = Arrays.copyOf(frame, frame.length+crcMode.getNumCrcBytes()); + System.arraycopy(crc, 0, framed, frame.length, crcMode.getNumCrcBytes()); + return framed; + } + + private static String hex(byte[] bytes) { + return UtilShimmer.bytesToHexStringWithSpacesFormatted(bytes); + } + + private void assertParsed(byte[]... expectedPayloads) { + List expected = new ArrayList(); + for(byte[] payload:expectedPayloads){ + expected.add(hex(payload)); + } + List parsed = new ArrayList(); + // Package-private, so ShimmerPC does not inherit it + ShimmerBluetooth device = mDevice; + for(RawBytePacketWithPCTimeStamp packet:device.mABQPacketByeArray){ + parsed.add(hex(packet.mDataArray)); + } + assertEquals("every good data packet is parsed, once and in order", expected, parsed); + } + + /** What is left in the parser's buffer */ + private void assertBuffered(byte... expected) { + assertEquals(hex(expected), hex(mDevice.mByteArrayOutputStream.toByteArray())); + } + + /** The start retired as refused, the device not logging and still streaming */ + private void assertRefused() { + assertFalse("the NACK is taken", mDevice.mWaitForAck); + assertFalse("the next instruction can be sent", mDevice.isInstructionStackLock()); + assertNull("the ACK timer is cancelled, so its special case cannot take the device for logging", + mDevice.mTimerCheckForAckOrResp); + assertTrue("the refused start is retired", mDevice.getListofInstructions().isEmpty()); + assertFalse("the device is not taken to be logging", mDevice.isSDLogging()); + assertTrue("the stream goes on", mDevice.isStreaming()); + assertEquals(BT_STATE.STREAMING, mDevice.getBluetoothRadioState()); + assertEquals("eventLogStartRefused, once", Collections.singletonList(ShimmerObject.START_LOGGING_ONLY_COMMAND), + mLogStartsRefused); + assertEquals("eventCommandRefused, once", Collections.singletonList(ShimmerObject.START_LOGGING_ONLY_COMMAND), + mCommandsRefused); + } + + private void refusedBetweenTwoPackets(BT_CRC_MODE crcMode) { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + receive(dataPacket(payload(1), crcMode), bareNack(crcMode), + dataPacket(payload(2), crcMode), dataPacket(payload(3), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertRefused(); + assertParsed(payload(1), payload(2), payload(3)); + assertBuffered(ShimmerObject.DATA_PACKET); + } + + @Test + public void aLogStartRefusedMidStreamWithoutACrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.OFF); + } + + @Test + public void aLogStartRefusedMidStreamWithAOneByteCrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.ONE_BYTE_CRC); + } + + @Test + public void aLogStartRefusedMidStreamWithATwoByteCrc() { + refusedBetweenTwoPackets(BT_CRC_MODE.TWO_BYTE_CRC); + } + + /** The refusal is not left to the ACK timer, which would take the device for logging 2 s on */ + @Test + public void theAckTimerDoesNotLaterTakeTheDeviceForLogging() throws Exception { + refusedBetweenTwoPackets(BT_CRC_MODE.ONE_BYTE_CRC); + Thread.sleep(2500); + assertFalse("still not logging after the ACK timer would have run out", mDevice.isSDLogging()); + } + + /** + * The NACK's own CRC shows it is a NACK, so a corrupt data packet ahead of it is dropped without + * losing the refusal + */ + private void refusedAfterACorruptPacket(BT_CRC_MODE crcMode, int indexToCorrupt) { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + byte[] corrupt = dataPacket(payload(1), crcMode); + corrupt[indexToCorrupt] ^= 0x01; + receive(corrupt, bareNack(crcMode), dataPacket(payload(2), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + assertRefused(); + assertParsed(payload(2)); + assertBuffered(ShimmerObject.DATA_PACKET); + } + + @Test + public void aRefusalWithAOneByteCrcAfterACorruptPacket() { + refusedAfterACorruptPacket(BT_CRC_MODE.ONE_BYTE_CRC, 1); + } + + /** Only the packet CRC's second byte is wrong, which is checked separately */ + @Test + public void aRefusalWithATwoByteCrcAfterACorruptPacket() { + refusedAfterACorruptPacket(BT_CRC_MODE.TWO_BYTE_CRC, 1+PACKET_SIZE+1); + } + + /** + * After a resync the buffer can already hold bytes beyond the NACK. Exactly the packet, the + * NACK and its CRC are consumed, and the rest stay as the start of the next frame. + */ + private void refusedWithTheNextFrameAlreadyBuffered(BT_CRC_MODE crcMode) throws Exception { + streamingShimmer3r(crcMode); + startSdLoggingWhileStreaming(); + byte[] nextFrameStart = Arrays.copyOf(dataPacket(payload(2), crcMode), 4); + ByteArrayOutputStream buffered = new ByteArrayOutputStream(); + buffered.write(dataPacket(payload(1), crcMode)); + buffered.write(bareNack(crcMode)); + buffered.write(nextFrameStart); + mDevice.mByteArrayOutputStream.write(buffered.toByteArray()); + for(long timestamp=0;timestamp + * 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() + * No hardware. + * + * @author Mark Nolan + */ +public class API_00041_SoundLevelShimmerPCTest { + + private static final int IDX_AUDIO_CONFIG = 233; + /** v1.01.026, the first release with the channel */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 26); + + private static ShimmerPC shimmer() { + ShimmerPC shimmer = new ShimmerPC("COM99"); + shimmer.setShimmerVersionObjectAndCreateSensorMap(S3R); + return shimmer; + } + + private static ShimmerPC readFrom(int audioConfig) { + byte[] config = shimmer().generateConfigBytesForWritingToShimmer().clone(); + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + ShimmerPC shimmer = shimmer(); + shimmer.configBytesParse(config, COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int writtenAudioConfig(ShimmerPC shimmer) { + return shimmer.generateConfigBytesForWritingToShimmer()[IDX_AUDIO_CONFIG] & 0xFF; + } + + @Test + public void byte233SurvivesTheCopyConsensysWritesFrom() { + ShimmerPC shimmer = readFrom(0x13); + assertTrue(shimmer.isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + + ShimmerPC clone = shimmer.deepClone(); + assertNotNull(clone); + assertTrue(clone.isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)); + assertEquals(0x13, writtenAudioConfig(clone)); + + assertTrue(clone.setSensorEnabledState(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL, false)); + assertEquals("the audio mode stays", 0x03, writtenAudioConfig(clone)); + assertEquals("the original is untouched", 0x13, writtenAudioConfig(shimmer)); + } + + /** Consensys streams with the arrays data structure on */ + @Test + public void decodedWithTheArraysDataStructure() { + ShimmerPC shimmer = shimmer(); + shimmer.mNChannels = 2; + shimmer.interpretDataPacketFormat(2, new byte[] {SensorSoundLevel.CHANNEL_ID, 0x03}); + shimmer.enableArraysDataStructure(true); + + byte[] packet = new byte[shimmer.getPacketSize()]; + int iSoundLevel = packet.length - 4; + packet[iSoundLevel] = (byte) 0x8F; // 6543 = 0x198F + packet[iSoundLevel + 1] = (byte) 0x19; + ObjectCluster objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertEquals(65.43, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.CAL.toString()), 1e-9); + assertEquals(6543, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.UNCAL.toString()), 0); + + packet[iSoundLevel] = 0x00; // 0x8000, no level + packet[iSoundLevel + 1] = (byte) 0x80; + objectCluster = shimmer.buildMsg(packet, COMMUNICATION_TYPE.BLUETOOTH, false, 0); + assertTrue(Double.isNaN(objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.CAL.toString()))); + assertEquals(-32768, objectCluster.getFormatClusterValue(SensorSoundLevel.ObjectClusterSensorName.SOUND_LEVEL, CHANNEL_TYPE.UNCAL.toString()), 0); + } +} diff --git a/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java new file mode 100644 index 000000000..736f0a440 --- /dev/null +++ b/ShimmerPCBasicExamples/src/main/java/com/shimmerresearch/bluetooth/TestNackNotStreaming.java @@ -0,0 +1,233 @@ +package com.shimmerresearch.bluetooth; + +import java.util.ArrayList; +import java.util.List; + +import com.shimmerresearch.bluetooth.ShimmerBluetooth.BT_STATE; +import com.shimmerresearch.driver.BasicProcessWithCallBack; +import com.shimmerresearch.driver.CallbackObject; +import com.shimmerresearch.driver.ShimmerDevice; +import com.shimmerresearch.driver.ShimmerMsg; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.tools.bluetooth.BasicShimmerBluetoothManagerPc; + +/** + * DEV-982 / PR #293, on hardware: a command refused while NOT streaming. + * + *

Why not streaming

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

How it gets a NACK

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

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

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

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

Running it

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