ci: debug with tmate

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

.github/workflows/docs_metadata_check.yml

@@ -0,0 +1,47 @@
+name: Docs Metadata
+
+permissions:
+  contents: write
+
+on:
+  pull_request: {}
+
+jobs:
+  metadata-check:
+    name: ${{ matrix.name }}
+    runs-on: [runs-on,runner=2cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=true]
+    container:
+      image: ghcr.io/px4/px4-dev:v1.16.0-ondemand
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: uORB Graphs
+            script: Tools/ci/metadata_uorb_graph.sh
+          - name: Failsafe Web
+            script: Tools/ci/metadata_failsafe_web.sh --debug
+          - name: uORB Messages
+            script: Tools/ci/metadata_msg_docs.sh
+          - name: Parameter Reference
+            script: Tools/ci/metadata_parameters.sh
+          - name: Airframe Reference
+            script: Tools/ci/metadata_airframe.sh
+          - name: Module Reference
+            script: Tools/ci/metadata_modules.sh
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Mark all directories safe for Git
+        run: git config --system --add safe.directory '*'
+
+      - name: Run ${{ matrix.name }} metadata check
+        run: ${{ matrix.script }} --test-only
+
+      - name: Setup tmate session
+        if: ${{ failure() }}
+        uses: mxschmitt/action-tmate@v3

.gitignore

@@ -109,3 +109,6 @@ src/systemcmds/topic_listener/listener_generated.cpp
 # colcon
 log/
 keys/
+
+# metadata dependencies
+_emscripten_sdk/

Makefile

@@ -379,7 +379,10 @@ module_documentation:
 extract_events:
 	@$(MAKE) --no-print-directory px4_sitl_default metadata_extract_events ver_gen
 
-px4_metadata: parameters_metadata airframe_metadata module_documentation extract_events
+msg_docs:
+	@$(MAKE) --no-print-directory px4_sitl_default metadata_msg_documentation ver_gen
+
+px4_metadata: parameters_metadata airframe_metadata module_documentation extract_events msg_docs
 
 doxygen:
 	@mkdir -p "$(SRC_DIR)"/build/doxygen

Tools/ci/metadata_airframe.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# metadata_airframe.sh — generate and sync PX4 airframe reference documentation
+#
+# Usage:
+#   Tools/ci/metadata_airframe.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run make target and comparison; exit 1 if diffs found, without copying file
+#   --debug       Show full make output and debug info for comparison
+#
+set -euo pipefail
+shopt -s nullglob
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --test-only) test_only=true; shift ;;
+    --debug)     debug=true; shift ;;
+    *) echo "Usage: $0 [--test-only] [--debug]"; exit 2 ;;
+  esac
+done
+
+# Paths and make target
+make_target="airframe_metadata"
+src_file="build/px4_sitl_default/docs/airframes.md"
+dest_file="docs/en/airframes/airframe_reference.md"
+
+# Run make target
+if [ "$debug" = true ]; then
+  echo "🔧 Running 'make $make_target' (verbose)"
+  make $make_target
+else
+  echo "🔧 Running 'make $make_target'"
+  make $make_target > /dev/null 2>&1
+fi
+
+# Verify build output
+if [[ ! -f "$src_file" ]]; then
+  echo "❌ Generated file not found: $src_file"
+  exit 1
+fi
+
+echo "🔍 Comparing airframe reference docs"
+
+# Compare files
+if cmp -s "$src_file" "$dest_file"; then
+  echo "✅ Airframe reference is up to date."
+  exit 0
+else
+  if [ "$debug" = true ]; then
+    echo "DEBUG: cmp -s '$src_file' '$dest_file'; echo \$?"
+  fi
+  echo "⚠️ Airframe reference needs updating."
+  if [ "$test_only" = true ]; then
+    exit 1
+  fi
+  # Copy over updated file
+  echo "📂 Copying updated airframe_reference.md"
+  cp -v "$src_file" "$dest_file"
+  echo "🚨 Airframe docs updated; commit the change:"
+  echo "    git status -s $dest_file"
+  echo "    git add $dest_file"
+  echo "    git commit -m 'docs: update airframe reference metadata'"
+  exit 1
+fi

