Add C++ debugging example

cpp/debugging_example/.gitignore

@@ -0,0 +1,3 @@
+build/
+backend-run.sh
+oakapp.toml

cpp/debugging_example/.oakappignore

@@ -0,0 +1,10 @@
+# Build artifacts
+build/
+
+# Documentation
+README.md
+
+# VCS
+.git/
+.github/
+.gitlab/

cpp/debugging_example/.vscode/launch.json

@@ -0,0 +1,31 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach to OAK (gdbserver)",
+      "type": "cppdbg",
+      "request": "launch",
+      "preLaunchTask": "App debug (start)",
+      "postDebugTask": "oakctl: app stop",
+      "program": "${workspaceFolder}/build/main_device",
+      "cwd": "${workspaceFolder}",
+      "MIMode": "gdb",
+      "targetArchitecture": "arm64",
+      "miDebuggerArgs": "-x ${workspaceFolder}/.vscode/oak.gdb",
+      "stopAtEntry": false,
+      "externalConsole": false,
+      "sourceFileMap": {
+        "/app": "${workspaceFolder}/cpp/debugging_example"
+      }
+    },
+    {
+      "name": "Run on OAK (no debug)",
+      "type": "cppdbg",
+      "request": "launch",
+      "preLaunchTask": "App run",
+      "postDebugTask": "oakctl: app stop",
+      "program": "${workspaceFolder}/build/main_device",
+      "cwd": "${workspaceFolder}"
+    }
+  ]
+}

cpp/debugging_example/.vscode/oakapp.debug.toml

@@ -0,0 +1,23 @@
+identifier = "com.example.cpp.camera_stream"
+entrypoint = ["bash", "-c", "/usr/bin/runsvdir -P /etc/service"]
+app_version = "1.0.0"
+
+build_steps = [
+    "apt-get install -y --no-install-recommends gdb gdbserver",
+    "mkdir -p /etc/service/backend",
+    "cp /app/backend-run.sh /etc/service/backend/run",
+    "chmod +x /etc/service/backend/run",
+    "cmake -S /app -B /app/build -DCMAKE_BUILD_TYPE=Debug",
+    "cmake --build /app/build --parallel",
+]
+
+assign_frontend_port = false
+
+[base_image]
+api_url = "https://registry-1.docker.io"
+service = "registry.docker.io"
+oauth_url = "https://auth.docker.io/token"
+auth_type = "repository"
+auth_name = "luxonis/oakapp-base"
+image_name = "luxonis/oakapp-base"
+image_tag = "1.2.6-cpp"

cpp/debugging_example/.vscode/oakapp.run.toml

@@ -0,0 +1,22 @@
+identifier = "com.example.cpp.camera_stream"
+entrypoint = ["bash", "-c", "/usr/bin/runsvdir -P /etc/service"]
+app_version = "1.0.0"
+
+build_steps = [
+    "mkdir -p /etc/service/backend",
+    "cp /app/backend-run.sh /etc/service/backend/run",
+    "chmod +x /etc/service/backend/run",
+    "cmake -S /app -B /app/build",
+    "cmake --build /app/build --parallel",
+]
+
+assign_frontend_port = false
+
+[base_image]
+api_url = "https://registry-1.docker.io"
+service = "registry.docker.io"
+oauth_url = "https://auth.docker.io/token"
+auth_type = "repository"
+auth_name = "luxonis/oakapp-base"
+image_name = "luxonis/oakapp-base"
+image_tag = "1.2.6-cpp"

cpp/debugging_example/.vscode/tasks.json

@@ -0,0 +1,141 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "oakctl: ensure placeholder",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && mkdir -p build && touch build/main_device"
+      ],
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "App run",
+      "dependsOn": [
+        "oakctl: ensure placeholder",
+        "oakctl: prep",
+        "oakctl: connect",
+        "oakctl: select config (run)",
+        "oakctl: app run (fg)"
+      ],
+      "dependsOrder": "sequence",
+      "problemMatcher": []
+    },
+    {
+      "label": "App debug (start)",
+      "dependsOn": [
+        "oakctl: ensure placeholder",
+        "oakctl: prep",
+        "oakctl: connect",
+        "oakctl: select config (debug)",
+        "oakctl: app debug",
+        "oakctl: wait"
+      ],
+      "dependsOrder": "sequence",
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: prep",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && mkdir -p .vscode build && BOARD_IP_INPUT=\"${input:boardIP}\" && if [ -n \"$BOARD_IP_INPUT\" ]; then BOARD_IP=\"$BOARD_IP_INPUT\"; else echo \"No IP provided; running oakctl list...\"; oakctl list | tee .vscode/oak_list.txt; grep -Eo \"([0-9]{1,3}\\\\.){3}[0-9]{1,3}\" .vscode/oak_list.txt | sort -u > .vscode/oak_ips.txt || true; COUNT=$(wc -l < .vscode/oak_ips.txt | tr -d \" \" ); if [ \"$COUNT\" = \"0\" ]; then echo \"No OAK devices found via oakctl list and no IP provided.\" 1>&2; exit 1; fi; if [ \"$COUNT\" = \"1\" ]; then BOARD_IP=$(head -n 1 .vscode/oak_ips.txt); echo \"Auto-selected BOARD_IP=$BOARD_IP\"; else echo \"Multiple devices found. Select IP by number:\"; nl -w2 -s\": \" .vscode/oak_ips.txt; printf \"#? \"; read -r SEL; BOARD_IP=$(sed -n \"${SEL}p\" .vscode/oak_ips.txt); if [ -z \"$BOARD_IP\" ]; then echo \"Invalid selection.\" 1>&2; exit 1; fi; fi; fi && printf \"set pagination off\\ntarget extended-remote %s:5678\\nremote get /app/build/main \\\"%s/build/main_device\\\"\\nset substitute-path /app %s\\nexec-file \\\"%s/build/main_device\\\"\\n\" \"$BOARD_IP\" \"${workspaceFolder}\" \"${workspaceFolder}\" \"${workspaceFolder}\" > .vscode/oak.gdb && touch build/main_device && chmod +x build/main_device && echo \"Using BOARD_IP=$BOARD_IP\""
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: connect",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && echo \"Trying oakctl connect without password (will prompt only if needed)...\" && if oakctl connect $BOARD_IP; then echo \"Connected to $BOARD_IP (cached auth or no auth needed).\"; else echo \"Connect failed; prompting for password...\"; printf \"OAK password: \"; stty -echo; read -r OAK_PASS; stty echo; echo; oakctl -p \"$OAK_PASS\" connect $BOARD_IP; fi"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: select config (run)",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && if [ -f .vscode/oakapp.run.toml ]; then cp -f .vscode/oakapp.run.toml oakapp.toml; echo \"Selected .vscode/oakapp.run.toml -> oakapp.toml\"; else echo \".vscode/oakapp.run.toml not found; using existing oakapp.toml\"; fi && printf \"#!/bin/sh\\necho \\\"Starting Backend\\\"\\n/app/build/main\\n\" > backend-run.sh && chmod +x backend-run.sh"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: select config (debug)",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && if [ -f .vscode/oakapp.debug.toml ]; then cp -f .vscode/oakapp.debug.toml oakapp.toml; echo \"Selected .vscode/oakapp.debug.toml -> oakapp.toml\"; else echo \".vscode/oakapp.debug.toml not found; using existing oakapp.toml\"; fi && printf \"#!/bin/sh\\necho \\\"Starting Backend\\\"\\ngdbserver 0.0.0.0:5678 /app/build/main\\n\" > backend-run.sh && chmod +x backend-run.sh"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: app run (fg)",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && oakctl app run . -d $BOARD_IP"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: app debug",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && oakctl app run . -d $BOARD_IP -b"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: app run (bg)",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && oakctl app run . -d $BOARD_IP -b"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: wait",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && echo \"Waiting for gdbserver on ${BOARD_IP}:5678...\" && for i in $(seq 1 90); do (echo > /dev/tcp/${BOARD_IP}/5678) >/dev/null 2>&1 && echo \"gdbserver is up.\" && exit 0; sleep 1; done; echo \"Timeout waiting for gdbserver.\"; exit 1"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "oakctl: app stop",
+      "type": "shell",
+      "command": "bash",
+      "args": [
+        "-lc",
+        "cd ${workspaceFolder} && source .vscode/oak.env && oakctl app stop 00000000-0000-0000-0000-000000000000 -d $BOARD_IP"
+      ],
+      "problemMatcher": []
+    }
+  ],
+  "inputs": [
+    {
+      "id": "boardIP",
+      "type": "promptString",
+      "description": "Enter OAK board IP address (or leave empty to auto-detect via oakctl list)",
+      "default": "192.168.1.198"
+    }
+  ]
+}

