openc3 7.2.0 → 7.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90e17f6bf28158ea786646171220e3c23aca07cce30559b3e64a29f83dabb50d
-  data.tar.gz: 9a13e73273ba67e7d6003a9578a34a8b1c0abadea3b8d4d369f1fd3803a4f0ec
+  metadata.gz: 787269f06fae8562e23d790d3c4887e2f913841dc818570fdafa06b29fd1b8e6
+  data.tar.gz: c6630dbc9c61bf71f96015db09ca9246ef80247f4f1b5de429c97b537551c4e4
 SHA512:
-  metadata.gz: eec5ccdb945747570717e5f60f9a89158d500d994f1fa5e6ebc81ed8bb263229950f10e1f277e0c68bf5d9fb531f3470354d45fda2164f7608c9ad22413b2022
-  data.tar.gz: a32f7675eacf6b41b345a4b5ae554292db011499d12a9e5e65173c514e5fac7e66da3bacea7ad5cf9a3738fcb96e3a82009997993fc70722d4a9ba4edd236261
+  metadata.gz: b72db91c6fd2febea1855d452a30e496b33bc5c19010ebc674ef044fea01d8cff1c921abcee824c39f32434e66fa9b4ed040bc1f164e9ea7cec99be431aec03a
+  data.tar.gz: 0ffeaa70a064e4d23cd49326e87b85e4eafefd0d4fa61a3db60fc503a8e48593c349588f4f28e374f4c7ba87408a66c072e822101f689bfc58cb3bcf567af966

data/bin/openc3cli

@@ -67,6 +67,7 @@ def print_usage
   puts "  cli load /PATH/FILENAME.gem SCOPE plugin_hash.json    # Loads a COSMOS plugin gem file"
   puts "    OPTIONS: --variables lets you pass a path to a JSON file containing your plugin's variables"
   puts "  cli list <SCOPE>                  # Lists installed plugins, SCOPE is DEFAULT if not given"
+  puts "  cli unload PLUGIN_NAME [SCOPE]    # Unload an installed COSMOS plugin"
   puts "  cli generate TYPE OPTIONS         # Generate various COSMOS entities"
   puts "    OPTIONS: --ruby or --python is required to specify the language in the generated code unless OPENC3_LANGUAGE is set"
   puts "  cli bridge CONFIG_FILENAME        # Run COSMOS host bridge"
@@ -77,6 +78,7 @@ def print_usage
   puts "  cli xtce_converter                # Convert to and from the XTCE format. Run with --help for more info."
   puts "  cli cstol_converter               # Converts CSTOL files (.prc) to COSMOS. Run with --help for more info."
   puts "  cli setpassword                   # Set the initial password from OPENC3_API_PASSWORD env var"
+  puts "  cli migratetouv PLUGIN_NAME SCOPE # Migrate plugin to per-plugin UV virtual environment"
   puts ""
 end
 
@@ -102,6 +104,42 @@ def check_environment
   end
 end
 
+# Report how an existing .xtce file fares against the XTCE 1.2 schema without failing
+def xtce_report_validation(filename)
+  namespace = OpenC3::XtceConverter.xtce_namespace(filename)
+  if namespace != OpenC3::XtceConverter::XTCE_1_2_NAMESPACE
+    puts "#{File.basename(filename)} declares #{namespace ? namespace : 'no XTCE namespace'}, skipping XTCE 1.2 schema validation"
+    return
+  end
+  errors = OpenC3::XtceConverter.schema_errors(filename)
+  if errors.empty?
+    puts "#{File.basename(filename)} is valid XTCE 1.2"
+  else
+    $stderr.puts "WARNING: #{filename} is not valid XTCE 1.2:"
+    errors.each { |error| $stderr.puts "  #{error}" }
+  end
+end
+
+# Validate every .xtce file written under output_dir. Returns false if any is invalid.
+def xtce_validate_exported(output_dir)
+  files = Dir.glob(File.join(output_dir, "**", "*.xtce")).sort
+  if files.empty?
+    $stderr.puts "ERROR: no .xtce files were written to #{output_dir}"
+    return false
+  end
+  valid = true
+  files.each do |filename|
+    errors = OpenC3::XtceConverter.schema_errors(filename)
+    next if errors.empty?
+
+    valid = false
+    $stderr.puts "ERROR: #{filename} is not valid XTCE 1.2:"
+    errors.each { |error| $stderr.puts "  #{error}" }
+  end
+  puts "Validated #{files.length} .xtce file(s) against the OMG XTCE 1.2 schema" if valid
+  valid
+end
+
 def xtce_converter(args)
   options = {}
   option_parser = OptionParser.new do |opts|
