dustingooding · dustingooding · Feb 1, 2026 · Jan 26, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -174,13 +174,22 @@ jobs:
           rustc --version
           cargo --version
 
-      - name: Install Protocol Buffers (Linux)
-        if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler libprotobuf-dev
+      - name: Setup vcpkg environment (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          echo "VCPKG_ROOT=$HOME/vcpkg" >> $GITHUB_ENV
+
+      - name: Install vcpkg dependencies (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          cd $VCPKG_ROOT
+          ./vcpkg install protobuf
+          echo "$VCPKG_ROOT/installed/${{ runner.os == 'macOS' && 'arm64-osx' || 'x64-linux' }}/tools/protobuf" >> $GITHUB_PATH
+        shell: bash
 
-      - name: Install Protocol Buffers (macOS)
-        if: runner.os == 'macOS'
-        run: brew install protobuf
+      - name: Install D-Bus (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libdbus-1-dev
 
       - name: Install Dependencies (Windows)
         if: runner.os == 'Windows'
@@ -195,9 +204,6 @@ jobs:
         env:
           VCPKG_BINARY_SOURCES: clear;files,${{ github.workspace }}\vcpkg_cache,readwrite
 
-      - name: Verify Protobuf installation
-        run: protoc --version
-
       - name: Determine CMake preset
         id: preset
         run: |
@@ -232,17 +238,26 @@ jobs:
 
       - name: Configure CMake (Windows)
         if: runner.os == 'Windows'
-        run: cmake --preset=${{ steps.preset.outputs.preset }} -DCMAKE_TOOLCHAIN_FILE="$env:USERPROFILE\vcpkg\scripts\buildsystems\vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows-static-md -D${{ env.PROJECT_NAME }}_ENABLE_IPO=${{matrix.enable_ipo }} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }} -DGIT_SHA:STRING=${{ github.sha }}
+        run: cmake --preset=${{ steps.preset.outputs.preset }} -D${{ env.PROJECT_NAME }}_ENABLE_IPO=${{matrix.enable_ipo }} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }} -DGIT_SHA:STRING=${{ github.sha }}
         env:
           VCPKG_BINARY_SOURCES: clear;files,${{ github.workspace }}\vcpkg_cache,readwrite
 
       - name: Configure CMake (Linux/macOS)
         if: runner.os != 'Windows'
         run: cmake --preset=${{ steps.preset.outputs.preset }} -D${{ env.PROJECT_NAME }}_ENABLE_IPO=${{matrix.enable_ipo }} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }} -DGIT_SHA:STRING=${{ github.sha }}
 
+      - name: Verify protoc installation
+        run: |
+          PROTOC_PATH="${{ runner.os == 'Windows' && format('{0}\vcpkg_installed\x64-windows-static-md\tools\protobuf\protoc.exe', github.workspace) || format('{0}/out/build/{1}/vcpkg_installed/{2}/tools/protobuf/protoc', github.workspace, steps.preset.outputs.preset, runner.os == 'macOS' && 'arm64-osx' || 'x64-linux') }}"
+          echo "Checking for protoc at: $PROTOC_PATH"
+          ls -la "$PROTOC_PATH" || find ${{ github.workspace }}/out/build -name protoc -type f
+        shell: bash
+
       - name: Build
         run: |
           cmake --build --preset=${{ steps.preset.outputs.preset }}
+        env:
+          PROTOC: ${{ runner.os == 'Windows' && format('{0}\vcpkg_installed\x64-windows-static-md\tools\protobuf\protoc.exe', github.workspace) || format('{0}/out/build/{1}/vcpkg_installed/{2}/tools/protobuf/protoc', github.workspace, steps.preset.outputs.preset, runner.os == 'macOS' && 'arm64-osx' || 'x64-linux') }}
 
       - name: Rust Quality Checks
         if: matrix.packaging_maintainer_mode == 'ON'

diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
@@ -61,8 +61,12 @@ jobs:
         echo "Disk space after cleanup:"
         df -h
 