cpp/debugging_example/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.20)
+
+project(camera_stream VERSION 1.0 LANGUAGES CXX)
+
+# Use C++17 standard
+set(CMAKE_CXX_STANDARD 17)
+
+# Depthai dependency
+find_package(depthai REQUIRED)
+message(STATUS "Found depthai: ${depthai_DIR}")
+
+# Add source files
+add_executable(main src/main.cpp)
+
+# Link with libraries
+target_link_libraries(main PUBLIC depthai::core)
+
+# Suppress warnings about C++17 ABI in GCC 10.1+
+target_compile_options(main PRIVATE -Wno-psabi)

cpp/debugging_example/README.md

@@ -0,0 +1,122 @@
+# Quick Start
+
+Follow these steps to enable remote debugging for your OAK C++ application.
+
+## Requirements
+
+### Open the Correct Folder
+
+You must open the **`debugging_example` directory itself as the VS Code workspace root**.
+
+Do **not** open the parent `oak-examples` directory. The debug configuration relies on `${workspaceFolder}` resolving to this example directory.
+
+### Install oakctl
+
+Debugging uses `oakctl` to discover devices and start applications on the device.
+
+Install `oakctl` by following the official documentation:
+
+https://docs.luxonis.com/software-v3/oak-apps/oakctl/
+
+Make sure the `oakctl` command is available in your terminal before starting debugging.
+
+______________________________________________________________________
+
+## 1. Install the VS Code C/C++ Extension
+
+Install the official Microsoft **C/C++ extension** for VS Code.
+
+Name: **C/C++**\
+VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools
+
+Or install from VS Code:
+
+1. Open **Extensions** (Ctrl+Shift+X)
+2. Search for **C/C++**
+3. Install **C/C++ (Microsoft)**
+
+This extension provides the `cppdbg` debugger used by this example.
+
+______________________________________________________________________
+
+## 2. Install GDB
+
+### Ubuntu
+
+Install the multi‑architecture GDB package:
+
+```bash
+sudo apt update
+sudo apt install gdb-multiarch
+```
+
+### macOS
+
+Install GDB with Homebrew:
+
+```bash
+brew install gdb
+```
+
+After installing on macOS, **remove the `miDebuggerPath` field** from `.vscode/launch.json` if it exists. The debugger will automatically use the system GDB.
+
+## 3. Start Debugging
+
+1. Open the `debugging_example` directory directly in VS Code.
+2. Press **F5** (Run → Start Debugging).
+3. Enter the **Device IP address** when prompted.
+   - If the field is left empty, the debugger will automatically run `oakctl list` to discover available devices and prompt you to select one.
+4. Enter the **Device password** if required.
+
+The debugger will automatically attach to the device.
+
+______________________________________________________________________
+
+## What Happens Behind the Scenes
+
+When you start debugging:
+
+- A local placeholder binary is created at:
+
+```
+build/main_device
+```
+
+(This is required by VS Code's C++ debugger validation step.)
+
+- Your device IP is written to:
+
+```
+.vscode/oak.env
+```
+
+This ensures the IP is stored locally and reused consistently across tasks.
+
+- A `.vscode/oak.gdb` file is generated dynamically.
+
+This file instructs GDB to:
+
+- Connect to `gdbserver` on the device
+
+- Pull the binary directly from the container
+
+- Reload symbols
+
+- Configure source path mapping
+
+- `oakctl` connects to the device and starts the application.
+
+- VS Code attaches GDB to `gdbserver` on port `5678`.
+
+All of this is automated through `tasks.json` and `launch.json`.
+
+______________________________________________________________________
+
+## Notes
+
+- The device IP is stored locally in `.vscode/oak.env` for consistency.
+- `.vscode/oak.gdb` is regenerated automatically when debugging starts.
+- No manual GDB commands are required.
+- No hardcoded paths are used — the setup relies entirely on `${workspaceFolder}`.
+
+This approach keeps the configuration minimal, reproducible, and portable across different OAK C++ projects.