diff --git a/docs/quale-iface-apis.md b/docs/quale-iface-apis.md new file mode 100644 index 0000000..e50d2b2 --- /dev/null +++ b/docs/quale-iface-apis.md @@ -0,0 +1,146 @@ +# Quale Interface APIs (QualeIface APIs) + +## Overview + +QualeIface APIs are libraries that connect to particular stim buffers and allow the mind to process the stim features presented in the device's stim buffers. They provide the interface between raw device data and the mind's processing capabilities. + +## Universally Understood Parameters + +The following parameters are universally understood across all QualeIface API implementations. + +### `history-buffer-duration-ms` / `hist-buff-duration-ms` / `histbuff-duration-ms` / `histbuff-ms` + +**Synonyms:** +- `history-buffer-duration-ms` +- `hist-buff-duration-ms` +- `histbuff-duration-ms` +- `histbuff-ms` + +**Description:** +This parameter determines how long the history of the particular StimBuff being attached to the DAP spec's device role will be. The value is specified in milliseconds and determines the duration of historical data that will be maintained in the stimulus buffer. + +**Specification:** +- The parameter is specified as part of the `quale-iface-api-params` in the DAP specification +- The value is an integer representing milliseconds +- If multiple synonyms are specified, the lattermost (last encountered) synonym takes precedence +- If not specified, a default value of 30000ms (30 seconds) is used + +**Example:** +``` ++edev|my-device|visual-qualeiface(histbuff-ms=60000)|v4l()|linux()|/dev/video0 +``` + +This example sets the history buffer duration to 60000ms (60 seconds). + +**Note:** +This parameter is specific to each stimbuff/deviceRole combination. Different device roles can have different history buffer durations based on their requirements. + +## Overview + +QualeIface APIs are interface libraries that connect to particular stim buffers and allow the mind to process the stim features presented in the device's stim buffers. They provide the interface between raw device data and the mind's processing capabilities. + +## Universally Understood QualeIface API Parameters + +This document describes quale-iface-api-params that are universally understood across all QualeIface implementations. + +### history-buffer-duration-ms / hist-buff-duration-ms / histbuff-duration-ms / histbuff-ms + +**Purpose:** Determines how long the history of the particular StimBuff being attached to the DAP spec's device role will be. + +**Synonyms:** +- `history-buffer-duration-ms` (full canonical name) +- `hist-buff-duration-ms` (abbreviated) +- `histbuff-duration-ms` (shortened) +- `histbuff-ms` (shortest) + +**Type:** Integer (milliseconds) + +**Scope:** Specific to each stimbuff/deviceRole. Each device attachment can specify its own history buffer duration independently. + +**Default:** If not specified, implementations typically use a default value (commonly 30000ms = 30 seconds). + +**Usage:** The value specifies the duration in milliseconds for which stimulus frames will be retained in the history buffer. This affects how many slots are allocated in the ring buffer: `nSlots = histbuffMs / CONFIG_STIMBUFF_FRAME_PERIOD_MS`. + +**Example:** +``` ++edev|my-camera|visual-qualeiface(histbuff-ms=60000)|v4l()|linux()|/dev/video0 +``` + +This example sets a 60-second history buffer duration for the visual qualeiface processing the camera's point cloud data. + +**Notes:** +- If multiple synonyms are specified in the same parameter list, the lattermost one takes precedence +- The parameter is parsed from the `quale-iface-api-params` section of the DAP specification +- This parameter is specific to each device attachment, allowing different devices to have different history durations + + +This document describes universally understood quale-iface-api-params that can be used across different QualeIface implementations. + +## history-buffer-duration-ms + +### Synonyms +The `history-buffer-duration-ms` parameter can be specified using any of the following names: +- `history-buffer-duration-ms` (full form) +- `hist-buff-duration-ms` (abbreviated) +- `histbuff-duration-ms` (abbreviated, no dashes) +- `histbuff-ms` (shortest form) + +### Description +The `history-buffer-duration-ms` parameter determines how long the history of the particular StimBuff being attached to the DAP spec's device role will be. This value specifies the duration in milliseconds for which stimulus frame history will be maintained in the buffer. + +### Usage +This parameter is **specific to each stimbuff/deviceRole**. Each device attachment can have its own history buffer duration, allowing fine-grained control over memory usage and history retention for different sensor types. + +### Example +``` ++edev|my-camera|visual-qualeiface(histbuff-ms=30000)|v4l()|linux()|/dev/video0 +``` + +This example sets a 30-second history buffer for the camera device's stimulus buffer. + +### Default Value +If not specified, the default value is **30000 milliseconds (30 seconds)**. + +### Notes +- The parameter value should be specified as an integer representing milliseconds +- Later synonyms in the parameter list will override earlier ones if multiple are specified +- The actual number of buffer slots allocated will be calculated based on this duration divided by the frame period (CONFIG_STIMBUFF_FRAME_PERIOD_MS) + + +This document describes universally understood parameters that can be used in quale-iface-api-params for device attachment specifications. + +## history-buffer-duration-ms + +**Synonyms:** +- `history-buffer-duration-ms` +- `hist-buff-duration-ms` +- `histbuff-duration-ms` +- `histbuff-ms` + +**Description:** + +The `history-buffer-duration-ms` parameter determines how long the history of the particular StimBuff being attached to the DAP spec's device role will be. This parameter is specific to each stimbuff/deviceRole combination. + +**Usage:** + +This parameter specifies the duration in milliseconds for which historical stimulus frame data will be retained in the buffer. The value determines the number of frames that can be stored, based on the frame period configured for the stimulus buffer. + +**Example:** + +``` ++edev|avia0|structural-qualeiface(histbuff-ms=60000)|livoxGen1()|livoxProto1()|3JEDK380010Z39 +``` + +This example sets the history buffer duration to 60000ms (60 seconds) for the avia0 device. + +**Default Value:** + +If not specified, the default value is 30000ms (30 seconds). + +**Notes:** + +- The parameter value should be specified in milliseconds +- Multiple synonyms can be used, with later synonyms in the parameter list taking precedence +- This parameter is parsed from the quale-iface-api-params, not from stim-buff-api-params or provider-params +- The actual number of buffer slots is calculated as: `histbuffMs / CONFIG_STIMBUFF_FRAME_PERIOD_MS` + diff --git a/stimBuffApis/livoxGen1/livoxGen1.cpp b/stimBuffApis/livoxGen1/livoxGen1.cpp index 352a62d..a98433e 100644 --- a/stimBuffApis/livoxGen1/livoxGen1.cpp +++ b/stimBuffApis/livoxGen1/livoxGen1.cpp @@ -178,11 +178,36 @@ public: return; } + // Parse history buffer duration from quale-iface-api-params + int histbuffMs = 30000; // Default: 30000ms (30 seconds) + const std::vector histbuffParamNames = { + "history-buffer-duration-ms", + "hist-buff-duration-ms", + "histbuff-duration-ms", + "histbuff-ms" + }; + + // Loop through synonyms in reverse order; lattermost synonym wins. + for (auto synIt = histbuffParamNames.rbegin(); + synIt != histbuffParamNames.rend(); ++synIt) + { + const auto& paramName = *synIt; + try { + histbuffMs = smo::device::DeviceAttachmentSpec + ::parseRequiredParamAsInt( + context->spec->qualeIfaceApiParams, paramName); + break; // Found and parsed successfully + } catch (const std::exception&) { + // Parameter not found or parse error, continue to next synonym + continue; + } + } + // Create and add PcloudStimulusBuffer to collection now that device is ready StimulusBuffer::PcloudFormatDesc formatDesc; formatDesc.format = StimulusBuffer::PcloudFormatDesc::Format::XYZI; auto pcloudStimBuff = std::make_shared( - *context->spec, context->deviceTmp, formatDesc, 30); + *context->spec, context->deviceTmp, formatDesc, histbuffMs, 30); context->stimBuff = pcloudStimBuff; context->deviceTmp->nAttachedStimBuffs++; diff --git a/stimBuffApis/livoxGen1/pcloudStimulusBuffer.cpp b/stimBuffApis/livoxGen1/pcloudStimulusBuffer.cpp index 251f21f..2351013 100644 --- a/stimBuffApis/livoxGen1/pcloudStimulusBuffer.cpp +++ b/stimBuffApis/livoxGen1/pcloudStimulusBuffer.cpp @@ -17,10 +17,11 @@ PcloudStimulusBuffer::PcloudStimulusBuffer( const device::DeviceAttachmentSpec& deviceAttachmentSpec, std::shared_ptr &device, const PcloudFormatDesc& formatDesc, + int histbuffMs, size_t nDgramsPerStagingBufferFrame) : StimulusBuffer( deviceAttachmentSpec, - static_cast((1000 * 30) / CONFIG_STIMBUFF_FRAME_PERIOD_MS), + static_cast(histbuffMs / CONFIG_STIMBUFF_FRAME_PERIOD_MS), openClInputConstraints, device->componentThread->getIoService()), deviceAttachmentSpec(deviceAttachmentSpec), device(device), diff --git a/stimBuffApis/livoxGen1/pcloudStimulusBuffer.h b/stimBuffApis/livoxGen1/pcloudStimulusBuffer.h index 2963143..03043b0 100644 --- a/stimBuffApis/livoxGen1/pcloudStimulusBuffer.h +++ b/stimBuffApis/livoxGen1/pcloudStimulusBuffer.h @@ -26,6 +26,7 @@ public: const device::DeviceAttachmentSpec& deviceAttachmentSpec, std::shared_ptr &device, const PcloudFormatDesc& formatDesc, + int histbuffMs, size_t nDgramsPerStagingBufferFrame); ~PcloudStimulusBuffer() = default;