Merge branch 'master' into develop

# Conflicts:
#	CMakeLists.txt
#	arrus/core/api/devices/us4r/Us4OEM.h
#	arrus/core/api/devices/us4r/Us4R.h
#	arrus/core/devices/us4r/Us4RImpl.cpp
#	arrus/core/devices/us4r/probeadapter/ProbeAdapterImplTest.cpp
#	arrus/core/devices/us4r/us4oem/Us4OEMImpl.cpp

CMakeLists.txt

@@ -88,7 +88,7 @@ set(ARRUS_DOCS_INSTALL_DIR docs)
 ################################################################################
 # Common dependencies
 ################################################################################
-find_package(Us4 0.6.9 EXACT REQUIRED US4OEM HV256 DBARLite)
+find_package(Us4 0.6.10 EXACT REQUIRED US4OEM HV256 DBARLite)
 find_package(Boost REQUIRED)
 set(Boost_USE_STATIC_LIBS ON)
 find_package(Protobuf REQUIRED)

api/python/examples/diverging_beams_3d.py

@@ -0,0 +1,97 @@
+"""
+This script acquires and reconstructs RF img for plane wave imaging
+(synthetic aperture).
+
+GPU usage is recommended.
+"""
+
+import arrus
+import arrus.session
+import arrus.utils.imaging
+import arrus.utils.us4r
+import queue
+import numpy as np
+
+from arrus.ops.us4r import (
+    Scheme,
+    Pulse,
+    Tx,
+    Rx,
+    TxRx,
+    TxRxSequence
+)
+from arrus.utils.imaging import (
+    Pipeline,
+    SelectFrames,
+    Squeeze,
+    Lambda,
+    RemapToLogicalOrder
+)
+from arrus.utils.gui import (
+    Display2D
+)
+
+arrus.set_clog_level(arrus.logging.INFO)
+arrus.add_log_file("test.log", arrus.logging.INFO)
+
+
+def main():
+    # Here starts communication with the device.
+    with arrus.Session() as sess:
+        us4r = sess.get_device("/Us4R:0")
+        us4r.set_hv_voltage(10)
+
+        n_elements = us4r.get_probe_model().n_elements
+        # Full transmit aperture, full receive aperture.
+        seq = TxRxSequence(
+            ops=[
+                TxRx(
+                    Tx(aperture=[True]*n_elements,
+                       excitation=Pulse(center_frequency=6e6, n_periods=2, inverse=False),
+                       # Custom delays 1.
+                       delays=[0]*n_elements),
+                    Rx(aperture=[True]*n_elements,
+                       sample_range=(0, 2048),
+                       downsampling_factor=1),
+                    pri=200e-6
+                ),
+            ],
+            # Turn off TGC.
+            tgc_curve=[14]*200,  # [dB]
+            # Time between consecutive acquisitions, i.e. 1/frame rate.
+            sri=50e-3
+        )
+        # Declare the complete scheme to execute on the devices.
+        scheme = Scheme(
+            # Run the provided sequence.
+            tx_rx_sequence=seq,
+            # Processing pipeline to perform on the GPU device.
+            processing=Pipeline(
+                steps=(
+                    RemapToLogicalOrder(),
+                    SelectFrames([0]),
+                    Squeeze(),
+                    Lambda(lambda data: data-(data.mean(axis=0).astype(np.int16)))
+                ),
+                placement="/GPU:0"
+            )
+        )
+        # Upload the scheme on the us4r-lite device.
+        buffer, metadata = sess.upload(scheme)
+        # Created 2D image display.
+        display = Display2D(metadata=metadata, value_range=(-1000, 1000))
+        # Start the scheme.
+        sess.start_scheme()
+        # Start the 2D display.
+        # The 2D display will consume data put the the input queue.
+        # The below function blocks current thread until the window is closed.
+        display.start(buffer)
+
+        print("Display closed, stopping the script.")
+
+    # When we exit the above scope, the session and scheme is properly closed.
+    print("Stopping the example.")
+
+
+if __name__ == "__main__":
+    main()

api/python/examples/pwi_3d.py

@@ -0,0 +1,97 @@
+"""
+This script acquires and reconstructs RF img for plane wave imaging
+(synthetic aperture).
+
+GPU usage is recommended.
+"""
+
+import arrus
+import arrus.session
+import arrus.utils.imaging
+import arrus.utils.us4r
+import queue
+import numpy as np
+
+from arrus.ops.us4r import (
+    Scheme,
+    Pulse,
+    Tx,
+    Rx,
+    TxRx,
+    TxRxSequence
+)
+from arrus.utils.imaging import (
+    Pipeline,
+    SelectFrames,
+    Squeeze,
+    Lambda,
+    RemapToLogicalOrder
+)
+from arrus.utils.gui import (
+    Display2D
+)
+
+arrus.set_clog_level(arrus.logging.INFO)
+arrus.add_log_file("test.log", arrus.logging.INFO)
+
+
+def main():
+    # Here starts communication with the device.
+    with arrus.Session() as sess:
+        us4r = sess.get_device("/Us4R:0")
+        us4r.set_hv_voltage(5)
+
+        n_elements = us4r.get_probe_model().n_elements
+        # Full transmit aperture, full receive aperture.
+        seq = TxRxSequence(
+            ops=[
+                TxRx(
+                    Tx(aperture=[True]*n_elements,
+                       excitation=Pulse(center_frequency=6e6, n_periods=2, inverse=False),
+                       # Custom delays 1.
+                       delays=[0]*n_elements),
+                    Rx(aperture=[True]*n_elements,
+                       sample_range=(0, 2048),
+                       downsampling_factor=1),
+                    pri=200e-6
+                ),
+            ],
+            # Turn off TGC.
+            tgc_curve=[14]*200,  # [dB]
+            # Time between consecutive acquisitions, i.e. 1/frame rate.
+            sri=50e-3
+        )
+        # Declare the complete scheme to execute on the devices.
+        scheme = Scheme(
+            # Run the provided sequence.
+            tx_rx_sequence=seq,
+            # Processing pipeline to perform on the GPU device.
+            processing=Pipeline(
+                steps=(
+                    RemapToLogicalOrder(),
+                    SelectFrames([0]),
+                    Squeeze(),
+                    Lambda(lambda data: data-(data.mean(axis=0).astype(np.int16)))
+                ),
+                placement="/GPU:0"
+            )
+        )
+        # Upload the scheme on the us4r-lite device.
+        buffer, metadata = sess.upload(scheme)
+        # Created 2D image display.
+        display = Display2D(metadata=metadata, value_range=(-1000, 1000))
+        # Start the scheme.
+        sess.start_scheme()
+        # Start the 2D display.
+        # The 2D display will consume data put the the input queue.
+        # The below function blocks current thread until the window is closed.
+        display.start(buffer)
+
+        print("Display closed, stopping the script.")
+
+    # When we exit the above scope, the session and scheme is properly closed.
+    print("Stopping the example.")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -24,10 +24,43 @@ class Us4OEM : public Device, public TriggerGenerator {
 
     ~Us4OEM() override = default;
 
+    /**
+     * Returns nominal sampling frequency on the us4OEM device.
+     */
     virtual float getSamplingFrequency() = 0;
 
+    /**
+     * Returns temperature measured by Us4OEM's FPGA [Celsius].
+     */
     virtual float getFPGATemperature() = 0;
 
+    /**
+     * Checks if the firmware version on the Us4OEM module is correct.
+     *
+     * @throws ::arrus::IllegalStateException when the incorrect version was detected.
+     */
+    virtual void checkFirmwareVersion() = 0;
+
+    /**
+     * Checks if the us4OEM is in the correct state (as seen by host PC).
+     *
+     * Note: currently only the firmware version is checked (to verify if the us4OEM module
+     * memory space is still available for the us4OEM module).
+     *
+     * @throws arrus::IllegalStateException when the incorrect version was detected.
+     */
+    virtual void checkState() = 0;
+
+    /**
+     * Returns firmware version installed on the us4OEM module.
+     */
+    virtual uint32 getFirmwareVersion() = 0;
+
+    /**
+     * Returns Tx component firmware version installed on this us4OEM module.
+     */
+    virtual uint32 getTxFirmwareVersion() = 0;
+
     Us4OEM(Us4OEM const&) = delete;
     Us4OEM(Us4OEM const&&) = delete;
     void operator=(Us4OEM const&) = delete;

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

@@ -154,6 +154,14 @@ class Us4R : public DeviceWithComponents {
      */
     virtual float getSamplingFrequency() const = 0;
 
+    /**
+     * Checks state of the Us4R device. Currently checks if each us4OEM module is in
+     * the correct state.
+     *
+     * @throws arrus::IllegalStateException when some inconsistent state was detected
+     */
+    virtual void checkState() const = 0;
+
 
     Us4R(Us4R const&) = delete;
     Us4R(Us4R const&&) = delete;

arrus/core/devices/us4r/Us4RImpl.cpp

@@ -262,7 +262,7 @@ void Us4RImpl::setActiveTermination(std::optional<uint16> value) {
 }
 
 uint8_t Us4RImpl::getNumberOfUs4OEMs() {
-    return (uint8_t)us4oems.size();
+    return static_cast<uint8_t>(us4oems.size());
 }
 
 void Us4RImpl::setTestPattern(Us4OEM::RxTestPattern pattern) {
@@ -276,4 +276,10 @@ float Us4RImpl::getSamplingFrequency() const {
     return us4oems[0]->getSamplingFrequency();
 }
 
+void Us4RImpl::checkState() const {
+    for(auto &us4oem: us4oems) {
+        us4oem->checkState();
+    }
+}
+
 }

arrus/core/devices/us4r/Us4RImpl.h

@@ -125,6 +125,7 @@ class Us4RImpl : public Us4R {
     uint8_t getNumberOfUs4OEMs() override;
     void setTestPattern(Us4OEM::RxTestPattern pattern) override;
     float getSamplingFrequency() const override;
+    void checkState() const override;
 
 private:
     UltrasoundDevice *getDefaultComponent();

arrus/core/devices/us4r/common.cpp

@@ -181,6 +181,12 @@ splitRxAperturesIfNecessary(const std::vector<TxRxParamsSequence> &seqs,
                     }
                 }
             }
+            if(seqIdx == 0) {
+                // NOTE: for us4OEM:0, even if it is RX nop, the results of this
+                // rx NOP will be transferred from us4OEM to host memory,
+                // to get the frame metadata.
+                maxSubapertureIdx = (std::max)((ChannelIdx)1, maxSubapertureIdx);
+            }
             currentFrameIdx[seqIdx] += maxSubapertureIdx;
         }
         // Check if all seqs have the same size.
@@ -204,4 +210,4 @@ splitRxAperturesIfNecessary(const std::vector<TxRxParamsSequence> &seqs,
     return std::make_tuple(result, opDestOp, opDestChannel);
 }
 
-}
+}

arrus/core/devices/us4r/external/ius4oem/Us4RLoggerWrapper.h

@@ -3,6 +3,7 @@
 
 #include <unordered_map>
 #include <utility>
+#include <stdexcept>
 
 // us4r
 #include <logging/Logger.h>
@@ -14,30 +15,41 @@ namespace arrus::devices {
 class Us4RLoggerWrapper : public us4r::Logger {
 public:
 
-    Us4RLoggerWrapper(arrus::Logger::SharedHandle logger)
+    explicit Us4RLoggerWrapper(arrus::Logger::SharedHandle logger)
             : logger(std::move(logger)) {}
 
     void
     log(const us4r::LogSeverity severity, const std::string &msg) override {
-        logger->log(sevMap.at(severity), msg);
+        switch(severity) {
+            case us4r::LogSeverity::TRACE:
+                logger->log(arrus::LogSeverity::TRACE, msg);
+                break;
+            case us4r::LogSeverity::DEBUG:
+                logger->log(arrus::LogSeverity::DEBUG, msg);
+                break;
+            case us4r::LogSeverity::INFO:
+                logger->log(arrus::LogSeverity::INFO, msg);
+                break;
+            case us4r::LogSeverity::WARNING:
+                logger->log(arrus::LogSeverity::WARNING, msg);
+                break;
+            case us4r::LogSeverity::ERROR:
+                logger->log(arrus::LogSeverity::ERROR, msg);
+                break;
+            case us4r::LogSeverity::FATAL:
+                logger->log(arrus::LogSeverity::FATAL, msg);
+                break;
+            default:
+                throw std::runtime_error("Unknown logging level");
+        }
     }
 
     void
     setAttribute(const std::string &key, const std::string &value) override {
         logger->setAttribute(key, value);
     }
-
 private:
     arrus::Logger::SharedHandle logger;
-
-    static const inline std::unordered_map<us4r::LogSeverity, arrus::LogSeverity> sevMap{
-            {us4r::LogSeverity::TRACE,   arrus::LogSeverity::TRACE},
-            {us4r::LogSeverity::DEBUG,   arrus::LogSeverity::DEBUG},
-            {us4r::LogSeverity::INFO,    arrus::LogSeverity::INFO},
-            {us4r::LogSeverity::WARNING, arrus::LogSeverity::WARNING},
-            {us4r::LogSeverity::ERROR,   arrus::LogSeverity::ERROR},
-            {us4r::LogSeverity::FATAL,   arrus::LogSeverity::FATAL},
-    };
 };
 
 }

arrus/core/devices/us4r/probeadapter/ProbeAdapterImplTest.cpp

@@ -92,7 +92,6 @@ class MockUs4OEM : public Us4OEMImplBase {
             (override));
     MOCK_METHOD(Interval<Voltage>, getAcceptedVoltageRange, (), (override));
     MOCK_METHOD(float, getSamplingFrequency, (), (override));
-    MOCK_METHOD(float, getFPGATemperature, (), (override));
     MOCK_METHOD(void, startTrigger, (), (override));
     MOCK_METHOD(void, stopTrigger, (), (override));
     MOCK_METHOD(void, start, (), (override));
@@ -105,6 +104,10 @@ class MockUs4OEM : public Us4OEMImplBase {
     MOCK_METHOD(std::vector<uint8_t>, getChannelMapping, (), (override));
     MOCK_METHOD(float, getFPGATemperature, (), (override));
     MOCK_METHOD(void, setTestPattern, (Us4OEMImpl::RxTestPattern), (override));
+    MOCK_METHOD(void, checkFirmwareVersion, (), (override));
+    MOCK_METHOD(void, checkState, (), (override));
+    MOCK_METHOD(uint32, getFirmwareVersion, (), (override));
+    MOCK_METHOD(uint32, getTxFirmwareVersion, (), (override));
 };
 
 class AbstractProbeAdapterImplTest : public ::testing::Test {