@@ -122,14 +160,17 @@ def xtce_converter(args)
     opts.on("-p", "--plugin PLUGIN", "Export .xtce file(s) from the plugin") do |arg|
       options[:plugin] = arg
     end
-    opts.on("-v", "--variables", "Optional variables file to pass to the plugin") do |arg|
+    opts.on("-v VARIABLES", "--variables VARIABLES", "Optional variables file to pass to the plugin") do |arg|
       options[:variables] = arg
     end
     opts.on("-r ROOT_TARGET", "--root_target ROOT_TARGET", "Optional flag to set which target is at the root of an XTCE document. If not specified, each target will be placed under a generic 'root' spacesystem") do |arg|
       options[:root_target_name] = arg
     end
-    opts.on("-t TIME_ASSOCIATION_NAME", "--time_association_name TIME_ASSOCIATION_NAME", "Optional flag to set which target is at the root of an XTCE document. If not specified, each target will be placed under a generic 'root' spacesystem") do |arg|
-      options[:time_association_name] = "PACKET_TIME"
+    opts.on("-t TIME_ASSOCIATION_NAME", "--time_association_name TIME_ASSOCIATION_NAME", "Optional telemetry item name to export as each packet's time, emitted as a TimeAssociation. If not specified, no TimeAssociation is written") do |arg|
+      options[:time_association_name] = arg
+    end
+    opts.on("--[no-]validate", "Validate .xtce files against the OMG XTCE 1.2 schema. On by default when exporting, where an invalid file fails the export. Off by default when importing, where it only reports since COSMOS also imports XTCE 1.0 / 1.1") do |arg|
+      options[:validate] = arg
     end
   end
 
@@ -149,6 +190,9 @@ def xtce_converter(args)
   OpenC3::Logger.level = OpenC3::Logger::DEBUG
 
   if options[:import] && options[:output]
+    # Reporting only. COSMOS imports XTCE 1.0 / 1.1 too, and those report errors against
+    # the 1.2 schema while importing perfectly well, so this never blocks an import.
+    xtce_report_validation(options[:import]) if options[:validate]
     packet_config = OpenC3::PacketConfig.new
     puts "Processing #{options[:import]}..."
     packet_config.process_file(options[:import], nil)
@@ -166,7 +210,14 @@ def xtce_converter(args)
       OpenC3::PluginModel.install_phase2(plugin_hash, scope: 'DEFAULT', validate_only: true,
         gem_file_path: options[:plugin])
       OpenC3::XtceConverter.combine_output_xtce(options[:output], options[:root_target_name])
-      result = 0 # bash and Windows consider 0 success
+      # Validate what we just wrote unless told not to. An exporter bug that only shows
+      # up on a particular config otherwise produces a file that looks fine here and is
+      # rejected by whatever ground system it was written for.
+      if options[:validate] == false
+        result = 0
+      else
+        result = xtce_validate_exported(options[:output]) ? 0 : ERROR_CODE
+      end # bash and Windows consider 0 success
     rescue => e
       puts "Error: #{e.message}"
       puts e.backtrace
@@ -226,7 +277,7 @@ ensure
   exit(result)
 end
 
