openc3 5.5.2.pre.beta0 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9afdd0579f3b0663d3cd0d378483b372c2f3c34faa5856d1c5ef5b4a1e582af3
-  data.tar.gz: 9224b37cda9d56d8e867a0ead73d815b3140979355a85d408824377e628fec10
+  metadata.gz: 9de820bd93122cc0e11533c3d875e3d6babce9247128f9a63fe3ad6e75b6d196
+  data.tar.gz: 293cf85c989666a805a3dec9125ba35692548c27910a09aff871f3c4c523fe7b
 SHA512:
-  metadata.gz: 2c3e6009efea9ee0b7669634ba9dd0c45dd81fa9f47405ddd44ec375993e7d85b8f4b51547cb943c3229e2bfd7e5aa5ddfc5ad1de8963a6d05e8220c029e3baf
-  data.tar.gz: 4cbe48f762771ad19429e19102f5fe427607814b1eb2149a06ed713a972d807481b767b023031fe21c21465a67108e39ceb0fef003d0ffea533b3db223960764
+  metadata.gz: 26a29caa9cd9a211959587b54c76c389dbb70390d573587972a52938c9a3c8ccfcbd702d52f942b37f89133bf76048018ef569a9dcd6ff1990b9030ba62d9208
+  data.tar.gz: c8dce98075822016cfe3c10624b2e54f174d32b87fda748eb04d43031a89535538d8746f1da0945201f9a8b614499c961bcf3bc61fd03973999dfccae122ceb3

data/bin/openc3cli

@@ -79,6 +79,28 @@ def print_usage
   puts ""
 end
 
+def check_environment
+  hostname = ENV['OPENC3_API_HOSTNAME'] || (ENV['OPENC3_DEVEL'] ? '127.0.0.1' : 'openc3-cosmos-cmd-tlm-api')
+  begin
+    Resolv.getaddress(hostname)
+  rescue Resolv::ResolvError
+    abort "Unable to resolv api hostname: #{hostname}"
+  end
+
+  if hostname =~ /openc3-cosmos-cmd-tlm-api/
+    $openc3_in_cluster = true
+  else
+    $openc3_in_cluster = false
+  end
+
+  unless $openc3_in_cluster
+    # Make sure the user has all the required environment variables set
+    abort "OPENC3_API_HOSTNAME environment variable is required" unless ENV['OPENC3_API_HOSTNAME']
+    abort "OPENC3_API_PORT environment variable is required" unless ENV['OPENC3_API_PORT']
+    abort "OPENC3_API_PASSWORD environment variable is required" unless ENV['OPENC3_API_PASSWORD']
+  end
+end
+
 def migrate(args)
   MIGRATE_PARSER.parse!(args)
   abort(MIGRATE_PARSER.to_s) if args.length == 0
@@ -101,9 +123,7 @@ def migrate(args)
   # NOTE: generate does a chdir to be inside the plugin directory
   ###############################################################
   plugin = args.shift
-  target_name = OpenC3::CliGenerator.generate(['plugin', plugin])
-  # Delete target contents from the plugin framework (but keep directory)
-  FileUtils.rm_rf Dir.glob("targets/#{target_name}/*")
+  OpenC3::CliGenerator.generate(['plugin', plugin])
 
   if MIGRATE_OPTIONS.all
     # Grab all target directories to match the command line input
@@ -301,6 +321,29 @@ def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_line
   end
 end
 
+def wait_process_complete(process_name)
+  STDOUT.flush
+  state = 'Running'
+  status = nil
+  while state == 'Running'
+    status = plugin_status(process_name)
+    state = status['state']
+    sleep(5)
+    print '.'
+    STDOUT.flush
+  end
+  puts "\nFinished: #{state}"
+  puts "Output:\n"
+  puts status['output']
+  if state == 'Complete'
+    puts "Success!"
+    exit 0
+  else
+    puts "Failed!"
+    exit 1
+  end
+end
+
 # Loads a plugin into the OpenC3 system
 # This code is used from the command line and is the same code that gets called if you
 # edit/upgrade or install a new plugin from the Admin interface
@@ -320,90 +363,142 @@ end
 #
 def load_plugin(plugin_file_path, scope:, plugin_hash_file: nil, force: false)
   scope ||= 'DEFAULT'