-    - name: Install Protocol Buffers
-      run: sudo apt-get update && sudo apt-get install -y protobuf-compiler libprotobuf-dev
+    - name: Install D-Bus
+      run: sudo apt-get update && sudo apt-get install -y libdbus-1-dev
+
+    - name: Setup vcpkg environment
+      run: |
+        echo "VCPKG_ROOT=$HOME/vcpkg" >> $GITHUB_ENV
 
     - name: Setup Cache
       uses: ./.github/actions/setup_cache
@@ -86,7 +90,7 @@ jobs:
 
         cmake: true
         ninja: true
-        vcpkg: false
+        vcpkg: true
         ccache: true
         clangtidy: false
 
@@ -107,11 +111,28 @@ jobs:
         rustc --version
         cargo --version
 
+    - name: Determine CMake preset
+      id: preset
+      run: |
+        if [ "${{ matrix.compiler }}" = "gcc-14" ]; then
+          if [ "${{ matrix.build_type }}" = "Debug" ]; then
+            echo "preset=unixlike-gcc-debug" >> $GITHUB_OUTPUT
+          else
+            echo "preset=unixlike-gcc-release" >> $GITHUB_OUTPUT
+          fi
+        else
+          if [ "${{ matrix.build_type }}" = "Debug" ]; then
+            echo "preset=unixlike-clang-debug" >> $GITHUB_OUTPUT
+          else
+            echo "preset=unixlike-clang-release" >> $GITHUB_OUTPUT
+          fi
+        fi
+      shell: bash
+
       # make sure coverage is only enabled for Debug builds, since it sets -O0 to make sure coverage
       # has meaningful results
     - name: Configure CMake
-      run: |
-        cmake -S . -B ./build -G "${{matrix.generator}}" -DCMAKE_BUILD_TYPE:STRING=${{matrix.build_type}} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }}
+      run: cmake --preset=${{ steps.preset.outputs.preset }} -D${{ env.PROJECT_NAME }}_PACKAGING_MAINTAINER_MODE:BOOL=${{matrix.packaging_maintainer_mode}} -D${{ env.PROJECT_NAME }}_ENABLE_COVERAGE:BOOL=${{ matrix.build_type == 'Debug' }}
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
@@ -125,9 +146,9 @@ jobs:
 
 
     - name: Build
-      # Execute the build.  You can specify a specific target with "--target <NAME>"
-      run: |
-        cmake --build ./build --config ${{matrix.build_type}}
+      run: cmake --build --preset=${{ steps.preset.outputs.preset }}
+      env:
+        PROTOC: ${{ github.workspace }}/out/build/${{ steps.preset.outputs.preset }}/vcpkg_installed/x64-linux/tools/protobuf/protoc
 
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@v4
diff --git a/CMakePresets.json b/CMakePresets.json
@@ -33,6 +33,8 @@
                 "strategy": "external"
             },
             "cacheVariables": {
+                "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
+                "VCPKG_TARGET_TRIPLET": "x64-windows-static-md",
                 "ENABLE_CPPCHECK_DEFAULT": "FALSE",
                 "ENABLE_CLANG_TIDY_DEFAULT": "FALSE"
             }
@@ -50,6 +52,9 @@
                     "Darwin"
                 ]
             },