-def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_lines: nil, scope:, existing_plugin_name:, force: false)
+def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_lines: nil, scope:, existing_plugin_name:, force: false, username: nil, version_history_files: nil)
   new_gem = File.basename(plugin_file_path)
   old_gem = existing_plugin_name.split("__")[0]
   puts "Updating existing plugin: #{existing_plugin_name} with #{File.basename(plugin_file_path)}"
@@ -247,6 +298,10 @@ def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_line
       plugin_model.destroy
 
       plugin_hash = OpenC3::PluginModel.install_phase1(plugin_file_path, existing_variables: variables, existing_plugin_txt_lines: plugin_txt_lines, process_existing: true, scope: scope)
+      # Carry Version History upgrade hints into the regenerated hash so
+      # install_phase2 can version modified files taken from the plugin.
+      plugin_hash['username'] = username if username
+      plugin_hash['version_history_files'] = version_history_files if version_history_files
       puts "Updating plugin: #{plugin_file_path}\n#{plugin_hash}"
       plugin_hash = OpenC3::PluginModel.install_phase2(plugin_hash, scope: scope)
       OpenC3::LocalMode.update_local_plugin(plugin_file_path, plugin_hash, old_plugin_name: plugin_name, scope: scope)
@@ -410,7 +465,8 @@ def load_plugin(plugin_file_path, scope:, plugin_hash_file: nil, force: false, v
       if existing_plugin_hash
         # Upgrade or Edit
         update_plugin(plugin_file_path, plugin_hash['name'], variables: plugin_hash['variables'], scope: scope,
-          plugin_txt_lines: plugin_hash['plugin_txt_lines'], existing_plugin_name: existing_plugin_hash['name'], force: force)
+          plugin_txt_lines: plugin_hash['plugin_txt_lines'], existing_plugin_name: existing_plugin_hash['name'], force: force,
+          username: plugin_hash['username'], version_history_files: plugin_hash['version_history_files'])
       else
         # New Install
         puts "Loading new plugin: #{plugin_file_path}\n#{plugin_hash}"
@@ -447,6 +503,10 @@ def unload_plugin(plugin_name, scope:)
       # Remove the backing gem now that no PluginModel references it,
       # so it disappears from the admin Packages tab.
       OpenC3::PluginModel.cleanup_gem(plugin_name, scope: scope)
+      # Drop this plugin's Version History repo. Uninstall-only: the upgrade
+      # path (update_plugin) reuses the repo and never reaches here, so history
+      # survives version bumps. No-op in Core / when versioning is disabled.
+      OpenC3::TargetModel.destroy_script_versions(plugin_name, scope: scope)
       OpenC3::Logger.info("PluginModel destroyed: #{plugin_name}", scope: scope)
     rescue => e
       abort("Error uninstalling plugin: #{scope}: #{plugin_name}: #{e.formatted}")
@@ -671,30 +731,18 @@ def cli_script_list(args, options)
 end
 
 def parse_suite_runner_options(options)
-  suite_runner = nil
   # suite must be given to enable Suite Runner execution
-  if options[:suite]
-    suite_runner = {}
-    suite_runner['suite'] = options[:suite]
-    if options[:group]
-      suite_runner['group'] = options[:group]
-      # script requires group to be set
-      if options[:script]
-        suite_runner['script'] = options[:script]
-      end
-    end
-    if options[:method]
-      suite_runner['method'] = options[:method]
-    else
-      suite_runner['method'] = 'start'
-    end
-    if options[:options]
-      suite_runner['options'] = options[:options].split(',')
-    else
-      suite_runner['options'] = ["continueAfterError"]
-    end
-  end
-  return suite_runner
+  return nil unless options[:suite]
+  require 'openc3/script/suite_runner'
+  # Build the canonical hash via the shared helper so the CLI applies the same
+  # shape, defaults, and validation (e.g. script requires group) as execution.
+  return OpenC3::SuiteRunner.build_options(
+    suite: options[:suite],
+    group: options[:group],
+    script: options[:script],
+    method: options[:method],
+    options: options[:options]&.split(','),
+  )
 end
 
 def cli_script_run(args, options)