-  # Only create the scope if it doesn't already exist
-  unless OpenC3::ScopeModel.names.include?(scope)
-    begin
-      puts "Creating scope: #{scope}"
-      scope_model = OpenC3::ScopeModel.new(name: scope, scope: scope)
-      scope_model.create
-      scope_model.deploy(".", {})
-    rescue => err
-      abort("Error creating scope: #{scope}: #{err.formatted}")
+  check_environment()
+  if $openc3_in_cluster
+    # In Cluster
+
+    # Only create the scope if it doesn't already exist
+    unless OpenC3::ScopeModel.names.include?(scope)
+      begin
+        puts "Creating scope: #{scope}"
+        scope_model = OpenC3::ScopeModel.new(name: scope, scope: scope)
+        scope_model.create
+        scope_model.deploy(".", {})
+      rescue => err
+        abort("Error creating scope: #{scope}: #{err.formatted}")
+      end
     end
-  end
 
-  begin
-    if plugin_hash_file
-      # Admin Create / Edit / or Upgrade Plugin
-      OpenC3::PluginModel.install_phase1(plugin_file_path, scope: scope)
-      plugin_hash = JSON.parse(File.read(plugin_hash_file), :allow_nan => true, :create_additions => true)
-    else
-      # Init or Command Line openc3cli load with no plugin_hash_file
-      file_full_name = File.basename(plugin_file_path, ".gem")
-      file_gem_name = file_full_name.split('-')[0..-2].join('-')
-      found = false
-      plugin_names = OpenC3::PluginModel.names(scope: scope)
-      plugin_names.each do |plugin_name|
-        gem_name = plugin_name.split("__")[0]
-        full_name = File.basename(gem_name, ".gem")
-        gem_name = full_name.split('-')[0..-2].join('-')
-        if file_gem_name == gem_name
-          found = true
-          # Upgrade if version changed else do nothing
-          if file_full_name != full_name
-            update_plugin(plugin_file_path, plugin_name, scope: scope, existing_plugin_name: plugin_name, force: force)
-          else
-            puts "No version change detected for: #{plugin_name}"
+    begin
+      if plugin_hash_file
+        # Admin Create / Edit / or Upgrade Plugin
+        OpenC3::PluginModel.install_phase1(plugin_file_path, scope: scope)
+        plugin_hash = JSON.parse(File.read(plugin_hash_file), :allow_nan => true, :create_additions => true)
+      else
+        # Init or Command Line openc3cli load with no plugin_hash_file
+        file_full_name = File.basename(plugin_file_path, ".gem")
+        file_gem_name = file_full_name.split('-')[0..-2].join('-')
+        found = false
+        plugin_names = OpenC3::PluginModel.names(scope: scope)
+        plugin_names.each do |plugin_name|
+          gem_name = plugin_name.split("__")[0]
+          full_name = File.basename(gem_name, ".gem")
+          gem_name = full_name.split('-')[0..-2].join('-')
+          if file_gem_name == gem_name
+            found = true
+            # Upgrade if version changed else do nothing
+            if file_full_name != full_name
+              update_plugin(plugin_file_path, plugin_name, scope: scope, existing_plugin_name: plugin_name, force: force)
+            else
+              puts "No version change detected for: #{plugin_name}"
+            end
           end
         end
+        return if found
+
+        plugin_hash = OpenC3::PluginModel.install_phase1(plugin_file_path, scope: scope)
       end
-      return if found
 
-      plugin_hash = OpenC3::PluginModel.install_phase1(plugin_file_path, scope: scope)
-    end
+      # Determine if plugin named in plugin_hash exists
+      existing_plugin_hash = OpenC3::PluginModel.get(name: plugin_hash['name'], scope: scope)
+
+      # Existing plugin hash will be present if plugin is being edited or upgraded
+      # However, a missing existing could also be that a plugin was updated in local mode directly from across installations
+      # changing the plugin name without really meaning to create a new instance of the plugin
+      # ie.
+      # User on machine 1 checks in a changed plugin_instance.json with a different name - There is still only one plugin desired and committed
+      # User on machine 2 starts up with the new configuration, OpenC3::PluginModel.get will return nil because the exact name is different
+      # In this case, the plugin should be updated without installing a second instance. analyze_local_mode figures this out.
+      unless existing_plugin_hash
+        existing_plugin_hash = OpenC3::LocalMode.analyze_local_mode(plugin_name: plugin_hash['name'], scope: scope)
+      end
 
