From 503b875adbd9251d22280af6c9463a5fd46659b0 Mon Sep 17 00:00:00 2001 From: Mark Nolan Date: Sun, 4 Oct 2026 20:40:49 +0100 Subject: [PATCH] DEV-1146: take an unsolicited status push off the receive buffer, in any state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The firmware pushes [0xFF] 0x8A 0x71 [crc] whenever its state changes for a reason the host did not cause: a dock or undock, the user button, a trial-duration expiry or a low-battery stop (log-and-stream-common docs/SHIMMER3_BT_COMMUNICATION_PROTOCOL.md §5.4). startProcessing() knew nothing of it: - Idle, it acted only on a leading 0xFF and dispatched on commandSent. A prefixed push was read as the waiting command's reply or left at the head of the buffer, and an unprefixed one was never consumed. Every later reply queued behind it, and with no command timeouts every later call hung. - Streaming, it sliced PacketSize+1 bytes without looking at the 0x00 header, so one push shifted every packet after it. Every pass now asks Shimmer3StatusPush.frame first, in any state and whatever command is waiting. A push comes off whole, with or without its ACK prefix and with its session CRC. Its status goes to deviceStatus and to a new delegate method, shimmerProtocolNewDeviceStatus, which has a default so existing delegates compile unchanged. - Width: one status byte, or two on a Shimmer3R from LogAndStream v1.00.024 (§5.3). Before connect() has read the versions, the byte after the first decides, and with a CRC on, the CRC does. - A push saying streaming stopped, once the stream has delivered a packet, returns the state to CONNECTED; the firmware sends no packet after it. So sendStopStreamingCommand now returns at once when not streaming, because only the streaming branch reads a stop's ACK. - The CRC moved to ShimmerUtilities so the framing and the tests share one copy; Shimmer3Protocol.shimmerUartCrcCalc calls it. Shimmer3DeviceStatusTest covers the framing, sizing and decoding, and ShimmerUtilitiesTest checks the CRC against the firmware's Python reference. The receive loop itself has no test: Shimmer3Protocol needs a live CBPeripheral. Unbuilt and untested: written without Xcode, so CI is the first compile. Co-Authored-By: Claude Opus 5.5 --- .../project.pbxproj | 8 + .../Shimmer3DeviceStatus.swift | 186 ++++++++++++++++++ .../ShimmerBluetooth/Shimmer3Protocol.swift | 95 ++++++--- .../ShimmerBluetooth/ShimmerProtocol.swift | 7 + .../ShimmerBluetooth/ShimmerUtilities.swift | 37 ++++ .../Shimmer3DeviceStatusTest.swift | 150 ++++++++++++++ .../ShimmerUtilitiesTest.swift | 11 ++ 7 files changed, 463 insertions(+), 31 deletions(-) create mode 100644 ShimmerBluetooth/ShimmerBluetooth/Shimmer3DeviceStatus.swift create mode 100644 ShimmerBluetooth/ShimmerBluetoothTests/Shimmer3DeviceStatusTest.swift diff --git a/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj b/ShimmerBluetooth/ShimmerBluetooth.xcodeproj/project.pbxproj index cf19962..5fc5e62 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 */; }; @@ -69,11 +71,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 = ""; }; @@ -147,6 +151,7 @@ 3A77128C2AE177A4006213A8 /* ShimmerDevice.swift */, 3A77128E2AE177AF006213A8 /* Shimmer3.swift */, 3A7A7F272AE77F0E001FD6BD /* Shimmer3Protocol.swift */, + DE11460A2C0100000000001A /* Shimmer3DeviceStatus.swift */, 3A780CD92AE12D8300EAF050 /* VerisenseProtocol.swift */, 3A7A7F232AE7753E001FD6BD /* ShimmerProtocol.swift */, 3A7712902AE26805006213A8 /* BLEByteRadioold.swift */, @@ -176,6 +181,7 @@ isa = PBXGroup; children = ( 3A780C942AE12BEB00EAF050 /* ShimmerBluetoothTests.swift */, + DE11460C2C0100000000001C /* Shimmer3DeviceStatusTest.swift */, 3AED206C2B0B10960066A0F8 /* ShimmerUtilitiesTest.swift */, 3AD7C6022BD23238000E5455 /* SensorTest.swift */, ); @@ -325,6 +331,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 */, @@ -337,6 +344,7 @@ buildActionMask = 2147483647; files = ( 3AED206D2B0B10960066A0F8 /* ShimmerUtilitiesTest.swift in Sources */, + DE11460D2C0100000000001D /* Shimmer3DeviceStatusTest.swift in Sources */, 3A780C952AE12BEB00EAF050 /* ShimmerBluetoothTests.swift in Sources */, 3AD7C6032BD23238000E5455 /* SensorTest.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..self.PacketSize){ var received = Array(self.receivedBytes.prefix(self.PacketSize+1)) //1 for the start of the packet @@ -1063,6 +1068,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]) { @@ -1401,6 +1452,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) @@ -1692,36 +1750,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 { @@ -2083,6 +2113,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 @@ -2138,6 +2170,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") + } + }