diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java b/ShimmerDriver/src/main/java/com/shimmerresearch/bluetooth/ShimmerBluetooth.java index 9cf80eb89..e0f241f43 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; @@ -106,6 +107,10 @@ import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; import com.shimmerresearch.driver.Configuration.Shimmer3; import com.shimmerresearch.driver.calibration.CalibDetails.CALIB_READ_SOURCE; +import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; +import com.shimmerresearch.driver.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; @@ -271,7 +276,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"; @@ -310,9 +343,13 @@ public int getNumCrcBytes() { /** 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 { NONE, RN4678_ERROR_DETECTION, + REBOOT_ON_DISCONNECT, + /** The event channel's records, sent to a host that opts in (DEV-971). Firmware without the event channel NACKs it. */ + EVENT_STREAM, } public static final Map mBtCommandMapOther; @@ -383,6 +420,8 @@ public enum SHIMMER_FEATURE { 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_AUDIO_STATUS_COMMAND, new BtCommandDetails(GET_AUDIO_STATUS_COMMAND, "GET_AUDIO_STATUS_COMMAND", AUDIO_STATUS_RESPONSE)); + aMap.put(GET_EVENT_CHANNEL_STATUS_COMMAND, new BtCommandDetails(GET_EVENT_CHANNEL_STATUS_COMMAND, "GET_EVENT_CHANNEL_STATUS_COMMAND", EVENT_CHANNEL_STATUS_RESPONSE)); + mBtGetCommandMap = Collections.unmodifiableMap(aMap); } @@ -505,6 +544,8 @@ public enum SHIMMER_FEATURE { aMap.put(BT_FW_VERSION_STR_RESPONSE, new BtCommandDetails(BT_FW_VERSION_STR_RESPONSE, "BT_FW_VERSION_STR_RESPONSE", -1)); aMap.put(AUDIO_STATUS_RESPONSE, new BtCommandDetails(AUDIO_STATUS_RESPONSE, "AUDIO_STATUS_RESPONSE", AUDIO_STATUS_LENGTH)); + aMap.put(EVENT_CHANNEL_STATUS_RESPONSE, new BtCommandDetails(EVENT_CHANNEL_STATUS_RESPONSE, "EVENT_CHANNEL_STATUS_RESPONSE", EventChannelStatus.LENGTH)); + mBtResponseMap = Collections.unmodifiableMap(aMap); } @@ -853,7 +894,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. @@ -970,8 +1022,27 @@ private void processNotStreamingWaitForResp() { //Check to see whether it is a response byte else if(isKnownResponse(byteBuffer[0])){ byte responseCommand = byteBuffer[0]; - - processResponseCommand(responseCommand); + + if(responseCommand==INSTREAM_CMD_RESPONSE && mEventFramesPossible) { + /* 0x8A can be the reply (a wrapped one such as the status) + * or an event record frame sent before it, which is taken + * and the reply still waited for (DEV-971) */ + byte[] subtype = readBytes(1, INSTREAM_CMD_RESPONSE); + if(subtype==null) { + return; + } + if(subtype[0]==EVENT_RECORD_RESPONSE) { + readEventFrameRestFromPort(); + return; + } + processInstreamResponse(subtype[0], false); + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF) { + clearCrcBytesFromBuffer(responseCommand); + } + } + else { + processResponseCommand(responseCommand); + } //JD: only stop timer after process because there are readbyte opeartions in the processresponsecommand stopTimerCheckForAckOrResp(); //cancel the ack timer mWaitForResponse=false; @@ -1015,6 +1086,16 @@ && bytesAvailableToBeRead()) { if(byteBuffer[0]==NACK_COMMAND_PROCESSED) { printLogDataForDebugging("NACK received with no command awaiting a reply - ignored"); } + /* An event record frame, which comes with no ACK (DEV-971). The + * serial buffer is not cleared after it, since another frame may + * already be behind it. */ + else if(byteBuffer[0]==INSTREAM_CMD_RESPONSE && mEventFramesPossible) { + byte[] subtype = readBytes(1, INSTREAM_CMD_RESPONSE); + if(subtype!=null && subtype[0]==EVENT_RECORD_RESPONSE) { + readEventFrameRestFromPort(); + return; + } + } else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { printLogDataForDebugging("ACK RECEIVED , Connected State!!"); byteBuffer = readBytes(1, INSTREAM_CMD_RESPONSE); @@ -1026,8 +1107,17 @@ else if(byteBuffer[0]==ACK_COMMAND_PROCESSED) { } } } - - clearSerialBuffer(); + + /* With the event channel on, records can be queued behind + * anything read here: behind a status push (when a press starts + * logging, say), or behind the link CRC a bare ACK leaves (the + * opt-in's ACK, whose first record follows at once). So only the + * bytes just read are dropped, and the rest are left for the next + * pass; clearing the buffer would wipe the records with them + * (DEV-971). */ + if(!mEventFramesPossible) { + clearSerialBuffer(); + } } } @@ -1089,7 +1179,32 @@ else if(bufferTemp[0]==DATA_PACKET //Then handle the ACK from the last SET command processAckWhileStreaming(); } - + + //The event channel status, [ACK][0xBA][9], which is not wrapped in 0x8A: + //readEventChannelStatus() is not sent while streaming, but one sent just + //before a stream started is answered once packets flow (DEV-971) + else if(bufferTemp[getPacketSizeWithCrc()+2]==EVENT_CHANNEL_STATUS_RESPONSE + && mWaitForAck && mCurrentCommand==GET_EVENT_CHANNEL_STATUS_COMMAND){ + byte[] responseData = readBytes(EventChannelStatus.LENGTH, EVENT_CHANNEL_STATUS_RESPONSE); + stopTimerCheckForAckOrResp(); //cancel the ack timer + mWaitForAck=false; + mWaitForResponse=false; + if(responseData!=null){ + if(mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF){ + clearCrcBytesFromBuffer(EVENT_CHANNEL_STATUS_RESPONSE); + } + takeEventChannelStatus(responseData); + } + processDataPacket(bufferTemp); + if(getListofInstructions().size()>0){ + removeInstruction(0); + } + mTransactionCompleted=true; + setInstructionStackLock(false); + clearBuffers(); + return; + } + //this is for LogAndStream support, command is transmitted and ack received else if(isSupportedInStreamCmds() && bufferTemp[getPacketSizeWithCrc()+2]==INSTREAM_CMD_RESPONSE){ printLogDataForDebugging("COMMAND TXed and ACK RECEIVED IN STREAM"); @@ -1099,6 +1214,25 @@ 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); + if(mWaitForAck){ + processAckWhileStreaming(); + } + else { + // Nothing waits for an ACK, so the SET that went last must not be acknowledged again + printLogDataForDebugging("ACK with no command awaiting it, before an event record - ignored"); + } + readEventFrameRestFromPort(); + clearBuffers(); + return; + } + boolean isReplyToCommandInFlight = inStreamResponseCommand!=null && isReplyToCommandInFlight(inStreamResponseCommand[0]); if(isReplyToCommandInFlight){ @@ -1138,6 +1272,37 @@ 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){ + int packetEnd = getPacketSizeWithCrc()+1; + if (mBtCommsCrcModeCurrent != BT_CRC_MODE.OFF) { + //The packet's own CRC confirms it + if (!checkCrc(bufferTemp, getPacketSize() + 1)) { + discardBufferBytesToNextPacket(); + return; + } + } + else { + //With no link CRC, a 0x8A where the next packet should start is + //only a frame, and the packet before it only a packet, once the + //frame's own CRC checks out. Otherwise the boundary is wrong (a + //byte lost, say), and the bytes are discarded as before. + int frameLength = EventFrame.getFrameLength(bufferTemp, packetEnd, bufferTemp.length-packetEnd); + if (frameLength==EventFrame.NEED_MORE) { + return; //wait for the rest of the frame + } + if (frameLength==EventFrame.NOT_A_FRAME) { + discardBufferBytesToNextPacket(); + return; + } + } + processDataPacket(bufferTemp); + clearBytesFromStartOfBuffers(bufferTemp, packetEnd); + } //Data packet followed by a NACK (a command refused while streaming, e.g. //any SET blocked by the firmware because it is sensing, or a log start the //device cannot carry out, DEV-1431) @@ -1200,6 +1365,10 @@ protected void processWhileStreaming() { printLogDataForDebugging("readbyte null"); } + if(processEventFrameAtStartOfBuffer()){ + return; + } + if(processAckAtStartOfBuffer()){ return; } @@ -1247,6 +1416,14 @@ private boolean processAckAtStartOfBuffer() { if(bufferTemp.length==2){ return true; //wait for the response opcode } + //Or a bare ACK to the SET command in flight, followed by an event record + //frame, which has no ACK of its own (DEV-971) + if(mEventFramesPossible && bufferTemp[2]==EVENT_RECORD_RESPONSE + && isKnownSetCommand(mCurrentCommand) && mBtCommsCrcModeCurrent==BT_CRC_MODE.OFF){ + clearBytesFromStartOfBuffers(bufferTemp, 1); + processAckWhileStreaming(); + return true; + } if(bufferTemp.length>3 || !isReplyToCommandInFlight(bufferTemp[2])){ return false; } @@ -1469,6 +1646,11 @@ else if(inStreamResponseCommand==VBATT_RESPONSE) { + "\tBatt %=" + battStatusDetails.getEstimatedChargePercentageParsed()); } } + else if(inStreamResponseCommand==EVENT_RECORD_RESPONSE && mEventFramesPossible){ + // Carries its own CRC and never the link CRC, so nothing more to clear + readEventFrameRestFromPort(); + responseWasParsed = false; + } else { responseWasParsed = false; @@ -2040,7 +2222,14 @@ else if(responseCommand==RWC_RESPONSE) { } } else if(responseCommand==INSTREAM_CMD_RESPONSE) { - processInstreamResponse(false); + byte[] inStreamResponseCommand = readBytes(1, INSTREAM_CMD_RESPONSE); + if(inStreamResponseCommand!=null){ + processInstreamResponse(inStreamResponseCommand[0], false); + if(inStreamResponseCommand[0]==EVENT_RECORD_RESPONSE && mEventFramesPossible){ + // An event record frame carries its own CRC and never the link CRC (DEV-971) + responseWasParsed = false; + } + } } else if(responseCommand==LSM303DLHC_ACCEL_LPMODE_RESPONSE) { byte[] responseData = readBytes(1, responseCommand); @@ -2207,6 +2396,14 @@ else if(responseCommand==AUDIO_STATUS_RESPONSE) { } } + + else if(responseCommand==EVENT_CHANNEL_STATUS_RESPONSE) { + byte[] responseData = readBytes(EventChannelStatus.LENGTH, responseCommand); + if(responseData!=null){ + takeEventChannelStatus(responseData); + } + } + else { consolePrintLn("Unhandled BT response: " + responseCommand); responseWasParsed = false; @@ -2234,12 +2431,16 @@ else if(responseCommand==AUDIO_STATUS_RESPONSE) { *

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

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