+            "cacheVariables": {
+                "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
+            },
             "vendor": {
                 "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
                     "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"

diff --git a/Dependencies.cmake b/Dependencies.cmake
@@ -252,4 +252,46 @@ function(radix_relay_setup_dependencies)
     endif()
   endif()
 
+  if(NOT TARGET simpleble::simpleble)
+    cpmaddpackage(
+      NAME SimpleBLE
+      GITHUB_REPOSITORY simpleble/simpleble
+      GIT_TAG v0.6.1
+      SOURCE_SUBDIR simpleble
+      OPTIONS
+        "SIMPLEBLE_PLAIN OFF"
+        "SIMPLEBLE_USE_SESSION_DBUS OFF"
+        "SIMPLEBLE_LOG_LEVEL INFO"
+        "SIMPLEBLUEZ_LOG_LEVEL FATAL"
+        "SIMPLEDBUS_LOG_LEVEL FATAL"
+      SYSTEM YES
+    )
+    if(SimpleBLE_ADDED)
+      message(STATUS "System SimpleBLE not found, built from source via CPM")
+      if(TARGET simpleble AND NOT TARGET simpleble::simpleble)
+        add_library(simpleble::simpleble ALIAS simpleble)
+        message(STATUS "Created simpleble::simpleble alias for simpleble target")
+      endif()
+      # Suppress specific deprecation warnings on MSVC for SimpleBLE
+      if(TARGET simpleble)
+        target_compile_options(simpleble PRIVATE
+          $<$<CXX_COMPILER_ID:MSVC>:/wd4996>
+        )
+        target_compile_definitions(simpleble PRIVATE
+          $<$<CXX_COMPILER_ID:MSVC>:_CRT_SECURE_NO_WARNINGS>
+        )
+      endif()
+      if(TARGET simpleble-c)
+        target_compile_options(simpleble-c PRIVATE
+          $<$<CXX_COMPILER_ID:MSVC>:/wd4996>
+        )
+        target_compile_definitions(simpleble-c PRIVATE
+          $<$<CXX_COMPILER_ID:MSVC>:_CRT_SECURE_NO_WARNINGS>
+        )
+      endif()
+    else()
+      message(STATUS "Found system SimpleBLE ${SimpleBLE_VERSION}")
+    endif()
+  endif()
+
 endfunction()
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -32,6 +32,57 @@ curl -LJO "https://github.com/aminya/setup-cpp/releases/latest/download/setup_cp
 RefreshEnv.cmd
 ```
 
+## Dependency Management Strategy
+
+Radix Relay uses a multi-layered dependency management approach:
+
+### Build Tools & Compilers (Spack - Local Development)
+
+For local development with precise version control:
+
+- **cmake** @3.27 - Build system
+- **ninja** @1.12 - Build generator
+- **llvm** @19.1 - Clang compiler toolchain
+- **gcc** @13.3 - GCC compiler toolchain
+- **doxygen** @1.9 - Documentation generator
+- **graphviz** @2.42 - Documentation diagrams
+- **pkgconf** @2.3 - Package config tool (required for SimpleBLE on Linux)
+
+**Installation:** See spack.yaml in the project root. Spack automatically installs these when you activate the environment.
+
+### C++ Library Dependencies (vcpkg)
+
+Managed via vcpkg.json, automatically installed during CMake configuration:
+
+- **protobuf** - All platforms (Protocol Buffers)
+- **openssl** - Windows only (Linux/macOS use system OpenSSL)
+- **sqlcipher** - Windows only (Linux/macOS use system packages)
+
+**Installation:** Automatically handled during CMake configuration.
+
+### Additional C++ Libraries (CPM - Automatic)
+
+Downloaded and built automatically via CMake Package Manager (CPM):
+
+- **SimpleBLE** (v0.6.1) - Cross-platform BLE library
+- **Boost** (asio, beast, system) - Async I/O and HTTP
+- **Slint** - GUI framework
+- **Replxx** - TUI readline library
+- **Catch2** - Testing framework
+- **libsignal** (Rust) - Signal Protocol via Corrosion
+
+**Installation:** No action required - handled by Dependencies.cmake.
+
+### System Libraries (Platform Package Managers)
+
+Platform-specific system dependencies:
+
+- **OpenSSL** - Linux/macOS only (vcpkg on Windows)
+- **SQLCipher** - Linux/macOS only (vcpkg on Windows)
+- **D-Bus** - Linux only (for SimpleBLE BlueZ backend)
+
+**Installation:** Use your system package manager (apt/dnf/pacman/brew).
+
 ## Manual Installation
 
 ### Required Dependencies
@@ -138,6 +189,53 @@ brew install protobuf
 
 Protocol Buffers is installed automatically via vcpkg during the build process.
 
+#### 6. BLE Transport Dependencies
+
+Required for Bluetooth Low Energy transport functionality.
+
+**System D-Bus (Linux only):**
+
+SimpleBLE on Linux uses the BlueZ backend which requires D-Bus development headers. On Windows and macOS, SimpleBLE uses native Bluetooth APIs (no D-Bus needed).
+
+```bash
+# Ubuntu/Debian
+sudo apt install libdbus-1-dev
+
+# Fedora/RHEL
+sudo dnf install dbus-devel
+
+# Arch
+sudo pacman -S dbus
+```
+
+**SimpleBLE (all platforms):**
+
+SimpleBLE is automatically downloaded and built via CPM (CMake Package Manager) during configuration. No manual installation needed.
+
+- **Version**: v0.6.1
+- **Linux**: Uses BlueZ backend (requires system D-Bus installed above)
+- **Windows**: Uses native Windows Bluetooth API
+- **macOS**: Uses CoreBluetooth framework
+
+**vcpkg Setup (for Protobuf):**
+
+Install vcpkg if you haven't already:
+
+```bash
+git clone https://github.com/microsoft/vcpkg.git /data/git/vcpkg
+/data/git/vcpkg/bootstrap-vcpkg.sh  # Linux/macOS
+# or
+git clone https://github.com/microsoft/vcpkg.git %USERPROFILE%\vcpkg
+%USERPROFILE%\vcpkg\bootstrap-vcpkg.bat  # Windows
+
+# Set environment variable (add to your shell profile or .envrc)
+export VCPKG_ROOT=/data/git/vcpkg  # Linux/macOS
+# or
+set VCPKG_ROOT=%USERPROFILE%\vcpkg  # Windows
+```
+
+The project's CMake presets automatically use the vcpkg toolchain for Protobuf and other dependencies.
+
 ### Optional Dependencies
 
 #### Documentation Tools
@@ -211,6 +309,8 @@ brew install llvm@19
 | C++ Compiler | C++20 support | Clang 19.1.1, GCC 14, or MSVC 2022 |
 | Rust | stable | Latest stable |
 | Protocol Buffers | 3.x | Latest |
+| pkg-config (Linux BLE) | Any | Latest |
+| D-Bus (Linux BLE) | 1.x | Latest |
 | Python (for docs) | 3.8 | 3.12+ |
 
 ## Verification
@@ -230,6 +330,10 @@ clang++ --version       # 19.1.1+ (Linux/macOS)
 g++ --version          # 14+ (Linux)
 # or
 cl                     # MSVC 2022 (Windows)
+
+# BLE dependencies (Linux only)
+pkg-config --version    # Any version
+pkg-config --exists dbus-1 && echo "D-Bus found" || echo "D-Bus not found"
 ```
 
 ## Next Steps
@@ -274,4 +378,22 @@ which protoc  # Linux/macOS
 where protoc  # Windows
 ```
 
+### BLE dependencies missing (Linux)
+
+If CMake cannot find DBus1 or pkg-config:
+
+```bash
+# Verify pkg-config is installed
+pkg-config --version
+
+# Verify D-Bus development libraries are installed
+pkg-config --exists dbus-1 && echo "Found" || echo "Not found"
+
+# If not found, install them:
+sudo apt install pkg-config libdbus-1-dev  # Ubuntu/Debian
+sudo dnf install pkgconfig dbus-devel      # Fedora/RHEL
+sudo pacman -S pkgconf dbus                # Arch
+spack install pkgconf dbus                 # Spack
+```
+
 If issues persist, see the [GitHub Issues](https://github.com/dustingooding/radix-relay/issues) or join discussions.
diff --git a/lib/transport/CMakeLists.txt b/lib/transport/CMakeLists.txt
@@ -17,7 +17,8 @@ target_link_system_libraries(
           Boost::beast
           Boost::system
           OpenSSL::SSL
-          OpenSSL::Crypto)
+          OpenSSL::Crypto
+          simpleble::simpleble)
 
 target_include_directories(radix_relay_transport ${WARNING_GUARD} PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>

diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt
@@ -108,3 +108,14 @@ target_link_libraries(
           radix_relay::radix_relay_options
           radix_relay::transport
           Catch2::Catch2WithMain)
+
+# Integration test for SimpleBLE with BlueZ (not in ALL target, requires BLE hardware or virtual HCI)
+# Build with: cmake --build <build-dir> --target simpleble_bluez_integration_test
+# Run with: ./test/simpleble_bluez_integration_test
+add_executable(simpleble_bluez_integration_test EXCLUDE_FROM_ALL simpleble_bluez_integration_test.cpp)
+target_link_libraries(
+  simpleble_bluez_integration_test
+  PRIVATE radix_relay::radix_relay_warnings
+          radix_relay::radix_relay_options
+          radix_relay::transport
+          Catch2::Catch2WithMain)