DEV-793 Address adversarial review: gyro sensitivity, block-ID guard, split-safe offsets, accel helpers

Review findings from PR #277 (all verified against code/datasheet before fixing):
1) K1: LSM6DSV gyro sensitivity now uses the ST datasheet angular-rate spec (4.375 mdps/LSB at +-125 dps, doubling per range - same as the gen-1 LSM6DS3) instead of a 32768/FS derivation, which was ~12.8% low. Verified: Test_029's rotation peak rescales 512 -> 586.9 dps, exactly the predicted x1.147.
2) CRITICAL: parseDataBlockMetaData now only accepts data-block IDs with parse support (<= LSM6DSV); the declared-but-unimplemented gen-2 IDs (LIGHT/ALGO_HUB/SKIN_TEMP/FLICKER) are rejected with the informative exception instead of corrupting the parse, and calculateFifoBlockSize throws instead of returning Integer.MIN_VALUE.
3) MAJOR: byte-offset arithmetic through the payload now uses a raw block size (getQtySensorDataBytesInDatablockRaw) that the midday/midnight CSV-split logic cannot recompute - the recomputed dataPacketSize*sampleCount is wrong for the variable-length LSM6DSV tagged FIFO.
4) MAJOR: isAnAccelEnabled/getPrimaryAccel/isSensorKeyAnAccel now include the LSM6DSV.
5) NIT: the LSM6DSV 'Sensor config:' line labels the mag rate 'Configured =' and appends the effective cap when it exceeds the IMU ODR.
6) Comment documenting why the gen-2 battery divider is gated on hardware revision rather than firmware version.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: marknolan

ShimmerDriver/src/main/java/com/shimmerresearch/verisense/VerisenseDevice.java

@@ -805,6 +805,8 @@ public SENSORS getPrimaryAccel() {
 			return SENSORS.LIS2DW12;
 		} else if(isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DS3_ACCEL)) {
 			return SENSORS.LSM6DS3;
+		} else if(isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DSV_ACCEL)) {
+			return SENSORS.LSM6DSV;
 		}
 		return null;
 	}
@@ -1032,9 +1034,20 @@ && isAnyLsm6dsvChannelEnabled()) {
 			sb.append("; Mag ");
 			sb.append(SENSOR_CONFIG_STRINGS.RATE);
 			if(isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DSV_MAG)) {
+				// Labelled "Configured" because the sensor hub reads the LIS2MDL once per
+				// accel/gyro sample, so the EFFECTIVE mag rate is capped at the IMU ODR.
+				sb.append(SENSOR_CONFIG_STRINGS.SAMPLING_RATE_CONFIGURED);
 				sb.append(sensorLsm6dsv.getMagRateFreq());
 				sb.append(" ");
 				sb.append(CHANNEL_UNITS.FREQUENCY);
+				double imuOdrHz = sensorLsm6dsv.getRateFreq();
+				if(imuOdrHz>0 && sensorLsm6dsv.getMagRateFreq()>imuOdrHz) {
+					sb.append(" (capped to ");
+					sb.append(imuOdrHz);
+					sb.append(" ");
+					sb.append(CHANNEL_UNITS.FREQUENCY);
+					sb.append(" by the IMU rate)");
+				}
 			} else {
 				sb.append("Off");
 			}
