DEV-793 Add VD6283 ambient-light decoder (data-block id 7)

First Phase-C gen-2 sensor: the VD6283TX45 ambient light. Data block = fixed 10 samples x 18 bytes (6 channels x 24-bit LE, order RED/VISIBLE/BLUE/GREEN/IR/CLEAR - the firmware only emits full blocks, partials are discarded on stop), so it rides the generic fixed-size block path. New SensorVD6283 ports the firmware App_vd6283tx.c conversions (and matches the web SDK's SensorVD6283.ts): UNCAL = raw counts, CAL = gain/exposure-normalised counts plus derived Lux (XYZ Y) and CCT (McCamy). Gain/exposure/dark-channel parsed from payload header bytes 30/31; enable from GEN_CFG_3 bit 3.

The light sample rate is NOT stored in the payload header and the achieved rate differs from both the configured rate and 1/exposure (per-measurement dead time, e.g. ~110 ms at the 100 ms exposure), so PayloadContentsDetailsV8orAbove derives it per payload from the median inter-light-block tick spacing before block timings are back-filled; the exposure-limited estimate seeds blocks when a payload has fewer than two light blocks. Metadata guard widened to accept id 7 (ALGO_HUB/SKIN_TEMP/FLICKER still fail loudly). Slot-1 visible-vs-dark is recorded in the CSV sensor-config line ('Slot1 = Visible|Dark'); the column name stays Light_Visible until a dark-enabled recording exists.

Hand-verified against the spec formulas on the first real light recording (DEV-793 2026-07-27, SR61-5 unit AF6A): normalized RED 278.586 and Lux 207.586 match manual computation exactly; 290 parsed rows = 29 blocks x 10 samples; derived rate 9.209 Hz. Full ASM_PC_00005 suite green.

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

Author: marknolan

ShimmerDriver/src/main/java/com/shimmerresearch/driver/Configuration.java

@@ -2647,6 +2647,8 @@ public class SensorBitmap {
 			public static final int LSM6DSV_ACCEL			= 1 << (4 + (8*0));
 			public static final int LSM6DSV_GYRO			= 1 << (3 + (8*0));
 			public static final int LSM6DSV_MAG				= 1 << (2 + (8*0));
+			/** VD6283TX45 ambient light (second-generation HW); enable is GEN_CFG_3 bit 3. */
+			public static final int VD6283					= 1 << (1 + (8*0));
 		}
 
 		public class DerivedSensorsBitMask {
@@ -2682,6 +2684,7 @@ public class SENSOR_ID {
 			public static final int LSM6DSV_ACCEL			= 2015;
 			public static final int LSM6DSV_GYRO			= 2016;
 			public static final int LSM6DSV_MAG				= 2017;
+			public static final int VD6283					= 2018;
 		}
 
 		public enum LABEL_SENSOR_TILE{

ShimmerDriver/src/main/java/com/shimmerresearch/sensors/AbstractSensor.java

@@ -68,6 +68,7 @@ public enum SENSORS{
 		LIS3MDL("LIS3MDL"), //to be changed
 		LIS2MDL("LIS2MDL"),
 		LSM6DSV("LSM6DSV"),
+		VD6283("VD6283"),
 		BMP390("BMP390");
 
 	    private final String text;

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

@@ -66,6 +66,7 @@
 import com.shimmerresearch.verisense.sensors.SensorLIS2DW12;
 import com.shimmerresearch.verisense.sensors.SensorLSM6DS3;
 import com.shimmerresearch.verisense.sensors.SensorLSM6DSV;
+import com.shimmerresearch.verisense.sensors.SensorVD6283;
 import com.shimmerresearch.verisense.sensors.SensorMAX86150;
 import com.shimmerresearch.verisense.sensors.SensorMAX86916;
 import com.shimmerresearch.verisense.sensors.SensorMAX86XXX;
@@ -587,6 +588,7 @@ public void configBytesParse(byte[] configBytes, COMMUNICATION_TYPE commType) {
 			if((gen2Cfg0 & (1<<5))!=0) { enabledSensors |= Configuration.Verisense.SensorBitmap.LSM6DSV_GYRO; }
 			int gen2GenCfg3 = configBytes[PAYLOAD_CONFIG_BYTE_INDEX.GEN_CFG_3] & 0xFF;
 			if((gen2GenCfg3 & (1<<2))!=0) { enabledSensors |= Configuration.Verisense.SensorBitmap.LSM6DSV_MAG; }
+			if((gen2GenCfg3 & (1<<3))!=0) { enabledSensors |= Configuration.Verisense.SensorBitmap.VD6283; }
 		}
 		setEnabledAndDerivedSensorsAndUpdateMaps(enabledSensors, mDerivedSensors, commType);
 
@@ -1056,6 +1058,32 @@ && isAnyLsm6dsvChannelEnabled()) {
 			sb.append(SENSOR_CONFIG_STRINGS.RESOLUTION);
 			sb.append("16-bit");
 			sb.append("}");
+		} else if(sensorClassKey==AbstractSensor.SENSORS.VD6283
+				&& isSensorEnabled(Configuration.Verisense.SENSOR_ID.VD6283)) {
+			// Second-generation ambient light. The configured sample rate isn't stored
+			// in the payload header, so only the calculated (achieved) rate is reported.
+			SensorVD6283 sensorVd6283 = getSensorVD6283();
+
+			sb.append(sensorClassKey.toString());
+			sb.append(" {Sampling Rate [");
+			sb.append(SENSOR_CONFIG_STRINGS.SAMPLING_RATE_CALCULATED);
+			if(!Double.isNaN(calculatedSamplingRate)) {
+				sb.append(UtilVerisenseDriver.formatDoubleToNdecimalPlaces(calculatedSamplingRate, 3));
+				sb.append(" ");
+				sb.append(CHANNEL_UNITS.FREQUENCY);
+			} else {
+				sb.append(UtilVerisenseDriver.UNAVAILABLE);
+			}
+			sb.append("]; Gain = ");
+			sb.append(UtilVerisenseDriver.formatDoubleToNdecimalPlaces(sensorVd6283.getGain(), 2));
+			sb.append("x; Exposure = ");
+			sb.append(UtilVerisenseDriver.formatDoubleToNdecimalPlaces(sensorVd6283.getExposureUs()/1000.0, 1));
+			sb.append(" ms; Slot1 = ");
+			sb.append(sensorVd6283.isDarkChannelEnabled() ? "Dark" : "Visible");
+			sb.append("; ");
+			sb.append(SENSOR_CONFIG_STRINGS.RESOLUTION);
+			sb.append("24-bit");
+			sb.append("}");
 		} else if(LIST_OF_PPG_SENSORS.contains(sensorClassKey) && isHwPpgAndAnyMaxChEnabled()) {
 			AbstractSensor abstractSensor = getAbstractSensorPpg();
 			if(abstractSensor!=null) {
@@ -1360,6 +1388,8 @@ public void sensorAndConfigMapsCreate() {
 		if(isPayloadDesignV13orAbove()) {
 			// Second-generation IMU (LSM6DSV accel/gyro + LIS2MDL mag via sensor hub)
 			addSensorClass(SENSORS.LSM6DSV, new SensorLSM6DSV(this));
+			// Second-generation ambient light
+			addSensorClass(SENSORS.VD6283, new SensorVD6283(this));
 		} else if(doesHwSupportLsm6ds3()) {
 			addSensorClass(SENSORS.LSM6DS3, new SensorLSM6DS3(this));
 		}
@@ -1573,6 +1603,9 @@ public List<SENSORS> getSensorKeysForDatablockId(DATABLOCK_SENSOR_ID datablockSe
 			case LSM6DSV:
 				listOfSensorIds.add(SENSORS.LSM6DSV);
 				break;
+			case LIGHT:
+				listOfSensorIds.add(SENSORS.VD6283);
+				break;
 			case PPG:
 				SENSORS sensorClassKey = getPpgSensorClassKey();
 				if(sensorClassKey!=null) {
@@ -1594,6 +1627,11 @@ public int calculateFifoBlockSize(SENSORS sensorClassKey) {
 			case LIS2DW12:
 				dataBlockSize = SensorLIS2DW12.FIFO_SIZE_IN_CHIP;
 				break;
+			case VD6283:
+				// Fixed-size block: the firmware only emits FULL blocks of
+				// NUM_LIGHT_SAMPLES_PER_BLOCK samples (partials are discarded on stop).
+				dataBlockSize = SensorVD6283.BLOCK_DATA_BYTES;
+				break;
 			case LSM6DS3:
 				AbstractSensor abstractSensor = getSensorClass(SENSORS.LSM6DS3);
 				if(abstractSensor!=null) {
@@ -1886,7 +1924,7 @@ public DataBlockDetails parseDataBlockMetaData(byte[] byteBuffer, int dataBlockS
 		// 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()) {
+		if(sensorId>0 && sensorId<=DATABLOCK_SENSOR_ID.LIGHT.ordinal()) {
 			DATABLOCK_SENSOR_ID datablockSensorId = payloadSensorIdValues[sensorId];
 
 			List<SENSORS> listOfSensorClassKeys = getOrCreateListOfSensorClassKeysForDataBlockId(datablockSensorId);
@@ -2328,6 +2366,14 @@ public SensorLSM6DSV getSensorLSM6DSV() {
 		return null;
 	}
 
+	public SensorVD6283 getSensorVD6283() {
+		AbstractSensor abstractSensor = getSensorClass(SENSORS.VD6283);
+		if(abstractSensor!=null && abstractSensor instanceof SensorVD6283) {
+			return (SensorVD6283) abstractSensor;
+		}
+		return null;
+	}
+
 	/**
 	 * @return Null if sensor not supported by current hardware
 	 * @see SensorGSRVerisense

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

@@ -42,6 +42,11 @@ public class PAYLOAD_CONFIG_BYTE_INDEX {
 		// Second-generation (payload design v13) only: GEN_CFG_3 at abs byte 29 (rel 25)
 		// carries the mag/light/skin-temp/algo-hub enables + LED mode.
 		public static final int GEN_CFG_3 = 25;
+		/** Second-generation only: ambient-light gain index in bits 2:0 and the
+		 * dark-channel enable in bit 7 (abs byte 30). */
+		public static final int LIGHT_GAIN_AND_DARK = 26;
+		/** Second-generation only: ambient-light exposure index (abs byte 31). */
+		public static final int LIGHT_EXPOSURE = 27;
 	}
 
 	public class BYTE_COUNT {

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

@@ -2,6 +2,7 @@
 
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.ListIterator;
 import java.util.Map.Entry;
@@ -92,6 +93,12 @@ public void parsePayloadContentsMetaData(int binFileByteIndex) throws IOExceptio
 
 		// --------- End of parsing ------------------
 
+		// The ambient-light sample rate isn't stored in the payload header (only
+		// gain/exposure are) and the achieved rate differs from both the configured
+		// rate and 1/exposure (per-measurement dead time), so refine it from the
+		// data itself before the block timings are back-filled below.
+		refineLightSamplingRateFromBlockTicks();
+
 		// Up to, and including, payload design v10, the real-world clock time that was
 		// stored in the payload footer was the real-world time at the end of the
 		// payload. From payload design v11 onwards, the real-world clock offset is
@@ -306,6 +313,59 @@ private boolean isParserAtEndOfBuffer(int bufferLength, int currentByteIndex) {
 		return (bufferLength-currentByteIndex)<(footerLength+BYTE_COUNT.PAYLOAD_CRC);
 	}
 
+	/**
+	 * Derive the achieved ambient-light sample period from the spacing of
+	 * consecutive light-block end ticks and apply it to the light blocks' sampling
+	 * rate before their timings are back-filled. The light sample rate cannot be
+	 * read from the stored payload header (see SensorVD6283.getRateFreq), and each
+	 * light block holds a fixed number of samples, so
+	 * {@code inter-block ticks / samples-per-block} is the exact per-sample period.
+	 * With fewer than two light blocks in the payload the exposure-limited
+	 * estimate the blocks were created with is left in place.
+	 */
+	private void refineLightSamplingRateFromBlockTicks() {
+		List<DataBlockDetails> lightBlocks = new ArrayList<DataBlockDetails>();
+		for(DataBlockDetails dataBlockDetails:listOfDataBlocksInOrder) {
+			if(dataBlockDetails.datablockSensorId==DATABLOCK_SENSOR_ID.LIGHT) {
+				lightBlocks.add(dataBlockDetails);
+			}
+		}
+		if(lightBlocks.size()<2) {
+			return;
+		}
+
+		// v11+ payloads store microcontroller-clock ticks per block, earlier designs
+		// store real-world-clock ticks; either works as only deltas are used.
+		boolean useUcClockTicks = verisenseDevice.isPayloadDesignV11orAbove();
+		List<Double> perSamplePeriodsS = new ArrayList<Double>();
+		for(int i=1;i<lightBlocks.size();i++) {
+			VerisenseTimeDetails prev = useUcClockTicks? lightBlocks.get(i-1).getTimeDetailsUcClock():lightBlocks.get(i-1).getTimeDetailsRwc();
+			VerisenseTimeDetails curr = useUcClockTicks? lightBlocks.get(i).getTimeDetailsUcClock():lightBlocks.get(i).getTimeDetailsRwc();
+			// 3-byte tick counter at 32768 Hz; handle wrap (every ~512 s, far above the
+			// ~1 s light-block cadence).
+			long deltaTicks = (curr.getEndTimeTicks() - prev.getEndTimeTicks()) & 0xFFFFFF;
+			int sampleCount = lightBlocks.get(i).getSampleCount();
+			if(deltaTicks>0 && sampleCount>0) {
+				perSamplePeriodsS.add((deltaTicks/32768.0)/sampleCount);
+			}
+		}
+		if(perSamplePeriodsS.isEmpty()) {
+			return;
+		}
+		// Median so a dropped block (a 2x gap) can't skew the period.
+		Collections.sort(perSamplePeriodsS);
+		double medianPeriodS = perSamplePeriodsS.get(perSamplePeriodsS.size()/2);
+		if(!(medianPeriodS>0)) {
+			return;
+		}
+
+		double achievedRateHz = 1.0/medianPeriodS;
+		for(DataBlockDetails dataBlockDetails:lightBlocks) {
+			dataBlockDetails.setSamplingRate(achievedRateHz);
+			dataBlockDetails.calculateTimestampDiffInS();
+		}
+	}
+
 	private void backfillDataBlockRwcTimestamps() {
 		backfillDataBlockUcClockOrRwcTimestamps(false);
 	}