-    # Determine if plugin named in plugin_hash exists
-    existing_plugin_hash = OpenC3::PluginModel.get(name: plugin_hash['name'], scope: scope)
-
-    # Existing plugin hash will be present if plugin is being edited or upgraded
-    # However, a missing existing could also be that a plugin was updated in local mode directly from across installations
-    # changing the plugin name without really meaning to create a new instance of the plugin
-    # ie.
-    # User on machine 1 checks in a changed plugin_instance.json with a different name - There is still only one plugin desired and committed
-    # User on machine 2 starts up with the new configuration, OpenC3::PluginModel.get will return nil because the exact name is different
-    # In this case, the plugin should be updated without installing a second instance. analyze_local_mode figures this out.
-    unless existing_plugin_hash
-      existing_plugin_hash = OpenC3::LocalMode.analyze_local_mode(plugin_name: plugin_hash['name'], scope: scope)
+      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)
+      else
+        # New Install
+        puts "Loading new 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, scope: scope)
+      end
+    rescue => error
+      abort("Error installing plugin: #{scope}: #{plugin_file_path}\n#{error.message}")
     end
+  else
+    # Outside Cluster
+    require 'openc3/script'
 
-    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)
+    if plugin_hash_file
+      plugin_hash = JSON.parse(File.read(plugin_hash_file), :allow_nan => true, :create_additions => true)
     else
-      # New Install
-      puts "Loading new 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, scope: scope)
+      plugin_hash = plugin_install_phase1(plugin_file_path, scope: scope)
     end
-  rescue => error
-    abort("Error installing plugin: #{scope}: #{plugin_file_path}\n#{error.message}")
+
+    process_name = plugin_install_phase2(plugin_hash, scope: scope)
+
+    print "Installing..."
+    wait_process_complete(process_name)
   end
 end
 
 def unload_plugin(plugin_name, scope:)
   scope ||= 'DEFAULT'
-  begin
-    OpenC3::PluginModel.new(name: plugin_name, scope: scope).destroy
-    OpenC3::LocalMode.remove_local_plugin(plugin_name, scope: scope)
-    OpenC3::Logger.info("PluginModel destroyed: #{plugin_name}", scope: scope)
-  rescue => err
-    abort("Error uninstalling plugin: #{scope}: #{plugin_name}: #{err.formatted}")
+  check_environment()
+  if $openc3_in_cluster
+    begin
+      plugin_model = OpenC3::PluginModel.get_model(name: plugin_name, scope: scope)
+      plugin_model.destroy
+      OpenC3::LocalMode.remove_local_plugin(plugin_name, scope: scope)
+      OpenC3::Logger.info("PluginModel destroyed: #{plugin_name}", scope: scope)
+    rescue => err
+      abort("Error uninstalling plugin: #{scope}: #{plugin_name}: #{err.formatted}")
+    end
+  else
+    # Outside Cluster
+    require 'openc3/script'
+    process_name = plugin_uninstall(plugin_name, scope: scope)
+    print "Uninstalling..."
+    wait_process_complete(process_name)
+  end
+end
+
+def cli_gem_install(gem_filename, scope:)
+  scope ||= 'DEFAULT'
+  check_environment()
+  if $openc3_in_cluster
+    OpenC3::GemModel.install(gem_filename, scope: scope)
+  else
+    # Outside Cluster
+    require 'openc3/script'
+    process_name = gem_install(gem_filename, scope: scope)
+    print "Installing..."
+    wait_process_complete(process_name)
   end
 end
 
-def gem_install(gem_filename, scope:)
-  OpenC3::GemModel.install(gem_filename, scope: scope)
+def cli_gem_uninstall(gem_filename, scope:)
+  scope ||= 'DEFAULT'
+  check_environment()
+  if $openc3_in_cluster
+    OpenC3::GemModel.destroy(gem_filename)
+  else
+    # Outside Cluster
+    require 'openc3/script'
+    gem_uninstall(gem_filename, scope: scope)
+    puts "Success!"
+  end
 end
 
 def get_redis_keys