@@ -1475,6 +1523,37 @@ if not ARGV[0].nil? # argument(s) given
   when 'migratepassword'
     migrate_password_hash()
 
+  when 'migratetouv'
+    if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli migratetouv PLUGIN_NAME [SCOPE]"
+      puts ""
+      puts "Migrate a plugin from the shared Python venv to a per-plugin UV virtual environment"
+      puts ""
+      puts "Arguments:"
+      puts "  PLUGIN_NAME       Name of the plugin to migrate (required)"
+      puts "  SCOPE             Scope of the plugin (optional, default: DEFAULT)"
+      puts ""
+      puts "Options:"
+      puts "  -h, --help        Show this help message"
+      exit(ARGV[1].nil? ? 1 : 0)
+    end
+    scope = ARGV[2] || 'DEFAULT'
+    check_environment()
+    begin
+      plugin_model = OpenC3::PluginModel.get_model(name: ARGV[1], scope: scope)
+      if plugin_model.nil?
+        abort("Plugin '#{ARGV[1]}' not found in scope '#{scope}'")
+      end
+      if plugin_model.migrate_to_uv!(scope: scope)
+        puts "Successfully migrated plugin '#{ARGV[1]}' to per-plugin UV venv"
+      else
+        puts "Migration failed for plugin '#{ARGV[1]}'. Check logs for details."
+        exit 1
+      end
+    rescue => e
+      abort("Error migrating plugin: #{e.formatted}")
+    end
+
   else # Unknown task
     print_usage()
     abort("Unknown task: #{ARGV[0]}")

data/bin/pipinstall

@@ -1,7 +1,8 @@
 #!/bin/sh
-uv venv "$PYTHONUSERBASE" --allow-existing
+VENV="${PIPINSTALL_VENV:-$PYTHONUSERBASE}"
+uv venv "$VENV" --allow-existing
 echo "uv pip install $@"
-uv pip install --python "$PYTHONUSERBASE" "$@"
+uv pip install --python "$VENV" "$@"
 if [ $? -eq 0 ]; then
     echo "Command succeeded"
     exit 0
@@ -27,7 +28,7 @@ if [ -d "$LAST_ARG" ] && [ -f "$LAST_ARG/pyproject.toml" ]; then
     TMPFILE=$(mktemp)
     uv pip compile ${OPTS} "${LAST_ARG}/pyproject.toml" > "$TMPFILE"
     if [ $? -eq 0 ] && [ -s "$TMPFILE" ]; then
-        uv pip install --python "$PYTHONUSERBASE" ${OPTS} -r "$TMPFILE"
+        uv pip install --python "$VENV" ${OPTS} -r "$TMPFILE"
         if [ $? -eq 0 ]; then
             echo "Dependencies installed successfully"
             rm -f "$TMPFILE"
@@ -38,7 +39,7 @@ if [ -d "$LAST_ARG" ] && [ -f "$LAST_ARG/pyproject.toml" ]; then
 fi
 
 echo "Warning: Install failed - retrying with --no-index"
-uv pip install --python "$PYTHONUSERBASE" --no-index "$@"
+uv pip install --python "$VENV" --no-index "$@"
 if [ $? -ne 0 ]; then
     echo "ERROR: uv pip install failed"
     exit 1

data/bin/pipuninstall

@@ -1,6 +1,10 @@
 #!/bin/sh
+# Uninstall a Python package from a venv. When PIPINSTALL_VENV is set (by
+# PythonPackageModel.destroy for per-plugin venvs), uninstall from that venv.
+# Otherwise fall back to the shared PYTHONUSERBASE.
+VENV="${PIPINSTALL_VENV:-$PYTHONUSERBASE}"
 echo "uv pip uninstall $@"