Protected because ShimmerAndroidAPI's Shimmer has its own streaming * parser, which needs to fail the command in flight the same way. */ protected void processNackFromCommand() { stopTimerCheckForAckOrResp(); //cancel the ack timer - printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand)); byte refusedCommand = mCurrentCommand; @@ -2249,9 +2450,18 @@ protected void processNackFromCommand() { * skip that command. */ boolean instructionStillQueued = mWaitForAck; + //Asked before the instruction is removed, since it looks at it + boolean eventChannelProbe = instructionStillQueued && isEventChannelProbeInFlight(); + printLogDataForDebugging("NACK Received for Command: \t\t" + btCommandToString(mCurrentCommand) + + (eventChannelProbe ? ", no event channel" : "")); + mWaitForAck=false; mWaitForResponse=false; + if(eventChannelProbe){ + setEventChannelSupported(false); + } + /* Mirror the ACK path's progress report so that an operation containing a * refused command can still reach its end value. * BluetoothProgressReportPerDevice.updateProgress() derives the counter @@ -2282,7 +2492,9 @@ protected void processNackFromCommand() { if(refusedCommand==START_LOGGING_ONLY_COMMAND || refusedCommand==START_SDBT_COMMAND){ processLogStartRefused(refusedCommand); } - eventCommandRefused(refusedCommand); + if(!eventChannelProbe){ + eventCommandRefused(refusedCommand); + } } /** @@ -2708,7 +2920,10 @@ else if(currentCommand==SET_TEST){ InShimmerTest = true; } else if (currentCommand == SET_FEATURE) { - // TODO: do something? + if(isEventChannelProbeInFlight()) { + // Only firmware with the event channel ACKs FEATURE_EVENT_STREAM + setEventChannelSupported(true); + } } else { //unhandled set command @@ -3064,6 +3279,11 @@ private void initializeShimmer3or3R(int hardwareVersion){ writeSetFeatureCommand(SHIMMER_FEATURE.RN4678_ERROR_DETECTION.ordinal(), 1); } + // The firmware may have changed since the last connection + setEventChannelSupported(null); + resetEventChannelConnectionState(); + readEventChannelSupport(); + if (isSetupDeviceWhileConnecting()){ if(mFixedShimmerConfigMode!=null && mFixedShimmerConfigMode!=FIXED_SHIMMER_CONFIG_MODE.NONE){ boolean triggerConfig = setFixedConfigWhenConnecting(); @@ -5168,7 +5388,36 @@ public void writeConfigBytes(){ public void writeConfigBytes(boolean readBackAfter){ if(this.getFirmwareVersionCode()>=6){ - writeConfigBytes(mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, generateConfigBytesForWritingToShimmer(), mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, readBackAfter); + byte[] configBytes = generateConfigBytesForWritingToShimmer(); + // Bytes the driver does not have from this Shimmer, as when a + // configuration is written on connect before it is read. They + // are skipped, so that the Shimmer keeps its own. Only on + // firmware that can have byte 232: older firmware is still + // written in whole chunks. + List skipIndexes = new ArrayList(); + if(mConfigByteLayout instanceof ConfigByteLayoutShimmer3){ + ConfigByteLayoutShimmer3 configByteLayoutCast = (ConfigByteLayoutShimmer3) mConfigByteLayout; + if(configByteLayoutCast.idxButtonLogMode>0){ + // Byte 232 (DEV-971), neither read nor set + if(!isButtonLogModeKnown()){ + skipIndexes.add(configByteLayoutCast.idxButtonLogMode); + } + // Byte 233 (DEV-99, DEV-1413) on a Shimmer3R, neither read + // nor set (the sound level or the audio mode) + if(configByteLayoutCast.idxAudioConfig>0 && !isAudioConfigKnown()){ + skipIndexes.add(configByteLayoutCast.idxAudioConfig); + } + } + } + if(!skipIndexes.isEmpty()){ + writeMem(SET_INFOMEM_COMMAND, mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, skipIndexes); + if(readBackAfter){ + readConfigBytes(); + } + } + else { + writeConfigBytes(mConfigByteLayout.MSP430_5XX_INFOMEM_D_ADDRESS, configBytes, mConfigByteLayout.MSP430_5XX_INFOMEM_LAST_ADDRESS, readBackAfter); + } } } @@ -5189,6 +5438,19 @@ public void writeConfigBytes(int startAddress, byte[] buf, int maxMemAddress, bo } public void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress){ + writeMem(command, startAddress, buf, maxMemAddress, Collections.emptyList()); + } + + /** + * Writes buf in chunks of up to 128 bytes, as {@link #writeMem(int, int, byte[], int)} + * does, but leaves out the bytes at skipIndexes: a chunk holding any goes + * as the runs of bytes between them, each at its own address. Every other + * chunk starts where it would have, which matters to the firmware for the + * chunks at 0 and 128. + * + * @param skipIndexes the indexes into buf of the bytes not to write, empty to write them all + */ + private void writeMem(int command, int startAddress, byte[] buf, int maxMemAddress, List skipIndexes){ this.mNumOfMemSetCmds = 0; if(this.getFirmwareVersionCode()>=6){ @@ -5212,10 +5474,18 @@ public void writeMem(int command, int startAddress, byte[] buf, int maxMemAddres currentPacketNumBytes = numBytesRemaining; } - byte[] infoSegBuf = Arrays.copyOfRange(buf, currentBytePointer, currentBytePointer + currentPacketNumBytes); - - writeMemCommand(command, currentStartAddr, infoSegBuf); - mNumOfMemSetCmds += 1; + // The chunk, or its runs between the bytes skipped + int chunkEnd = currentBytePointer + currentPacketNumBytes; + int runStart = currentBytePointer; + for(int i=currentBytePointer;i<=chunkEnd;i++){ + if(i==chunkEnd || skipIndexes.contains(i)){ + if(i>runStart){ + writeMemCommand(command, currentStartAddr + (runStart-currentBytePointer), Arrays.copyOfRange(buf, runStart, i)); + mNumOfMemSetCmds += 1; + } + runStart = i+1; + } + } currentStartAddr += currentPacketNumBytes; numBytesRemaining -= currentPacketNumBytes; @@ -5266,6 +5536,254 @@ public void writeSetFeatureCommand(int feature, int setting){ writeInstruction(new byte[]{SET_FEATURE, (byte)feature, (byte)setting}); } + /** + * Asks the Shimmer whether its firmware has the event channel, and with it + * configuration byte 232 (DEV-971): SET_FEATURE with FEATURE_EVENT_STREAM + * and 0, which changes nothing, since a connection starts opted out. + * Firmware with the event channel ACKs it and firmware without NACKs it; + * {@link #isEventChannelSupported()} has the answer. LogAndStream_Shimmer3R + * v1.01.026 is the first Shimmer3R release with the event channel, and no + * Shimmer3 release has it yet. The builds before a release report the + * release before them, so the driver asks rather than going by the version. + *

+ * Firmware older than SET_FEATURE is not asked, and has no event channel. + * Nor is a Shimmer that is streaming, where a NACK is not yet handled. + */ + public void readEventChannelSupport() { + if(!getShimmerVerObject().isSupportedSetFeature()) { + setEventChannelSupported(false); + } + else if(!isStreaming()) { + writeSetFeatureCommand(SHIMMER_FEATURE.EVENT_STREAM.ordinal(), 0); + } + } + + /** Whether the command awaiting its ACK is SET_FEATURE for FEATURE_EVENT_STREAM, which tells whether the event channel is there */ + private boolean isEventChannelProbeInFlight() { + if(mCurrentCommand!=SET_FEATURE) { + return false; + } + List instructions = getListofInstructions(); + if(instructions.isEmpty()) { + return false; + } + byte[] instruction = instructions.get(0); + return instruction!=null && instruction.length>1 + && instruction[0]==SET_FEATURE + && instruction[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal(); + } + + /** + * 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() || isStreamStartQueued()) { + return false; + } + writeInstruction(new byte[]{GET_EVENT_CHANNEL_STATUS_COMMAND}); + return true; + } + + /** + * Whether a start of streaming is queued or in flight: the instruction list + * keeps a command until it is answered, and isStreaming() turns true only + * then. A status read queued behind it would be answered between data packets. + */ + private boolean isStreamStartQueued() { + List instructions = getListofInstructions(); + synchronized(instructions){ + for(byte[] instruction:instructions){ + if(instruction!=null && instruction.length>0 + && (instruction[0]==START_STREAMING_COMMAND || instruction[0]==START_SDBT_COMMAND)){ + return true; + } + } + } + return false; + } + + /** The last answer to {@link #readEventChannelStatus()}, or null */ + public EventChannelStatus getEventChannelStatus() { + return mEventChannelStatus; + } + + /** 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); + } + + /** Keeps the event channel status's 9 bytes and hands them to each listener */ + private void takeEventChannelStatus(byte[] responseData) { + EventChannelStatus status = EventChannelStatus.parse(responseData, 0); + mEventChannelStatus = status; + printLogDataForDebugging("Event channel status:\t" + status); + for(EventChannelListener listener:getEventChannelListeners()){ + try { + listener.onEventChannelStatus(this, status); + } catch (RuntimeException e) { + printLogDataForDebugging("Event channel listener threw: " + e); + } + } + } + + private void dispatchEventRecord(EventRecord record) { + mEventFramesReceived++; + printLogDataForDebugging("Event record:\t" + record); + for(EventChannelListener listener:getEventChannelListeners()) { + try { + listener.onEventRecord(this, record); + } catch (RuntimeException e) { + printLogDataForDebugging("Event channel listener threw: " + e); + } + } + } + //endregion --------- READ/WRITE FUNCTIONS --------- diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java index 3578fdd21..6c412e5c6 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java @@ -908,6 +908,12 @@ public class GuiLabelConfig{ public static final String ENABLE_ERROR_LEDS_SD = "SD Error LEDs"; public static final String LOW_POWER_AUTOSTOP = "Low-power Autostop"; public static final String AUDIO_MODE = "Audio Mode"; + /** Configuration byte 232 bits 0-2 (DEV-971), an Integer, see ButtonLogMode.BUTTON_MODE_* */ + public static final String BUTTON_MODE = "Button Mode"; + /** Configuration byte 232 bits 3-4 (DEV-971), an Integer, see ButtonLogMode.LOG_TRIGGERS_* */ + public static final String LOG_TRIGGERS = "Log Triggers"; + /** Configuration byte 232 bit 5 (DEV-971), a Boolean */ + public static final String TTL_INPUT = "TTL Input"; public static final String KINEMATIC_LPM = "Kinematic Sensors Low-Power Mode";//XXX-RS-LSM-SensorClass? What about HighResolutionMode?! public static final String CALIBRATION_ALL = AbstractSensor.GuiLabelConfigCommon.CALIBRATION_ALL; diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java index abe265efd..8d450164b 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/ShimmerObject.java @@ -36,6 +36,7 @@ import com.shimmerresearch.driver.calibration.UtilCalibration; import com.shimmerresearch.driver.calibration.CalibDetails.CALIB_READ_SOURCE; import com.shimmerresearch.driver.shimmer2r3.BluetoothModuleVersionDetails; +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; import com.shimmerresearch.driver.shimmer2r3.ConfigByteLayoutShimmer3; import com.shimmerresearch.driver.shimmerGq.ConfigByteLayoutShimmerGq802154; import com.shimmerresearch.driverUtilities.ChannelDetails; @@ -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; /** Shimmer3R audio (DEV-99): firmware without audio leaves it unanswered */ public static final byte GET_AUDIO_STATUS_COMMAND = (byte) 0xBC; @@ -584,6 +590,13 @@ public String toString() { /** Only internal apps may switch raw audio on; any other app writes it off. */ private static boolean sIsRawAudioAllowed = false; + /** Configuration byte 232 as read from the Shimmer or set by the host (DEV-971), see {@link ButtonLogMode} */ + private int mButtonLogMode = 0; + /** Whether mButtonLogMode is the Shimmer's own: read from it, or set by the host */ + private boolean mIsButtonLogModeKnown = false; + /** The Shimmer's answer to the event channel probe (SET_FEATURE): null until it has answered */ + private Boolean mIsEventChannelSupported = null; + protected int mTrialId = 0; protected int mTrialNumberOfShimmers = 0; protected int mTrialDurationEstimatedInSecs = 0; @@ -5011,6 +5024,10 @@ public void setDefaultShimmerConfiguration() { setButtonStart(true); setShowErrorLedsRtc(true); setShowErrorLedsSd(true); + // Byte 232's own default, legacy. Whether it is the Shimmer's is + // left as it was: a default the Shimmer was never read for is not + // written to it over Bluetooth. + mButtonLogMode = 0; setBluetoothBaudRate(9); //460800 @@ -5195,6 +5212,13 @@ public void configBytesParse(byte[] configBytes, COMMUNICATION_TYPE commType) { if(isVerCompatibleWithAnyOf(Configuration.Shimmer3.configOptionLowPowerAutoStop.mListOfCompatibleVersionInfo)) { setLowBattAutoStop((configBytes[configByteLayoutCast.idxSDExperimentConfig1] >> configByteLayoutCast.bitShiftLowBattStop) & configByteLayoutCast.maskLowBattStop); } + + // Kept as read, 0xFF included, so that a full configuration + // write gives the Shimmer back its own byte + if(configByteLayoutCast.idxButtonLogMode>0 && configBytes.length>configByteLayoutCast.idxButtonLogMode) { + mButtonLogMode = configBytes[configByteLayoutCast.idxButtonLogMode] & 0xFF; + mIsButtonLogModeKnown = true; + } byte[] macIdBytes = new byte[configByteLayoutCast.lengthMacIdBytes]; System.arraycopy(configBytes, configByteLayoutCast.idxMacAddress, macIdBytes, 0 , configByteLayoutCast.lengthMacIdBytes); @@ -5411,6 +5435,15 @@ public byte[] configBytesGenerate(boolean generateForWritingToShimmer, COMMUNICA mConfigBytes[configByteLayoutCast.idxSDNumOfShimmers] = (byte) (mTrialNumberOfShimmers & 0xFF); } + + // Byte 232 (DEV-971). The image starts from zeros, so without + // this a full write turned the button mode back to legacy. The + // rules go first: they hold userButtonEnable and singleTouchStart, + // packed into bytes 217 and 218 below, as the firmware will. + if(configByteLayoutCast.idxButtonLogMode>0) { + applyButtonLogModeRules(); + mConfigBytes[configByteLayoutCast.idxButtonLogMode] = (byte) getButtonLogModeToWrite(); + } if(getFirmwareIdentifier()==FW_ID.SDLOG || getFirmwareIdentifier()==FW_ID.LOGANDSTREAM || getFirmwareIdentifier()==FW_ID.STROKARE) { mConfigBytes[configByteLayoutCast.idxSDExperimentConfig0] = (byte) ((mButtonStart & configByteLayoutCast.maskButtonStart) << configByteLayoutCast.bitShiftButtonStart); @@ -6688,6 +6721,163 @@ public void setDisableBluetooth(boolean state) { public void setButtonStart(int state) { this.mButtonStart = state; } + + /** + * Configuration byte 232 (DEV-971) as the driver holds it: as read from the + * Shimmer, 0xFF included, or as set. {@link #getButtonLogModeCorrected()} + * is what the firmware acts on. + */ + public int getButtonLogMode() { + return mButtonLogMode; + } + + /** + * Sets configuration byte 232 (DEV-971) whole. The firmware corrects a + * value it cannot act on to 0 (see {@link ButtonLogMode#correct(int)}). + * Like the field setters, it holds userButtonEnable and singleTouchStart + * as that firmware will ({@link #applyButtonLogModeRules()}). + */ + public void setButtonLogMode(int value) { + mButtonLogMode = value & 0xFF; + mIsButtonLogModeKnown = true; + applyButtonLogModeRules(); + } + + /** + * Sets the three fields of configuration byte 232 (DEV-971) at once. + * + * @param buttonMode one of ButtonLogMode.BUTTON_MODE_* + * @param logTriggers one of ButtonLogMode.LOG_TRIGGERS_*, read only when buttonMode is not legacy + * @param ttlInputEnabled whether the TTL input's edges are recorded + */ + public void setButtonLogMode(int buttonMode, int logTriggers, boolean ttlInputEnabled) { + setButtonLogMode(ButtonLogMode.compose(0, buttonMode, logTriggers, ttlInputEnabled)); + } + + /** What the user button does: one of ButtonLogMode.BUTTON_MODE_*, as the firmware will act on it */ + public int getButtonMode() { + return getButtonLogModeCorrected() & ButtonLogMode.MASK_BUTTON_MODE; + } + + /** + * Sets what the user button does (byte 232 bits 0-2). The other two fields + * keep the values last set, so they can be set in any order. Not + * BUTTON_MODE_LEGACY, it holds userButtonEnable at the mode's nearest + * equivalent and clears singleTouchStart where no press can start logging, + * as the firmware does. + * + * @param buttonMode one of ButtonLogMode.BUTTON_MODE_* + */ + public void setButtonMode(int buttonMode) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, buttonMode, ButtonLogMode.getRawLogTriggers(mButtonLogMode), ButtonLogMode.isRawTtlInputEnabled(mButtonLogMode))); + } + + /** + * What else starts SD logging: one of ButtonLogMode.LOG_TRIGGERS_*, as the + * firmware will act on it. Always LOG_TRIGGERS_HOST while the button mode + * is legacy, which does not read them. + */ + public int getLogTriggers() { + return (getButtonLogModeCorrected() & ButtonLogMode.MASK_LOG_TRIGGERS) >> ButtonLogMode.BIT_SHIFT_LOG_TRIGGERS; + } + + /** + * Sets what else starts SD logging (byte 232 bits 3-4). Read only when the + * button mode is not legacy, but kept for when it is set. + * + * @param logTriggers one of ButtonLogMode.LOG_TRIGGERS_* + */ + public void setLogTriggers(int logTriggers) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, ButtonLogMode.getRawButtonMode(mButtonLogMode), logTriggers, ButtonLogMode.isRawTtlInputEnabled(mButtonLogMode))); + } + + /** Whether the TTL input's edges are recorded, as the firmware will act on it */ + public boolean isTtlInputEnabled() { + return (getButtonLogModeCorrected() & ButtonLogMode.MASK_TTL_INPUT)!=0; + } + + /** Sets whether the TTL input's edges are recorded (byte 232 bit 5), whatever the button mode */ + public void setTtlInputEnabled(boolean ttlInputEnabled) { + setButtonLogMode(ButtonLogMode.compose(mButtonLogMode, ButtonLogMode.getRawButtonMode(mButtonLogMode), ButtonLogMode.getRawLogTriggers(mButtonLogMode), ttlInputEnabled)); + } + + /** + * Whether the driver has the Shimmer's own byte 232: read from it, or set + * here. When it has neither, a full configuration write over Bluetooth + * leaves the Shimmer's byte as it is. + */ + public boolean isButtonLogModeKnown() { + return mIsButtonLogModeKnown; + } + + /** + * Whether the driver has the Shimmer3R's own byte 233, the microphone's + * configuration ({@link SensorSoundLevel#isAudioConfigKnown(ShimmerDevice)}). + * True where there is no such byte. + */ + public boolean isAudioConfigKnown() { + AbstractSensor abstractSensor = getSensorClass(AbstractSensor.SENSORS.SOUND_LEVEL); + return !(abstractSensor instanceof SensorSoundLevel) || ((SensorSoundLevel) abstractSensor).isAudioConfigKnown(this); + } + + /** + * Whether byte 232 can be taken at its word: the Shimmer answered the event + * channel probe, or the byte holds a value the firmware keeps. Firmware + * without the byte leaves it 0xFF, which is not one, and the dock cannot + * probe. + */ + public boolean isButtonLogModeMeaningful() { + return (mIsEventChannelSupported!=null && mIsEventChannelSupported) || ButtonLogMode.isValid(mButtonLogMode); + } + + /** + * Byte 232 as this Shimmer's firmware will act on it, corrected for its + * board; 0, legacy, where the byte cannot be taken at its word + * ({@link #isButtonLogModeMeaningful()}). + */ + public int getButtonLogModeCorrected() { + if(!isButtonLogModeMeaningful()) { + return 0; + } + return ButtonLogMode.correctForBoard(mButtonLogMode, getHardwareVersion(), getExpansionBoardDetails()); + } + + /** The byte a full configuration write puts at 232: corrected where meaningful, otherwise as read */ + protected int getButtonLogModeToWrite() { + return isButtonLogModeMeaningful() ? getButtonLogModeCorrected() : mButtonLogMode; + } + + /** + * On firmware that has byte 232, does what it does when it takes a + * configuration (ShimConfig_checkAndCorrectConfig): holds userButtonEnable + * (byte 217 bit 5) at the button mode's nearest equivalent, which the legacy + * mode leaves as it is, and clears singleTouchStart (byte 218 bit 7). That + * firmware is LogAndStream from the release that brought SET_FEATURE, none + * of it built with single touch (IS_SUPPORTED_SINGLE_TOUCH is 0 in + * log-and-stream-common), so it clears the bit whatever byte 232 holds. + * Other firmware changes neither here. + */ + protected void applyButtonLogModeRules() { + if(!mShimmerVerObject.isSupportedSetFeature()) { + return; + } + setSingleTouch(false); + setButtonStart(ButtonLogMode.getNearestUserButtonEnable(getButtonLogModeCorrected(), isButtonStart())); + } + + /** + * The Shimmer's answer to the event channel probe (DEV-971): true if it + * ACKed SET_FEATURE's FEATURE_EVENT_STREAM, false if it NACKed it or its + * firmware is older than SET_FEATURE, null until asked. Not version-based: + * the event channel's builds report the release before them. + */ + public Boolean isEventChannelSupported() { + return mIsEventChannelSupported; + } + + protected void setEventChannelSupported(Boolean isEventChannelSupported) { + mIsEventChannelSupported = isEventChannelSupported; + } protected void setDisableBluetooth(int state) { this.mDisableBluetooth = state; @@ -9788,6 +9978,15 @@ public Object getConfigValueUsingConfigLabel(String identifier, String configLab case(Configuration.Shimmer3.GuiLabelConfig.EXPERIMENT_SYNC_WHEN_LOGGING): returnValue = isSyncWhenLogging(); break; + case(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE): + returnValue = getButtonMode(); + break; + case(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS): + returnValue = getLogTriggers(); + break; + case(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT): + returnValue = isTtlInputEnabled(); + break; case(Configuration.Shimmer3.GuiLabelConfig.KINEMATIC_LPM): if(isLSM303DigitalAccelLPM()&&checkLowPowerGyro()&&checkLowPowerMag()) { @@ -9961,6 +10160,15 @@ public Object setConfigValueUsingConfigLabel(String identifier, String configLab setDisableBluetooth(!(boolean)valueToSet); setSyncWhenLogging((boolean)valueToSet); break; + case(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE): + setButtonMode((int)valueToSet); + break; + case(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS): + setLogTriggers((int)valueToSet); + break; + case(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT): + setTtlInputEnabled((boolean)valueToSet); + break; case(Configuration.Shimmer3.GuiLabelConfig.KINEMATIC_LPM): setLowPowerAccelWR((boolean)valueToSet); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java new file mode 100644 index 000000000..d27b0dd87 --- /dev/null +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ButtonLogMode.java @@ -0,0 +1,285 @@ +package com.shimmerresearch.driver.shimmer2r3; + +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID_SR_CODES; + +/** + * Configuration byte 232 (NV_BUTTON_LOG_MODE) on a Shimmer3 or Shimmer3R + * running LogAndStream with the event channel (DEV-971): what the user button + * does, what else may start SD logging, and whether the TTL input is recorded. + * + *

+ *    bits 0-2  button mode   BUTTON_MODE_*
+ *    bits 3-4  log triggers  LOG_TRIGGERS_*, read only when the button mode is not legacy
+ *    bit 5     TTL input recorded, whatever the button mode
+ *    bit 6     unused, cleared
+ *    bit 7     must be 0
+ * 
+ * + * 0 means "as before": userButtonEnable (byte 217 bit 5) decides both what a + * press does and whether leaving the dock starts logging. Anything the + * firmware cannot act on reads as 0 too: bit 7 set (erased memory, and + * firmware before the byte, is 0xFF), a reserved value, or log triggers under + * the legacy button mode. + * + * A port of log-and-stream-common Configuration/shimmer_button_log_mode.c, + * through the web SDK's devices/events/buttonLogMode.ts, kept rule for rule so + * the driver reads every one of the 256 values as the firmware does. The table + * and the reasons behind each rule are in log-and-stream-common + * docs/SHIMMER3_CONFIGURATION_INFOMEM.md section 8.3. + * + * @author Mark Nolan + */ +public class ButtonLogMode { + + /** Offset of the byte in the configuration bytes (128 + 104) */ + public static final int CONFIG_BYTE_INDEX = 232; + + public static final int MASK_BUTTON_MODE = 0x07; + public static final int BIT_SHIFT_LOG_TRIGGERS = 3; + public static final int MASK_LOG_TRIGGERS = 0x18; + public static final int MASK_TTL_INPUT = 0x20; + public static final int MASK_INVALID = 0x80; + + /** userButtonEnable decides, as before the byte existed */ + public static final int BUTTON_MODE_LEGACY = 0; + /** A press does nothing, and the LED shows nothing while it is held */ + public static final int BUTTON_MODE_DISABLED = 1; + /** A press starts and stops logging */ + public static final int BUTTON_MODE_SINGLE_PRESS = 2; + /** A double press starts and stops logging */ + public static final int BUTTON_MODE_DOUBLE_PRESS = 3; + /** A double press starts and stops logging, and every press and release is recorded */ + public static final int BUTTON_MODE_DOUBLE_PRESS_RECORDED = 4; + /** Every press and release is recorded, and a press never starts or stops logging */ + public static final int BUTTON_MODE_RECORDED = 5; + + /** A host command only */ + public static final int LOG_TRIGGERS_HOST = 0; + /** A host command, or leaving the dock (on Shimmer3R, unplugging USB-C) */ + public static final int LOG_TRIGGERS_HOST_OR_UNDOCK = 1; + /** Nothing: SD logging is off */ + public static final int LOG_TRIGGERS_NONE = 2; + + private static boolean isButtonModeBuilt(int buttonMode) { + return buttonMode>=BUTTON_MODE_DISABLED && buttonMode<=BUTTON_MODE_RECORDED; + } + + private static boolean canPressStartLogging(int buttonMode) { + return buttonMode==BUTTON_MODE_SINGLE_PRESS + || buttonMode==BUTTON_MODE_DOUBLE_PRESS + || buttonMode==BUTTON_MODE_DOUBLE_PRESS_RECORDED; + } + + /** + * The byte the firmware acts on, and writes back after a configuration + * write: raw itself when it is valid, 0 when bit 7 is set, and otherwise the + * button mode and log triggers cleared when either is not valid (a legacy + * byte's log triggers are not read, so they are cleared too). Bit 5 stands on + * its own unless bit 7 is set. Bit 6 is cleared. + */ + public static int correct(int raw) { + int value = raw & 0xFF; + if((value & MASK_INVALID)!=0){ + return 0; + } + int buttonMode = value & MASK_BUTTON_MODE; + int logTriggers = (value & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + int ttlInput = value & MASK_TTL_INPUT; + if(!isButtonModeBuilt(buttonMode) || logTriggers>LOG_TRIGGERS_NONE){ + return ttlInput; + } + return value & (MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + } + + /** Whether the firmware keeps the value as it is */ + public static boolean isValid(int raw) { + return correct(raw)==(raw & 0xFF); + } + + /** The button mode the firmware acts on (bits 0-2 of the corrected byte) */ + public static int getButtonMode(int raw) { + return correct(raw) & MASK_BUTTON_MODE; + } + + /** The log triggers the firmware acts on: 0 whenever the button mode is legacy */ + public static int getLogTriggers(int raw) { + return (correct(raw) & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + } + + /** Whether the TTL input's edges are recorded */ + public static boolean isTtlInputEnabled(int raw) { + return (correct(raw) & MASK_TTL_INPUT)!=0; + } + + /** Whether every press and release goes to the event channel (modes 4 and 5) */ + public static boolean isRecordingButtonPresses(int raw) { + int buttonMode = getButtonMode(raw); + return buttonMode==BUTTON_MODE_DOUBLE_PRESS_RECORDED || buttonMode==BUTTON_MODE_RECORDED; + } + + /** Whether SD logging is off: log triggers 2, which only a non-legacy mode reads */ + public static boolean isLoggingDisabled(int raw) { + return getLogTriggers(raw)==LOG_TRIGGERS_NONE; + } + + /** + * Whether a press (or, in the double-press modes, a double press) starts + * and stops logging. Logging off wins over a mode whose press would: the + * LED still shows the press, and nothing starts. + */ + public static boolean isPressStartingLogging(int raw, boolean userButtonEnable) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return userButtonEnable; + } + return canPressStartLogging(buttonMode) && !isLoggingDisabled(raw); + } + + /** + * Whether leaving the dock, or on Shimmer3R unplugging USB-C, starts + * logging. Never with single touch, where the sync centre's press starts + * every node. + */ + public static boolean isUndockStartingLogging(int raw, boolean userButtonEnable, boolean singleTouchStart) { + if(singleTouchStart){ + return false; + } + if(getButtonMode(raw)==BUTTON_MODE_LEGACY){ + return !userButtonEnable; + } + return getLogTriggers(raw)==LOG_TRIGGERS_HOST_OR_UNDOCK; + } + + /** + * The userButtonEnable the firmware holds byte 217 at for this byte, so a + * host or firmware that knows only byte 217 never falls back to an undock + * start. False only where a press cannot start logging and leaving the dock + * does; otherwise true. A legacy byte leaves userButtonEnable as it is. + */ + public static boolean getNearestUserButtonEnable(int raw, boolean userButtonEnable) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return userButtonEnable; + } + return !(!canPressStartLogging(buttonMode) && getLogTriggers(raw)==LOG_TRIGGERS_HOST_OR_UNDOCK); + } + + /** + * Whether single touch can work: it needs a press that can start logging. + * Firmware built with single touch clears singleTouchStart when this is + * false. No LogAndStream release is built with it, and each clears + * singleTouchStart whatever this byte holds. + */ + public static boolean isSingleTouchAllowed(int raw) { + int buttonMode = getButtonMode(raw); + if(buttonMode==BUTTON_MODE_LEGACY){ + return true; + } + return canPressStartLogging(buttonMode) && !isLoggingDisabled(raw); + } + + /** + * The corrected byte with press recording taken out, as the firmware does + * on a board with no button edges to record (SR48-6-0): a recorded double + * press becomes a plain double press, and recording alone becomes disabled. + */ + public static int withoutPressRecording(int raw) { + int fixed = correct(raw); + int rest = fixed & ~MASK_BUTTON_MODE & 0xFF; + switch(fixed & MASK_BUTTON_MODE){ + case BUTTON_MODE_DOUBLE_PRESS_RECORDED: + return rest | BUTTON_MODE_DOUBLE_PRESS; + case BUTTON_MODE_RECORDED: + return rest | BUTTON_MODE_DISABLED; + default: + return fixed; + } + } + + /** + * The byte for a set of settings, corrected the way the firmware will + * correct it, so what a host writes is what it reads back. A legacy button + * mode drops the log triggers, and an out-of-range value makes the button + * mode and log triggers read as legacy while the TTL bit stands. + */ + public static int encode(int buttonMode, int logTriggers, boolean ttlInputEnabled) { + return correct(compose(0, buttonMode, logTriggers, ttlInputEnabled)); + } + + /** + * The byte with its three fields replaced, before correction, so fields can + * be set one at a time in any order: log triggers set while the button mode + * is still legacy survive until the mode is set. Bits 6 and 7 come out + * clear; an out-of-range button mode or log triggers leaves that field 0. + */ + public static int compose(int raw, int buttonMode, int logTriggers, boolean ttlInputEnabled) { + int value = (raw & MASK_INVALID)!=0 ? 0 : raw & (MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + value &= ~(MASK_BUTTON_MODE | MASK_LOG_TRIGGERS | MASK_TTL_INPUT); + if(buttonMode>=0 && buttonMode<=MASK_BUTTON_MODE){ + value |= buttonMode; + } + if(logTriggers>=0 && logTriggers<=(MASK_LOG_TRIGGERS >> BIT_SHIFT_LOG_TRIGGERS)){ + value |= logTriggers << BIT_SHIFT_LOG_TRIGGERS; + } + if(ttlInputEnabled){ + value |= MASK_TTL_INPUT; + } + return value; + } + + /** The raw fields of a byte, bit 7 making all of them 0, as a setter starts from them */ + public static int getRawButtonMode(int raw) { + return (raw & MASK_INVALID)!=0 ? 0 : raw & MASK_BUTTON_MODE; + } + + public static int getRawLogTriggers(int raw) { + return (raw & MASK_INVALID)!=0 ? 0 : (raw & MASK_LOG_TRIGGERS) >> BIT_SHIFT_LOG_TRIGGERS; + } + + public static boolean isRawTtlInputEnabled(int raw) { + return (raw & MASK_INVALID)==0 && (raw & MASK_TTL_INPUT)!=0; + } + + /** + * Whether a board's button edges reach the firmware. Not on SR48-6-0, a + * Shimmer3R whose button is wired to BOOT0, whose interrupt is used for dock + * detection (ShimBrd_isBoardSr48_6_0, log-and-stream-common + * Boards/shimmer_boards.c). A board whose identity is unknown gets it. + */ + public static boolean isButtonEdgeRecordingSupported(int hardwareVersion, ExpansionBoardDetails board) { + return !isSr48_6_0(hardwareVersion, board); + } + + /** Whether a board has the TTL input. Not on SR48-6-0 (ShimBrd_isTtlInputSupported). */ + public static boolean isTtlInputSupported(int hardwareVersion, ExpansionBoardDetails board) { + return !isSr48_6_0(hardwareVersion, board); + } + + private static boolean isSr48_6_0(int hardwareVersion, ExpansionBoardDetails board) { + return hardwareVersion==HW_ID.SHIMMER_3R + && board!=null + && board.getExpansionBoardId()==HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED + && board.getExpansionBoardRev()==6 + && board.getExpansionBoardRevSpecial()==0; + } + + /** + * The byte the firmware keeps on a board: corrected, with press recording + * and the TTL input taken out where the board has neither + * (ShimConfig_checkAndCorrectConfig, log-and-stream-common + * Configuration/shimmer_config.c). + */ + public static int correctForBoard(int raw, int hardwareVersion, ExpansionBoardDetails board) { + int value = correct(raw); + if(!isButtonEdgeRecordingSupported(hardwareVersion, board)){ + value = withoutPressRecording(value); + } + if(!isTtlInputSupported(hardwareVersion, board)){ + value &= ~MASK_TTL_INPUT & 0xFF; + } + return value; + } + +} diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java index 5c3f01ae6..57c76ecfd 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driver/shimmer2r3/ConfigByteLayoutShimmer3.java @@ -105,6 +105,8 @@ public class ConfigByteLayoutShimmer3 extends ConfigByteLayout implements Serial public int idxMacAddress = 128+96; // 6bytes public int idxSDConfigDelayFlag = 128+102; public int idxBtFactoryReset = 0; + /** Button mode, log triggers and TTL input (DEV-971), see {@link ButtonLogMode}. 0 where the firmware cannot have it. */ + public int idxButtonLogMode = 0; public int idxNode0 = 128+128+0; @@ -417,6 +419,14 @@ public ConfigByteLayoutShimmer3(int firmwareIdentifier, int firmwareVersionMajor || compareVersions(FW_ID.LOGANDSTREAM,0,8,1)) { idxBtFactoryReset = 128+103; } + + // The event channel's builds report the release before them, so only + // the earliest firmware that can carry it is known from the version. + // Whether it is really there is the SET_FEATURE probe's answer + // (ShimmerBluetooth.readEventChannelSupport()) or a valid byte read back. + if(mShimmerVerObject.isSupportedSetFeature()) { + idxButtonLogMode = ButtonLogMode.CONFIG_BYTE_INDEX; + } // if(mShimmerVerObject.isVerCompatibleWithAnyOf(Configuration.Shimmer3.configOptionLowPowerAutoStop.mListOfCompatibleVersionInfo)) { // maskLowBattStop = 0; @@ -562,6 +572,9 @@ public HashMap getMapOfByteDescriptions(){ if(idxBtFactoryReset>0){ mapOfByteDescriptions.put(idxBtFactoryReset, "idxBtFactoryReset"); } + if(idxButtonLogMode>0){ + mapOfByteDescriptions.put(idxButtonLogMode, "idxButtonLogMode"); + } mapOfByteDescriptions.put(idxNode0, "Node0"); diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/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/driverUtilities/ShimmerVerObject.java b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java index 05c046afd..c22e31888 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/driverUtilities/ShimmerVerObject.java @@ -748,4 +748,22 @@ public boolean isSupportedBtBatteryRequest() { || compareVersions(HW_ID.SHIMMER_3, FW_ID.BTSTREAM, 0, 8, 1)); } + /** + * Whether the firmware has SET_FEATURE (0xB7), with its feature id and + * value, and NACKs a feature id it does not know. It came with + * log-and-stream-common: LogAndStream_Shimmer3R v1.0.52 and + * LogAndStream_Shimmer3 v1.0.17. Older firmware discards the 0xB7 byte + * unanswered and takes the two bytes after it as commands, so a feature id + * of 3 there is GET_SAMPLING_RATE_COMMAND, which is ACKed. SET_FEATURE must + * not be sent to it. + *

+ * This is also the earliest firmware whose builds can carry the DEV-971 + * event channel and configuration byte 232: those builds report the release + * before them, so the version alone cannot say whether they do. + */ + public boolean isSupportedSetFeature() { + return compareVersions(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 52) + || compareVersions(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17); + } + } diff --git a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java index a9879ff3f..7dbb508b8 100644 --- a/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java +++ b/ShimmerDriver/src/main/java/com/shimmerresearch/sensors/soundlevel/SensorSoundLevel.java @@ -75,6 +75,8 @@ public class SensorSoundLevel extends AbstractSensor { /** Byte 233's audio mode and gain preset as read (bits 0-3, DEV-99), written back as they are */ private int mAudioModeAndGain = 0; + /** Whether byte 233 has been read from the Shimmer, and so mAudioModeAndGain is its own */ + private boolean mIsAudioConfigRead = false; public class GuiLabelSensors{ public static final String SOUND_LEVEL = "Sound Level"; @@ -255,6 +257,7 @@ public void configBytesParse(ShimmerDevice shimmerDevice, byte[] configBytes, CO if(isAudioModeSupported(shimmerDevice)){ ((ShimmerObject) shimmerDevice).setAudioMode(mAudioModeAndGain & configByteLayoutCast.maskAudioMode); } + mIsAudioConfigRead = true; SensorDetails sensorDetails = mSensorMap.get(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL); if(sensorDetails!=null){ @@ -278,6 +281,26 @@ public int getAudioModeAndGain() { return mAudioModeAndGain; } + /** + * Whether a configuration write has a byte 233 to give: it was read from + * the Shimmer, or a part of it was set here, the sound level turned on or + * the audio mode (DEV-1459) changed from the one read. Before a read, bits + * 0-3 are not known, and writing them as 0 would turn the Shimmer's audio + * mode off. With the sound level or an audio mode set before a read, the + * rest of bits 0-3 are written as 0 all the same, since one bit cannot be + * written on its own. An audio mode set back to Off before a read looks + * like one never set, so the Shimmer keeps its own. + */ + public boolean isAudioConfigKnown(ShimmerDevice shimmerDevice) { + if(mIsAudioConfigRead || isSensorEnabled(Configuration.Shimmer3.SENSOR_ID.SHIMMER_SOUND_LEVEL)){ + return true; + } + // As configBytesGenerate() decides whether to write the mode set here + ConfigByteLayout configByteLayout = shimmerDevice.getConfigByteLayout(); + return isAudioModeSupported(shimmerDevice) && configByteLayout instanceof ConfigByteLayoutShimmer3 + && ((ShimmerObject) shimmerDevice).getAudioMode()!=(mAudioModeAndGain & ((ConfigByteLayoutShimmer3) configByteLayout).maskAudioMode); + } + @Override public Object setConfigValueUsingConfigLabel(Integer sensorId, String configLabel, Object valueToSet) { return super.setConfigValueUsingConfigLabelCommon(sensorId, configLabel, valueToSet); diff --git a/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java new file mode 100644 index 000000000..647205381 --- /dev/null +++ b/ShimmerDriver/src/test/java/com/shimmerresearch/driver/API_00045_ButtonLogModeTest.java @@ -0,0 +1,209 @@ +package com.shimmerresearch.driver; + +import static org.junit.Assert.*; + +import java.util.Set; +import java.util.TreeSet; + +import org.junit.Test; + +import com.shimmerresearch.driver.shimmer2r3.ButtonLogMode; +import com.shimmerresearch.driverUtilities.ExpansionBoardDetails; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID_SR_CODES; + +/** + * DEV-971: configuration byte 232, the button mode, log triggers and TTL + * input. The driver has to read every value as the firmware does + * (log-and-stream-common Configuration/shimmer_button_log_mode.c), so the + * cases below are the table in that repo's + * docs/SHIMMER3_CONFIGURATION_INFOMEM.md section 8.3, row for row: the 16 + * values the firmware keeps, what a press does, what starts logging, and the + * userButtonEnable the firmware holds byte 217 at. + * + * @author Mark Nolan + */ +public class API_00045_ButtonLogModeTest { + + /** What a press does, in the table's words */ + private enum PRESS { + /** As userButtonEnable says: the legacy mode */ + LEGACY, + NOTHING, + /** Nothing starts, but the LED shows the press: logging is off */ + LED_ONLY, + STARTS_STOPS, + DOUBLE_STARTS_STOPS, + } + + /** One row of the table */ + private static class Row { + final int value; + final PRESS press; + final boolean recorded; + final boolean undockStarts; + final boolean loggingOff; + /** null: unchanged, the legacy mode */ + final Boolean userButtonEnableHeldAt; + + Row(int value, PRESS press, boolean recorded, boolean undockStarts, boolean loggingOff, Boolean userButtonEnableHeldAt) { + this.value = value; + this.press = press; + this.recorded = recorded; + this.undockStarts = undockStarts; + this.loggingOff = loggingOff; + this.userButtonEnableHeldAt = userButtonEnableHeldAt; + } + } + + private static final Row[] TABLE = { + new Row(0x00, PRESS.LEGACY, false, false, false, null), + new Row(0x01, PRESS.NOTHING, false, false, false, true), + new Row(0x09, PRESS.NOTHING, false, true, false, false), + new Row(0x11, PRESS.NOTHING, false, false, true, true), + new Row(0x02, PRESS.STARTS_STOPS, false, false, false, true), + new Row(0x0A, PRESS.STARTS_STOPS, false, true, false, true), + new Row(0x12, PRESS.LED_ONLY, false, false, true, true), + new Row(0x03, PRESS.DOUBLE_STARTS_STOPS, false, false, false, true), + new Row(0x0B, PRESS.DOUBLE_STARTS_STOPS, false, true, false, true), + new Row(0x13, PRESS.LED_ONLY, false, false, true, true), + new Row(0x04, PRESS.DOUBLE_STARTS_STOPS, true, false, false, true), + new Row(0x0C, PRESS.DOUBLE_STARTS_STOPS, true, true, false, true), + new Row(0x14, PRESS.NOTHING, true, false, true, true), + new Row(0x05, PRESS.NOTHING, true, false, false, true), + new Row(0x0D, PRESS.NOTHING, true, true, false, false), + new Row(0x15, PRESS.NOTHING, true, false, true, true), + }; + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + /** Each row stands with bit 5 set too, which only turns the TTL input on */ + private static void checkRow(Row row, int value) { + String name = hex(value); + assertEquals(name + " is kept as it is", value, ButtonLogMode.correct(value)); + assertTrue(name + " is valid", ButtonLogMode.isValid(value)); + assertEquals(name + " TTL input", (value & 0x20)!=0, ButtonLogMode.isTtlInputEnabled(value)); + assertEquals(name + " presses recorded", row.recorded, ButtonLogMode.isRecordingButtonPresses(value)); + assertEquals(name + " logging off", row.loggingOff, ButtonLogMode.isLoggingDisabled(value)); + + for(boolean userButtonEnable:new boolean[] {false, true}){ + String state = name + " with userButtonEnable " + userButtonEnable; + boolean held = row.userButtonEnableHeldAt==null ? userButtonEnable : row.userButtonEnableHeldAt; + assertEquals(state + ": the userButtonEnable held", held, ButtonLogMode.getNearestUserButtonEnable(value, userButtonEnable)); + + boolean pressStarts = row.press==PRESS.STARTS_STOPS || row.press==PRESS.DOUBLE_STARTS_STOPS + || (row.press==PRESS.LEGACY && userButtonEnable); + // The firmware acts on the userButtonEnable it holds + assertEquals(state + ": a press starts logging", pressStarts, ButtonLogMode.isPressStartingLogging(value, held)); + + boolean undockStarts = row.press==PRESS.LEGACY ? !userButtonEnable : row.undockStarts; + assertEquals(state + ": leaving the dock starts logging", undockStarts, ButtonLogMode.isUndockStartingLogging(value, held, false)); + assertFalse(state + ": single touch suppresses the undock start", ButtonLogMode.isUndockStartingLogging(value, held, true)); + } + + // Single touch needs a press that can start logging + boolean singleTouch = row.press==PRESS.LEGACY || row.press==PRESS.STARTS_STOPS || row.press==PRESS.DOUBLE_STARTS_STOPS; + assertEquals(name + " single touch allowed", singleTouch, ButtonLogMode.isSingleTouchAllowed(value)); + } + + @Test + public void theSixteenValuesTheFirmwareKeeps() { + for(Row row:TABLE){ + checkRow(row, row.value); + } + } + + @Test + public void eachWithTheTtlInputOn() { + for(Row row:TABLE){ + checkRow(row, row.value | ButtonLogMode.MASK_TTL_INPUT); + } + } + + @Test + public void theTableIsEveryValueTheFirmwareKeeps() { + Set valid = new TreeSet(); + for(int value=0;value<256;value++){ + if(ButtonLogMode.isValid(value)){ + valid.add(value); + } + } + Set expected = new TreeSet(); + for(Row row:TABLE){ + expected.add(row.value); + expected.add(row.value | ButtonLogMode.MASK_TTL_INPUT); + } + assertEquals(expected, valid); + } + + /** Restates the section 8.3 correction independently of ButtonLogMode, for all 256 values */ + @Test + public void everyOtherValueIsCorrectedAsTheFirmwareDoes() { + for(int value=0;value<256;value++){ + int expected; + int buttonMode = value & 0x07; + int logTriggers = (value >> 3) & 0x03; + if((value & 0x80)!=0){ + expected = 0; // bit 7 set: the whole byte reads as 0, TTL input off + } + else if(buttonMode==0 || buttonMode>5 || logTriggers==3){ + expected = value & 0x20; // legacy, reserved: bits 0-4 cleared, TTL input as it is + } + else { + expected = value & 0x3F; // bit 6 is unused and cleared + } + assertEquals(hex(value), expected, ButtonLogMode.correct(value)); + assertEquals(hex(value) + " button mode", expected & 0x07, ButtonLogMode.getButtonMode(value)); + assertEquals(hex(value) + " log triggers", (expected >> 3) & 0x03, ButtonLogMode.getLogTriggers(value)); + } + } + + @Test + public void erasedMemoryReadsAsLegacy() { + assertEquals(0, ButtonLogMode.correct(0xFF)); + assertFalse(ButtonLogMode.isValid(0xFF)); + assertEquals("bit 7 takes the TTL input with it", 0, ButtonLogMode.correct(0xA0)); + assertEquals("a byte read from a Java byte[]", 0, ButtonLogMode.correct((byte) 0xFF)); + } + + @Test + public void encodeIsWhatTheFirmwareKeeps() { + assertEquals("the button off", 0x01, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_HOST, false)); + assertEquals("the button off and logging off", 0x11, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + assertEquals("legacy drops the log triggers", 0x00, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + assertEquals("the TTL input alone", 0x20, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_HOST, true)); + assertEquals("a reserved mode reads as legacy", 0x20, ButtonLogMode.encode(6, ButtonLogMode.LOG_TRIGGERS_HOST_OR_UNDOCK, true)); + assertEquals("reserved log triggers read as legacy", 0x00, ButtonLogMode.encode(ButtonLogMode.BUTTON_MODE_DISABLED, 3, false)); + assertEquals("an out-of-range mode is left 0", 0x00, ButtonLogMode.encode(9, ButtonLogMode.LOG_TRIGGERS_NONE, false)); + } + + @Test + public void fieldsSetOneAtATimeInEitherOrder() { + int triggersFirst = ButtonLogMode.compose(0, ButtonLogMode.BUTTON_MODE_LEGACY, ButtonLogMode.LOG_TRIGGERS_NONE, false); + triggersFirst = ButtonLogMode.compose(triggersFirst, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.getRawLogTriggers(triggersFirst), false); + assertEquals(0x11, triggersFirst); + + int modeFirst = ButtonLogMode.compose(0, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.LOG_TRIGGERS_HOST, false); + modeFirst = ButtonLogMode.compose(modeFirst, ButtonLogMode.getRawButtonMode(modeFirst), ButtonLogMode.LOG_TRIGGERS_NONE, false); + assertEquals(0x11, modeFirst); + + assertEquals("erased memory gives nothing to keep", 0x01, ButtonLogMode.compose(0xFF, ButtonLogMode.BUTTON_MODE_DISABLED, ButtonLogMode.getRawLogTriggers(0xFF), ButtonLogMode.isRawTtlInputEnabled(0xFF))); + } + + @Test + public void sr48_6_0HasNoButtonEdgesAndNoTtlInput() { + ExpansionBoardDetails sr48_6_0 = new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 6, 0); + assertEquals("recorded double press becomes double press", 0x03, ButtonLogMode.correctForBoard(0x04, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("recorded alone becomes disabled", 0x11, ButtonLogMode.correctForBoard(0x15, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("the TTL input goes", 0x0B, ButtonLogMode.correctForBoard(0x2C, HW_ID.SHIMMER_3R, sr48_6_0)); + assertEquals("a mode without recording stays", 0x02, ButtonLogMode.correctForBoard(0x02, HW_ID.SHIMMER_3R, sr48_6_0)); + + ExpansionBoardDetails sr48_7_0 = new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 7, 0); + assertEquals("a later SR48 has both", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3R, sr48_7_0)); + assertEquals("the rule is Shimmer3R's", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3, sr48_6_0)); + assertEquals("an unknown board has both", 0x24, ButtonLogMode.correctForBoard(0x24, HW_ID.SHIMMER_3R, null)); + } + +} diff --git a/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_00038_EventChannelProbeTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.java new file mode 100644 index 000000000..2990a817f --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00038_EventChannelProbeTest.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_STATE; +import com.shimmerresearch.bluetooth.ShimmerBluetooth.SHIMMER_FEATURE; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; +import com.shimmerresearch.shimmer3.communication.ByteCommunication; +import com.shimmerresearch.verisense.communication.ByteCommunicationListener; + +import jssc.SerialPortTimeoutException; + +/** + * DEV-971: whether a Shimmer has the event channel, and with it configuration + * byte 232, is asked rather than read off its version, because the event + * channel's builds report the release before them. The question is SET_FEATURE + * with FEATURE_EVENT_STREAM and 0: firmware with the event channel ACKs it and + * firmware without NACKs it. + *

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

+ * No hardware: the IOThread runs as connect() starts it, over an in-memory + * radio that answers as the firmware does. It lives in this package because + * mIOThread is a protected member of ShimmerBluetooth. + * + * @author Mark Nolan + */ +public class API_00038_EventChannelProbeTest { + + private static final byte FEATURE_EVENT_STREAM = (byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal(); + + private static class AnsweringRadio implements ByteCommunication { + final ConcurrentLinkedDeque rx = new ConcurrentLinkedDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + /** How the firmware answers FEATURE_EVENT_STREAM */ + final byte eventStreamAnswer; + + AnsweringRadio(byte eventStreamAnswer) { + this.eventStreamAnswer = eventStreamAnswer; + } + + int countWritten(byte command) { + int count = 0; + synchronized(written){ + for(byte[] w:written){ + if(w[0]==command){ + count++; + } + } + } + return count; + } + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + if(buffer[0]==ShimmerObject.SET_FEATURE && buffer[1]==FEATURE_EVENT_STREAM){ + rx.add(eventStreamAnswer); + } + else { + // Every other command here is a SET, which the firmware acknowledges + rx.add(ShimmerObject.ACK_COMMAND_PROCESSED); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + if(rx.size() progressReports = Collections.synchronizedList(new ArrayList()); + final List commandsRefused = Collections.synchronizedList(new ArrayList()); + volatile boolean connectionLost = false; + + WatchedShimmer() { + super("COM99"); + } + + @Override + protected void eventCommandRefused(byte command) { + commandsRefused.add(command); + super.eventCommandRefused(command); + } + + @Override + protected void sendProgressReport(BluetoothProgressReportPerCmd pRPC) { + progressReports.add((byte) pRPC.mCommandCompleted); + super.sendProgressReport(pRPC); + } + + @Override + protected void connectionLost() { + connectionLost = true; + super.connectionLost(); + } + } + + private WatchedShimmer mDevice; + + @After + public void tearDown() { + if(mDevice!=null){ + mDevice.stopTimerCheckForAckOrResp(); + mDevice.disconnectNoException(); + } + } + + /** A connected Shimmer, not streaming, with its IOThread running as connect() starts it */ + private AnsweringRadio connectedShimmer(ShimmerVerObject svo, byte eventStreamAnswer) { + AnsweringRadio radio = new AnsweringRadio(eventStreamAnswer); + mDevice = new WatchedShimmer(); + mDevice.setTestRadio(radio); + mDevice.setShimmerVersionObjectAndCreateSensorMap(svo); + mDevice.setIsInitialised(true); + mDevice.mIOThread = mDevice.new IOThread(); + mDevice.mIOThread.start(); + return radio; + } + + /** Waits for the instruction list to empty, well inside the 5 s ACK timer that drops the connection */ + private void waitForInstructionsDone(long timeoutMs) throws InterruptedException { + long end = System.currentTimeMillis()+timeoutMs; + while((!mDevice.getListofInstructions().isEmpty() || mDevice.isInstructionStackLock()) && System.currentTimeMillis() + * 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, each reply one burst */ + private static class AnsweringRadio extends WaitingTestRadio { + /** Sent ahead of the next command's ACK, as a record already queued would be */ + volatile byte[] beforeNextAck = null; + /** Sent between the next status command's ACK and its reply */ + volatile byte[] betweenAckAndReply = null; + + @Override + byte[] answer(byte[] buffer) { + java.io.ByteArrayOutputStream reply = new java.io.ByteArrayOutputStream(); + byte[] early = beforeNextAck; + if(early!=null) { + beforeNextAck = null; + reply.write(early, 0, early.length); + } + if(buffer[0]==ShimmerObject.SET_FEATURE && buffer[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal()){ + reply.write(ShimmerObject.ACK_COMMAND_PROCESSED); + if(buffer[2]!=0) { + // The first record at the opt-in, then one already made + reply.write(INITIAL_STATE, 0, INITIAL_STATE.length); + reply.write(MARKER_PRESS, 0, MARKER_PRESS.length); + } + } + else if(buffer[0]==ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND){ + reply.write(ShimmerObject.ACK_COMMAND_PROCESSED); + byte[] between = betweenAckAndReply; + if(between!=null) { + betweenAckAndReply = null; + reply.write(between, 0, between.length); + } + reply.write(ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE); + byte[] status = hex("03 0B 02 05 00 02 00 01 00"); + reply.write(status, 0, status.length); + } + else { + reply.write(ShimmerObject.ACK_COMMAND_PROCESSED); + } + return reply.toByteArray(); + } + } + + private ShimmerPC mIdleDevice; + private AnsweringRadio mAnsweringRadio; + + @After + public void disconnectIdleDevice() { + if(mIdleDevice!=null){ + mIdleDevice.stopTimerCheckForAckOrResp(); + mIdleDevice.disconnectNoException(); + } + } + + /** Connected, not streaming, the IOThread running, and the event channel probe answered */ + private void idleShimmerWithTheEventChannel() throws InterruptedException { + mAnsweringRadio = new AnsweringRadio(); + mIdleDevice = new ShimmerPC("COM99"); + mIdleDevice.setTestRadio(mAnsweringRadio); + mIdleDevice.setShimmerVersionObjectAndCreateSensorMap(S3R_V1_1_25); + mIdleDevice.setIsInitialised(true); + mIdleDevice.addEventChannelListener(mCollected); + mIdleDevice.mIOThread = mIdleDevice.new IOThread(); + mIdleDevice.mIOThread.start(); + mIdleDevice.readEventChannelSupport(); + waitForInstructionsDone(); + assertEquals(Boolean.TRUE, mIdleDevice.isEventChannelSupported()); + } + + private void waitForInstructionsDone() throws InterruptedException { + long end = System.currentTimeMillis()+2000; + while((!mIdleDevice.getListofInstructions().isEmpty() || mIdleDevice.isInstructionStackLock()) && System.currentTimeMillis() + * The streaming tests hand the parser one byte at a time on the test's thread. + * The idle tests run the IOThread over {@link WaitingTestRadio}, whose bursts + * arrive whole and whose reads wait, so the driver's reads cannot race the + * test's writes. + */ +public class API_00044_EventStreamReviewReproTest { + + private static final int PACKET_SIZE = 9; + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + private static final BT_CRC_MODE[] CRC_MODES = {BT_CRC_MODE.OFF, BT_CRC_MODE.ONE_BYTE_CRC, BT_CRC_MODE.TWO_BYTE_CRC}; + + private static byte[] frame(int type, int seq, long ticks, int channel, int state) { + byte[] f = new byte[21]; + f[0] = (byte) 0x8A; + f[1] = (byte) 0xBB; + f[2] = 16; + f[3] = (byte) type; + f[5] = (byte) seq; + f[6] = (byte) (seq>>8); + for(int i=0;i<8;i++) { + f[7+i] = (byte) (ticks>>(8*i)); + } + f[15] = (byte) channel; + f[16] = (byte) state; + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(f, 19); + f[19] = crc[0]; + f[20] = crc[1]; + return f; + } + + private static final byte[] INITIAL_STATE = frame(EventRecord.TYPE_INITIAL_STATE, 0, 0x357237100000L, EventRecord.CHANNEL_NONE, 0); + private static final byte[] PRESS = frame(EventRecord.TYPE_EDGE, 1, 0x357237185333L, EventRecord.CHANNEL_BUTTON, 1); + private static final byte[] RELEASE = frame(EventRecord.TYPE_EDGE, 2, 0x357237186333L, EventRecord.CHANNEL_BUTTON, 0); + + /** A reply as the firmware frames it on a link with {@code crcMode}: its bytes, then the link CRC over them */ + private static byte[] withLinkCrc(byte[] bytes, BT_CRC_MODE crcMode) { + byte[] crc = ShimmerCrc.shimmerUartCrcCalc(bytes, bytes.length); + byte[] out = Arrays.copyOf(bytes, bytes.length+crcMode.getNumCrcBytes()); + System.arraycopy(crc, 0, out, bytes.length, crcMode.getNumCrcBytes()); + return out; + } + + private static class Collected implements EventChannelListener { + final List records = Collections.synchronizedList(new ArrayList()); + final List statuses = Collections.synchronizedList(new ArrayList()); + @Override public void onEventRecord(ShimmerBluetooth shimmer, EventRecord record) { records.add(record); } + @Override public void onEventChannelStatus(ShimmerBluetooth shimmer, EventChannelStatus status) { statuses.add(status); } + void clear() { records.clear(); statuses.clear(); } + } + + private final Collected mCollected = new Collected(); + private final List mAcksProcessed = Collections.synchronizedList(new ArrayList()); + + // ------------------------------------------------------------------ + // Streaming parser, fed one byte at a time + // ------------------------------------------------------------------ + + private static class QueueRadio implements ByteCommunication { + final Deque rx = new ArrayDeque(); + void queue(byte... bytes) { for(byte b:bytes) rx.add(b); } + @Override public byte[] readBytes(int n, int timeout) throws SerialPortTimeoutException { + if(rx.size() parsed() { + List out = new ArrayList(); + ShimmerBluetooth d = mStreaming; + for(RawBytePacketWithPCTimeStamp p:d.mABQPacketByeArray) out.add(hex(p.mDataArray)); + return out; + } + + @After + public void stopTimers() { + if(mStreaming!=null) { + mStreaming.stopTimerCheckForAckOrResp(); + mStreaming.stopTimerReadStatus(); + } + if(mIdle!=null) { + mIdle.stopTimerCheckForAckOrResp(); + mIdle.disconnectNoException(); + } + } + + /** + * Finding 2: an ACK with no command waiting for it, then a frame. The SET + * that went last must not have its ACK handling run a second time. No link + * CRC: with one, a bare ACK goes through the older bare-ACK branch, which + * acknowledges unguarded for a data packet too (not changed here). + */ + @Test + public void finding2_anAckNobodyWaitsForBeforeAFrameDoesNotReRunTheLastSetsAck() { + streamingShimmer3r(BT_CRC_MODE.OFF); + alreadyOptedIn(); + // The last command was a SET that completed long ago + mStreaming.mCurrentCommand = ShimmerObject.SET_SAMPLING_RATE_COMMAND; + receive(dataPacket(payload(1), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED}, PRESS, + dataPacket(payload(2), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + assertEquals("the record is taken", 1, mCollected.records.size()); + assertEquals("no SET's ACK is processed: none was in flight", Collections.emptyList(), mAcksProcessed); + assertEquals(Arrays.asList(hex(payload(1)), hex(payload(2))), parsed()); + } + + /** + * Finding 3: no link CRC, opted in, and a byte lost from a packet, so the + * parser's boundary falls one byte late and lands on a data byte of 0x8A. + * The misframed bytes must not be handed on as a packet, and the parser must + * resync so that the good packets after them still arrive. + */ + @Test + public void finding3_withoutACrcAMisframedPacketBeforeA0x8ADataByteIsNotTakenAsAPacket() { + streamingShimmer3r(BT_CRC_MODE.OFF); + alreadyOptedIn(); + byte[] good = dataPacket(payload(1), BT_CRC_MODE.OFF); + // Packet 2 loses its 4th byte on the link + byte[] p2 = new byte[] {0x20, (byte) 0x8A, 0x01, 0x02, 0x07, 0x05, 0x08, 0x3F, 0x09}; + byte[] p2Lost = new byte[1+p2.length-1]; + p2Lost[0] = ShimmerObject.DATA_PACKET; + System.arraycopy(p2, 0, p2Lost, 1, 3); + System.arraycopy(p2, 4, p2Lost, 4, p2.length-4); + // Packet 3's first data byte is 0x8A, where the late boundary lands + byte[] p3Payload = new byte[] {(byte) 0x8A, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x01}; + receive(good, p2Lost, dataPacket(p3Payload, BT_CRC_MODE.OFF), dataPacket(payload(4), BT_CRC_MODE.OFF), + dataPacket(payload(5), BT_CRC_MODE.OFF), new byte[] {ShimmerObject.DATA_PACKET}); + byte[] misframed = new byte[PACKET_SIZE]; + System.arraycopy(p2Lost, 1, misframed, 0, p2Lost.length-1); + misframed[PACKET_SIZE-1] = ShimmerObject.DATA_PACKET; + List got = parsed(); + assertFalse("misframed bytes " + hex(misframed) + " were taken as a packet: " + got, got.contains(hex(misframed))); + assertEquals("the good packets either side arrive, the damaged one does not", + Arrays.asList(hex(payload(1)), hex(p3Payload), hex(payload(4)), hex(payload(5))), got); + } + + /** + * Finding 5, the consequence, with each link CRC: a status reply, + * [ACK][0xBA][9], between data packets is taken, the command retired, the + * lock released and the packets either side parsed. + */ + @Test + public void finding5_aStatusReplyBetweenDataPacketsIsTaken() { + for(BT_CRC_MODE crcMode:CRC_MODES) { + streamingShimmer3r(crcMode); + mStreaming.mCurrentCommand = ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND; + mStreaming.getListofInstructions().add(new byte[] {ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND}); + mStreaming.setInstructionStackLock(true); + mStreaming.mWaitForAck = true; + mStreaming.startTimerCheckForAckOrResp(2); + byte[] reply = withLinkCrc(new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED, ShimmerObject.EVENT_CHANNEL_STATUS_RESPONSE, + 0x03, 0x0B, 0x02, 0x05, 0x00, 0x02, 0x00, 0x01, 0x00}, crcMode); + receive(dataPacket(payload(1), crcMode), reply, dataPacket(payload(2), crcMode), + dataPacket(payload(3), crcMode), new byte[] {ShimmerObject.DATA_PACKET}); + String m = crcMode + ": "; + assertEquals(m + "the status reply is taken", 1, mCollected.statuses.size()); + assertEquals(m + "its values", 5, mCollected.statuses.get(0).getNextSequenceNumber()); + assertFalse(m + "no longer waits for the ACK", mStreaming.mWaitForAck); + assertTrue(m + "the command is retired", mStreaming.getListofInstructions().isEmpty()); + assertFalse(m + "the next instruction can be sent", mStreaming.isInstructionStackLock()); + assertNull(m + "the ACK timer is cancelled", mStreaming.mTimerCheckForAckOrResp); + assertEquals(m + "the packets either side are parsed", + Arrays.asList(hex(payload(1)), hex(payload(2)), hex(payload(3))), parsed()); + } + } + + /** + * Finding 5, the precondition: readEventChannelStatus() is not queued + * behind a start of streaming that has not been acknowledged yet. + */ + @Test + public void finding5_theStatusIsNotQueuedBehindAStartOfStreaming() throws Exception { + ShimmerPC s = new ShimmerPC("COM98"); + s.setShimmerVersionObjectAndCreateSensorMap(S3R); + // As the probe leaves it on a unit with the event channel + java.lang.reflect.Method m = com.shimmerresearch.driver.ShimmerObject.class.getDeclaredMethod("setEventChannelSupported", Boolean.class); + m.setAccessible(true); + m.invoke(s, Boolean.TRUE); + s.startStreaming(); + boolean sent = s.readEventChannelStatus(); + boolean queuedAfterStart = false; + boolean startSeen = false; + for(byte[] ins:s.getListofInstructions()) { + if(ins[0]==ShimmerObject.START_STREAMING_COMMAND) startSeen = true; + if(startSeen && ins[0]==ShimmerObject.GET_EVENT_CHANNEL_STATUS_COMMAND) queuedAfterStart = true; + } + s.stopTimerCheckForAckOrResp(); + s.stopTimerReadStatus(); + assertFalse("refused", sent); + assertFalse("the status is queued after a start of streaming", queuedAfterStart); + } + + // ------------------------------------------------------------------ + // Idle, with the IOThread running + // ------------------------------------------------------------------ + + /** Answers every command with an ACK, with its link CRC, then {@link #afterOptInAck} for the opt-in, all in one burst */ + private static class AckingRadio extends WaitingTestRadio { + volatile BT_CRC_MODE crcMode = BT_CRC_MODE.OFF; + volatile byte[] afterOptInAck = new byte[0]; + + @Override + byte[] answer(byte[] command) { + byte[] ack = withLinkCrc(new byte[] {ShimmerObject.ACK_COMMAND_PROCESSED}, crcMode); + if(command[0]==ShimmerObject.SET_FEATURE && command[1]==(byte) SHIMMER_FEATURE.EVENT_STREAM.ordinal() && command[2]!=0) { + return concat(ack, afterOptInAck); + } + return ack; + } + } + + private ShimmerPC mIdle; + private AckingRadio mAcking; + + /** Connected over a link with {@code crcMode}, not streaming, opted in; {@code afterOptInAck} comes in the opt-in's ACK's burst */ + private void idleOptedIn(BT_CRC_MODE crcMode, byte[] afterOptInAck) throws InterruptedException { + if(mIdle!=null) { + mIdle.stopTimerCheckForAckOrResp(); + mIdle.disconnectNoException(); + } + mCollected.clear(); + mAcking = new AckingRadio(); + mAcking.crcMode = crcMode; + mAcking.afterOptInAck = afterOptInAck; + mIdle = new ShimmerPC("COM97"); + mIdle.setTestRadio(mAcking); + mIdle.setShimmerVersionObjectAndCreateSensorMap(S3R); + mIdle.setCurrentBtCommsCrcMode(crcMode); + mIdle.setIsInitialised(true); + mIdle.addEventChannelListener(mCollected); + mIdle.mIOThread = mIdle.new IOThread(); + mIdle.mIOThread.start(); + assertTrue(mIdle.writeEventStream(true)); + long end = System.currentTimeMillis()+2000; + while((!mIdle.getListofInstructions().isEmpty() || mIdle.isInstructionStackLock()) && System.currentTimeMillis() + * No hardware. It lives in this package because the instruction list is a + * protected member of ShimmerBluetooth. + * + * @author Mark Nolan + */ +public class API_00046_ButtonLogModeConfigWriteTest { + + private static final int IDX_BUTTON_LOG_MODE = 232; + private static final int IDX_TRIAL_CONFIG0 = 217; + private static final int IDX_TRIAL_CONFIG1 = 218; + private static final int USER_BUTTON_ENABLE = 0x20; + private static final int SINGLE_TOUCH_START = 0x80; + + /** A Shimmer3R on a release whose builds can carry the event channel */ + private static final ShimmerVerObject S3R_EVENT_CHANNEL_CAPABLE = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 25); + + /** Lets a test give the probe's answer */ + private static class ProbedShimmer extends ShimmerPC { + private static final long serialVersionUID = 1L; + ProbedShimmer() { + super("COM99"); + } + void probeAnswered(Boolean isEventChannelSupported) { + setEventChannelSupported(isEventChannelSupported); + } + } + + private static ProbedShimmer shimmer(ShimmerVerObject svo) { + ProbedShimmer shimmer = new ProbedShimmer(); + shimmer.setShimmerVersionObjectAndCreateSensorMap(svo); + return shimmer; + } + + /** + * A configuration as a Shimmer on that firmware would answer it, with the + * given bytes 232, 217 and 218: the image a second, unread Shimmer makes + */ + private static byte[] configFromShimmer(ShimmerVerObject svo, int buttonLogMode, int trialConfig0, int trialConfig1) { + ShimmerPC source = new ShimmerPC("COM98"); + source.setShimmerVersionObjectAndCreateSensorMap(svo); + byte[] config = source.generateConfigBytesForWritingToShimmer().clone(); + config[IDX_BUTTON_LOG_MODE] = (byte) buttonLogMode; + config[IDX_TRIAL_CONFIG0] = (byte) trialConfig0; + config[IDX_TRIAL_CONFIG1] = (byte) trialConfig1; + return config; + } + + private static ProbedShimmer readFrom(ShimmerVerObject svo, int buttonLogMode, int trialConfig0, int trialConfig1) { + ProbedShimmer shimmer = shimmer(svo); + shimmer.configBytesParse(configFromShimmer(svo, buttonLogMode, trialConfig0, trialConfig1), COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + private static int written(ShimmerPC shimmer, int idx) { + return shimmer.generateConfigBytesForWritingToShimmer()[idx] & 0xFF; + } + + private static String hex(int value) { + return String.format("0x%02X", value); + } + + @Test + public void theByteReadGoesBackOnAFullWrite() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + assertTrue(shimmer.isButtonLogModeKnown()); + assertEquals(ButtonLogMode.BUTTON_MODE_DISABLED, shimmer.getButtonMode()); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, shimmer.getLogTriggers()); + assertEquals("before DEV-971 this was 0", 0x11, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void everyValueTheFirmwareKeepsGoesBack() { + for(int value=0;value<256;value++){ + if(!ButtonLogMode.isValid(value)){ + continue; + } + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, value, USER_BUTTON_ENABLE, 0); + assertEquals(hex(value), value, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + } + + @Test + public void userButtonEnableIsHeldAtTheModesEquivalent() { + ProbedShimmer undockStart = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x09, USER_BUTTON_ENABLE, 0); + undockStart.setButtonStart(true); + assertEquals("0x09: nothing on a press, logging on an undock", 0, written(undockStart, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertFalse(undockStart.isButtonStart()); + + ProbedShimmer disabled = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x01, 0, 0); + assertEquals("0x01: held at 1, so firmware without the byte never adds an undock start", USER_BUTTON_ENABLE, written(disabled, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertTrue(disabled.isButtonStart()); + + ProbedShimmer legacy = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, 0, 0); + assertEquals("legacy leaves it as it is", 0, written(legacy, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + } + + /** LogAndStream is built without single touch, and clears it whatever byte 232 holds */ + @Test + public void singleTouchIsClearedInEveryMode() { + int[] values = { + 0x00, // legacy + 0x01, // no press can start logging + 0x12, // a press that could, but logging is off + 0x02, // a press that starts logging + 0x03, // a double press that does + }; + for(int value:values){ + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, value, USER_BUTTON_ENABLE, SINGLE_TOUCH_START); + shimmer.setSingleTouch(true); + assertEquals(hex(value), 0, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + assertFalse(hex(value), shimmer.isSingleTouch()); + } + } + + @Test + public void aValueSetIsWrittenWhateverTheOrderOfTheFields() { + ProbedShimmer modeFirst = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + modeFirst.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + modeFirst.setLogTriggers(ButtonLogMode.LOG_TRIGGERS_NONE); + assertEquals(0x11, written(modeFirst, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer triggersFirst = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + triggersFirst.setLogTriggers(ButtonLogMode.LOG_TRIGGERS_NONE); + assertEquals("legacy does not read them yet", ButtonLogMode.LOG_TRIGGERS_HOST, triggersFirst.getLogTriggers()); + triggersFirst.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, triggersFirst.getLogTriggers()); + assertEquals(0x11, written(triggersFirst, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer ttl = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + ttl.setTtlInputEnabled(true); + assertEquals("the other fields stay", 0x31, written(ttl, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void theConfigLabelsSetAndGetTheFields() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x00, USER_BUTTON_ENABLE, 0); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS, ButtonLogMode.LOG_TRIGGERS_NONE); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE, ButtonLogMode.BUTTON_MODE_RECORDED); + shimmer.setConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT, true); + assertEquals(0x35, written(shimmer, IDX_BUTTON_LOG_MODE)); + assertEquals(ButtonLogMode.BUTTON_MODE_RECORDED, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.BUTTON_MODE)); + assertEquals(ButtonLogMode.LOG_TRIGGERS_NONE, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.LOG_TRIGGERS)); + assertEquals(true, shimmer.getConfigValueUsingConfigLabel(Configuration.Shimmer3.GuiLabelConfig.TTL_INPUT)); + } + + @Test + public void erasedMemoryIsKeptAsReadAndReadsAsLegacy() { + ProbedShimmer shimmer = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0xFF, 0, SINGLE_TOUCH_START); + assertFalse(shimmer.isButtonLogModeMeaningful()); + assertEquals(ButtonLogMode.BUTTON_MODE_LEGACY, shimmer.getButtonMode()); + assertEquals(0xFF, written(shimmer, IDX_BUTTON_LOG_MODE)); + assertEquals("legacy leaves userButtonEnable", 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertEquals("the firmware clears single touch all the same", 0, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + } + + @Test + public void aByteTheFirmwareWouldCorrectIsTrustedOnlyAfterTheProbe() { + // Reserved button mode 7 with the TTL input on: no firmware writes it + ProbedShimmer unprobed = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x27, USER_BUTTON_ENABLE, 0); + assertFalse(unprobed.isTtlInputEnabled()); + assertEquals("kept as read", 0x27, written(unprobed, IDX_BUTTON_LOG_MODE)); + + ProbedShimmer probed = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x27, USER_BUTTON_ENABLE, 0); + probed.probeAnswered(true); + assertTrue(probed.isTtlInputEnabled()); + assertEquals("as the firmware corrects it", 0x20, written(probed, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void sr48_6_0HasNeitherInput() { + ProbedShimmer shimmer = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + shimmer.setExpansionBoardDetails(new ExpansionBoardDetails(HW_ID_SR_CODES.EXP_BRD_GSR_UNIFIED, 6, 0)); + shimmer.configBytesParse(configFromShimmer(S3R_EVENT_CHANNEL_CAPABLE, 0x24, USER_BUTTON_ENABLE, 0), COMMUNICATION_TYPE.BLUETOOTH); + assertEquals(0x03, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void firmwareThatCannotHaveTheByteIsWrittenAsBefore() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = readFrom(svo, 0x11, USER_BUTTON_ENABLE, 0); + assertFalse(svo.getFirmwareVersionParsed(), shimmer.isButtonLogModeKnown()); + assertEquals(svo.getFirmwareVersionParsed(), 0, written(shimmer, IDX_BUTTON_LOG_MODE)); + } + ProbedShimmer s3 = readFrom(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 1, 9), 0x11, USER_BUTTON_ENABLE, 0); + assertEquals("a Shimmer3 release that can", 0x11, written(s3, IDX_BUTTON_LOG_MODE)); + } + + @Test + public void firmwareThatCannotHaveTheByteKeepsBytes217And218() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.SDLOG, 0, 19, 0), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = readFrom(svo, 0x00, 0, SINGLE_TOUCH_START); + shimmer.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + assertEquals(svo.getFirmwareVersionParsed(), 0, written(shimmer, IDX_TRIAL_CONFIG0) & USER_BUTTON_ENABLE); + assertEquals(svo.getFirmwareVersionParsed(), SINGLE_TOUCH_START, written(shimmer, IDX_TRIAL_CONFIG1) & SINGLE_TOUCH_START); + } + } + + // ---- The Bluetooth write's SET_INFOMEM chunks + + /** [address, length] of each SET_INFOMEM queued: [0x8C, length, address LSB, address MSB, data...] */ + private static List infoMemChunks(ShimmerBluetooth shimmer) { + List chunks = new ArrayList(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + chunks.add(new int[] {(instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8), instruction[1]&0xFF}); + } + } + return chunks; + } + + private static byte[] infoMemChunkAt(ShimmerBluetooth shimmer, int address) { + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND + && ((instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8))==address){ + return instruction; + } + } + fail("no SET_INFOMEM at " + address); + return null; + } + + private static void assertChunks(String message, int[][] expected, ShimmerBluetooth shimmer) { + List chunks = infoMemChunks(shimmer); + List actual = new ArrayList(); + for(int[] chunk:chunks){ + actual.add(Arrays.toString(chunk)); + } + List wanted = new ArrayList(); + for(int[] chunk:expected){ + wanted.add(Arrays.toString(chunk)); + } + assertEquals(message, wanted, actual); + } + + /** The 128-byte chunks of the Shimmer's image, as the write has always sent them */ + private static int[][] allChunks(ShimmerBluetooth shimmer) { + int length = shimmer.generateConfigBytesForWritingToShimmer().length; + int[][] chunks = new int[length/128][]; + for(int i=0;i chunks = new ArrayList(); + for(int[] chunk:allChunks(shimmer)){ + if(chunk[0]==128){ + chunks.addAll(Arrays.asList(parts)); + } + else { + chunks.add(chunk); + } + } + return chunks.toArray(new int[0][]); + } + + /** Either side of byte 232 */ + private static int[][] chunksWithout232(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 104}, new int[] {233, 23}); + } + + /** Either side of bytes 232 and 233: a Shimmer3R's, before a read (API_00047) */ + private static int[][] chunksWithout232And233(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 104}, new int[] {234, 22}); + } + + /** Either side of byte 233 */ + private static int[][] chunksWithout233(ShimmerBluetooth shimmer) { + return chunk128As(shimmer, new int[] {128, 105}, new int[] {234, 22}); + } + + @Test + public void beforeAReadTheBluetoothWriteLeavesTheShimmersByte() { + ProbedShimmer shimmer = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + assertFalse(shimmer.isButtonLogModeKnown()); + shimmer.writeConfigBytes(false); + assertChunks("a configuration written on connect, before the read; a Shimmer3R's byte 233 is left out too", + chunksWithout232And233(shimmer), shimmer); + + // The bytes either side of 232 and 233 are the image's + byte[] image = shimmer.generateConfigBytesForWritingToShimmer(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + int address = (instruction[2]&0xFF) | ((instruction[3]&0xFF)<<8); + int length = instruction[1]&0xFF; + assertArrayEquals("chunk at " + address, Arrays.copyOfRange(image, address, address+length), Arrays.copyOfRange(instruction, 4, 4+length)); + } + } + + ProbedShimmer s3 = shimmer(new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 17)); + s3.writeConfigBytes(false); + assertChunks("the first Shimmer3 release that can", chunksWithout232(s3), s3); + } + + @Test + public void onceReadOrSetTheBluetoothWriteHasTheByte() { + ProbedShimmer read = readFrom(S3R_EVENT_CHANNEL_CAPABLE, 0x11, USER_BUTTON_ENABLE, 0); + read.writeConfigBytes(false); + assertChunks("read", allChunks(read), read); + + ProbedShimmer set = shimmer(S3R_EVENT_CHANNEL_CAPABLE); + set.setButtonMode(ButtonLogMode.BUTTON_MODE_DISABLED); + set.writeConfigBytes(false); + assertChunks("set, with byte 233 still unread", chunksWithout233(set), set); + byte[] chunk = infoMemChunkAt(set, 128); + assertEquals("set, before anything was read", 0x01, chunk[4 + IDX_BUTTON_LOG_MODE - 128] & 0xFF); + } + + @Test + public void olderFirmwareIsWrittenInWholeChunksAsBefore() { + ShimmerVerObject[] older = { + new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 0, 51), + new ShimmerVerObject(HW_ID.SHIMMER_3, FW_ID.LOGANDSTREAM, 1, 0, 16), + }; + for(ShimmerVerObject svo:older){ + ProbedShimmer shimmer = shimmer(svo); + shimmer.writeConfigBytes(false); + assertChunks(svo.getFirmwareVersionParsed(), allChunks(shimmer), shimmer); + } + } + +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java new file mode 100644 index 000000000..4e23f4b04 --- /dev/null +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/bluetooth/API_00047_AudioConfigWriteTest.java @@ -0,0 +1,168 @@ +package com.shimmerresearch.bluetooth; + +import static org.junit.Assert.*; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import org.junit.Test; + +import com.shimmerresearch.driver.Configuration; +import com.shimmerresearch.driver.Configuration.COMMUNICATION_TYPE; +import com.shimmerresearch.driver.ShimmerObject; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.FW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerDetails.HW_ID; +import com.shimmerresearch.driverUtilities.ShimmerVerObject; +import com.shimmerresearch.pcDriver.ShimmerPC; + +/** + * Configuration byte 233 on a Shimmer3R (DEV-99 audio mode and gain in bits + * 0-3, DEV-1413 sound level in bit 4) through a Bluetooth configuration write. + * The host can set bit 4 and the audio mode (bits 0-1, DEV-1459), but not the + * gain preset (bits 2-3), which it only gives back as read. So before a read, + * the write leaves the byte out, as it does byte 232 (API_00046), and the + * Shimmer keeps its own. The exceptions are the sound level turned on, or an + * audio mode set, before a read: the byte is then written with the rest of + * bits 0-3 at 0, since a SET_INFOMEM cannot write one bit. + *

+ * No hardware. It lives in this package because the instruction list is a + * protected member of ShimmerBluetooth. + */ +public class API_00047_AudioConfigWriteTest { + + private static final int IDX_BUTTON_LOG_MODE = 232; + private static final int IDX_AUDIO_CONFIG = 233; + private static final int SOUND_LEVEL_BIT = 0x10; + + /** v1.01.026, the first release with the sound level */ + private static final ShimmerVerObject S3R = new ShimmerVerObject(HW_ID.SHIMMER_3R, FW_ID.LOGANDSTREAM, 1, 1, 26); + + private static ShimmerPC shimmer() { + ShimmerPC shimmer = new ShimmerPC("COM99"); + shimmer.setShimmerVersionObjectAndCreateSensorMap(S3R); + return shimmer; + } + + private static ShimmerPC readFrom(int buttonLogMode, int audioConfig) { + byte[] config = shimmer().generateConfigBytesForWritingToShimmer().clone(); + config[IDX_BUTTON_LOG_MODE] = (byte) buttonLogMode; + config[IDX_AUDIO_CONFIG] = (byte) audioConfig; + ShimmerPC shimmer = shimmer(); + shimmer.configBytesParse(config, COMMUNICATION_TYPE.BLUETOOTH); + return shimmer; + } + + /** Each SET_INFOMEM queued: [0x8C, length, address LSB, address MSB, data...] */ + private static List infoMemWrites(ShimmerBluetooth shimmer) { + List writes = new ArrayList(); + for(byte[] instruction:shimmer.getListofInstructions()){ + if(instruction!=null && instruction[0]==ShimmerObject.SET_INFOMEM_COMMAND){ + writes.add(instruction); + } + } + return writes; + } + + private static int address(byte[] write) { + return (write[2]&0xFF) | ((write[3]&0xFF)<<8); + } + + private static int length(byte[] write) { + return write[1]&0xFF; + } + + /** The value written at idx, or -1 if no SET_INFOMEM covers it */ + private static int writtenAt(ShimmerBluetooth shimmer, int idx) { + for(byte[] write:infoMemWrites(shimmer)){ + if(idx>=address(write) && idx chunks(ShimmerBluetooth shimmer) { + List chunks = new ArrayList(); + for(byte[] write:infoMemWrites(shimmer)){ + chunks.add(Arrays.toString(new int[] {address(write), length(write)})); + } + return chunks; + } + + @Test + public void beforeAReadTheBluetoothWriteLeavesTheShimmersAudioByte() { + ShimmerPC shimmer = shimmer(); + shimmer.writeConfigBytes(false); + assertEquals("a configuration written on connect, before the read, would turn the Shimmer's audio mode and sound level off", + -1, writtenAt(shimmer, IDX_AUDIO_CONFIG)); + } + + @Test + public void beforeAReadBytes232And233AreBothLeftOut() { + ShimmerPC shimmer = shimmer(); + shimmer.writeConfigBytes(false); + int length = shimmer.generateConfigBytesForWritingToShimmer().length; + List wanted = new ArrayList(); + for(int address=0;address + *

  • {@link #queue(byte[]...)} adds a burst whole, under the same lock reads + * take, so the IOThread never sees half of it;
  • + *
  • a read waits up to its timeout for the bytes it asks for, as a serial + * port does, rather than failing the moment they are short.
  • + * + * Subclasses answer what the driver writes by overriding {@link #answer(byte[])}. + */ +abstract class WaitingTestRadio implements ByteCommunication { + + private final Deque mRx = new ArrayDeque(); + final List written = Collections.synchronizedList(new ArrayList()); + + /** Adds the chunks as one burst: a read sees all of it or none of it */ + void queue(byte[]... chunks) { + synchronized(mRx) { + for(byte[] chunk:chunks) { + for(byte b:chunk) { + mRx.add(b); + } + } + } + } + + /** Adds single bytes as one burst */ + void queueBytes(byte... bytes) { + queue(bytes); + } + + /** The reply to one command the driver wrote, as one burst; empty for none */ + abstract byte[] answer(byte[] command); + + @Override + public boolean writeBytes(byte[] buffer) { + written.add(buffer.clone()); + byte[] reply = answer(buffer.clone()); + if(reply!=null && reply.length>0) { + queue(reply); + } + return true; + } + + @Override + public byte[] readBytes(int byteCount, int timeout) throws SerialPortTimeoutException { + long end = System.currentTimeMillis()+Math.max(timeout, 1); + while(true) { + synchronized(mRx) { + if(mRx.size()>=byteCount) { + byte[] out = new byte[byteCount]; + for(int i=0;i=end) { + throw new SerialPortTimeoutException("TEST", "readBytes", timeout); + } + try { + Thread.sleep(2); + } catch (InterruptedException e) { + Thread.currentThread().interrupt(); + throw new SerialPortTimeoutException("TEST", "readBytes", timeout); + } + } + } + + @Override + public int getInputBufferBytesCount() { + synchronized(mRx) { + return mRx.size(); + } + } + + @Override public boolean isOpened() { return true; } + @Override public boolean closePort() { return true; } + @Override public boolean openPort() { return true; } + @Override public boolean setParams(int i, int j, int k, int l) { return true; } + @Override public boolean purgePort(int i) { return true; } + @Override public void setByteCommunicationListener(ByteCommunicationListener byteCommListener) { } + @Override public void removeRadioListenerList() { } + + /** The bytes of several chunks, in order */ + static byte[] concat(byte[]... chunks) { + int n = 0; + for(byte[] c:chunks) { + n += c.length; + } + byte[] out = new byte[n]; + int at = 0; + for(byte[] c:chunks) { + System.arraycopy(c, 0, out, at, c.length); + at += c.length; + } + return out; + } + +} diff --git a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java similarity index 98% rename from ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java rename to ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java index 51ddbb03f..c93dafa8c 100644 --- a/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00042_Shimmer3rAudioStatusTest.java +++ b/ShimmerDriverPC/src/test/java/com/shimmerresearch/pcDriver/API_00048_Shimmer3rAudioStatusTest.java @@ -12,7 +12,7 @@ * DEV-1459: status byte 1 bits 1-2, audio recording and audio fault * (log-and-stream-common SHIMMER3R_AUDIO.md §5). No hardware. */ -public class API_00042_Shimmer3rAudioStatusTest { +public class API_00048_Shimmer3rAudioStatusTest { /** Reaches the status parser, which the driver calls on each status frame */ private static class StatusShimmer extends ShimmerPC { 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); }