@@ -510,7 +605,10 @@ if not ARGV[0].nil? # argument(s) given
     unload_plugin(ARGV[1], scope: ARGV[2])
 
   when 'geminstall'
-    gem_install(ARGV[1], scope: ARGV[2])
+    cli_gem_install(ARGV[1], scope: ARGV[2])
+
+  when 'gemuninstall'
+    cli_gem_uninstall(ARGV[1], scope: ARGV[2])
 
   when 'generate'
     OpenC3::CliGenerator.generate(ARGV[1..-1])

data/data/config/_interfaces.yaml

@@ -17,7 +17,6 @@ tcpip_client_interface.rb:
     - name: Write Timeout
       required: true
       description: Number of seconds to wait before aborting the write.
-        Pass 'nil' to block on write.
       values: .+
     - name: Read Timeout
       required: true
@@ -43,7 +42,6 @@ tcpip_server_interface.rb:
     - name: Write Timeout
       required: true
       description: Number of seconds to wait before aborting the write.
-        Pass 'nil' to block on write.
       values: .+
     - name: Read Timeout
       required: true
@@ -90,9 +88,7 @@ udp_interface.rb:
       values: .+
     - name: Write Timeout
       required: false
-      description:
-        Number of seconds to wait before aborting the write. Default is
-        'nil' (block on write).
+      description: Number of seconds to wait before aborting the write
       values: .+
     - name: Read Timeout
       required: false
@@ -134,7 +130,6 @@ serial_interface.rb:
     - name: Write Timeout
       required: true
       description: Number of seconds to wait before aborting the write.
-        Pass 'nil' to block on write.
       values: .+
     - name: Read Timeout
       required: true

data/data/config/interface_modifiers.yaml

@@ -6,6 +6,9 @@ MAP_TARGET:
       required: true
       description: Target name to map to this interface
       values: .+
+  example: |
+    INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
+      MAP_TARGET DATA
 MAP_CMD_TARGET:
   summary: Maps a target name to an interface for commands only
   since: 5.2.0
@@ -14,6 +17,9 @@ MAP_CMD_TARGET:
       required: true
       description: Command target name to map to this interface
       values: .+
+  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
 MAP_TLM_TARGET:
   summary: Maps a target name to an interface for telemetry only
   since: 5.2.0
@@ -22,6 +28,9 @@ MAP_TLM_TARGET:
       required: true
       description: Telemetry target name to map to this interface
       values: .+
+  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
 DONT_CONNECT:
   summary: Server will not automatically try to connect to the interface at startup
 DONT_RECONNECT:
@@ -43,14 +52,41 @@ DISABLE_DISCONNECT:
     Use this keyword to prevent the user from disconnecting from the interface.
     This is typically used in a 'production' environment where you would not want
     the user to inadvertantly disconnect from a target.
-DONT_LOG:
-  summary: Disable logging commands and telemetry on this interface
 LOG_RAW:
+  summary: Deprecated, use LOG_STREAM
+LOG_STREAM:
   summary: Log all data on the interface exactly as it is sent and received
   description:
-    LOG_RAW does not add any OpenC3 headers and thus can not be read by OpenC3 tools.
+    LOG_STREAM does not add any OpenC3 headers and thus can not be read by OpenC3 tools.
     It is primarily useful for low level debugging of an interface. You will have to
     manually parse these logs yourself using a hex editor or other application.
+  since: 5.5.2
+  parameters:
+    - name: Cycle Time
+      required: false
+      description:
+        Amount of time to wait before cycling the log file. Default is 10 min.
+        If nil refer to Cycle Hour and Cycle Minute.
+      values: .*
+    - name: Cycle Size
+      required: false
+      description: Amount of data to write before cycling the log file. Default is 50MB.
+      values: .*
+    - name: Cycle Hour
+      required: false
+      description:
+        The time at which to cycle the log. Combined with Cycle Minute to cycle
+        the log daily at the specified time. If nil, the log will be cycled hourly at the specified Cycle Minute.
+        Only applies if Cycle Time is nil.
+      values: .*
+    - name: Cycle Minute
+      required: false
+      description: See Cycle Hour.
+      values: .*
+  example: |
+    INTERFACE EXAMPLE example_interface.rb
+      # Override the default log time of 600
+      LOG_STREAM 60
 PROTOCOL:
   summary: Protocols modify the interface by processing the data
   description:
@@ -71,6 +107,14 @@ PROTOCOL:
     - name: Protocol specific parameters
       required: false
       description: Additional parameters used by the protocol
+  example: |
+    INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil nil
+      MAP_TARGET DATA
+      # Rather than defining the LENGTH protocol on the INTERFACE line we define it here
+      PROTOCOL READ LengthProtocol 0 16 0 1 BIG_ENDIAN 4 0xBA5EBA11
+    INTERFACE DATA_INT tcpip_client_interface.rb host.docker.internal 8080 8081 10.0 nil BURST
+      MAP_TARGET DATA
+      PROTOCOL READ IgnorePacketProtocol INST IMAGE # Drop all INST IMAGE packets
 OPTION:
   summary: Set a parameter on an interface
   description:
@@ -90,6 +134,10 @@ OPTION:
       required: false
       description: Parameters to pass to the option
       values: .*
+  example: |
+    INTERFACE SERIAL_INT serial_interface.rb COM1 COM1 115200 NONE 1 10.0 nil
+      OPTION FLOW_CONTROL RTSCTS
+      OPTION DATA_BITS 8
 SECRET:
   summary: Define a secret needed by this interface
   description: Defines a secret for this interface and optionally assigns its value to an option
@@ -105,7 +153,7 @@ SECRET:
       required: true
       description: The name of the secret to retrieve
       values: .*
-    - name: Environment Variable of File Path
+    - name: Environment Variable or File Path
       required: true
       description: Environment variable name or file path to store secret
       values: .*
@@ -117,3 +165,6 @@ SECRET:
       required: false
       description: Name of the secret store for stores with multipart keys
       values: .*
+  example: |
+    SECRET ENV USERNAME ENV_USERNAME USERNAME
+    SECRET FILE KEY "/tmp/DATA/cert" KEY

data/data/config/microservice.yaml

@@ -1,7 +1,6 @@
 ---
 MICROSERVICE:
   summary: Defines a new microservice
-  example: MICROSERVICE EXAMPLE example-microservice
   description: Defines a microservice that the plugin adds to the OpenC3 system. Microservices are background software processes that perform persistent processing.
   parameters:
     - name: Microservice Folder Name
@@ -12,6 +11,7 @@ MICROSERVICE:
       description: The specific name of this instance of the microservice in the OpenC3 system
       required: true
       values: .+
+  example: MICROSERVICE EXAMPLE openc3-example
   modifiers:
     ENV:
       summary: Sets an environment variable in the microservice.
@@ -24,6 +24,9 @@ MICROSERVICE:
           required: true
           description: Environment variable value
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          ENV COMPANY OpenC3
     WORK_DIR:
       summary: Set the working directory
       description: Working directory to run the microservice CMD in.  Can be a path relative to the microservice folder in the plugin, or an absolute path in the container the microservice runs in.
@@ -32,6 +35,9 @@ MICROSERVICE:
           required: true
           description: Working directory to run the microservice CMD in. Can be a path relative to the microservice folder in the plugin, or an absolute path in the container the microservice runs in.
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          WORK_DIR .
     PORT:
       summary: Open port for the microservice
       description: Kubernetes needs a Service to be applied to open a port so this is required for Kubernetes support
@@ -45,6 +51,9 @@ MICROSERVICE:
           required: false
           description: Port protocol. Default is TCP.
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          PORT 7272
     TOPIC:
       summary: Associate a Redis topic
       description: Redis topic to associate with this microservice. Standard OpenC3 microservices such as decom_microservice use this information to know what packet streams to subscribe to. The TOPIC keyword can be used as many times as necessary to associate all needed topics.