Tools/ci/metadata_failsafe_web.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+#
+# metadata_failsafe_web.sh — build and sync failsafe webapp metadata files
+#
+# Usage:
+#   Tools/ci/metadata_failsafe_web.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run build and comparison; exit 1 if diffs found, without copying files
+#   --debug       Show full build output and debug info for file comparisons and EMSDK install
+#
+set -euo pipefail
+shopt -s nullglob
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --test-only) test_only=true; shift ;;
+    --debug)     debug=true; shift ;;
+    *) echo "Usage: $0 [--test-only] [--debug]"; exit 2 ;;
+  esac
+done
+
+# Paths and commands
+build_cmd="make failsafe_web"
+src_dir="build/px4_sitl_default_failsafe_web"
+dest_dir="docs/public/config/failsafe"
+
+# Ensure Emscripten SDK is available
+if ! command -v emcc >/dev/null 2>&1; then
+  echo "🔧 Emscripten not found. Ensuring EMSDK is installed."
+  # Clone SDK only if not already present
+  if [ ! -d "_emscripten_sdk" ]; then
+    if [ "$debug" = true ]; then
+      git clone https://github.com/emscripten-core/emsdk.git _emscripten_sdk
+    else
+      git clone https://github.com/emscripten-core/emsdk.git _emscripten_sdk > /dev/null 2>&1
+    fi
+  fi
+  pushd _emscripten_sdk >/dev/null
+  if [ "$debug" = true ]; then
+    ./emsdk install latest
+    ./emsdk activate latest
+  else
+    ./emsdk install latest > /dev/null 2>&1
+    ./emsdk activate latest > /dev/null 2>&1
+  fi
+  popd >/dev/null
+  # Load environment into current shell
+  if [ "$debug" = true ]; then
+    # shellcheck source=/dev/null
+    . ./_emscripten_sdk/emsdk_env.sh
+  else
+    # shellcheck source=/dev/null
+    . ./_emscripten_sdk/emsdk_env.sh > /dev/null 2>&1
+  fi
+fi
+
+# Build step
+if [ "$debug" = true ]; then
+  echo "🔧 Running build: $build_cmd"
+  $build_cmd
+else
+  echo "🔧 Running build"
+  $build_cmd > /dev/null 2>&1
+fi
+
+# Gather built files
+src_files=("$src_dir"/*.{js,wasm,json})
+if [ ${#src_files[@]} -eq 0 ]; then
+  echo "❌ No generated files found in $src_dir. Build failed or path wrong."
+  exit 1
+fi
+
+# Prepare destination
+echo "🔍 Checking failsafe web metadata"
+mkdir -p "$dest_dir"
+
+changed=()
+for src in "${src_files[@]}"; do
+  name=$(basename "$src")
+  dst="$dest_dir/$name"
+
+  if [[ ! -f "$dst" ]]; then
+    [ "$debug" = true ] && echo "DEBUG: missing $dst"
+    changed+=("$name")
+  elif ! cmp -s "$src" "$dst"; then
+    [ "$debug" = true ] && echo "DEBUG: cmp -s '$src' '$dst'; echo \$?"
+    changed+=("$name")
+  fi
+done
+
+if [ ${#changed[@]} -eq 0 ]; then
+  echo "✅ All failsafe web metadata files are in sync."
+  exit 0
+fi
+
+echo "⚠️ Detected updates in:"
+for f in "${changed[@]}"; do echo "  - $f"; done
+
+if [ "$test_only" = true ]; then
+  echo "🚨 Failsafe web metadata needs update; rerun without --test-only to apply."
+  exit 1
+fi
+
+echo "📂 Copying updated files"
+for f in "${changed[@]}"; do cp -v "$src_dir/$f" "$dest_dir/$f"; done
+
+echo "🚨 Failsafe web metadata updated; please commit changes."
+exit 1

Tools/ci/metadata_modules.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+#
+# metadata_modules.sh - generate and sync PX4 module reference documentation
+#
+# Usage:
+#   Tools/ci/metadata_modules.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run make target and comparison; exit 1 if diffs found, without copying files
+#   --debug       Show full make output and debug info for file comparisons
+#
+set -euo pipefail
+shopt -s nullglob
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --test-only) test_only=true; shift ;;
+    --debug)     debug=true; shift ;;
+    *) echo "Usage: $0 [--test-only] [--debug]"; exit 2 ;;
+  esac
+done
+
+# Paths and make target
+make_target="module_documentation"
+src_dir="build/px4_sitl_default/docs/modules"
+dest_dir="docs/en/modules"
+
+# Run make target
+if [ "$debug" = true ]; then
+  echo "🔧 Running 'make $make_target' (verbose)"
+  make $make_target
+else
+  echo "🔧 Running 'make $make_target'"
+  make $make_target > /dev/null 2>&1
+fi
+
+# Verify build output
+src_files=("$src_dir"/*)
+if [ ${#src_files[@]} -eq 0 ]; then
+  echo "❌ No generated module docs found in $src_dir. Build failed or path wrong."
+  exit 1
+fi
+
+# ─── Strip trailing whitespace from all generated module docs (unless test-only) ─────────────
+if [ "$test_only" = false ]; then
+  echo "✂️ Removing trailing whitespace from generated module docs"
+  for src in "${src_files[@]}"; do
+    sed -i 's/[[:space:]]\+$//' "$src"
+  done
+else
+  [ "$debug" = true ] && echo "🧪 Test-only mode: skipping whitespace removal"
+fi
+
+echo "🔍 Checking module reference docs in $dest_dir"
+mkdir -p "$dest_dir"
+
+changed=()
+for src in "${src_files[@]}"; do
+  name=$(basename "$src")
+  dst="$dest_dir/$name"
+
+  if [[ ! -e "$dst" ]]; then
+    [ "$debug" = true ] && echo "DEBUG: missing $dst"
+    changed+=("$name")
+  else
+    # Use diff -q -b (ignore whitespace changes) and --strip-trailing-cr (ignore CRLF vs LF)
+    if ! diff -q -b --strip-trailing-cr "$src" "$dst" > /dev/null; then
+      [ "$debug" = true ] && echo "DEBUG: diff -q -b --strip-trailing-cr '$src' '$dst'  (exit_code=$?)"
+      changed+=("$name")
+    fi
+  fi
+done
+
+if [ ${#changed[@]} -eq 0 ]; then
+  echo "✅ All module reference docs are up to date."
+  exit 0
+fi
+
+echo "⚠️ Detected updates in module docs:"
+for f in "${changed[@]}"; do echo "  - $f"; done
+
+if [ "$test_only" = true ]; then
+  echo "🚨 Module reference docs need updating; rerun without --test-only to apply."
+  exit 1
+fi
+
+echo "📂 Copying updated module docs to $dest_dir"
+for f in "${changed[@]}"; do
+  cp -rv "$src_dir/$f" "$dest_dir/$f"
+done
+
+echo "🚨 Module reference docs updated; please commit changes:"
+echo "    git status -s $dest_dir"
+echo "    git add $dest_dir/*"
+echo "    git commit -m 'docs: update module reference metadata'"
+exit 1

Tools/ci/metadata_msg_docs.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# metadata_msg_docs.sh — generate and sync uORB message reference documentation
+#
+# Usage:
+#   Tools/ci/metadata_msg_docs.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run make target and comparison; exit 1 if diffs found, without copying files
+#   --debug       Show full make output and debug info for file comparisons
+#
+set -euo pipefail
+shopt -s nullglob
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --test-only) test_only=true; shift ;;
+    --debug)     debug=true; shift ;;
+    *) echo "Usage: $0 [--test-only] [--debug]"; exit 2 ;;
+  esac
+done
+
+# Paths and make target
+make_target="msg_docs"
+src_dir="build/px4_sitl_default/msg_docs"
+dest_dir="docs/en/msg_docs"
+middleware_dir="docs/en/middleware"
+
+# Run make target
+if [ "$debug" = true ]; then
+  echo "🔧 Running 'make $make_target' (verbose)"
+  make $make_target
+else
+  echo "🔧 Running 'make $make_target'"
+  make $make_target > /dev/null 2>&1
+fi
+
+# Verify build output
+src_files=("$src_dir"/*)
+if [ ${#src_files[@]} -eq 0 ]; then
+  echo "❌ No files found in $src_dir. Build target '$make_target' failed or path is wrong."
+  exit 1
+fi
+
+echo "🔍 Checking uORB message docs in $dest_dir"
+mkdir -p "$dest_dir"
+
+changed=()
+for src in "${src_files[@]}"; do
+  name=$(basename "$src")
+
+  # special-case dds_topics.md
+  if [[ "$name" == "dds_topics.md" ]]; then
+    dst="$middleware_dir/$name"
+  else
+    dst="$dest_dir/$name"
+  fi
+
+  if [[ ! -f "$dst" ]]; then
+    [ "$debug" = true ] && echo "DEBUG: missing $dst"
+    changed+=("$name")
+  elif ! cmp -s "$src" "$dst"; then
+    [ "$debug" = true ] && echo "DEBUG: cmp -s '$src' '$dst'; echo \$?"
+    changed+=("$name")
+  fi
+done
+
+if [ ${#changed[@]} -eq 0 ]; then
+  echo "✅ All uORB message docs are up to date."
+  exit 0
+fi
+
+echo "⚠️ Detected updates in the following docs:"
+for f in "${changed[@]}"; do echo "  - $f"; done
+
+if [ "$test_only" = true ]; then
+  echo "🚨 uORB message docs need updating! Rerun without --test-only to apply changes."
+  exit 1
+fi
+
+echo "📂 Copying updated doc files to $dest_dir"
+for f in "${changed[@]}"; do
+  if [[ "$f" == "dds_topics.md" ]]; then
+    cp -v "$src_dir/$f" "$middleware_dir/$f"
+  else
+    cp -v "$src_dir/$f" "$dest_dir/$f"
+  fi
+done
+
+echo "🚨 uORB message docs updated; please commit changes:"
+echo "    git status -s $dest_dir"
+echo "    git add $dest_dir/*"
+echo "    git commit -m 'docs: update uORB message reference docs'"
+exit 1

Tools/ci/metadata_parameters.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# metadata_parameters.sh — generate and sync PX4 parameter reference documentation
+#
+# Usage:
+#   Tools/ci/metadata_parameters.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run make target and comparison; exit 1 if diffs found, without copying file
+#   --debug       Show full make output and debug info for comparison
+#
+set -euo pipefail
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --test-only) test_only=true; shift ;;
+    --debug)     debug=true; shift ;;
+    *) echo "Usage: $0 [--test-only] [--debug]"; exit 2 ;;
+  esac
+done
+
+# Paths and make target
+make_target="parameters_metadata"
+src_file="build/px4_sitl_default/docs/parameters.md"
+dest_file="docs/en/advanced_config/parameter_reference.md"
+
+# Run make target
+if [ "$debug" = true ]; then
+  echo "🔧 Running 'make $make_target' (verbose)"
+  make $make_target
+else
+  echo "🔧 Running 'make $make_target'"
+  make $make_target > /dev/null 2>&1
+fi
+
+# ─── Strip trailing whitespace from the newly generated Markdown ────────────────────────────────
+echo "✂️ Removing trailing whitespace from $src_file"
+sed -i 's/[[:space:]]\+$//' "$src_file"
+
+# Verify build output
+if [[ ! -f "$src_file" ]]; then
+  echo "❌ Generated file not found: $src_file"
+  exit 1
+fi
+
+echo "🔍 Comparing parameter docs"
+
+# Compare files
+if cmp -s "$src_file" "$dest_file"; then
+  echo "✅ Parameter reference is up to date."
+  exit 0
+else
+  if [ "$debug" = true ]; then
+    echo "DEBUG: cmp -s '$src_file' '$dest_file'; echo \$?"
+  fi
+  echo "⚠️ Parameter reference needs updating."
+  if [ "$test_only" = true ]; then
+    exit 1
+  fi
+  # Copy over updated file
+  echo "📂 Copying updated parameter_reference.md"
+  cp -v "$src_file" "$dest_file"
+  echo "🚨 Parameter docs updated; commit the change:"
+  echo "    git status -s $dest_file"
+  echo "    git add $dest_file"
+  echo "    git commit -m 'docs: update parameter reference metadata'"
+  exit 1
+fi

Tools/ci/metadata_uorb_graph.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+#
+# update_uorb_graphs.sh — generate, compare, and sync uORB graph JSONs
+#
+# Usage:
+#   ./scripts/update_uorb_graphs.sh [--test-only] [--debug]
+#
+# Options:
+#   --test-only   Run generation and comparison only; exit 1 if diffs found, without copying files
+#   --debug       Echo debug info for missing or differing files and show full make output
+#
+# Examples:
+#   # CI mode: fail if docs need updates
+#   ./scripts/update_uorb_graphs.sh --test-only
+#
+#   # Developer mode: regenerate and sync JSONs
+#   ./scripts/update_uorb_graphs.sh
+#
+set -euo pipefail
+
+shopt -s nullglob
+
+# Parse flags
+test_only=false
+debug=false
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+		--test-only)
+			test_only=true
+			shift
+			;;
+		--debug)
+			debug=true
+			shift
+			;;
+		*)
+			echo "Usage: $0 [--test-only] [--debug]"
+			exit 2
+			;;
+	esac
+done
+
+# Paths
+graph_dir="Tools/uorb_graph"
+dest_dir="docs/public/middleware"
+
+# Generate uORB graphs (conditionally silent)
+if [ "$debug" = true ]; then
+	echo "🔧 Generating uORB message graphs (verbose output)"
+	make uorb_graphs
+else
+	echo "🔧 Generating uORB message graphs"
+	make uorb_graphs > /dev/null 2>&1
+fi
+
+# Verify generation
+src_files=("$graph_dir"/*.json)
+if [ ${#src_files[@]} -eq 0 ]; then
+	echo "❌ No JSON files found in $graph_dir. Generation failed or path is wrong."
+	exit 1
+fi
+
+echo "🔍 Checking for updated uORB graph JSONs"
+mkdir -p "$dest_dir"
+
+changed=()
+for src in "${src_files[@]}"; do
+	name=$(basename "$src")
+	dst="$dest_dir/$name"
+
+	if [[ ! -f "$dst" ]]; then
+		[ "$debug" = true ] && echo "DEBUG: $dst missing"
+		changed+=("$name")
+
+	elif ! cmp -s "$src" "$dst"; then
+		[ "$debug" = true ] && echo "DEBUG: cmp -s '$src' '$dst'; echo \$?"
+		changed+=("$name")
+	fi
+done
+
+if [ ${#changed[@]} -eq 0 ]; then
+	echo "✅ All uORB graph JSONs are already in sync."
+	exit 0
+fi
+
+echo "⚠️ Detected updates in the following files:"
+for name in "${changed[@]}"; do
+	echo "	- $name"
+done
+
+if [ "$test_only" = true ]; then
+	echo
+	echo "🚨 uORB graph docs need updating! Rerun without --test-only to apply changes."
+	exit 1
+fi
+
+echo
+echo "📂 Copying updated files over"
+for name in "${changed[@]}"; do
+	cp -v "$graph_dir/$name" "$dest_dir/$name"
+done
+
+echo
+echo "🚨 uORB graph docs need updating! Review above, then run:"
+echo "	git status -s $dest_dir/"
+echo "	git add $dest_dir/*.json"
+echo "	git commit -m 'docs: metadata: update uORB graph JSONs'"
+exit 1

Tools/msg/generate_msg_docs.py

@@ -12,14 +12,25 @@ import sys
 
 import yaml
 
-def generate_dds_yaml_doc(allMessageFiles, output_file = 'dds_topics.md'):
+def sort_dds_topics(topics):
+    return sorted(
+        topics,
+        key=lambda pub: pub["type"].rsplit("::", 1)[-1]
+    )
+
+def generate_dds_yaml_doc(allMessageFiles, output_dir):
     """
     Generates human readable version of dds_topics.yaml.
     Default output is to docs/en/middleware/dds_topics.md
     """
+    output_file = 'dds_topics.md'
+    dds_markdown = ""
+    if not os.path.isdir(output_dir):
+        print("Output directory not found")
+        sys.exit(1)
 
     dds_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),"../../src/modules/uxrce_dds_client/dds_topics.yaml")
-    output_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),f"../../docs/en/middleware/{output_file}")
+    output_file_path = os.path.join(output_dir, output_file)
 
     try:
         with open(dds_file_path, 'r') as file:
@@ -43,7 +54,7 @@ def generate_dds_yaml_doc(allMessageFiles, output_file = 'dds_topics.md'):
                 all_topics.add(message['topic'].split('/')[-1])
         for message in allMessageFiles:
             all_messages_in_source.add(message.split('/')[-1].split('.')[0])
-        messagesNotExported = all_messages_in_source - all_message_types
+        messagesNotExported = sorted(all_messages_in_source - all_message_types)
 
         # write out the dds file
         dds_markdown="""# dds_topics.yaml — PX4 Topics Exposed to ROS 2
@@ -63,14 +74,14 @@ Topic | Type| Rate Limit
 --- | --- | ---
 """
 
-        for message in data["publications"]:
+        for message in sort_dds_topics(data["publications"]):
             type = message['type']
             px4Type=type.split("::")[-1]
             dds_markdown += f"`{message['topic']}` | [{type}](../msg_docs/{px4Type}.md) | {message.get('rate_limit','')}\n"
 
         dds_markdown += "\n## Subscriptions\n\nTopic | Type\n--- | ---\n"
 
-        for message in data["subscriptions"]:
+        for message in sort_dds_topics(data["subscriptions"]):
             type = message['type']
             px4Type=type.split("::")[-1]
             dds_markdown += f"{message['topic']} | [{type}](../msg_docs/{px4Type}.md)\n"
@@ -82,18 +93,17 @@ Topic | Type| Rate Limit
         else:
             print("Warning - we now have subscription_multi data - check format")
             dds_markdown += "Topic | Type\n--- | ---\n"
-            for message in data["subscriptions_multi"]:
+            for message in sort_dds_topics(data["subscriptions_multi"]):
                 dds_markdown += f"{message['topic']} | {message['type']}\n"
 
         if messagesNotExported:
             # Print the topics that are not exported to DDS
             dds_markdown += "\n## Not Exported\n\nThese messages are not listed in the yaml file.\nThey are not build into the module, and hence are neither published or subscribed."
             dds_markdown += "\n\n::: details See messages\n"
-            for item in  messagesNotExported:
+            for item in sorted(messagesNotExported):
                 dds_markdown += f"\n- [{item}](../msg_docs/{item}.md)"
             dds_markdown += "\n:::\n" # End of details block
 
-        #print(dds_markdown)
         with open(output_file_path, 'w') as content_file:
                 content_file.write(dds_markdown)
 
@@ -127,6 +137,7 @@ if __name__ == "__main__":
 
     parser = argparse.ArgumentParser(description='Generate docs from .msg files')
     parser.add_argument('-d', dest='dir', help='output directory', required=True)
+    parser.add_argument('--dds_topics', dest='dds_topics', help='Generate dds yaml doc', action='store_true')
     args = parser.parse_args()
 
     output_dir = args.dir
@@ -137,6 +148,9 @@ if __name__ == "__main__":
     msg_files = get_msgs_list(msg_path)
     msg_files.sort()
 
+    if args.dds_topics:
+        generate_dds_yaml_doc(msg_files, output_dir)
+
     versioned_msgs_list = ''
     unversioned_msgs_list = ''
 
@@ -227,5 +241,3 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m
     index_file = os.path.join(output_dir, 'index.md')
     with open(index_file, 'w') as content_file:
             content_file.write(index_text)
-
-    generate_dds_yaml_doc(msg_files)

Tools/uorb_graph/create.py

@@ -59,7 +59,7 @@ def get_N_colors(N, s=0.8, v=0.9):
 def topic_filename(topic):
     MSG_PATH = 'msg/'
 
-    file_list = os.listdir(MSG_PATH)
+    file_list = sorted(os.listdir(MSG_PATH))
     msg_files = [file.replace('.msg', '') for file in file_list if file.endswith(".msg")]
 
     if topic in msg_files:
@@ -369,12 +369,14 @@ class Graph(object):
             if not scope.is_empty():
                 scopes_with_topic[name] = scope
 
+        # scopes_with_topic = sorted(scopes_with_topic)
+
         self._print_ambiguities = ambiguous_topics
         if use_topic_pubsub_union:
-            self._print_topics = subscribed_topics | published_topics
+            self._print_topics = sorted(subscribed_topics | published_topics)
             self._print_scopes = scopes_with_topic
         else:
-            self._print_topics = subscribed_topics & published_topics
+            self._print_topics = sorted(subscribed_topics & published_topics)
 
             # cull scopes to only those that pub or sub to a topic that has both
             intersect_scopes = {}
@@ -392,7 +394,7 @@ class Graph(object):
             log.debug('ignoring excluded path '+path)
             return
 
-        entries = os.listdir(path)
+        entries = sorted(os.listdir(path))
 
         # check if entering a new scope
         cmake_file = 'CMakeLists.txt'
@@ -685,8 +687,8 @@ class OutputJSON(object):
 
 
         # edges
-        for name,scope in output_scopes.items():
-            for topic in scope.publications:
+        for name,scope in sorted(output_scopes.items(), key=lambda kv: kv[0]):
+            for topic in sorted(scope.publications):
                 if topic in output_topics:
                     edge = {}
                     edge['source'] = 'm_'+name
@@ -695,8 +697,8 @@ class OutputJSON(object):
                     edge['style'] = 'dashed'
                     edges.append(edge)
 
-        for name,scope in output_scopes.items():
-            for topic in scope.subscriptions:
+        for name,scope in sorted(output_scopes.items(), key=lambda kv: kv[0]):
+            for topic in sorted(scope.subscriptions):
                 if topic in output_topics:
                     edge = {}
                     edge['source'] = 't_'+topic
@@ -723,10 +725,16 @@ if "__main__" == __name__:
             log.setLevel(logging.DEBUG)
             print("set log level to DEBUG")
 
+
+    print('')
+    print('== Starting uorb_graph/create.py ==')
+    if args.file:
+        print('  =Filename:', os.path.basename(args.file))
+
     # ignore topics that are subscribed/published by many topics, but are not really
     # useful to show in the graph
     topic_blacklist = [ 'parameter_update', 'mavlink_log', 'log_message' ]
-    print('Excluded topics: '+str(topic_blacklist))
+    print('  =Excluded Topics: '+str(topic_blacklist))
 
     if len(args.modules) == 0:
         scope_whitelist = []
@@ -757,7 +765,7 @@ if "__main__" == __name__:
     if 0 < len(args.exclude_path):
         path_blacklist = args.exclude_path
     if path_blacklist:
-        print('Excluded Path: '+str(path_blacklist))
+        print('  =Excluded Path: '+str(path_blacklist))
 
     graph.build(source_paths, path_blacklist=path_blacklist, use_topic_pubsub_union=args.use_topic_union, merge_depends=args.merge_depends)
 
@@ -784,3 +792,6 @@ if "__main__" == __name__:
         pass
     else:
         print('Error: unknown output format '+args.output)
+
+    print("== Completed uorb_graph/create.py ==")
+    print("")

cmake/metadata.cmake

@@ -116,10 +116,18 @@ add_custom_target(metadata_extract_events
 	USES_TERMINAL
 )
 
+add_custom_target(metadata_msg_documentation
+	COMMAND ${CMAKE_COMMAND} -E make_directory ${PX4_BINARY_DIR}/msg_docs
+	COMMAND ${PYTHON_EXECUTABLE} ${PX4_SOURCE_DIR}/Tools/msg/generate_msg_docs.py --dds_topics -d ${PX4_BINARY_DIR}/msg_docs
+	COMMENT "Generating uORB message documentation"
+	USES_TERMINAL
+)
+
 add_custom_target(all_metadata
 	DEPENDS
 		metadata_airframes
 		metadata_parameters
 		metadata_module_documentation
 		metadata_extract_events
+		metadata_msg_documentation
 )

docs/en/SUMMARY.md

@@ -730,6 +730,7 @@
       - [Protocols/Microservices](mavlink/protocols.md)
         - [Standard Modes Protocol](mavlink/standard_modes.md)
     - [uXRCE-DDS (PX4-ROS 2/DDS Bridge)](middleware/uxrce_dds.md)
+      - [DDS Topic List](middleware/dds_topics.md)
   - [Modules & Commands](modules/modules_main.md)
     - [Autotune](modules/modules_autotune.md)
     - [Commands](modules/modules_command.md)

docs/en/middleware/dds_topics.md

@@ -0,0 +1,276 @@
+# dds_topics.yaml — PX4 Topics Exposed to ROS 2
+
+::: info
+This document is [auto-generated](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/msg/generate_msg_docs.py) from the source code.
+:::
+
+
+The [dds_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml) file specifies which uORB message definitions are compiled into the [uxrce_dds_client](../modules/modules_system.md#uxrce-dds-client) module when [PX4 is built](../middleware/uxrce_dds.md#code-generation), and hence which topics are available for ROS 2 applications to subscribe or publish (by default).
+
+This document shows a markdown-rendered version of [dds_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml), listing the publications, subscriptions, and so on.
+
+## Publications
+
+Topic | Type| Rate Limit
+--- | --- | ---
+`/fmu/out/airspeed_validated` | [px4_msgs::msg::AirspeedValidated](../msg_docs/AirspeedValidated.md) | 50.0
+`/fmu/out/arming_check_request` | [px4_msgs::msg::ArmingCheckRequest](../msg_docs/ArmingCheckRequest.md) | 5.0
+`/fmu/out/battery_status` | [px4_msgs::msg::BatteryStatus](../msg_docs/BatteryStatus.md) | 1.0
+`/fmu/out/collision_constraints` | [px4_msgs::msg::CollisionConstraints](../msg_docs/CollisionConstraints.md) | 50.0
+`/fmu/out/estimator_status_flags` | [px4_msgs::msg::EstimatorStatusFlags](../msg_docs/EstimatorStatusFlags.md) | 5.0
+`/fmu/out/failsafe_flags` | [px4_msgs::msg::FailsafeFlags](../msg_docs/FailsafeFlags.md) | 5.0
+`/fmu/out/home_position` | [px4_msgs::msg::HomePosition](../msg_docs/HomePosition.md) | 5.0
+`/fmu/out/manual_control_setpoint` | [px4_msgs::msg::ManualControlSetpoint](../msg_docs/ManualControlSetpoint.md) | 25.0
+`/fmu/out/message_format_response` | [px4_msgs::msg::MessageFormatResponse](../msg_docs/MessageFormatResponse.md) | 
+`/fmu/out/mode_completed` | [px4_msgs::msg::ModeCompleted](../msg_docs/ModeCompleted.md) | 50.0
+`/fmu/out/position_setpoint_triplet` | [px4_msgs::msg::PositionSetpointTriplet](../msg_docs/PositionSetpointTriplet.md) | 5.0
+`/fmu/out/register_ext_component_reply` | [px4_msgs::msg::RegisterExtComponentReply](../msg_docs/RegisterExtComponentReply.md) | 
+`/fmu/out/sensor_combined` | [px4_msgs::msg::SensorCombined](../msg_docs/SensorCombined.md) | 
+`/fmu/out/vehicle_gps_position` | [px4_msgs::msg::SensorGps](../msg_docs/SensorGps.md) | 50.0
+`/fmu/out/timesync_status` | [px4_msgs::msg::TimesyncStatus](../msg_docs/TimesyncStatus.md) | 10.0
+`/fmu/out/vehicle_attitude` | [px4_msgs::msg::VehicleAttitude](../msg_docs/VehicleAttitude.md) | 
+`/fmu/out/vehicle_command_ack` | [px4_msgs::msg::VehicleCommandAck](../msg_docs/VehicleCommandAck.md) | 
+`/fmu/out/vehicle_control_mode` | [px4_msgs::msg::VehicleControlMode](../msg_docs/VehicleControlMode.md) | 50.0
+`/fmu/out/vehicle_global_position` | [px4_msgs::msg::VehicleGlobalPosition](../msg_docs/VehicleGlobalPosition.md) | 50.0
+`/fmu/out/vehicle_land_detected` | [px4_msgs::msg::VehicleLandDetected](../msg_docs/VehicleLandDetected.md) | 5.0
+`/fmu/out/vehicle_local_position` | [px4_msgs::msg::VehicleLocalPosition](../msg_docs/VehicleLocalPosition.md) | 50.0
+`/fmu/out/vehicle_odometry` | [px4_msgs::msg::VehicleOdometry](../msg_docs/VehicleOdometry.md) | 
+`/fmu/out/vehicle_status` | [px4_msgs::msg::VehicleStatus](../msg_docs/VehicleStatus.md) | 5.0
+`/fmu/out/vtol_vehicle_status` | [px4_msgs::msg::VtolVehicleStatus](../msg_docs/VtolVehicleStatus.md) | 
+
+## Subscriptions
+
+Topic | Type
+--- | ---
+/fmu/in/actuator_motors | [px4_msgs::msg::ActuatorMotors](../msg_docs/ActuatorMotors.md)
+/fmu/in/actuator_servos | [px4_msgs::msg::ActuatorServos](../msg_docs/ActuatorServos.md)
+/fmu/in/arming_check_reply | [px4_msgs::msg::ArmingCheckReply](../msg_docs/ArmingCheckReply.md)
+/fmu/in/config_overrides_request | [px4_msgs::msg::ConfigOverrides](../msg_docs/ConfigOverrides.md)
+/fmu/in/distance_sensor | [px4_msgs::msg::DistanceSensor](../msg_docs/DistanceSensor.md)
+/fmu/in/fixed_wing_lateral_setpoint | [px4_msgs::msg::FixedWingLateralSetpoint](../msg_docs/FixedWingLateralSetpoint.md)
+/fmu/in/fixed_wing_longitudinal_setpoint | [px4_msgs::msg::FixedWingLongitudinalSetpoint](../msg_docs/FixedWingLongitudinalSetpoint.md)
+/fmu/in/goto_setpoint | [px4_msgs::msg::GotoSetpoint](../msg_docs/GotoSetpoint.md)
+/fmu/in/lateral_control_configuration | [px4_msgs::msg::LateralControlConfiguration](../msg_docs/LateralControlConfiguration.md)
+/fmu/in/longitudinal_control_configuration | [px4_msgs::msg::LongitudinalControlConfiguration](../msg_docs/LongitudinalControlConfiguration.md)
+/fmu/in/manual_control_input | [px4_msgs::msg::ManualControlSetpoint](../msg_docs/ManualControlSetpoint.md)
+/fmu/in/message_format_request | [px4_msgs::msg::MessageFormatRequest](../msg_docs/MessageFormatRequest.md)
+/fmu/in/mode_completed | [px4_msgs::msg::ModeCompleted](../msg_docs/ModeCompleted.md)
+/fmu/in/obstacle_distance | [px4_msgs::msg::ObstacleDistance](../msg_docs/ObstacleDistance.md)
+/fmu/in/offboard_control_mode | [px4_msgs::msg::OffboardControlMode](../msg_docs/OffboardControlMode.md)
+/fmu/in/onboard_computer_status | [px4_msgs::msg::OnboardComputerStatus](../msg_docs/OnboardComputerStatus.md)
+/fmu/in/register_ext_component_request | [px4_msgs::msg::RegisterExtComponentRequest](../msg_docs/RegisterExtComponentRequest.md)
+/fmu/in/sensor_optical_flow | [px4_msgs::msg::SensorOpticalFlow](../msg_docs/SensorOpticalFlow.md)
+/fmu/in/telemetry_status | [px4_msgs::msg::TelemetryStatus](../msg_docs/TelemetryStatus.md)
+/fmu/in/trajectory_setpoint | [px4_msgs::msg::TrajectorySetpoint](../msg_docs/TrajectorySetpoint.md)
+/fmu/in/unregister_ext_component | [px4_msgs::msg::UnregisterExtComponent](../msg_docs/UnregisterExtComponent.md)
+/fmu/in/vehicle_attitude_setpoint | [px4_msgs::msg::VehicleAttitudeSetpoint](../msg_docs/VehicleAttitudeSetpoint.md)
+/fmu/in/vehicle_command | [px4_msgs::msg::VehicleCommand](../msg_docs/VehicleCommand.md)
+/fmu/in/vehicle_command_mode_executor | [px4_msgs::msg::VehicleCommand](../msg_docs/VehicleCommand.md)
+/fmu/in/config_control_setpoints | [px4_msgs::msg::VehicleControlMode](../msg_docs/VehicleControlMode.md)
+/fmu/in/aux_global_position | [px4_msgs::msg::VehicleGlobalPosition](../msg_docs/VehicleGlobalPosition.md)
+/fmu/in/vehicle_mocap_odometry | [px4_msgs::msg::VehicleOdometry](../msg_docs/VehicleOdometry.md)
+/fmu/in/vehicle_visual_odometry | [px4_msgs::msg::VehicleOdometry](../msg_docs/VehicleOdometry.md)
+/fmu/in/vehicle_rates_setpoint | [px4_msgs::msg::VehicleRatesSetpoint](../msg_docs/VehicleRatesSetpoint.md)
+/fmu/in/vehicle_thrust_setpoint | [px4_msgs::msg::VehicleThrustSetpoint](../msg_docs/VehicleThrustSetpoint.md)
+/fmu/in/vehicle_torque_setpoint | [px4_msgs::msg::VehicleTorqueSetpoint](../msg_docs/VehicleTorqueSetpoint.md)
+
+## Subscriptions Multi
+
+None
+
+## Not Exported
+
+These messages are not listed in the yaml file.
+They are not build into the module, and hence are neither published or subscribed.
+
+::: details See messages
+
+- [ActionRequest](../msg_docs/ActionRequest.md)
+- [ActuatorArmed](../msg_docs/ActuatorArmed.md)
+- [ActuatorControlsStatus](../msg_docs/ActuatorControlsStatus.md)
+- [ActuatorOutputs](../msg_docs/ActuatorOutputs.md)
+- [ActuatorServosTrim](../msg_docs/ActuatorServosTrim.md)
+- [ActuatorTest](../msg_docs/ActuatorTest.md)
+- [AdcReport](../msg_docs/AdcReport.md)
+- [Airspeed](../msg_docs/Airspeed.md)
+- [AirspeedValidatedV0](../msg_docs/AirspeedValidatedV0.md)
+- [AirspeedWind](../msg_docs/AirspeedWind.md)
+- [ArmingCheckReplyV0](../msg_docs/ArmingCheckReplyV0.md)
+- [AutotuneAttitudeControlStatus](../msg_docs/AutotuneAttitudeControlStatus.md)
+- [ButtonEvent](../msg_docs/ButtonEvent.md)
+- [CameraCapture](../msg_docs/CameraCapture.md)
+- [CameraStatus](../msg_docs/CameraStatus.md)
+- [CameraTrigger](../msg_docs/CameraTrigger.md)
+- [CanInterfaceStatus](../msg_docs/CanInterfaceStatus.md)
+- [CellularStatus](../msg_docs/CellularStatus.md)
+- [ControlAllocatorStatus](../msg_docs/ControlAllocatorStatus.md)
+- [Cpuload](../msg_docs/Cpuload.md)
+- [DatamanRequest](../msg_docs/DatamanRequest.md)
+- [DatamanResponse](../msg_docs/DatamanResponse.md)
+- [DebugArray](../msg_docs/DebugArray.md)
+- [DebugKeyValue](../msg_docs/DebugKeyValue.md)
+- [DebugValue](../msg_docs/DebugValue.md)
+- [DebugVect](../msg_docs/DebugVect.md)
+- [DifferentialPressure](../msg_docs/DifferentialPressure.md)
+- [DistanceSensorModeChangeRequest](../msg_docs/DistanceSensorModeChangeRequest.md)
+- [Ekf2Timestamps](../msg_docs/Ekf2Timestamps.md)
+- [EscReport](../msg_docs/EscReport.md)
+- [EscStatus](../msg_docs/EscStatus.md)
+- [EstimatorAidSource1d](../msg_docs/EstimatorAidSource1d.md)
+- [EstimatorAidSource2d](../msg_docs/EstimatorAidSource2d.md)
+- [EstimatorAidSource3d](../msg_docs/EstimatorAidSource3d.md)
+- [EstimatorBias](../msg_docs/EstimatorBias.md)
+- [EstimatorBias3d](../msg_docs/EstimatorBias3d.md)
+- [EstimatorEventFlags](../msg_docs/EstimatorEventFlags.md)
+- [EstimatorGpsStatus](../msg_docs/EstimatorGpsStatus.md)
+- [EstimatorInnovations](../msg_docs/EstimatorInnovations.md)
+- [EstimatorSelectorStatus](../msg_docs/EstimatorSelectorStatus.md)
+- [EstimatorSensorBias](../msg_docs/EstimatorSensorBias.md)
+- [EstimatorStates](../msg_docs/EstimatorStates.md)
+- [EstimatorStatus](../msg_docs/EstimatorStatus.md)
+- [Event](../msg_docs/Event.md)
+- [EventV0](../msg_docs/EventV0.md)
+- [FailureDetectorStatus](../msg_docs/FailureDetectorStatus.md)
+- [FigureEightStatus](../msg_docs/FigureEightStatus.md)
+- [FixedWingLateralGuidanceStatus](../msg_docs/FixedWingLateralGuidanceStatus.md)
+- [FixedWingLateralStatus](../msg_docs/FixedWingLateralStatus.md)
+- [FixedWingRunwayControl](../msg_docs/FixedWingRunwayControl.md)
+- [FlightPhaseEstimation](../msg_docs/FlightPhaseEstimation.md)
+- [FollowTarget](../msg_docs/FollowTarget.md)
+- [FollowTargetEstimator](../msg_docs/FollowTargetEstimator.md)
+- [FollowTargetStatus](../msg_docs/FollowTargetStatus.md)
+- [FuelTankStatus](../msg_docs/FuelTankStatus.md)
+- [GeneratorStatus](../msg_docs/GeneratorStatus.md)
+- [GeofenceResult](../msg_docs/GeofenceResult.md)
+- [GeofenceStatus](../msg_docs/GeofenceStatus.md)
+- [GimbalControls](../msg_docs/GimbalControls.md)
+- [GimbalDeviceAttitudeStatus](../msg_docs/GimbalDeviceAttitudeStatus.md)
+- [GimbalDeviceInformation](../msg_docs/GimbalDeviceInformation.md)
+- [GimbalDeviceSetAttitude](../msg_docs/GimbalDeviceSetAttitude.md)
+- [GimbalManagerInformation](../msg_docs/GimbalManagerInformation.md)
+- [GimbalManagerSetAttitude](../msg_docs/GimbalManagerSetAttitude.md)
+- [GimbalManagerSetManualControl](../msg_docs/GimbalManagerSetManualControl.md)
+- [GimbalManagerStatus](../msg_docs/GimbalManagerStatus.md)
+- [GpioConfig](../msg_docs/GpioConfig.md)
+- [GpioIn](../msg_docs/GpioIn.md)
+- [GpioOut](../msg_docs/GpioOut.md)
+- [GpioRequest](../msg_docs/GpioRequest.md)
+- [GpsDump](../msg_docs/GpsDump.md)
+- [GpsInjectData](../msg_docs/GpsInjectData.md)
+- [Gripper](../msg_docs/Gripper.md)
+- [HealthReport](../msg_docs/HealthReport.md)
+- [HeaterStatus](../msg_docs/HeaterStatus.md)
+- [HoverThrustEstimate](../msg_docs/HoverThrustEstimate.md)
+- [InputRc](../msg_docs/InputRc.md)
+- [InternalCombustionEngineControl](../msg_docs/InternalCombustionEngineControl.md)
+- [InternalCombustionEngineStatus](../msg_docs/InternalCombustionEngineStatus.md)
+- [IridiumsbdStatus](../msg_docs/IridiumsbdStatus.md)
+- [IrlockReport](../msg_docs/IrlockReport.md)
+- [LandingGear](../msg_docs/LandingGear.md)
+- [LandingGearWheel](../msg_docs/LandingGearWheel.md)
+- [LandingTargetInnovations](../msg_docs/LandingTargetInnovations.md)
+- [LandingTargetPose](../msg_docs/LandingTargetPose.md)
+- [LaunchDetectionStatus](../msg_docs/LaunchDetectionStatus.md)
+- [LedControl](../msg_docs/LedControl.md)
+- [LogMessage](../msg_docs/LogMessage.md)
+- [LoggerStatus](../msg_docs/LoggerStatus.md)
+- [MagWorkerData](../msg_docs/MagWorkerData.md)
+- [MagnetometerBiasEstimate](../msg_docs/MagnetometerBiasEstimate.md)
+- [ManualControlSwitches](../msg_docs/ManualControlSwitches.md)
+- [MavlinkLog](../msg_docs/MavlinkLog.md)
+- [MavlinkTunnel](../msg_docs/MavlinkTunnel.md)
+- [Mission](../msg_docs/Mission.md)
+- [MissionResult](../msg_docs/MissionResult.md)
+- [MountOrientation](../msg_docs/MountOrientation.md)
+- [NavigatorMissionItem](../msg_docs/NavigatorMissionItem.md)
+- [NavigatorStatus](../msg_docs/NavigatorStatus.md)
+- [NormalizedUnsignedSetpoint](../msg_docs/NormalizedUnsignedSetpoint.md)
+- [OpenDroneIdArmStatus](../msg_docs/OpenDroneIdArmStatus.md)
+- [OpenDroneIdOperatorId](../msg_docs/OpenDroneIdOperatorId.md)
+- [OpenDroneIdSelfId](../msg_docs/OpenDroneIdSelfId.md)
+- [OpenDroneIdSystem](../msg_docs/OpenDroneIdSystem.md)
+- [OrbTest](../msg_docs/OrbTest.md)
+- [OrbTestLarge](../msg_docs/OrbTestLarge.md)
+- [OrbTestMedium](../msg_docs/OrbTestMedium.md)
+- [OrbitStatus](../msg_docs/OrbitStatus.md)
+- [ParameterResetRequest](../msg_docs/ParameterResetRequest.md)
+- [ParameterSetUsedRequest](../msg_docs/ParameterSetUsedRequest.md)
+- [ParameterSetValueRequest](../msg_docs/ParameterSetValueRequest.md)
+- [ParameterSetValueResponse](../msg_docs/ParameterSetValueResponse.md)
+- [ParameterUpdate](../msg_docs/ParameterUpdate.md)
+- [Ping](../msg_docs/Ping.md)
+- [PositionControllerLandingStatus](../msg_docs/PositionControllerLandingStatus.md)
+- [PositionControllerStatus](../msg_docs/PositionControllerStatus.md)
+- [PositionSetpoint](../msg_docs/PositionSetpoint.md)
+- [PowerButtonState](../msg_docs/PowerButtonState.md)
+- [PowerMonitor](../msg_docs/PowerMonitor.md)
+- [PpsCapture](../msg_docs/PpsCapture.md)
+- [PurePursuitStatus](../msg_docs/PurePursuitStatus.md)
+- [PwmInput](../msg_docs/PwmInput.md)
+- [Px4ioStatus](../msg_docs/Px4ioStatus.md)
+- [QshellReq](../msg_docs/QshellReq.md)
+- [QshellRetval](../msg_docs/QshellRetval.md)
+- [RadioStatus](../msg_docs/RadioStatus.md)
+- [RateCtrlStatus](../msg_docs/RateCtrlStatus.md)
+- [RcChannels](../msg_docs/RcChannels.md)
+- [RcParameterMap](../msg_docs/RcParameterMap.md)
+- [RoverAttitudeSetpoint](../msg_docs/RoverAttitudeSetpoint.md)
+- [RoverAttitudeStatus](../msg_docs/RoverAttitudeStatus.md)
+- [RoverPositionSetpoint](../msg_docs/RoverPositionSetpoint.md)
+- [RoverRateSetpoint](../msg_docs/RoverRateSetpoint.md)
+- [RoverRateStatus](../msg_docs/RoverRateStatus.md)
+- [RoverSteeringSetpoint](../msg_docs/RoverSteeringSetpoint.md)
+- [RoverThrottleSetpoint](../msg_docs/RoverThrottleSetpoint.md)
+- [RoverVelocitySetpoint](../msg_docs/RoverVelocitySetpoint.md)
+- [RoverVelocityStatus](../msg_docs/RoverVelocityStatus.md)
+- [Rpm](../msg_docs/Rpm.md)
+- [RtlStatus](../msg_docs/RtlStatus.md)
+- [RtlTimeEstimate](../msg_docs/RtlTimeEstimate.md)
+- [SatelliteInfo](../msg_docs/SatelliteInfo.md)
+- [SensorAccel](../msg_docs/SensorAccel.md)
+- [SensorAccelFifo](../msg_docs/SensorAccelFifo.md)
+- [SensorAirflow](../msg_docs/SensorAirflow.md)
+- [SensorBaro](../msg_docs/SensorBaro.md)
+- [SensorCorrection](../msg_docs/SensorCorrection.md)
+- [SensorGnssRelative](../msg_docs/SensorGnssRelative.md)
+- [SensorGyro](../msg_docs/SensorGyro.md)
+- [SensorGyroFft](../msg_docs/SensorGyroFft.md)
+- [SensorGyroFifo](../msg_docs/SensorGyroFifo.md)
+- [SensorHygrometer](../msg_docs/SensorHygrometer.md)
+- [SensorMag](../msg_docs/SensorMag.md)
+- [SensorPreflightMag](../msg_docs/SensorPreflightMag.md)
+- [SensorSelection](../msg_docs/SensorSelection.md)
+- [SensorUwb](../msg_docs/SensorUwb.md)
+- [SensorsStatus](../msg_docs/SensorsStatus.md)
+- [SensorsStatusImu](../msg_docs/SensorsStatusImu.md)
+- [SystemPower](../msg_docs/SystemPower.md)
+- [TakeoffStatus](../msg_docs/TakeoffStatus.md)
+- [TaskStackInfo](../msg_docs/TaskStackInfo.md)
+- [TecsStatus](../msg_docs/TecsStatus.md)
+- [TiltrotorExtraControls](../msg_docs/TiltrotorExtraControls.md)
+- [TrajectorySetpoint6dof](../msg_docs/TrajectorySetpoint6dof.md)
+- [TransponderReport](../msg_docs/TransponderReport.md)
+- [TuneControl](../msg_docs/TuneControl.md)
+- [UavcanParameterRequest](../msg_docs/UavcanParameterRequest.md)
+- [UavcanParameterValue](../msg_docs/UavcanParameterValue.md)
+- [UlogStream](../msg_docs/UlogStream.md)
+- [UlogStreamAck](../msg_docs/UlogStreamAck.md)
+- [VehicleAcceleration](../msg_docs/VehicleAcceleration.md)
+- [VehicleAirData](../msg_docs/VehicleAirData.md)
+- [VehicleAngularAccelerationSetpoint](../msg_docs/VehicleAngularAccelerationSetpoint.md)
+- [VehicleAngularVelocity](../msg_docs/VehicleAngularVelocity.md)
+- [VehicleAttitudeSetpointV0](../msg_docs/VehicleAttitudeSetpointV0.md)
+- [VehicleConstraints](../msg_docs/VehicleConstraints.md)
+- [VehicleImu](../msg_docs/VehicleImu.md)
+- [VehicleImuStatus](../msg_docs/VehicleImuStatus.md)
+- [VehicleLocalPositionSetpoint](../msg_docs/VehicleLocalPositionSetpoint.md)
+- [VehicleMagnetometer](../msg_docs/VehicleMagnetometer.md)
+- [VehicleOpticalFlow](../msg_docs/VehicleOpticalFlow.md)
+- [VehicleOpticalFlowVel](../msg_docs/VehicleOpticalFlowVel.md)
+- [VehicleRoi](../msg_docs/VehicleRoi.md)
+- [VehicleStatusV0](../msg_docs/VehicleStatusV0.md)
+- [VelocityLimits](../msg_docs/VelocityLimits.md)
+- [WheelEncoders](../msg_docs/WheelEncoders.md)
+- [Wind](../msg_docs/Wind.md)
+- [YawEstimatorStatus](../msg_docs/YawEstimatorStatus.md)
+:::

docs/en/modules/modules_driver.md

@@ -1141,7 +1141,7 @@ px4io <command> [arguments...]
 
 ## rgbled
 
-Source: [drivers/lights/rgbled_ncp5623c](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/lights/rgbled_ncp5623c)
+Source: [drivers/lights/rgbled](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/lights/rgbled)
 
 ### Usage {#rgbled_usage}
 
@@ -1156,9 +1156,7 @@ rgbled <command> [arguments...]
      [-f <val>]  bus frequency in kHz
      [-q]        quiet startup (no message if no device found)
      [-a <val>]  I2C address
-                 default: 57
-     [-o <val>]  RGB PWM Assignment
-                 default: 123
+                 default: 85
 
    stop
 
@@ -1479,7 +1477,7 @@ Start the driver with a given device:
 ```
 uwb start -d /dev/ttyS2
 ```
-	
+
 ### Usage {#uwb_usage}
 
 ```
@@ -1639,7 +1637,7 @@ Source: [modules/zenoh](https://github.com/PX4/PX4-Autopilot/tree/main/src/modul
 ### Description
 
 Zenoh demo bridge
-	
+
 ### Usage {#zenoh_usage}
 
 ```

docs/en/modules/modules_driver_distance_sensor.md

@@ -200,6 +200,43 @@ lightware_sf45_serial <command> [arguments...]
 
 ## ll40ls
 
+Source: [drivers/distance_sensor/ll40ls](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/distance_sensor/ll40ls)
+
+
+### Description
+
+I2C bus driver for LidarLite rangefinders.
+
+The sensor/driver must be enabled using the parameter SENS_EN_LL40LS.
+
+Setup/usage information: https://docs.px4.io/main/en/sensor/lidar_lite.html
+
+### Usage {#ll40ls_usage}
+
+```
+ll40ls <command> [arguments...]
+ Commands:
+   start
+     [-I]        Internal I2C bus(es)
+     [-X]        External I2C bus(es)
+     [-b <val>]  board-specific bus (default=all) (external SPI: n-th bus
+                 (default=1))
+     [-f <val>]  bus frequency in kHz
+     [-q]        quiet startup (no message if no device found)
+     [-a <val>]  I2C address
+                 default: 98
+     [-R <val>]  Sensor rotation - downward facing by default
+                 default: 25
+
+   regdump
+
+   stop
+
+   status        print status info
+```
+
+## ll40ls_pwm
+
 Source: [drivers/distance_sensor/ll40ls_pwm](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/distance_sensor/ll40ls_pwm)
 
 
@@ -211,10 +248,10 @@ The sensor/driver must be enabled using the parameter SENS_EN_LL40LS.
 
 Setup/usage information: https://docs.px4.io/main/en/sensor/lidar_lite.html
 
-### Usage {#ll40ls_usage}
+### Usage {#ll40ls_pwm_usage}
 
 ```
-ll40ls <command> [arguments...]
+ll40ls_pwm <command> [arguments...]
  Commands:
    start         Start driver
      [-R <val>]  Sensor rotation - downward facing by default
@@ -342,7 +379,7 @@ Source: [drivers/distance_sensor/srf05](https://github.com/PX4/PX4-Autopilot/tre
 
   The sensor/driver must be enabled using the parameter SENS_EN_HXSRX0X.
 
-  
+
 ### Usage {#srf05_usage}
 
 ```

docs/en/modules/modules_system.md

@@ -343,7 +343,7 @@ Source: [modules/internal_combustion_engine_control](https://github.com/PX4/PX4-
 
 
 ### Description
-		
+
 The module controls internal combustion engine (ICE) features including:
 ignition (on/off), throttle and choke level, starter engine delay, and user request.
 
@@ -377,18 +377,21 @@ The ICE is implemented with a (4) state machine:
 ![Architecture](../../assets/hardware/ice/ice_control_state_machine.png)
 
 The state machine:
-		
+
 - Checks if [Rpm.msg](../msg_docs/Rpm.md) is updated to know if the engine is running
 - Allows for user inputs from:
-  - AUX{N}
+  - Manual control AUX
   - Arming state in [VehicleStatus.msg](../msg_docs/VehicleStatus.md)
+- In the state "Stopped" the throttle is set to NAN, which by definition will set the
+  throttle output to the disarmed value configured for the specific output.
+
 
 The module publishes [InternalCombustionEngineControl.msg](../msg_docs/InternalCombustionEngineControl.md).
-		
+
 The architecture is as shown below:
 
 ![Architecture](../../assets/hardware/ice/ice_control_diagram.png)
-		
+
 <a id="internal_combustion_engine_control_usage"></a>
 
 ### Usage {#internal_combustion_engine_control_usage}

docs/en/msg_docs/ArmingCheckReply.md

@@ -1,43 +1,59 @@
 # ArmingCheckReply (UORB message)
 
+Arming check reply.
 
+This is a response to an ArmingCheckRequest message sent by the FMU to an external component, such as a ROS 2 navigation mode.
+The response contains the current set of external mode requirements, and a queue of events indicating recent failures to set the mode (which the FMU may then forward to a ground station).
+The request is sent regularly to all registered ROS modes, even while armed, so that the FMU always knows and can forward the current state.
+
+Note that the external component is identified by its registration_id, which is allocated to the component during registration (arming_check_id in RegisterExtComponentReply).
+The message is not used by internal/FMU components, as their mode requirements are known at compile time.
 
 [source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/ArmingCheckReply.msg)
 
 ```c
-uint32 MESSAGE_VERSION = 0
+# Arming check reply.
+#
+# This is a response to an ArmingCheckRequest message sent by the FMU to an external component, such as a ROS 2 navigation mode.
+# The response contains the current set of external mode requirements, and a queue of events indicating recent failures to set the mode (which the FMU may then forward to a ground station).
+# The request is sent regularly to all registered ROS modes, even while armed, so that the FMU always knows and can forward the current state.
+#
+# Note that the external component is identified by its registration_id, which is allocated to the component during registration (arming_check_id in RegisterExtComponentReply).
+# The message is not used by internal/FMU components, as their mode requirements are known at compile time.
 
-uint64 timestamp # time since system start (microseconds)
+uint32 MESSAGE_VERSION = 1
 
-uint8 request_id
-uint8 registration_id
+uint64 timestamp # [us] Time since system start.
 
-uint8 HEALTH_COMPONENT_INDEX_NONE = 0
+uint8 request_id # Id of ArmingCheckRequest for which this is a response.
+uint8 registration_id # Id of external component emitting this response.
 
-uint8 health_component_index      # HEALTH_COMPONENT_INDEX_*
-bool health_component_is_present
-bool health_component_warning
-bool health_component_error
+uint8 HEALTH_COMPONENT_INDEX_NONE = 0 # Index of health component for which this response applies.
 
-bool can_arm_and_run              # whether arming is possible, and if it's a navigation mode, if it can run
+uint8 health_component_index # [@enum HEALTH_COMPONENT_INDEX]
+bool health_component_is_present # Unused. Intended for use with health events interface (health_component_t in events.json).
+bool health_component_warning # Unused. Intended for use with health events interface (health_component_t in events.json).
+bool health_component_error # Unused. Intended for use with health events interface (health_component_t in events.json).
 
-uint8 num_events
+bool can_arm_and_run # True if the component can arm. For navigation mode components, true if the component can arm in the mode or switch to the mode when already armed.
 
-Event[5] events
+uint8 num_events # Number of queued failure messages (Event) in the events field.
+
+Event[5] events # Arming failure reasons (Queue of events to report to GCS).
 
 # Mode requirements
-bool mode_req_angular_velocity
-bool mode_req_attitude
-bool mode_req_local_alt
-bool mode_req_local_position
-bool mode_req_local_position_relaxed
-bool mode_req_global_position
-bool mode_req_mission
-bool mode_req_home_position
-bool mode_req_prevent_arming
-bool mode_req_manual_control
+bool mode_req_angular_velocity # Requires angular velocity estimate (e.g. from gyroscope).
+bool mode_req_attitude # Requires an attitude estimate.
+bool mode_req_local_alt # Requires a local altitude estimate.
+bool mode_req_local_position # Requires a local position estimate.
+bool mode_req_local_position_relaxed # Requires a more relaxed global position estimate.
+bool mode_req_global_position # Requires a global position estimate.
+bool mode_req_global_position_relaxed # Requires a relaxed global position estimate.
+bool mode_req_mission # Requires an uploaded mission.
+bool mode_req_home_position # Requires a home position (such as RTL/Return mode).
+bool mode_req_prevent_arming # Prevent arming (such as in Land mode).
+bool mode_req_manual_control # Requires a manual controller
 
-
-uint8 ORB_QUEUE_LENGTH = 4
+uint8 ORB_QUEUE_LENGTH = 4 #
 
 ```

docs/en/msg_docs/ArmingCheckReplyV0.md

@@ -0,0 +1,43 @@
+# ArmingCheckReplyV0 (UORB message)
+
+
+
+[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/px4_msgs_old/msg/ArmingCheckReplyV0.msg)
+
+```c
+uint32 MESSAGE_VERSION = 0
+
+uint64 timestamp # time since system start (microseconds)
+
+uint8 request_id
+uint8 registration_id
+
+uint8 HEALTH_COMPONENT_INDEX_NONE = 0
+
+uint8 health_component_index      # HEALTH_COMPONENT_INDEX_*
+bool health_component_is_present
+bool health_component_warning
+bool health_component_error
+
+bool can_arm_and_run              # whether arming is possible, and if it's a navigation mode, if it can run
+
+uint8 num_events
+
+EventV0[5] events
+
+# Mode requirements
+bool mode_req_angular_velocity
+bool mode_req_attitude
+bool mode_req_local_alt
+bool mode_req_local_position
+bool mode_req_local_position_relaxed
+bool mode_req_global_position
+bool mode_req_mission
+bool mode_req_home_position
+bool mode_req_prevent_arming
+bool mode_req_manual_control
+
+
+uint8 ORB_QUEUE_LENGTH = 4
+
+```

docs/en/msg_docs/ArmingCheckRequest.md

@@ -1,16 +1,30 @@
 # ArmingCheckRequest (UORB message)
 
+Arming check request.
 
+Broadcast message to request arming checks be reported by all registered components, such as external ROS 2 navigation modes.
+All registered components should respond with an ArmingCheckReply message that indicates their current mode requirements, and any arming failure information.
+The request is sent regularly, even while armed, so that the FMU always knows the current arming state for external modes, and can forward it to ground stations.
+
+The reply will include the published request_id, allowing correlation of all arming check information for a particular request.
+The reply will also include the registration_id for each external component, provided to it during the registration process (RegisterExtComponentReply).
 
 [source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/ArmingCheckRequest.msg)
 
 ```c
+# Arming check request.
+#
+# Broadcast message to request arming checks be reported by all registered components, such as external ROS 2 navigation modes.
+# All registered components should respond with an ArmingCheckReply message that indicates their current mode requirements, and any arming failure information.
+# The request is sent regularly, even while armed, so that the FMU always knows the current arming state for external modes, and can forward it to ground stations.
+#
+# The reply will include the published request_id, allowing correlation of all arming check information for a particular request.
+# The reply will also include the registration_id for each external component, provided to it during the registration process (RegisterExtComponentReply).
+
 uint32 MESSAGE_VERSION = 0
 
-uint64 timestamp # time since system start (microseconds)
+uint64 timestamp # [us] Time since system start.
 
-# broadcast message to request all registered arming checks to be reported
-
-uint8 request_id
+uint8 request_id # Id of this request. Allows correlation with associated ArmingCheckReply messages.
 
 ```

docs/en/msg_docs/Event.md

@@ -2,10 +2,12 @@
 
 Events interface
 
-[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/Event.msg)
+[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/versioned/Event.msg)
 
 ```c
 # Events interface
+uint32 MESSAGE_VERSION = 1
+
 uint64 timestamp			# time since system start (microseconds)
 
 uint32 id                   # Event ID

docs/en/msg_docs/EventV0.md

@@ -0,0 +1,24 @@
+# EventV0 (UORB message)
+
+this message is required here in the msg_old folder because other msg are depending on it
+Events interface
+
+[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/px4_msgs_old/msg/EventV0.msg)
+
+```c
+# this message is required here in the msg_old folder because other msg are depending on it
+# Events interface
+
+uint32 MESSAGE_VERSION = 0
+
+uint64 timestamp			# time since system start (microseconds)
+
+uint32 id                   # Event ID
+uint16 event_sequence       # Event sequence number
+uint8[25] arguments         # (optional) arguments, depend on event id
+
+uint8 log_levels            # Log levels: 4 bits MSB: internal, 4 bits LSB: external
+
+uint8 ORB_QUEUE_LENGTH = 16
+
+```

docs/en/msg_docs/FailsafeFlags.md

@@ -22,6 +22,7 @@ uint32 mode_req_local_alt
 uint32 mode_req_local_position
 uint32 mode_req_local_position_relaxed
 uint32 mode_req_global_position
+uint32 mode_req_global_position_relaxed
 uint32 mode_req_mission
 uint32 mode_req_offboard_signal
 uint32 mode_req_home_position
@@ -39,6 +40,7 @@ bool local_position_invalid           # Local position estimate invalid
 bool local_position_invalid_relaxed   # Local position with reduced accuracy requirements invalid (e.g. flying with optical flow)
 bool local_velocity_invalid           # Local velocity estimate invalid
 bool global_position_invalid          # Global position estimate invalid
+bool global_position_invalid_relaxed  # Global position estimate invalid with relaxed accuracy requirements
 bool auto_mission_missing             # No mission available
 bool offboard_control_signal_lost     # Offboard signal lost
 bool home_position_invalid            # No home position available

docs/en/msg_docs/InternalCombustionEngineControl.md

@@ -7,10 +7,10 @@
 ```c
 uint64 timestamp        		# time since system start (microseconds)
 
-bool ignition_on          		# activate/deactivate ignition (Spark Plug)
-float32 throttle_control		# [0,1] - Motor should idle with 0. Includes slew rate if enabled.
-float32 choke_control			# [0,1] - 1 fully closes the air inlet.
-float32 starter_engine_control		# [0,1] - control value for electric starter motor.
+bool ignition_on          		# activate/deactivate ignition (spark plug)
+float32 throttle_control		# setpoint for throttle actuator, with slew rate if enabled, idles with 0 [norm] [@range 0,1] [@uncontrolled NAN to stop motor]
+float32 choke_control			# setpoint for choke actuator, 1: fully closed [norm] [@range 0,1]
+float32 starter_engine_control		# setpoint for (electric) starter motor [norm] [@range 0,1]
 
 uint8 user_request			# user intent for the ICE being on/off
 

docs/en/msg_docs/index.md

@@ -16,10 +16,11 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m
 - [ActuatorMotors](ActuatorMotors.md) — Motor control message
 - [ActuatorServos](ActuatorServos.md) — Servo control message
 - [AirspeedValidated](AirspeedValidated.md)
-- [ArmingCheckReply](ArmingCheckReply.md)
-- [ArmingCheckRequest](ArmingCheckRequest.md)
+- [ArmingCheckReply](ArmingCheckReply.md) — Arming check reply.
+- [ArmingCheckRequest](ArmingCheckRequest.md) — Arming check request.
 - [BatteryStatus](BatteryStatus.md)
 - [ConfigOverrides](ConfigOverrides.md) — Configurable overrides by (external) modes or mode executors
+- [Event](Event.md) — Events interface
 - [FixedWingLateralSetpoint](FixedWingLateralSetpoint.md) — Fixed Wing Lateral Setpoint message
 Used by the fw_lateral_longitudinal_control module
 At least one of course, airspeed_direction, or lateral_acceleration must be finite.
@@ -124,7 +125,6 @@ scale errors, in-run bias and thermal drift (if thermal compensation is enabled
 - [EstimatorStates](EstimatorStates.md)
 - [EstimatorStatus](EstimatorStatus.md)
 - [EstimatorStatusFlags](EstimatorStatusFlags.md)
-- [Event](Event.md) — Events interface
 - [FailsafeFlags](FailsafeFlags.md) — Input flags for the failsafe state machine set by the arming & health checks.
 - [FailureDetectorStatus](FailureDetectorStatus.md)
 - [FigureEightStatus](FigureEightStatus.md)
@@ -298,6 +298,9 @@ NaN means the state was not controlled
 - [Wind](Wind.md)
 - [YawEstimatorStatus](YawEstimatorStatus.md)
 - [AirspeedValidatedV0](AirspeedValidatedV0.md)
+- [ArmingCheckReplyV0](ArmingCheckReplyV0.md)
+- [EventV0](EventV0.md) — this message is required here in the msg_old folder because other msg are depending on it
+Events interface
 - [VehicleAttitudeSetpointV0](VehicleAttitudeSetpointV0.md)
 - [VehicleStatusV0](VehicleStatusV0.md) — Encodes the system state of the vehicle published by commander
 

src/drivers/distance_sensor/ll40ls_pwm/ll40ls.cpp

@@ -150,7 +150,7 @@ The sensor/driver must be enabled using the parameter SENS_EN_LL40LS.
 Setup/usage information: https://docs.px4.io/main/en/sensor/lidar_lite.html
 )DESCR_STR");
 
-	PRINT_MODULE_USAGE_NAME("ll40ls", "driver");
+	PRINT_MODULE_USAGE_NAME("ll40ls_pwm", "driver");
 	PRINT_MODULE_USAGE_SUBCATEGORY("distance_sensor");
 	PRINT_MODULE_USAGE_COMMAND_DESCR("start","Start driver");
 	PRINT_MODULE_USAGE_PARAM_INT('R', 25, 0, 25, "Sensor rotation - downward facing by default", true);