livoxGen1: add n-dgrams-per-frame param

docs/livox-gen1-lidar-dap-spec.md

@@ -40,6 +40,11 @@ Each stim-buff-api is designed to work with specific stim-iface libraries that u
 +edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
 ```
 
+**Example with n-dgrams-per-frame parameter**:
+```
++edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10,n-dgrams-per-frame=30) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
+```
+
 **Alternative Format Examples**:
 ```
 +edev | avia0 | pcloud(format=spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(command-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39
@@ -142,9 +147,10 @@ The `livoxProto1` provider accepts the following parameters:
 
 Each stim-buff-api accepts device-specific parameters:
 
-| Parameter | Description | Example |
+| Parameter | Description | Default | Example |
-|-----------|-------------|---------|
+|-----------|-------------|---------|---------|
-| `data-rate-hz` | Data sampling rate in Hz | `data-rate-hz=10` |
+| `data-rate-hz` | Data sampling rate in Hz | - | `data-rate-hz=10` |
+| `n-dgrams-per-frame` / `num-dgrams-per-frame` | Number of UDP datagrams per staging buffer frame | 30 | `n-dgrams-per-frame=30` or `num-dgrams-per-frame=30` |
 
 ### Quale-Iface-API Parameters
 

stimBuffApis/livoxGen1/livoxGen1.cpp

@@ -109,6 +109,35 @@ static int parseHistbuffMs(
 	return histbuffMs;
 }
 
+// Helper function to parse n-dgrams-per-frame from stim-buff-api params
+static size_t parseNDgramsPerFrame(
+	const std::shared_ptr<smo::device::DeviceAttachmentSpec>& spec)
+{
+	size_t nDgramsPerFrame = 30;  // Default: 30 datagrams per frame
+	const std::vector<std::string> nDgramsPerFrameParamNames = {
+		"n-dgrams-per-frame",
+		"num-dgrams-per-frame"
+	};
+
+	// Loop through synonyms in reverse order; lattermost synonym wins.
+	for (auto synIt = nDgramsPerFrameParamNames.rbegin();
+		synIt != nDgramsPerFrameParamNames.rend(); ++synIt)
+	{
+		const auto& paramName = *synIt;
+		try {
+			nDgramsPerFrame = static_cast<size_t>(
+				smo::device::DeviceAttachmentSpec::parseRequiredParamAsInt(
+					spec->stimBuffApiParams, paramName));
+			break; // Found and parsed successfully
+		} catch (const std::exception&) {
+			// Parameter not found or parse error, continue to next synonym
+			continue;
+		}
+	}
+
+	return nDgramsPerFrame;
+}
+
 // LivoxProto1DllState constructor implementation
 LivoxProto1DllState::LivoxProto1DllState()
 : dlopenHandle(nullptr, DlCloser),
@@ -282,8 +311,11 @@ public:
 		formatDesc.format = PcloudStimulusProducer::PcloudFormatDesc::Format
 			::XYZI;
 
+		// Parse n-dgrams-per-frame from stim-buff-api params (default: 30)
+		size_t nDgramsPerFrame = parseNDgramsPerFrame(context->spec);
+
 		auto pcloudDataProducer = std::make_shared<PcloudStimulusProducer>(
-			context->spec, context->deviceTmp, formatDesc, 30);
+			context->spec, context->deviceTmp, formatDesc, nDgramsPerFrame);
 
 		context->stimProducer = pcloudDataProducer;
 		context->deviceTmp->nAttachedStimulusProducers++;