-uv pip uninstall --python "$PYTHONUSERBASE" "$@"
+uv pip uninstall --python "$VENV" "$@"
 if [ $? -eq 0 ]; then
     echo "Command succeeded"
 else

data/bin/uvinstall

@@ -0,0 +1,149 @@
+#!/bin/sh
+# Per-plugin UV virtual environment installer
+# Usage: uvinstall <plugin_venv_name> <gem_path> [extra uv args...]
+#
+# Creates an isolated venv at /gems/plugin_venvs/<plugin_venv_name>/.venv
+# and installs Python dependencies from the plugin's gem_path.
+#
+# Two installation paths:
+#   1. If gem_path contains uv.lock: uses `uv sync --frozen` (reproducible)
+#   2. Otherwise: falls back to `uv pip install` for requirements.txt / pyproject.toml
+#
+# Network safety: uv's own HTTP controls (connect timeout, read timeout,
+# bounded retries) make a slow or unreachable index fail fast instead of
+# hanging the plugin install (which stalls the whole deploy - the init hook
+# never completes and helm's --wait times out). These are idle/connect
+# timeouts, NOT a total-transfer cap, so a large but healthy download (e.g.
+# torch over a slow link) is never killed mid-stream as long as bytes keep
+# arriving. Both paths try OFFLINE first so a plugin whose wheels are already
+# in the seeded UV cache installs deterministically without ever touching the
+# network.
+
+PLUGIN_VENV_NAME="$1"
+GEM_PATH="$2"
+shift 2
+UV_ARGS="$@"
+
+if [ -z "$PLUGIN_VENV_NAME" ] || [ -z "$GEM_PATH" ]; then
+    echo "Usage: uvinstall <plugin_venv_name> <gem_path> [extra uv args...]"
+    exit 1
+fi
+
+# Bound uv's network behavior with uv's own HTTP knobs. Unlike a blunt
+# wall-clock cap, these fail fast on a dead/unreachable index or a stalled
+# connection WITHOUT killing a large but progressing download. All overridable.
+#   UV_HTTP_CONNECT_TIMEOUT - give up connecting to an unreachable index (s)
+#   UV_HTTP_TIMEOUT         - give up when a connection stalls mid-read (s)
+#   UV_HTTP_RETRIES         - bounded retries for transient failures
+# The values below match uv's own defaults; they are set explicitly so plugin
+# installs keep this behavior even if a future uv release changes its defaults,
+# and so an operator has a documented place to raise them for a slow index.
+export UV_HTTP_CONNECT_TIMEOUT="${UV_HTTP_CONNECT_TIMEOUT:-10}"
+export UV_HTTP_TIMEOUT="${UV_HTTP_TIMEOUT:-30}"
+export UV_HTTP_RETRIES="${UV_HTTP_RETRIES:-3}"
+
+# Run a uv command offline first (cache-only: instant, cannot hang, works in
+# air-gapped clusters) and only retry online on a cache miss. Both paths below
+# use this so a plugin whose wheels are already in the seeded UV cache never
+# touches the network.
+uv_offline_then_online() {
+    if uv "$@" --offline; then
+        return 0
+    fi
+    # Expected for any plugin whose wheels aren't in the seeded cache (a new
+    # third-party plugin, or a pin that differs from the one baked in), so this
+    # is informational, not an error - the online attempt below is the real one.
+    echo "Offline uv cache miss; retrying online"
+    uv "$@"
+}
+
+VENV_BASE="/gems/plugin_venvs/${PLUGIN_VENV_NAME}"
+VENV_DIR="${VENV_BASE}/.venv"
+
+echo "Creating per-plugin venv for '${PLUGIN_VENV_NAME}' at ${VENV_DIR}"
+mkdir -p "${VENV_BASE}"
+
+# Path 1: uv.lock present - use `uv sync --frozen` for reproducible installs
+if [ -f "${GEM_PATH}/uv.lock" ] && [ -f "${GEM_PATH}/pyproject.toml" ]; then
+    echo "Found uv.lock - using uv sync --frozen for reproducible install"
+
+    # Copy pyproject.toml and uv.lock into the venv base directory
+    cp "${GEM_PATH}/pyproject.toml" "${VENV_BASE}/pyproject.toml"
+    cp "${GEM_PATH}/uv.lock" "${VENV_BASE}/uv.lock"
+
+    # Create venv and sync dependencies
+    cd "${VENV_BASE}"
+    uv venv "${VENV_DIR}" --allow-existing
+
+    # Offline sync first, online only on a cache miss (bounded by UV_HTTP_*)
+    uv_offline_then_online sync --frozen --no-dev --no-install-project ${UV_ARGS}
+    RESULT=$?
+
+    if [ $RESULT -eq 0 ]; then
+        echo "uv sync --frozen succeeded"
+        touch "${VENV_BASE}/.uv_managed"
+        exit 0
+    fi
+
+    echo "Warning: uv sync --frozen failed (exit code ${RESULT}), falling back to uv pip install"
+fi
+
+# Path 2: Fallback - use uv pip install for requirements.txt or pyproject.toml
+# Every install here is also offline-first (same reasoning as path 1), so an
+# unlocked plugin whose wheels happen to be cached installs without network too.
+uv venv "${VENV_DIR}" --allow-existing
+
+if [ -f "${GEM_PATH}/requirements.txt" ]; then
+    echo "Installing from requirements.txt via uv pip install"
+    uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} -r "${GEM_PATH}/requirements.txt"
+    RESULT=$?
+elif [ -f "${GEM_PATH}/pyproject.toml" ]; then
+    echo "Installing from pyproject.toml via uv pip install"
+    uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} "${GEM_PATH}"
+    RESULT=$?
+
+    # `uv pip install <path>` builds the plugin as a package before installing
+    # its dependencies, which fails for a pyproject.toml that only declares
+    # dependencies and isn't a buildable distribution (no [build-system], a
+    # missing/empty source layout, or a build backend that can't run offline).
+    # Fall back to installing the declared dependencies without building. The
+    # compile step only resolves declared deps into a pinned requirements file;
+    # the install that follows it is the one that fetches, so it gets the same
+    # offline-then-online treatment. Each compile attempt re-truncates TMPFILE
+    # so a partial offline write can never be mixed into the online result.
+    if [ $RESULT -ne 0 ]; then
+        echo "Warning: Failed to build Python package, attempting to install declared dependencies from pyproject.toml"
+        TMPFILE=$(mktemp)
+        uv pip compile --offline ${UV_ARGS} "${GEM_PATH}/pyproject.toml" > "$TMPFILE"
+        COMPILED=$?
+        if [ $COMPILED -ne 0 ] || [ ! -s "$TMPFILE" ]; then
+            echo "Offline uv pip compile missed the cache; retrying online"
+            uv pip compile ${UV_ARGS} "${GEM_PATH}/pyproject.toml" > "$TMPFILE"
+            COMPILED=$?
+        fi
+        # Both the exit status AND a non-empty file are required: uv writes its
+        # "autogenerated by uv" header before resolution runs, so a compile that
+        # fails partway still leaves a non-empty file. Installing from that would
+        # produce a venv missing dependencies and report success.
+        if [ $COMPILED -eq 0 ] && [ -s "$TMPFILE" ]; then
+            uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} -r "$TMPFILE"
+            RESULT=$?
+        fi
+        rm -f "$TMPFILE"
+    fi
+else
+    echo "ERROR: No requirements.txt, pyproject.toml, or uv.lock found in ${GEM_PATH}"
+    exit 1
+fi
+
+if [ $RESULT -eq 0 ]; then
+    echo "Python packages installed successfully"
+    touch "${VENV_BASE}/.uv_managed"
+    exit 0
+fi
+
+# No --no-index last resort here anymore: every attempt above already ran
+# cache-only first via uv_offline_then_online, so a cache-only retry at this
+# point would repeat an attempt that has already failed.
+echo "ERROR: uvinstall failed for plugin ${PLUGIN_VENV_NAME}"
+exit 1