@@ -53,6 +62,12 @@ MICROSERVICE:
           required: true
           description: Redis Topic to associate with the microservice
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          # Manually assigning topics is an advanced topic and requires
+          # intimate knowledge of the internal COSMOS data structures.
+          TOPIC DEFAULT__openc3_log_messages
+          TOPIC DEFAULT__TELEMETRY__EXAMPLE__STATUS
     TARGET_NAME:
       summary: Associate a OpenC3 target
       description: OpenC3 target to associate with the microservice. For standard OpenC3 microservices such as decom_microservice this causes the target configuration to get loaded into the container for the microservice.
@@ -61,6 +76,9 @@ MICROSERVICE:
           required: true
           description: OpenC3 target to associate with the microservice
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          TARGET_NAME EXAMPLE
     CMD:
       summary: Command line to execute to run the microservice.
       description: Command line to execute to run the microservice.
@@ -69,6 +87,9 @@ MICROSERVICE:
           required: true
           description: One or more arguments to exec to run the microservice.
           values: .+
+      example: |
+        MICROSERVICE EXAMPLE openc3-example
+          CMD ruby example_target.rb
     OPTION:
       summary: Pass an option to the microservice
       description: Generic key/value(s) options to pass to the microservice. These take the form of KEYWORD/PARAMS like a line in a OpenC3 configuration file. Multiple OPTION keywords can be used to pass multiple options to the microservice.
@@ -82,8 +103,8 @@ MICROSERVICE:
           description: One or more values to associate with the option
           values: .+
     CONTAINER:
-      summary: Docker Container.
-      description: Container to execute and run the microservice in.
+      summary: Docker Container
+      description: Container to execute and run the microservice in. Only used in COSMOS Enterprise Edition.
       parameters:
         - name: Args
           required: false
@@ -112,6 +133,9 @@ MICROSERVICE:
           required: false
           description: Name of the secret store for stores with multipart keys
           values: .*
+      example: |
+        SECRET ENV USERNAME ENV_USERNAME
+        SECRET FILE KEY "/tmp/DATA/cert"
     ROUTE_PREFIX:
       summary: Prefix of route
       description: Prefix of route to the microservice to expose externally with Traefik
@@ -121,3 +145,6 @@ MICROSERVICE:
           required: true
           description: Route prefix. Must be unique across all scopes. Something like /myprefix
           values: .*
+      example: |
+        MICROSERVICE CFDP CFDP
+          ROUTE_PREFIX /cfdp

data/data/config/widgets.yaml

@@ -1316,11 +1316,9 @@ Interactive Widgets:
         The api.tlm() function returns a Promise which is resolved with then()
         at which point we send the command with the telemetry value we received.
 
-        Scripts can be launched from a BUTTON using the `runScript()` method.
-      # warning:
-      #   If your button logic gets complex it's recommended to require a separate
-      #   script and pass the screen to the script using self,
-      #   e.g. require utility.rb; utility_method(self).
+        Scripts can be launched from a BUTTON using the `runScript()` method. `runScript()` takes three parameters,
+        the name of the script, whether to open the script in the foreground of Script Runner (default = true), and a hash of
+        environment variables. For example: `runScript('INST/procedures/script.rb', false, {'VAR': 'VALUE'})`
       parameters:
         - name: Button Text
           required: true
@@ -1332,7 +1330,14 @@ Interactive Widgets:
           values: .+
       example: |
         BUTTON 'Start Collect' 'api.cmd("INST COLLECT with TYPE NORMAL, DURATION 5")'
-        BUTTON 'Run Script' 'runScript("INST/procedures/script.rb")'
+        BUTTON 'Run Checks' 'runScript("INST/procedures/checks.rb")'
+        # More complex example with background checkbox and env vars
+        NAMED_WIDGET SCRIPTNAME COMBOBOX collect.rb checks.rb
+        NAMED_WIDGET BG CHECKBUTTON 'Background'
+        BUTTON 'Run Script' "var script=screen.getNamedWidget('SCRIPTNAME').text();" \
+          # Set an environment variable to be used by the script as ENV['TYPE']
+          "var env = {}; env['TYPE'] = 'TEST';" \
+          "runScript('INST/procedures/'+script, !screen.getNamedWidget('BG').checked(), env)"
     CHECKBUTTON:
       summary: Displays a check box
       description: