Release 2.2, 25.08. (#34)

* Release 2.2.0-EA, 25.06.

Signed-off-by: Patrick O'Grady <[email protected]>

* change i2c timeout to enable vb1940-aio (#28)

* updated manifest file to fix FPGA ping issue (#29)

Co-authored-by: Gil Shapira <[email protected]>

* changes to address bugs found on EA codebase (#30)

* Release 2.2.0, 25.08.

Signed-off-by: Patrick O'Grady <[email protected]>

* Add watchdog timeouts to the known anomaly list. (#36)

* Update instructions for configuring IP addresses. (#37)

* Pin the specific version of cuda-python. (#38)

---------

Signed-off-by: Patrick O'Grady <[email protected]>
Co-authored-by: Yosi Levi <[email protected]>
Co-authored-by: Gil Shapira <[email protected]>

Author: 3 people

.clang-format

@@ -0,0 +1 @@
+BasedOnStyle: webkit

.gitattributes

@@ -1,5 +1,6 @@
 **/*.pcap filter=lfs diff=lfs merge=lfs -text
 **/*.pdf filter=lfs diff=lfs merge=lfs -text
 **/*.png filter=lfs diff=lfs merge=lfs -text
+**/*.docx filter=lfs diff=lfs merge=lfs -text
 .gitlab-ci.yml export-ignore
 RELEASE.sh export-ignore

.gitignore

@@ -5,13 +5,27 @@ ci/coverage.xml
 dist
 tags
 cscope.*
+.vscode/
 # cache
 .cache
 # build folders
+build
 *.egg-info
 # tao peoplenet files
 *.fp16
 *.onnx
 # NSight profiler files
 *.ncu-rep
 *.nsys-rep
+# Configurator files
+configurator/build
+configurator/meta-openembedded
+configurator/poky
+spi-vm.log
+spi-vm.pid
+
+# Emulation files
+src/hololink/emulation/test_emulator_hsb
+*.o
+dlpack.h
+

CMakeLists.txt

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,52 +17,80 @@ cmake_minimum_required(VERSION 3.20)
 
 # Options
 option(HOLOLINK_BUILD_PYTHON "Build Hololink Python Bindings" ON)
+option(HOLOLINK_BUILD_TESTS "Build Hololink Tests" ON)
+option(HOLOLINK_BUILD_ONLY_NATIVE "Build only native (i.e. C++) components" OFF)
+option(HOLOLINK_BUILD_SIPL "Build NvSIPL capture components" OFF)
 
-project(hololink)
+file(READ "VERSION" HOLOLINK_VERSION)
+string(STRIP ${HOLOLINK_VERSION} HOLOLINK_VERSION)
+string(REGEX MATCH "^([0-9]+\.[0-9]+\.[0-9]+)" HOLOLINK_VERSION_NUM ${HOLOLINK_VERSION})
 
-include(CTest)
+set(PROJECT_LANGUAGES CXX)
+if (NOT HOLOLINK_BUILD_ONLY_NATIVE)
+  list(APPEND PROJECT_LANGUAGES CUDA)
+endif()
 
-# Find Holoscan
-find_package(holoscan 0.6 REQUIRED CONFIG PATHS "/opt/nvidia/holoscan")
+project(hololink
+  LANGUAGES ${PROJECT_LANGUAGES}
+  VERSION ${HOLOLINK_VERSION_NUM})
 
-# Find pybind11
-find_package(Python3 REQUIRED COMPONENTS Interpreter Development)
+if (NOT HOLOLINK_BUILD_ONLY_NATIVE)
+  include(CTest)
 
-set(HOLOSCAN_SDK_VERSION "$ENV{HOLOSCAN_SDK_VERSION}")
-set(HOLOSCAN_SDK_VERSION_EXPECTED "2.7.0")
+  # Find Holoscan
+  find_package(holoscan 3.3 REQUIRED CONFIG PATHS "/opt/nvidia/holoscan")
 
-if(NOT HOLOSCAN_SDK_VERSION VERSION_EQUAL HOLOSCAN_SDK_VERSION_EXPECTED)
-  message(FATAL_ERROR "Expected Holoscan version ${HOLOSCAN_SDK_VERSION_EXPECTED} but found ${HOLOSCAN_SDK_VERSION}, please check pybind11 version of the Holoscan SDK and update here if needed")
-endif()
+  # Find pybind11
+  find_package(Python3 REQUIRED COMPONENTS Interpreter Development)
+
+  # We fetch pybind11 since we need the same version as the Holoscan SDK
+  # and it's not necessarily available on all the platforms
+  include(FetchContent)
+  FetchContent_Declare(pybind11
+    GIT_REPOSITORY https://github.com/pybind/pybind11
+    GIT_TAG v2.13.6
+    GIT_SHALLOW TRUE
+  )
+  FetchContent_MakeAvailable(pybind11)
+
+  # We fetch googletest since we need the same version as the Holoscan SDK.
+  # As recommended by the user guide (https://google.github.io/googletest/quickstart-cmake.html),
+  # we use Git commit hash of the GoogleTest version to use the same version as the Holoscan SDK.
+  # (https://github.com/google/googletest/releases/tag/release-1.12.1)
+  FetchContent_Declare(
+    googletest
+    URL https://github.com/google/googletest/archive/58d77fa8070e8cec2dc1ed015d66b454c8d78850.zip
+  )
+  FetchContent_MakeAvailable(googletest)
+
+  # add CMAKE_MODULE_PATH for pybind11_add_hololink_module
+  list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
 
-# We fetch pybind11 since we need the same version as the Holoscan SDK
-# and it's not necessarily available on all the platforms
-include(FetchContent)
-FetchContent_Declare(pybind11
-  GIT_REPOSITORY https://github.com/pybind/pybind11
-  GIT_TAG v2.11.1
-  GIT_SHALLOW TRUE
-)
-FetchContent_MakeAvailable(pybind11)
-
-# add CMAKE_MODULE_PATH for pybind11_add_hololink_module
-list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
-
-# enabled trace and debug log messages in debug buld only
-if(CMAKE_BUILD_TYPE STREQUAL "Release")
-  add_compile_definitions(HOLOSCAN_LOG_ACTIVE_LEVEL=2)
-else()
-  add_compile_definitions(HOLOSCAN_LOG_ACTIVE_LEVEL=0)
+  # enabled trace and debug log messages in debug build only
+  if(CMAKE_BUILD_TYPE STREQUAL "Release")
+    add_compile_definitions(HOLOSCAN_LOG_ACTIVE_LEVEL=2)
+  else()
+    add_compile_definitions(HOLOSCAN_LOG_ACTIVE_LEVEL=0)
+  endif()
 endif()
 
 if(NOT CMAKE_INSTALL_LIBDIR)
   set(CMAKE_INSTALL_LIBDIR lib)
 endif()
 
 add_subdirectory(src)
+add_subdirectory(tools)
+add_subdirectory(examples)
 
+if(NOT HOLOLINK_BUILD_ONLY_NATIVE)
+if(HOLOLINK_BUILD_TESTS)
+  add_subdirectory(tests)
+endif()
 if(HOLOLINK_BUILD_PYTHON)
   add_subdirectory(python)
 endif()
+add_subdirectory(scripts)
+endif()
 
-add_subdirectory(examples)
+# Add packaging
+include(cmake/HololinkCPack.cmake)

README.md

@@ -22,6 +22,12 @@ including instructions for setup on
 configurations. Please see the user guide for host configuration and instructions on
 running unit tests.
 
+## Troubleshooting
+
+Be sure and check the
+[release notes](https://docs.nvidia.com/holoscan/sensor-bridge/latest/release_notes.html)
+for frequently asked questions and troubleshooting tips.
+
 ## Submitting changes
 
 This software is published under the Apache 2.0 license, allowing unrestricted

RELEASE_NOTES.md

@@ -1,5 +1,108 @@
 # Release Notes
 
+## 2.2-GA, August 2025
+
+### Dependencies
+
+- IGX: [IGX-SW 1.1.2 Production Release](https://developer.nvidia.com/igx-downloads)
+- AGX: Use [SDK Manager](https://developer.nvidia.com/sdk-manager) to set up JetPack
+  6.2.1.
+- Holoscan Sensor Bridge, 10G; FPGA v2507.
+
+Be sure and follow the installation instructions included with the release, including
+PTP configuration and HSB device firmware updates. To generate documentation, in the
+host system, run `sh docs/make_docs.sh`, then use your browser to look at
+`docs/user_guide/_build/html/index.html`.
+
+### Updates from 2.0-GA
+
+- **HSB 2.2-GA relies on FPGA IP version 2507.** Check the user guide for instructions
+  on how to update your configuration. Note that updating your FPGA is only supported
+  for configurations currently running the 2412 or newer version (included with 2.0-GA).
+  If your configuration is older, follow the instructions to update to 2.0 first.
+
+- **HSB is updated to work with Holoscan SDK 3.3.** See the
+  [release notes for HSDK 3.3 here.](https://github.com/nvidia-holoscan/holoscan-sdk/releases/tag/v3.3.0)
+
+- **Synchronized I2C transactions.** By default, the `i2c_transaction` API executes an
+  I2C bus transaction immediately. Imx274Cam now includes a demonstration method called
+  `synchronized_set_register`, which queues an I2C transaction to update a camera
+  configuration register in the blanking interval between video frames. You can see how
+  this works by following calls to `Imx274Cam.synchronized_test_pattern_update()` as
+  called in `tests/test_i2c.py`.
+
+- **C++ Tools and utilities, including FPGA programming.** Support for systems without
+  python is enhanced by moving some tools to a C++ implementation. This includes
+
+  - `program_lattice_cpnx100` for programming Lattice CPNX100 based HSB boards
+  - `hololink-reset` (which replaces the `hololink reset` command)
+  - `hololink-enumerate` (which replaces the `hololink enumerate` command)
+  - `hololink-set-ip` (which replaces the `hololink set-ip` command)
+  - `hololink-read` and `hololink-write` (replace the `hololink read` and
+    `hololink write` commands)
+
+  Run any of these scripts with `--help` to get a description of command-line options.
+  The `hololink` command (which is python based) will be deprecated in a future release.
+
+- **Support for Leopard Imaging VB1940.** This includes support for stereo imaging with
+  left and right synchronized operation with global shutter. HSB also provides support
+  for the on-board IMU: IMU data is sent to the host via a third data channel and (on
+  appropriately equipped systems) is written directly to GPU memory via RDMA. This
+  camera sends all data using a single network interface. For example code showing how
+  to configure and access this data, see `examples/vb1940_stereo_imu_player.py`.
+
+- **COE (P1722B) Support.** Software emulation is provided for another RDMA message
+  format specified by the upcoming P1722B COE ("camera over Ethernet") standard. Future
+  host systems will support RDMA of P1722B traffic; this release includes HSB FPGA
+  support for generating these messages and software handling of received data using CPU
+  and the Linux network stack.
+
+- **E-con IMX715 and E-con ECam0M30ToF depth sensors.** For examples using these
+  configurations, see `examples/imx715_player.py` and `examples/ecam0m30tof_player.py`.
+
+### FAQ
+
+- If your application, running in the demo container, halts with a "Failed to initialize
+  glfw" message, make sure to grant the application permission to connect with the
+  display via the "xhost +" command. This command is not remembered across reboots.
+
+- Reverting to FPGA 2412 on Lattice HSB units. If you need to revert a Lattice HSB unit
+  back to 2412, use the 2.2-GA tree and program with the 2412 manifest file. From within
+  the demo container:
+
+  ```sh
+  program_lattice_cpnx100 scripts/manifest-2412.yaml
+  ```
+
+  After programming and power cycling, you can update your tree, going back to the
+  2.0-GA release.
+
+- PTP configuration following boot-up is very touchy and error-prone. If you have
+  trouble with received PTP timestamps, make sure you follow the user guide
+  [host setup instructions](https://docs.nvidia.com/holoscan/sensor-bridge/latest/setup.html)
+  carefully.
+
+- Running tools like "nomachine" on non-RDMA capable systems--where CPU is used to
+  emulate RDMA functionality, e.g. AGX-- can frequently lead to packet drops for
+  high-speed sensor data. In camera applications, this can appear as momentary white
+  streaks on the display. In the current CPU-driven implementation, after a video frame
+  is delivered to the holoscan pipeline, we clear the receiver buffer to all 0xFF. If a
+  UDP packet with video data is dropped, then that 0xFF wouldn't be replaced with actual
+  video data-- and that's where the white streaks come from. Adjusting `rmem_max` (per
+  [host setup instructions](https://docs.nvidia.com/holoscan/sensor-bridge/latest/setup.html))
+  and adjusting core affinity for your application may help mitigate packet loss.
+
+### Known Anomalies
+
+- Rare observations of IMX274 producing images with distorted video, which seem to be
+  system specific. Investigation of this is underway.
+
+- Watchdog timeouts during `pytest --imx274 --ptp`. Testing sometimes terminates early
+  with a Watchdog exception, indicating that the host is not properly receiving frame
+  data. This happens occasionally during testing and in varying places, and only under
+  conditions where frequent reset and reinitialization of the HSB unit and sensor occur.
+  Investigation of this is underway.
+
 ## 2.0-GA, January 2025
 
 ### Dependencies
@@ -77,7 +180,7 @@ look at `docs/user_guide/_build/html/index.html`.
   manifest file. From within the demo container:
 
   ```sh
-  hololink program scripts/manifest-2407.yaml
+  program_lattice_cpnx100 scripts/manifest-2407.yaml
   ```
 
   After programming and power cycling, the board will no longer be visible to the 2.0-GA

VERSION

@@ -1 +1 @@
-2.0.0
+2.2.0

ci/Dockerfile.lint

@@ -32,5 +32,5 @@ RUN apt-get update \
     clang-format \
   && rm -rf /var/lib/apt/lists/*
 
-RUN pip3 install black flake8 isort
+RUN pip3 install black flake8 isort codespell
 RUN pip3 install mdformat mdformat-tables

ci/acceptable_words.txt

@@ -0,0 +1,2 @@
+OEN
+inout

ci/lint.sh

@@ -58,6 +58,9 @@ SKIP=( \
     build*
 )
 
+# Codespell checks for spelling mistakes.  Don't include PDF files.
+CODESPELL_FILES=( `git ls-files | grep -v '.pdf$'` )
+
 C_FILES=( `git ls-files | egrep '.(cpp|hpp)$' ` )
 DOCS_FILES=( `git ls-files | egrep '.md$' ` )
 
@@ -71,6 +74,15 @@ SKIP_ISORT=${SKIP[*]/#/--skip }
 # value used by black.
 MDFORMAT="--wrap 88 --end-of-line lf"
 
+# Allow some flake8 violations
+# E203 - black puts spaces around the ':' in array slices
+# E501 - black uses 88 character lengths; flake8 complains for lines longer than 79
+# F824 - Allow the code to say 'global x' then only read from that variable; this
+#   helps readers of your code.
+# W503 - black formats long expressions with the operator at the beginning
+#   of the line
+FLAKE8="--ignore=E203,E501,F824,W503"
+
 umask 0
 
 # By default, run lint; specify "--format" to
@@ -83,19 +95,21 @@ case "$1" in
         set -o xtrace
         isort $SKIP_ISORT --profile black .
         black "--extend-exclude=$SKIP_RE" .
-        flake8 --ignore=E501,E203,W503 --extend-exclude=$SKIP_COMMAS
-        clang-format --style=webkit -i ${C_FILES[*]}
+        flake8 $FLAKE8 --extend-exclude=$SKIP_COMMAS
+        clang-format --style=file:${ROOT}/.clang-format -i ${C_FILES[*]}
         mdformat $MDFORMAT ${DOCS_FILES[*]}
+        codespell --ignore-words=$HERE/acceptable_words.txt ${CODESPELL_FILES[*]}
         exit 0
         ;;
     --do-lint)
         # We rely on 'set -o errexit' above to terminate on an error
         set -o xtrace
         isort --check-only $SKIP_ISORT --profile black .
         black --check "--extend-exclude=$SKIP_RE" .
-        flake8 --ignore=E501,E203,W503 --extend-exclude=$SKIP_COMMAS
-        clang-format --style=webkit --dry-run -Werror ${C_FILES[*]}
+        flake8 $FLAKE8 --extend-exclude=$SKIP_COMMAS
+        clang-format --style=file:${ROOT}/.clang-format --dry-run -Werror ${C_FILES[*]}
         mdformat --check $MDFORMAT ${DOCS_FILES[*]}
+        codespell --ignore-words=$HERE/acceptable_words.txt ${CODESPELL_FILES[*]}
         exit 0
         ;;
     --do-*)