diff --git a/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj b/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj index d0ee776..1774485 100644 --- a/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj +++ b/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj @@ -18,12 +18,14 @@ 3A780C8A2AE12BEB00EAF050 /* ShimmerBluetooth.docc in Sources */ = {isa = PBXBuildFile; fileRef = 3A780C892AE12BEB00EAF050 /* ShimmerBluetooth.docc */; }; 3A780C902AE12BEB00EAF050 /* ShimmerBluetooth.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 3A780C852AE12BEB00EAF050 /* ShimmerBluetooth.framework */; }; 3A780C952AE12BEB00EAF050 /* ShimmerBluetoothTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3A780C942AE12BEB00EAF050 /* ShimmerBluetoothTests.swift */; }; + DE11460D2C0100000000001D /* Shimmer3DeviceStatusTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = DE11460C2C0100000000001C /* Shimmer3DeviceStatusTest.swift */; }; 3A780C962AE12BEB00EAF050 /* ShimmerBluetooth.h in Headers */ = {isa = PBXBuildFile; fileRef = 3A780C882AE12BEB00EAF050 /* ShimmerBluetooth.h */; settings = {ATTRIBUTES = (Public, ); }; }; 3A780CA12AE12C0100EAF050 /* CoreBluetooth.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 3A780CA02AE12C0100EAF050 /* CoreBluetooth.framework */; }; 3A780CDA2AE12D8300EAF050 /* VerisenseProtocol.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3A780CD92AE12D8300EAF050 /* VerisenseProtocol.swift */; }; 3A7A7F242AE7753E001FD6BD /* ShimmerProtocol.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3A7A7F232AE7753E001FD6BD /* ShimmerProtocol.swift */; }; 3A7A7F262AE776FC001FD6BD /* ByteCommunication.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3A7A7F252AE776FC001FD6BD /* ByteCommunication.swift */; }; 3A7A7F282AE77F0E001FD6BD /* Shimmer3Protocol.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3A7A7F272AE77F0E001FD6BD /* Shimmer3Protocol.swift */; }; + DE11460B2C0100000000001B /* Shimmer3DeviceStatus.swift in Sources */ = {isa = PBXBuildFile; fileRef = DE11460A2C0100000000001A /* Shimmer3DeviceStatus.swift */; }; 3AA359132AF34D89008AD334 /* Shimmer3InfoMem.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3AA359122AF34D89008AD334 /* Shimmer3InfoMem.swift */; }; 3AA359152AF37943008AD334 /* ConfigByteLayoutShimmer3.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3AA359142AF37943008AD334 /* ConfigByteLayoutShimmer3.swift */; }; 3AB320E62B070830003D94F8 /* Sensor.swift in Sources */ = {isa = PBXBuildFile; fileRef = 3AB320E52B070830003D94F8 /* Sensor.swift */; }; @@ -71,11 +73,13 @@ 3A780C892AE12BEB00EAF050 /* ShimmerBluetooth.docc */ = {isa = PBXFileReference; lastKnownFileType = folder.documentationcatalog; path = ShimmerBluetooth.docc; sourceTree = ""; }; 3A780C8F2AE12BEB00EAF050 /* ShimmerBluetoothTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = ShimmerBluetoothTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; }; 3A780C942AE12BEB00EAF050 /* ShimmerBluetoothTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShimmerBluetoothTests.swift; sourceTree = ""; }; + DE11460C2C0100000000001C /* Shimmer3DeviceStatusTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Shimmer3DeviceStatusTest.swift; sourceTree = ""; }; 3A780CA02AE12C0100EAF050 /* CoreBluetooth.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreBluetooth.framework; path = Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS17.0.sdk/System/Library/Frameworks/CoreBluetooth.framework; sourceTree = DEVELOPER_DIR; }; 3A780CD92AE12D8300EAF050 /* VerisenseProtocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VerisenseProtocol.swift; sourceTree = ""; }; 3A7A7F232AE7753E001FD6BD /* ShimmerProtocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ShimmerProtocol.swift; sourceTree = ""; }; 3A7A7F252AE776FC001FD6BD /* ByteCommunication.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ByteCommunication.swift; sourceTree = ""; }; 3A7A7F272AE77F0E001FD6BD /* Shimmer3Protocol.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Shimmer3Protocol.swift; sourceTree = ""; }; + DE11460A2C0100000000001A /* Shimmer3DeviceStatus.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Shimmer3DeviceStatus.swift; sourceTree = ""; }; 3AA359122AF34D89008AD334 /* Shimmer3InfoMem.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Shimmer3InfoMem.swift; sourceTree = ""; }; 3AA359142AF37943008AD334 /* ConfigByteLayoutShimmer3.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ConfigByteLayoutShimmer3.swift; sourceTree = ""; }; 3AB320E52B070830003D94F8 /* Sensor.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Sensor.swift; sourceTree = ""; }; @@ -151,6 +155,7 @@ 3A77128C2AE177A4006213A8 /* ShimmerDevice.swift */, 3A77128E2AE177AF006213A8 /* Shimmer3.swift */, 3A7A7F272AE77F0E001FD6BD /* Shimmer3Protocol.swift */, + DE11460A2C0100000000001A /* Shimmer3DeviceStatus.swift */, 3A780CD92AE12D8300EAF050 /* VerisenseProtocol.swift */, 3A7A7F232AE7753E001FD6BD /* ShimmerProtocol.swift */, 3A7712902AE26805006213A8 /* BLEByteRadioold.swift */, @@ -181,6 +186,7 @@ isa = PBXGroup; children = ( 3A780C942AE12BEB00EAF050 /* ShimmerBluetoothTests.swift */, + DE11460C2C0100000000001C /* Shimmer3DeviceStatusTest.swift */, 3AED206C2B0B10960066A0F8 /* ShimmerUtilitiesTest.swift */, 3AD7C6022BD23238000E5455 /* SensorTest.swift */, DE10230C2C0100000000001C /* TimestampUnwrapVectorsTest.swift */, @@ -332,6 +338,7 @@ 3AED20712B0C4BA60066A0F8 /* MagSensor.swift in Sources */, 3A7A7F242AE7753E001FD6BD /* ShimmerProtocol.swift in Sources */, 3A7A7F282AE77F0E001FD6BD /* Shimmer3Protocol.swift in Sources */, + DE11460B2C0100000000001B /* Shimmer3DeviceStatus.swift in Sources */, 92B4B5502DF035C100225A97 /* HighGAccelSensor.swift in Sources */, 3AEB12F92BCE6F7E00B5F6F1 /* Shimmer3SpeedTestProtocol.swift in Sources */, 3AA359132AF34D89008AD334 /* Shimmer3InfoMem.swift in Sources */, @@ -344,6 +351,7 @@ buildActionMask = 2147483647; files = ( 3AED206D2B0B10960066A0F8 /* ShimmerUtilitiesTest.swift in Sources */, + DE11460D2C0100000000001D /* Shimmer3DeviceStatusTest.swift in Sources */, 3A780C952AE12BEB00EAF050 /* ShimmerBluetoothTests.swift in Sources */, 3AD7C6032BD23238000E5455 /* SensorTest.swift in Sources */, DE10230D2C0100000000001D /* TimestampUnwrapVectorsTest.swift in Sources */, diff --git a/ShimmerBluetooth/ShimmerBluetooth/Shimmer3DeviceStatus.swift b/ShimmerBluetooth/ShimmerBluetooth/Shimmer3DeviceStatus.swift new file mode 100644 index 0000000..9f816a4 --- /dev/null +++ b/ShimmerBluetooth/ShimmerBluetooth/Shimmer3DeviceStatus.swift @@ -0,0 +1,186 @@ +// +// Shimmer3DeviceStatus.swift +// ShimmerBluetooth +// +// Created by Shimmer Engineering on 04/10/2026. +// + +import Foundation + +/// What a Shimmer3 or Shimmer3R says it is doing: the status bytes of a STATUS_RESPONSE (0x71). +/// +/// The firmware pushes them unasked whenever its state changes for a reason the host did not +/// cause: a dock, an undock, the user button, a trial-duration expiry or a low-battery stop. The +/// bits are in log-and-stream-common `docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md` §5.3 and the push +/// in §5.4; `Shimmer3StatusPush` finds one in the byte stream. +public struct Shimmer3DeviceStatus: Equatable { + /// Sitting in a dock. + public let docked: Bool + /// Sensing, for a stream, an SD recording or both. + public let sensing: Bool + /// The real-world clock has been set this power cycle. False on firmware too old to report it. + public let rtcSet: Bool + /// Logging to the SD card. + public let sdLogging: Bool + /// Streaming over Bluetooth. + public let streaming: Bool + /// An SD card is in the slot. False on firmware too old to report it. + public let sdInserted: Bool + /// The SD card or its file is unusable. False on firmware too old to report it. + public let sdBadFile: Bool + /// The red LED's state, as TOGGLE_LED_COMMAND flips it. False on firmware too old to report it. + public let redLedOn: Bool + /// USB plugged in, from the second status byte, which only a Shimmer3R sends, from LogAndStream + /// v1.00.024. nil where that byte is absent, so "not reported" is never read as "unplugged". + public let usbPluggedIn: Bool? + /// The status bytes as they arrived. + public let raw: [UInt8] + + /// Decodes the status bytes alone, the ones after 0x8A 0x71. nil when there are none. + public init?(statusBytes: [UInt8]) { + guard let byte0 = statusBytes.first else { + return nil + } + // ShimBt_assembleStatusBytes, log-and-stream-common Comms/shimmer_bt_uart.c + docked = (byte0 & 0x01) != 0 + sensing = (byte0 & 0x02) != 0 + rtcSet = (byte0 & 0x04) != 0 + sdLogging = (byte0 & 0x08) != 0 + streaming = (byte0 & 0x10) != 0 + sdInserted = (byte0 & 0x20) != 0 + sdBadFile = (byte0 & 0x40) != 0 + redLedOn = (byte0 & 0x80) != 0 + if (statusBytes.count >= 2){ + usbPluggedIn = (statusBytes[1] & 0x01) != 0 + } else { + usbPluggedIn = nil + } + raw = statusBytes + } +} + +/// Finds an unsolicited status push at the head of the receive buffer, and sizes it. +/// +/// A push is `[0xFF] 0x8A 0x71 [crc...]` (§3.2, §5.4): +/// +/// - The leading ACK is on by default. SET_INSTREAM_RESPONSE_ACK_PREFIX_STATE (0xA3) turns it off, +/// and the firmware turns it back on at every disconnect. This API never turns it off, so with no +/// CRC an ACK followed at once by an unprefixed push would read as one prefixed push. +/// - The status is 1 byte, or 2 on a Shimmer3R from LogAndStream v1.00.024 (`statusPayloadBytes`). +/// - The session CRC, 0 to 2 bytes, covers everything before it, the ACK included +/// (`ShimBt_instreamStatusRespSend`, log-and-stream-common `Comms/shimmer_bt_uart.c`). +/// +/// A host must take one at any time, between a command and its reply too, whether or not it is +/// streaming, and must not take its 0xFF for the ACK of the command it is waiting on (§5.4, rules 1 +/// and 2). So `Shimmer3Protocol` asks here before anything else reads the buffer. +enum Shimmer3StatusPush { + + /// What the receive buffer starts with. + enum Head: Equatable { + /// Not a status push. + case notAPush + /// The start of one: wait for the rest. + case incomplete + /// A whole push, `length` bytes from its first byte to its last CRC byte. `crcValid` is false + /// when the session CRC does not match, and then `statusBytes` cannot be trusted. + case push(length: Int, statusBytes: [UInt8], crcValid: Bool) + } + + /// LogAndStream's firmware identifier in the GET_FW_VERSION_COMMAND reply (`REV_FW_IDENTIFIER`). + static let FW_IDENTIFIER_LOGANDSTREAM = 3 + + /// How many status bytes this device sends: 2 on a Shimmer3R running LogAndStream v1.00.024 or + /// later, 1 on anything else, and nil while the versions that decide it are unread (they are -1 + /// until then). + /// + /// The second byte came with log-and-stream-common 8377afc, first released in + /// LogAndStream_Shimmer3R_v1.00.024 (§5.3 and Appendix A). It is compiled only for SHIMMER3R, so + /// the hardware decides first: Shimmer3 LogAndStream reaches the same version numbers and never + /// sends it. + static func statusPayloadBytes(hardwareVersion: Int, firmwareIdentifier: Int, firmwareMajor: Int, firmwareMinor: Int, firmwareInternal: Int) -> Int? { + if (hardwareVersion < 0){ + return nil + } + if (hardwareVersion != Shimmer3Protocol.HardwareType.Shimmer3R.rawValue){ + return 1 + } + if (firmwareIdentifier < 0){ + return nil + } + if (firmwareIdentifier != FW_IDENTIFIER_LOGANDSTREAM){ + return 1 + } + return (firmwareMajor, firmwareMinor, firmwareInternal) >= (1, 0, 24) ? 2 : 1 + } + + /// What `buffer` starts with: a whole status push, the start of one, or something else. + /// + /// A lone 0xFF is not taken for the start of a push. It is an ACK until more bytes say otherwise, + /// which is how the receive loop reads the first byte of every other frame too. + /// + /// - Parameters: + /// - statusBytes: 1 or 2, from `statusPayloadBytes`, or nil while that is unknown. + /// - crcBytes: the session CRC's length: 0, 1 or 2. + static func frame(_ buffer: [UInt8], statusBytes: Int?, crcBytes: Int) -> Head { + let header: Int // up to and including the 0x71 + if (buffer.first == Shimmer3Protocol.PacketTypeShimmer.instreamCmdResponse.rawValue){ + header = 2 + } else if (buffer.count >= 2 && buffer[0] == Shimmer3Protocol.PacketTypeShimmer.ackCommand.rawValue && buffer[1] == Shimmer3Protocol.PacketTypeShimmer.instreamCmdResponse.rawValue){ + header = 3 + } else { + return .notAPush + } + if (buffer.count < header){ + return .incomplete + } + if (buffer[header - 1] != Shimmer3Protocol.PacketTypeShimmer.statusResponse.rawValue){ + return .notAPush // a different 0x8A message, and this API asks for none of them + } + + let width: Int + if let knownWidth = statusBytes { + width = knownWidth + } else { + // Unknown until connect() has read both versions, so the bytes have to say. A second + // status byte is 0x00 or 0x01: bit 0 is usbPluggedIn and bits 1-7 are zero (§5.3). + // With no CRC, a single status byte is followed by the next message, which starts 0xFF, + // 0xFE or 0x8A; 0x00 starts only a data packet, and no stream runs before the versions + // are read. With a CRC, a single status byte is followed by the CRC's low byte, which + // can be 0x00 or 0x01 as well, so there the CRC decides. + if (buffer.count < header + 2){ + return .incomplete + } + if (buffer[header + 1] > 0x01){ + width = 1 + } else if (crcBytes == 0){ + width = 2 + } else if (buffer.count < header + 2 + crcBytes){ + return .incomplete + } else if (!crcMatches(buffer, covering: header + 2, crcBytes: crcBytes) && crcMatches(buffer, covering: header + 1, crcBytes: crcBytes)){ + width = 1 + } else { + width = 2 + } + } + + let length = header + width + crcBytes + if (buffer.count < length){ + return .incomplete + } + return .push(length: length, statusBytes: Array(buffer[header..<(header + width)]), crcValid: crcMatches(buffer, covering: header + width, crcBytes: crcBytes)) + } + + /// Whether the `crcBytes` bytes after `buffer[0.. Bool { + if (crcBytes == 0){ + return true + } + let crc = ShimmerUtilities.shimmerUartCrcCalc(buffer, length) + for i in 0..= 1+Int(self.CRCMode.rawValue)){ self.processNackFromCommand() } @@ -1177,6 +1183,52 @@ public class Shimmer3Protocol : NSObject, ShimmerProtocol { self.processing = false } + /// The status the device last pushed unsolicited, this connection (log-and-stream-common + /// `docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md` §5.4). nil until it pushes one. + public private(set) var deviceStatus: Shimmer3DeviceStatus? + + /// Takes an unsolicited status push off the head of receivedBytes, in any state and whatever + /// command is waiting (§5.4). Left alone, a push stayed at the head of the buffer, or had its + /// 0xFF taken for the waiting command's ACK, and every reply after it queued behind it; in a + /// stream it shifted every packet after it. + /// + /// - Returns: true when the head is a push, consumed or still arriving, so that nothing else + /// reads the buffer this pass. + private func processStatusPushAtHead() -> Bool { + let statusWidth = Shimmer3StatusPush.statusPayloadBytes(hardwareVersion: REV_HW_MAJOR, firmwareIdentifier: REV_FW_IDENTIFIER, firmwareMajor: REV_FW_MAJOR, firmwareMinor: REV_FW_MINOR, firmwareInternal: REV_FW_INTERNAL) + switch Shimmer3StatusPush.frame(self.receivedBytes, statusBytes: statusWidth, crcBytes: Int(self.CRCMode.rawValue)) { + case .notAPush: + return false + case .incomplete: + return true + case .push(let length, let statusBytes, let crcValid): + let received = Array(self.receivedBytes.prefix(length)) + self.receivedBytes.removeFirst(length) + guard crcValid, let status = Shimmer3DeviceStatus(statusBytes: statusBytes) else { + // Dropped rather than acted on. The firmware pushes again at its next change. + print("[CRC ERROR] : status push \(received)") + return true + } + print("Status push received: \(status)") + self.deviceStatus = status + /* The device stopped streaming by itself: a dock, the user button, the trial duration + * or a low battery. Nothing of the stream follows the push, because ShimSens_saveData + * sends only while btStreaming is set, so the bytes behind it are replies again. + * + * Not before this stream's first packet, though. START_STREAMING_COMMAND is ACKed + * before TASK_STARTSENSING sets btStreaming, so a push built between the two says + * streaming is off and the stream then starts all the same. And a stop this API sent + * is left to its own ACK, which the streaming branch waits for. */ + if (self.BTState == Shimmer3BTState.STREAMING && !status.streaming + && self.numberOfPackets > 0 && self.commandSent != PacketTypeShimmer.stopStreamingCommand){ + print("Streaming stopped by the device") + self.changeState(btState:Shimmer3BTState.CONNECTED) + } + self.delegate?.shimmerProtocolNewDeviceStatus(message: status) + return true + } + } + func interpretDataPacketFormat(nC: Int, signalid: [UInt8]) { @@ -1525,6 +1577,13 @@ public class Shimmer3Protocol : NSObject, ShimmerProtocol { } private func sendStopStreamingCommandInternal() async -> Bool? { + guard BTState == Shimmer3BTState.STREAMING else { + // Nothing to stop: the stream never started, or the device ended it and said so in a + // status push (processStatusPushAtHead). Only the streaming branch reads a stop's ACK, + // so one sent now would sit ahead of every later reply. + print("StopStreaming not sent: not streaming") + return true + } let bytes:[UInt8] = [PacketTypeShimmer.stopStreamingCommand.rawValue] commandSent = PacketTypeShimmer.stopStreamingCommand radio!.writeBytes(bytes:bytes) @@ -1887,36 +1946,8 @@ public class Shimmer3Protocol : NSObject, ShimmerProtocol { } func shimmerUartCrcCalc(_ msg: [UInt8], _ len: Int) -> [UInt8] { - let CRC_INIT: Int = 0xB0CA - var crcCalc = shimmerUartCrcByte(CRC_INIT, msg[0]) - var i = 1 - - while i < len { - crcCalc = shimmerUartCrcByte(crcCalc, msg[i]) - i += 1 - } - - if len % 2 > 0 { - crcCalc = shimmerUartCrcByte(crcCalc, 0x00) - } - - let crcCalcArray: [UInt8] = [ - UInt8(crcCalc & 0xFF), // CRC LSB - UInt8((crcCalc >> 8) & 0xFF) // CRC MSB - ] - - return crcCalcArray - } - - func shimmerUartCrcByte(_ crc: Int, _ b: UInt8) -> Int { - var crcValue = crc & 0xFFFF - crcValue = (crcValue >> 8) | (crcValue << 8) - crcValue ^= Int(b) & 0xFF - crcValue ^= (crcValue & 0xFF) >> 4 - crcValue ^= crcValue << 12 - crcValue ^= (crcValue & 0xFF) << 5 - crcValue &= 0xFFFF - return crcValue + // In ShimmerUtilities so that the status push framing and the tests share this one copy. + return ShimmerUtilities.shimmerUartCrcCalc(msg, len) } func checkCrc(_ bufferTemp: [UInt8], _ length: Int) -> Bool { @@ -2279,6 +2310,8 @@ public class Shimmer3Protocol : NSObject, ShimmerProtocol { case setExgRegsCommand = 0x61 case exgRegsResponse = 0x62 case getExgRegsCommand = 0x63 + case statusResponse = 0x71 + case instreamCmdResponse = 0x8A } public enum BTCRCMode: UInt8 { case OFF = 0 @@ -2334,6 +2367,7 @@ extension Shimmer3Protocol : ByteCommunicationDelegate { public func byteCommunicationDisconnected(connectionloss: Bool) { self.continuation?.resume(returning: false) self.continuation = nil + self.deviceStatus = nil self.changeState(btState:Shimmer3BTState.DISCONNECTED) stopProcessing() print("Current State: \(BTState)") diff --git a/ShimmerBluetooth/ShimmerBluetooth/ShimmerProtocol.swift b/ShimmerBluetooth/ShimmerBluetooth/ShimmerProtocol.swift index e4ca031..2ac792e 100644 --- a/ShimmerBluetooth/ShimmerBluetooth/ShimmerProtocol.swift +++ b/ShimmerBluetooth/ShimmerBluetooth/ShimmerProtocol.swift @@ -22,4 +22,11 @@ public protocol ShimmerProtocolDelegate { func shimmerProtocolNewMessage(message:String) func shimmerProtocolNewObjectCluster(message:ObjectCluster) func shimmerBTStateChange(message:Shimmer3Protocol.Shimmer3BTState) + /// A status the device pushed unasked: it was docked or undocked, its button was pressed, or a + /// trial duration or low battery stopped it. + func shimmerProtocolNewDeviceStatus(message:Shimmer3DeviceStatus) +} +public extension ShimmerProtocolDelegate { + /// Optional: a delegate written before status pushes were handled goes on compiling, and ignores them. + func shimmerProtocolNewDeviceStatus(message:Shimmer3DeviceStatus) {} } diff --git a/ShimmerBluetooth/ShimmerBluetooth/ShimmerUtilities.swift b/ShimmerBluetooth/ShimmerBluetooth/ShimmerUtilities.swift index 0f587fe..1d7988b 100644 --- a/ShimmerBluetooth/ShimmerBluetooth/ShimmerUtilities.swift +++ b/ShimmerBluetooth/ShimmerBluetooth/ShimmerUtilities.swift @@ -187,4 +187,41 @@ public class ShimmerUtilities{ public static func isAllZeros(_ bytes: [UInt8]) -> Bool { return bytes.allSatisfy { $0 == 0x00 } } + + /// The Bluetooth link CRC over `msg[0.. [UInt8] { + let CRC_INIT: Int = 0xB0CA + var crcCalc = shimmerUartCrcByte(CRC_INIT, msg[0]) + var i = 1 + + while i < len { + crcCalc = shimmerUartCrcByte(crcCalc, msg[i]) + i += 1 + } + + if len % 2 > 0 { + crcCalc = shimmerUartCrcByte(crcCalc, 0x00) + } + + let crcCalcArray: [UInt8] = [ + UInt8(crcCalc & 0xFF), // CRC LSB + UInt8((crcCalc >> 8) & 0xFF) // CRC MSB + ] + + return crcCalcArray + } + + static func shimmerUartCrcByte(_ crc: Int, _ b: UInt8) -> Int { + var crcValue = crc & 0xFFFF + crcValue = (crcValue >> 8) | (crcValue << 8) + crcValue ^= Int(b) & 0xFF + crcValue ^= (crcValue & 0xFF) >> 4 + crcValue ^= crcValue << 12 + crcValue ^= (crcValue & 0xFF) << 5 + crcValue &= 0xFFFF + return crcValue + } } diff --git a/ShimmerBluetooth/ShimmerBluetoothTests/Shimmer3DeviceStatusTest.swift b/ShimmerBluetooth/ShimmerBluetoothTests/Shimmer3DeviceStatusTest.swift new file mode 100644 index 0000000..10d00cd --- /dev/null +++ b/ShimmerBluetooth/ShimmerBluetoothTests/Shimmer3DeviceStatusTest.swift @@ -0,0 +1,150 @@ +// +// Shimmer3DeviceStatusTest.swift +// ShimmerBluetoothTests +// +// Created by Shimmer Engineering on 04/10/2026. +// + +import XCTest +@testable import ShimmerBluetooth + +/// The unsolicited status push, `[0xFF] 0x8A 0x71 [crc...]`: log-and-stream-common +/// `docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md` §3.2, §5.3 and §5.4. +class Shimmer3DeviceStatusTest: XCTestCase { + + /// A push as `ShimBt_instreamStatusRespSend` builds it: the ACK if prefixed, 0x8A 0x71, the + /// status bytes, then the session CRC over all of that. + func push(_ status: [UInt8], prefixed: Bool, crcBytes: Int) -> [UInt8] { + var bytes: [UInt8] = prefixed ? [0xFF, 0x8A, 0x71] : [0x8A, 0x71] + bytes.append(contentsOf: status) + return bytes + Array(ShimmerUtilities.shimmerUartCrcCalc(bytes, bytes.count).prefix(crcBytes)) + } + + /// A bare ACK with the session CRC, which is how the reply to a waiting command starts. + func bareAck(crcBytes: Int) -> [UInt8] { + return [0xFF] + Array(ShimmerUtilities.shimmerUartCrcCalc([0xFF], 1).prefix(crcBytes)) + } + + func testDecodesEachBitOfTheFirstStatusByte() { + // Bit 0 to bit 7, ShimBt_assembleStatusBytes (§5.3) + let fields: [KeyPath] = [\.docked, \.sensing, \.rtcSet, \.sdLogging, \.streaming, \.sdInserted, \.sdBadFile, \.redLedOn] + for bit in 0..<8 { + let status = Shimmer3DeviceStatus(statusBytes: [UInt8(1 << bit)])! + for (index, field) in fields.enumerated() { + XCTAssertEqual(status[keyPath: field], index == bit, "status bit \(bit), field \(index)") + } + } + } + + func testOnlyASecondStatusByteReportsUsb() { + XCTAssertNil(Shimmer3DeviceStatus(statusBytes: [0x21])!.usbPluggedIn, "one byte: not reported, which is not unplugged") + XCTAssertEqual(Shimmer3DeviceStatus(statusBytes: [0x21, 0x00])!.usbPluggedIn, false) + XCTAssertEqual(Shimmer3DeviceStatus(statusBytes: [0x21, 0x01])!.usbPluggedIn, true) + XCTAssertEqual(Shimmer3DeviceStatus(statusBytes: [0x21, 0x01])!.raw, [0x21, 0x01]) + XCTAssertNil(Shimmer3DeviceStatus(statusBytes: [])) + } + + func testStatusPayloadBytes() { + func width(_ hardware: Int, _ firmwareIdentifier: Int, _ major: Int, _ minor: Int, _ fwInternal: Int) -> Int? { + return Shimmer3StatusPush.statusPayloadBytes(hardwareVersion: hardware, firmwareIdentifier: firmwareIdentifier, firmwareMajor: major, firmwareMinor: minor, firmwareInternal: fwInternal) + } + let shimmer3 = Shimmer3Protocol.HardwareType.Shimmer3.rawValue + let shimmer3R = Shimmer3Protocol.HardwareType.Shimmer3R.rawValue + let logAndStream = Shimmer3StatusPush.FW_IDENTIFIER_LOGANDSTREAM + + // Unknown until the versions are read. + XCTAssertNil(width(-1, -1, -1, -1, -1)) + XCTAssertNil(width(shimmer3R, -1, -1, -1, -1)) + // No Shimmer3 sends a second byte, at any version, so its hardware is enough. + XCTAssertEqual(width(shimmer3, -1, -1, -1, -1), 1) + XCTAssertEqual(width(shimmer3, logAndStream, 1, 1, 6), 1) + // Shimmer3R LogAndStream from v1.00.024. + XCTAssertEqual(width(shimmer3R, logAndStream, 1, 0, 23), 1) + XCTAssertEqual(width(shimmer3R, logAndStream, 1, 0, 24), 2) + XCTAssertEqual(width(shimmer3R, logAndStream, 1, 0, 50), 2) + XCTAssertEqual(width(shimmer3R, logAndStream, 1, 1, 0), 2, "minor 1 is after v1.00.024, whatever the internal number") + XCTAssertEqual(width(shimmer3R, logAndStream, 0, 0, 30), 1, "major 0 is before v1.00.024, whatever the internal number") + // Firmware other than LogAndStream (1 is BtStream). + XCTAssertEqual(width(shimmer3R, 1, 1, 0, 30), 1) + } + + func testFramesTheFirmwareReferenceCrcVectors() { + // CRCs from log-and-stream-common Extras/python_scripts/Shimmer_common/shimmer_crc.py, not from this API. + XCTAssertEqual(Shimmer3StatusPush.frame([0xFF, 0x8A, 0x71, 0x31, 0xC5, 0xBA], statusBytes: 1, crcBytes: 2), .push(length: 6, statusBytes: [0x31], crcValid: true)) + XCTAssertEqual(Shimmer3StatusPush.frame([0xFF, 0x8A, 0x71, 0x31, 0x01, 0x1E, 0x4B], statusBytes: 2, crcBytes: 2), .push(length: 7, statusBytes: [0x31, 0x01], crcValid: true)) + XCTAssertEqual(Shimmer3StatusPush.frame([0x8A, 0x71, 0x31, 0xE8, 0x7C], statusBytes: 1, crcBytes: 2), .push(length: 5, statusBytes: [0x31], crcValid: true)) + XCTAssertEqual(Shimmer3StatusPush.frame([0x8A, 0x71, 0x31, 0x01, 0xC9], statusBytes: 2, crcBytes: 1), .push(length: 5, statusBytes: [0x31, 0x01], crcValid: true)) + } + + func testFramesAPushWithAndWithoutPrefixInEveryCrcMode() { + for prefixed in [true, false] { + for crcBytes in 0...2 { + for status: [UInt8] in [[0x21], [0x21, 0x01]] { + let bytes = push(status, prefixed: prefixed, crcBytes: crcBytes) + let expected = Shimmer3StatusPush.Head.push(length: bytes.count, statusBytes: status, crcValid: true) + let context = "prefixed \(prefixed), CRC \(crcBytes), status \(status)" + XCTAssertEqual(Shimmer3StatusPush.frame(bytes, statusBytes: status.count, crcBytes: crcBytes), expected, context) + // Whatever follows is left alone: here, the reply to the command that was waiting. + XCTAssertEqual(Shimmer3StatusPush.frame(bytes + bareAck(crcBytes: crcBytes), statusBytes: status.count, crcBytes: crcBytes), expected, context) + } + } + } + } + + func testWaitsForTheRestOfAPush() { + for prefixed in [true, false] { + for crcBytes in 0...2 { + let bytes = push([0x21, 0x01], prefixed: prefixed, crcBytes: crcBytes) + for count in 1.. Shimmer3StatusPush.Head { + return Shimmer3StatusPush.frame(bytes, statusBytes: statusBytes, crcBytes: crcBytes) + } + XCTAssertEqual(frame([]), .notAPush) + XCTAssertEqual(frame(bareAck(crcBytes: crcBytes)), .notAPush, "an ACK's CRC is F4 65, never 8A 71") + XCTAssertEqual(frame([0xFE, 0xC5, 0x56]), .notAPush, "a NACK") + XCTAssertEqual(frame([0x00, 0x01, 0x02, 0x03, 0x04]), .notAPush, "a data packet") + XCTAssertEqual(frame([0xFF, 0x2F, 0x03, 0x00, 0x01, 0x00, 0x18, 0x00]), .notAPush, "an ACK and its reply") + XCTAssertEqual(frame([0xFF, 0x8A, 0x94, 0x00, 0x08, 0x00]), .notAPush, "the battery reply, also behind 0x8A") + XCTAssertEqual(frame([0xFF, 0xFF, 0x8A, 0x71, 0x21]), .notAPush, "an ACK ahead of a push goes first") + } + } + } + + func testFramesAPushWhoseCrcDoesNotMatch() { + var bytes = push([0x21, 0x01], prefixed: true, crcBytes: 2) + bytes[bytes.count - 1] ^= 0xFF + XCTAssertEqual(Shimmer3StatusPush.frame(bytes, statusBytes: 2, crcBytes: 2), .push(length: 7, statusBytes: [0x21, 0x01], crcValid: false), "still sized, so the stream stays aligned") + } + + func testTellsTheWidthBeforeTheVersionsAreRead() { + // Every first status byte, both widths, both prefix states and every CRC mode, followed by + // what comes next during connect(): the reply to the command that is waiting. The CRC is + // what makes this hard. A one-byte push's CRC low byte is 0x00 or 0x01, as a second status + // byte would be, for 0x52 and 0x71 prefixed and for 0x1F and 0x96 unprefixed. + for prefixed in [true, false] { + for crcBytes in 0...2 { + for byte0 in 0...255 { + for status: [UInt8] in [[UInt8(byte0)], [UInt8(byte0), 0x00], [UInt8(byte0), 0x01]] { + let bytes = push(status, prefixed: prefixed, crcBytes: crcBytes) + XCTAssertEqual(Shimmer3StatusPush.frame(bytes + bareAck(crcBytes: crcBytes), statusBytes: nil, crcBytes: crcBytes), + .push(length: bytes.count, statusBytes: status, crcValid: true), + "prefixed \(prefixed), CRC \(crcBytes), status \(status)") + } + } + } + } + // With no CRC, a one-byte status cannot be told from the first of two until the next byte arrives. + XCTAssertEqual(Shimmer3StatusPush.frame([0xFF, 0x8A, 0x71, 0x21], statusBytes: nil, crcBytes: 0), .incomplete) + } +} diff --git a/ShimmerBluetooth/ShimmerBluetoothTests/ShimmerUtilitiesTest.swift b/ShimmerBluetooth/ShimmerBluetoothTests/ShimmerUtilitiesTest.swift index 2298d89..fd216d9 100644 --- a/ShimmerBluetooth/ShimmerBluetoothTests/ShimmerUtilitiesTest.swift +++ b/ShimmerBluetooth/ShimmerBluetoothTests/ShimmerUtilitiesTest.swift @@ -278,4 +278,15 @@ class ShimmerUtilitiesTest: XCTestCase { } } + func testShimmerUartCrcCalcMatchesTheFirmwareReference() { + // [LSB, MSB] from log-and-stream-common Extras/python_scripts/Shimmer_common/shimmer_crc.py + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0xFF], 1), [0xF4, 0x65], "a bare ACK, odd length so padded") + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0xFE], 1), [0xC5, 0x56], "a bare NACK") + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0xFF, 0x8A, 0x71, 0x31], 4), [0xC5, 0xBA], "even length, not padded") + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0xFF, 0x8A, 0x71, 0x31, 0x01], 5), [0x1E, 0x4B]) + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0x8A, 0x71, 0x31], 3), [0xE8, 0x7C]) + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0x8A, 0x71, 0x31, 0x01], 4), [0xC9, 0x6C]) + XCTAssertEqual(ShimmerUtilities.shimmerUartCrcCalc([0xFF, 0x8A, 0x71, 0x52, 0xAA], 4), [0x00, 0xE6], "only the first len bytes count") + } + }