data/data/config/interface_modifiers.yaml

@@ -1,11 +1,16 @@
 ---
 MAP_TARGET:
   summary: Maps a target name to an interface
+  description: See [Mapping Targets to Interfaces](/docs/configuration/interfaces#mapping-targets-to-interfaces) for more information.
   parameters:
     - name: Target Name
       required: true
       description: Target name to map to this interface
       values: .+
+    - name: Enabled State
+      required: false
+      description: Initial enabled state of the target on this interface. Defaults to ENABLED.
+      values: ["ENABLED", "DISABLED"]
   ruby_example: |
     INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
       MAP_TARGET DATA
@@ -14,12 +19,17 @@ MAP_TARGET:
       MAP_TARGET DATA
 MAP_CMD_TARGET:
   summary: Maps a target name to an interface for commands only
+  description: See [Mapping Targets to Interfaces](/docs/configuration/interfaces#mapping-targets-to-interfaces) for more information.
   since: 5.2.0
   parameters:
     - name: Target Name
       required: true
       description: Command target name to map to this interface
       values: .+
+    - name: Enabled State
+      required: false
+      description: Initial enabled state of the command target on this interface. Defaults to ENABLED.
+      values: ["ENABLED", "DISABLED"]
   ruby_example: |
     INTERFACE CMD_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
       MAP_CMD_TARGET DATA # Only DATA commands go on the CMD_INT interface
@@ -28,12 +38,17 @@ MAP_CMD_TARGET:
       MAP_CMD_TARGET DATA # Only DATA commands go on the CMD_INT interface
 MAP_TLM_TARGET:
   summary: Maps a target name to an interface for telemetry only
+  description: See [Mapping Targets to Interfaces](/docs/configuration/interfaces#mapping-targets-to-interfaces) for more information.
   since: 5.2.0
   parameters:
     - name: Target Name
       required: true
       description: Telemetry target name to map to this interface
       values: .+
+    - name: Enabled State
+      required: false
+      description: Initial enabled state of the telemetry target on this interface. Defaults to ENABLED.
+      values: ["ENABLED", "DISABLED"]
   ruby_example: |
     INTERFACE TLM_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
       MAP_TLM_TARGET DATA # Only DATA telemetry received on TLM_INT interface

data/data/config/item_modifiers.yaml

@@ -136,7 +136,8 @@ LIMITS:
     - name: Persistence
       required: true
       description: Number of consecutive times the telemetry item must be within
-        a different limits range before changing limits state.
+        a different limits range before changing limits state. Note if you have
+        multiple LIMITS items they should all have the same persistence value.
       values: \d+
     - name: Initial State
       required: true

data/data/config/microservice.yaml

@@ -117,7 +117,11 @@ MICROSERVICE:
           values: .+
     SECRET:
       summary: Define a secret needed by this microservice
-      description: Defines a secret for this microservice. For more information see [Admin Secrets](/docs/tools/admin#secrets).
+      description:
+        Defines a secret for this microservice. For more information see [Admin Secrets](/docs/tools/admin#secrets).
+        Note that unlike the INTERFACE SECRET, the microservice SECRET does not take an Option Name parameter,
+        because the secret value is injected directly into the microservice process as an environment variable
+        (Type ENV) or written to a file (Type FILE).
       since: 5.3.0
       parameters:
         - name: Type

data/data/config/screen.yaml

@@ -159,7 +159,8 @@ NAMED_WIDGET:
     - name: Widget Name
       required: true
       description: The unique name applied to the following widget instance.
-        Names must be unique per screen.
+        Names must be unique per screen. Names are case insensitive, e.g.
+        getNamedWidget('duration') returns the widget named DURATION.
       values: .+
     - name: Widget Type
       required: true

data/data/config/target.yaml

@@ -81,6 +81,13 @@ TARGET:
       description:
         Sets the retention time directly on QuestDB tables for automatic data expiration.
         QuestDB will automatically remove data older than this retention time.
+        Tables are partitioned by day and QuestDB only drops whole partitions, so the
+        effective granularity is one day. Hour values are rounded up to whole days
+        ("1h" becomes 1 day, "25h" becomes 2 days) so data is never dropped early,
+        and data is not removed until the entire day partition is older than the retention
+        time (expect up to a day of extra data). Expiration is evaluated when new data is
+        written to the table, so an idle table is not expired.
+        Changing this value and reinstalling the plugin updates existing tables.
       since: 7.0.0
       parameters:
         - name: Time
@@ -95,6 +102,13 @@ TARGET:
       description:
         Sets the retention time directly on QuestDB tables for automatic data expiration.
         QuestDB will automatically remove data older than this retention time.
+        Tables are partitioned by day and QuestDB only drops whole partitions, so the
+        effective granularity is one day. Hour values are rounded up to whole days
+        ("1h" becomes 1 day, "25h" becomes 2 days) so data is never dropped early,
+        and data is not removed until the entire day partition is older than the retention
+        time (expect up to a day of extra data). Expiration is evaluated when new data is
+        written to the table, so an idle table is not expired.
+        Changing this value and reinstalling the plugin updates existing tables.
       since: 7.0.0
       parameters:
         - name: Time
@@ -104,6 +118,13 @@ TARGET:
             Supported units are h (hours), d (days), w (weeks), M (months), y (years).
             Default = nil = Forever
           values: \d+[hdwMy]
+    DECOM_FLUSH_PERIOD:
+      summary: Period in seconds between flushing rows to the TSDB. Higher values use less CPU.
+      parameters:
+        - name: Period
+          required: true
+          description: Number of seconds between flushing rows to the TSDB (default = 5.0)
+          values: .+
     LOG_RETAIN_TIME:
       summary: How long to keep all regular telemetry logs in seconds.
       parameters:
@@ -170,3 +191,20 @@ TARGET:
           values: \d+
       example: |
         DB_SHARD 0
+    STORED_LIMITS_MODE:
+      summary: Controls how limits are evaluated for stored (non-real-time) telemetry packets
+      description:
+        Sets the limits handling policy for packets where the stored flag is true
+        (e.g., packets from file interfaces or historical data replay).
+        PROCESS processes limits normally including logging and reactions.
+        LOG evaluates limits and logs state changes but does not trigger limits reactions
+        or update the current limits state used by the API.
+        DISABLE skips limits processing entirely for stored packets.
+      since: 7.2.1
+      parameters:
+        - name: Mode
+          required: true
+          description: "PROCESS (default), LOG, or DISABLE"
+          values: ^(PROCESS|LOG|DISABLE)$
+      example: |
+        STORED_LIMITS_MODE DISABLE

data/data/config/tool.yaml

@@ -2,7 +2,9 @@
 TOOL:
   summary: Define a tool
   example: TOOL DEMO Demo
-  description: Defines a tool that the plugin adds to the OpenC3 system. Tools are web based applications that make use of the Single-SPA javascript library that allows them to by dynamically added to the running system as independent frontend microservices.
+  description: |
+    Defines a tool that the plugin adds to the OpenC3 system. Tools are web based applications that make use of the Single-SPA javascript library that allows them to be dynamically added to the running system as independent frontend microservices.
+    Tools are global to the entire COSMOS installation. Regardless of the scope a plugin is installed into, its tools are always installed into the DEFAULT scope and are available in every scope.
   parameters:
     - name: Tool Folder Name
       description: The exact name of the tool folder in the plugin. ie. tools/ToolFolderName