@@ -1237,14 +1250,15 @@ public boolean isAnAdcChEnabled() {
 	//TODO set derived algorithm enabled bit like as done for PPG rather then checking
 	public boolean isAnAccelEnabled() {
 		if(isSensorEnabled(Configuration.Verisense.SENSOR_ID.LIS2DW12_ACCEL)
-				|| isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DS3_ACCEL)) {
+				|| isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DS3_ACCEL)
+				|| isSensorEnabled(Configuration.Verisense.SENSOR_ID.LSM6DSV_ACCEL)) {
 			return true;
 		}
 		return false;
 	}
 
 	public static boolean isSensorKeyAnAccel(SENSORS sensorClassKey) {
-		if(sensorClassKey==SENSORS.LIS2DW12 || sensorClassKey==SENSORS.LSM6DS3) {
+		if(sensorClassKey==SENSORS.LIS2DW12 || sensorClassKey==SENSORS.LSM6DS3 || sensorClassKey==SENSORS.LSM6DSV) {
 			return true;
 		}
 		return false;
@@ -1623,6 +1637,11 @@ public int calculateFifoBlockSize(SENSORS sensorClassKey) {
 			default:
 				break;
 		}
+		if(dataBlockSize==Integer.MIN_VALUE) {
+			// Fail loudly rather than returning a sentinel that silently corrupts the
+			// data-block byte index further down the parse.
+			throw new IllegalStateException("calculateFifoBlockSize: no FIFO block size defined for sensor class " + sensorClassKey);
+		}
 		return dataBlockSize;
 	}
 
@@ -1861,8 +1880,13 @@ public DataBlockDetails parseDataBlockMetaData(byte[] byteBuffer, int dataBlockS
 
 		DataBlockDetails dataBlockDetails = null;
 		DATABLOCK_SENSOR_ID[] payloadSensorIdValues = DATABLOCK_SENSOR_ID.values();
-		// -1 because PPG_MAX86150 has been temporarily added to PAYLOAD_SENSOR_ID 
-		if(sensorId>0 && sensorId<payloadSensorIdValues.length-1) {
+		// Only IDs with a parse implementation are accepted. The enum intentionally
+		// declares the remaining second-generation block IDs (LIGHT, ALGO_HUB,
+		// SKIN_TEMP, FLICKER) ahead of their parser support - accepting them here
+		// without a getSensorKeysForDatablockId()/calculateFifoBlockSize() handler
+		// would corrupt the parse, so they are rejected with the informative
+		// exception below until their decoders are implemented.
+		if(sensorId>0 && sensorId<=DATABLOCK_SENSOR_ID.LSM6DSV.ordinal()) {
 			DATABLOCK_SENSOR_ID datablockSensorId = payloadSensorIdValues[sensorId];
 
 			List<SENSORS> listOfSensorClassKeys = getOrCreateListOfSensorClassKeysForDataBlockId(datablockSensorId);

ShimmerDriver/src/main/java/com/shimmerresearch/verisense/payloaddesign/DataBlockDetails.java

@@ -53,6 +53,15 @@ public enum DATABLOCK_SENSOR_ID {
 	private VerisenseTimeDetails timeDetailsUcClock = new VerisenseTimeDetails();
 
 	public int qtySensorDataBytesInDatablock;
+	/**
+	 * The raw on-disk sensor-data byte length as parsed from the payload. Unlike
+	 * {@link #qtySensorDataBytesInDatablock} this is never recomputed by the
+	 * midday/midnight CSV-split logic ({@link #setSampleCountAndUpdateDataBlockSize(int)})
+	 * - essential for variable-length blocks (e.g. the LSM6DSV tagged FIFO, whose raw
+	 * length includes timestamp-tag and magnetometer entries that don't map 1:1 to
+	 * aligned samples). Always use this for advancing byte offsets through the payload.
+	 */
+	private int qtySensorDataBytesInDatablockRaw;
 	public int dataPacketSize;
 	private double samplingRate;
 
@@ -102,10 +111,15 @@ public DataBlockDetails(DATABLOCK_SENSOR_ID datablockSensorId, int payloadIndex,
 
 	public void setMetadata(int dataBlockSizeSensorData, int dataPacketSize, double samplingRate) {
 		this.qtySensorDataBytesInDatablock = dataBlockSizeSensorData;
+		this.qtySensorDataBytesInDatablockRaw = dataBlockSizeSensorData;
 		this.dataPacketSize = dataPacketSize;
 		setSamplingRate(samplingRate);
 		calculateSampleCount();
 	}
+
+	public int getQtySensorDataBytesInDatablockRaw() {
+		return qtySensorDataBytesInDatablockRaw;
+	}
 
 	public void setRwcEndTimeMinutesAndCalculateTimings(long rtcEndTimeMinutes) {
 		setUcClockOrRwcClockEndTimeMinutesAndCalculateTimings(rtcEndTimeMinutes, false);

ShimmerDriver/src/main/java/com/shimmerresearch/verisense/payloaddesign/PayloadContentsDetailsV8orAbove.java

@@ -57,7 +57,10 @@ public void parsePayloadContentsMetaData(int binFileByteIndex) throws IOExceptio
 			setOfPayloadSensorIds.add(dataBlockDetails.datablockSensorId);
 
 			// Update byte offset as it's passed by value into "parseDataBlockMetaData"
-			int dataBlockTotalSize = BYTE_COUNT.PAYLOAD_CONTENTS_GEN8_SENSOR_ID + BYTE_COUNT.PAYLOAD_CONTENTS_RTC_BYTES_TICKS + dataBlockDetails.qtySensorDataBytesInDatablock;  
+			// Use the RAW block size for byte-offset arithmetic - qtySensorDataBytesInDatablock
+			// can be recomputed by the midday/midnight split logic (wrongly for
+			// variable-length blocks such as the LSM6DSV tagged FIFO).
+			int dataBlockTotalSize = BYTE_COUNT.PAYLOAD_CONTENTS_GEN8_SENSOR_ID + BYTE_COUNT.PAYLOAD_CONTENTS_RTC_BYTES_TICKS + dataBlockDetails.getQtySensorDataBytesInDatablockRaw();
 			currentByteIndexInPayload += dataBlockTotalSize;
 
 			if(isParserAtEndOfBuffer(byteBuffer.length, currentByteIndexInPayload)) {
@@ -407,7 +410,8 @@ public void parsePayloadSensorData() {
 				if(dataBlockDetails.listOfSensorClassKeys.contains(sensorClassKey)) {
 					verisenseDevice.parseDataBlockData(dataBlockDetails, byteBuffer, currentByteIndex, COMMUNICATION_TYPE.SD);
 				}
-				currentByteIndex += dataBlockDetails.qtySensorDataBytesInDatablock;
+				// RAW size: immune to midday/midnight split recomputation (see above)
+				currentByteIndex += dataBlockDetails.getQtySensorDataBytesInDatablockRaw();
 
 				dataBlockIndex++;
 

ShimmerDriver/src/main/java/com/shimmerresearch/verisense/sensors/SensorBattVoltageVerisense.java

@@ -262,6 +262,10 @@ public ObjectCluster processDataCustom(SensorDetails sensorDetails, byte[] rawDa
 						mShimmerDevice.getShimmerVerObject().getHardwareVersion(), mShimmerDevice.getExpansionBoardRev())) {
 					// Second-generation hardware (SR61-5/6, SR68-9/10) battery-sense divider.
 					// Matches the firmware's own conversion in hal_asm_battery.c (measureBatteryVoltage).
+					// Deliberately gated on the HARDWARE revision (not isPayloadDesignV13orAbove):
+					// the divider is a property of the board's battery-sense circuit, present
+					// regardless of which firmware happens to be flashed - the firmware applies
+					// the same hardware-keyed rule.
 					calData *= BATTERY_VOLTAGE_DIVIDER_RATIO_GEN2;
 				}
 				objectCluster.addCalData(channelDetails, calData, objectCluster.getIndexKeeper()-1);

ShimmerDriver/src/main/java/com/shimmerresearch/verisense/sensors/SensorLSM6DSV.java

@@ -241,12 +241,15 @@ public static final class DatabaseConfigHandle {
 	public static final double[][] SENS_ACCEL_8G  = {{417.6759,0,0},{0,417.6759,0},{0,0,417.6759}};
 	public static final double[][] SENS_ACCEL_16G = {{208.8379,0,0},{0,208.8379,0},{0,0,208.8379}};
 
-	// Gyro sensitivity (LSB per dps) = 32768/FS_dps
-	public static final double[][] SENS_GYRO_125DPS  = {{262.144,0,0},{0,262.144,0},{0,0,262.144}};
-	public static final double[][] SENS_GYRO_250DPS  = {{131.072,0,0},{0,131.072,0},{0,0,131.072}};
-	public static final double[][] SENS_GYRO_500DPS  = {{65.536,0,0},{0,65.536,0},{0,0,65.536}};
-	public static final double[][] SENS_GYRO_1000DPS = {{32.768,0,0},{0,32.768,0},{0,0,32.768}};
-	public static final double[][] SENS_GYRO_2000DPS = {{16.384,0,0},{0,16.384,0},{0,0,16.384}};
+	// Gyro sensitivity (LSB per dps) from the ST datasheet angular-rate sensitivity
+	// (4.375 mdps/LSB at +-125 dps, doubling per range) - the same spec/values as the
+	// gen-1 LSM6DS3. NOTE: the gyro does NOT span the full 16-bit range at its nominal
+	// full scale (unlike the accel), so a 32768/FS derivation is ~12.8% off.
+	public static final double[][] SENS_GYRO_125DPS  = {{228.571428571,0,0},{0,228.571428571,0},{0,0,228.571428571}};
+	public static final double[][] SENS_GYRO_250DPS  = {{114.285714286,0,0},{0,114.285714286,0},{0,0,114.285714286}};
+	public static final double[][] SENS_GYRO_500DPS  = {{57.142857143,0,0},{0,57.142857143,0},{0,0,57.142857143}};
+	public static final double[][] SENS_GYRO_1000DPS = {{28.571428571,0,0},{0,28.571428571,0},{0,0,28.571428571}};
+	public static final double[][] SENS_GYRO_2000DPS = {{14.285714286,0,0},{0,14.285714286,0},{0,0,14.285714286}};
 
 	// Mag sensitivity (LSB per uT) = 1/0.15
 	public static final double[][] SENS_MAG = {{6.666667,0,0},{0,6.666667,0},{0,0,6.666667}};