ARRUS-84: expose DTGC, LPF, ActiveTermination, PGA, LNA parameters in…

… C++ interface. (#232)

api/python/arrus/utils/imaging.py

@@ -1146,12 +1146,12 @@ def __init__(self, queue, block=True, ignore_full=False):
         self.block = block
         self.ignore_full = ignore_full
         if self.block:
-            self._process = self._put_block
+            self.process = self._put_block
         else:
             if self.ignore_full:
-                self._process = self._put_ignore_full
+                self.process = self._put_ignore_full
             else:
-                self._process = self._put_non_block
+                self.process = self._put_non_block
         self._copy_func = None
 
     def set_pkgs(self, num_pkg, **kwargs):

arrus/common/asserts.h

@@ -72,7 +72,7 @@ do {                                                      \
 } while(0)
 
 /**
- * Check if A >= B, otherwise throws arrus::IllegalArgumentException.
+ * Check if value in range [min, max], otherwise throws arrus::IllegalArgumentException.
  */
 #define ARRUS_REQUIRES_IN_CLOSED_INTERVAL(value, min, max, MSG) \
 do {                                                      \

arrus/core/CMakeLists.txt

@@ -180,7 +180,8 @@ set(SRC_FILES
     ../common/logging/impl/LogSeverity.cpp
     api/arrus.h
     api/session.h
-    api/common.h api/io.h)
+    api/common.h api/io.h
+        devices/us4r/validators/RxSettingsValidator.h)
 
 set_source_files_properties(${SRC_FILES} PROPERTIES COMPILE_FLAGS
     "${ARRUS_CPP_STRICT_COMPILE_OPTIONS}")

arrus/core/api/devices/us4r/ProbeAdapter.h

@@ -20,8 +20,6 @@ class ProbeAdapter : public Device {
 
     [[nodiscard]] virtual ChannelIdx getNumberOfChannels() const = 0;
 
-    virtual void setTgcCurve(const std::vector<float> &curve) = 0;
-
 protected:
     explicit ProbeAdapter(const DeviceId &id): Device(id) {}
 };

arrus/core/api/devices/us4r/RxSettings.h

@@ -10,18 +10,53 @@
 
 namespace arrus::devices {
 
+/*
+ * AFE (RX) settings.
+ *
+ * Us4R AFE settings currently includes:
+ * - DTGC attenuation, available: 0, 6, 12, 18, 24, 30, 36, 42 [dB] or std::nullopt; nullopt turns off DTGC.
+ * - LNA gain, available: 12, 18, 24 [dB].
+ * - PGA gain, available: 24, 30 [dB].
+ * - TGC samples: analog TGC curve samples [dB]. Up to 1022 samples. TGC samples should be in range
+ *   [min, max](closed interval) where min = (lna gain + pga gain)-40, and max = (lna gain, pga gain).
+ *   Empty list turns off analog TGC.
+ * - Active termination, available: 50, 100, 200, 400 [Ohm] or std::nullopt. null opt turns off active termination
+ * - LPF cutoff, available: 10000000, 15000000, 20000000, 30000000, 35000000, 50000000 [Hz].
+ * - applyTgcCharacteristic: whether to apply pre-computed (by us4us) TGC response characteristic, so that the observed
+ *   gain better corresponds to the applied one.
+ *
+ * Constraints:
+ * - only one of the following can be turned on: DTGC or analog TGC.
+ * - when applyTgcCharacteristic == true, LNA and PGA gain has to be (current limitation of the selected TGC
+ *   characteristic).
+ */
 class RxSettings {
 public:
     using TGCSample = arrus::ops::us4r::TGCSampleValue;
     using TGCCurve = arrus::ops::us4r::TGCCurve;
+    static constexpr float TGC_ATTENUATION_RANGE = 40.0f;
+
+    /**
+     * A helper function that computes a pair of (min, max) acceptable analog TGC gain for given PGA and LNA gain
+     * values.
+     *
+     * @param pgaGain PGA gain value to consider
+     * @param lnaGain LNA gain value to consider
+     * @return a pair (min, max) acceptable sample value.
+     */
+    static std::pair<float, float> getTgcMinMax(uint16 pgaGain, uint16 lnaGain) {
+        float max = float(pgaGain) + float(lnaGain);
+        float min = max-TGC_ATTENUATION_RANGE;
+        return {min, max};
+    }
+
+    RxSettings(const std::optional<uint16> &dtgcAttenuation, uint16 pgaGain, uint16 lnaGain,
+               TGCCurve tgcSamples, uint32 lpfCutoff, const std::optional<uint16> &activeTermination,
+               bool applyTgcCharacteristic = true)
+            : dtgcAttenuation(dtgcAttenuation), pgaGain(pgaGain), lnaGain(lnaGain), tgcSamples(std::move(tgcSamples)),
+              lpfCutoff(lpfCutoff), activeTermination(activeTermination),
+              applyTgcCharacteristic(applyTgcCharacteristic) {}
 
-    RxSettings(
-            const std::optional<uint16> &dtgcAttenuation, uint16 pgaGain,
-            uint16 lnaGain, TGCCurve tgcSamples, uint32 lpfCutoff,
-            const std::optional<uint16> &activeTermination)
-            : dtgcAttenuation(dtgcAttenuation), pgaGain(pgaGain),
-              lnaGain(lnaGain), tgcSamples(std::move(tgcSamples)),
-              lpfCutoff(lpfCutoff), activeTermination(activeTermination) {}
 
     const std::optional<uint16> &getDtgcAttenuation() const {
         return dtgcAttenuation;
@@ -47,16 +82,18 @@ class RxSettings {
         return activeTermination;
     }
 
-
+    bool isApplyTgcCharacteristic() const {
+        return applyTgcCharacteristic;
+    }
 
 private:
     std::optional<uint16> dtgcAttenuation;
     uint16 pgaGain;
     uint16 lnaGain;
-
     TGCCurve tgcSamples;
     uint32 lpfCutoff;
     std::optional<uint16> activeTermination;
+    bool applyTgcCharacteristic;
 };
 
 }

arrus/core/api/devices/us4r/Us4R.h

@@ -13,7 +13,7 @@
 #include "arrus/core/api/framework/Buffer.h"
 #include "arrus/core/api/framework/DataBufferSpec.h"
 #include "FrameChannelMapping.h"
-
+#include "arrus/core/api/devices/us4r/RxSettings.h"
 
 namespace arrus::devices {
 
@@ -74,11 +74,66 @@ class Us4R : public DeviceWithComponents {
     virtual void disableHV() = 0;
 
     /**
-     * Sets tgc curve points asynchronously.
+     * Equivalent to setTgcCurve(curve, true).
+     */
+    virtual void setTgcCurve(const std::vector<float>& tgcCurvePoints) = 0;
+
+    /**
+     * Sets TGC curve points asynchronously.
+     *
+     * Setting empty vector turns off analog TGC.
+     * Setting non-empty vector turns off DTGC and turns on analog TGC.
+     *
+     * TGC curve can have up to 1022 samples.
      *
      * @param tgcCurvePoints tgc curve points to set.
+     * @param applyCharacteristic set it to true if you want to compensate response characteristic (pre-computed
+     * by us4us). If true, LNA and PGA gains should be set to 24 an 30 dB, respectively, otherwise an
+     * ::arrus::IllegalArgumentException will be thrown.
      */
-    virtual void setTgcCurve(const std::vector<float>& tgcCurvePoints) = 0;
+    virtual void setTgcCurve(const std::vector<float>& tgcCurvePoints, bool applyCharacteristic) = 0;
+
+    /**
+     * Sets PGA gain.
+     *
+     * See docs of arrus::devices::RxSettings for more information.
+     */
+    virtual void setPgaGain(uint16 value) = 0;
+
+    /**
+     * Sets LNA gain.
+     *
+     * See docs of arrus::devices::RxSettings for more information.
+     */
+    virtual void setLnaGain(uint16 value) = 0;
+
+    /**
+     * Sets LPF cutoff.
+     *
+     * See docs of arrus::devices::RxSettings for more information.
+     */
+    virtual void setLpfCutoff(uint32 value) = 0;
+
+    /**
+     * Sets DTGC attenuation.
+     *
+     * See docs of arrus::devices::RxSettings for more information.
+     */
+    virtual void setDtgcAttenuation(std::optional<uint16> value) = 0;
+
+    /**
+    * Sets active termination.
+    *
+    * See docs of arrus::devices::RxSettings for more information.
+    */
+    virtual void setActiveTermination(std::optional<uint16> value) = 0;
+
+    /**
+     * Sets a complete list of RxSettings on all Us4R components.
+     *
+     * @param settings settings to apply
+     */
+    virtual void setRxSettings(const RxSettings &settings) = 0;
 
     virtual void start() = 0;
     virtual void stop() = 0;

arrus/core/api/devices/us4r/Us4RSettings.h

@@ -18,11 +18,8 @@ class Us4RSettings {
 public:
     using ReprogrammingMode = Us4OEMSettings::ReprogrammingMode;
 
-    explicit Us4RSettings(
-        std::vector<Us4OEMSettings> us4OemSettings,
-        std::optional<HVSettings> hvSettings)
-        : us4oemSettings(std::move(us4OemSettings)),
-          hvSettings(std::move(hvSettings)) {}
+    explicit Us4RSettings(std::vector<Us4OEMSettings> us4OemSettings, std::optional<HVSettings> hvSettings)
+        : us4oemSettings(std::move(us4OemSettings)), hvSettings(std::move(hvSettings)) {}
 
     Us4RSettings(
         ProbeAdapterSettings probeAdapterSettings,