openc3 7.2.1 → 7.4.0

data/data/config/interface_modifiers.yaml

@@ -168,7 +168,7 @@ SECRET:
   summary: Define a secret needed by this interface
   description:
     Defines a secret for this interface and optionally assigns its value to an option.
-    For more information see [Admin Secrets](/docs/tools/admin#secrets).
+    For more information see the [Secrets guide](/docs/guides/secrets) and [Admin Secrets](/docs/tools/admin#secrets).
   since: 5.3.0
   parameters:
     - name: Type
@@ -186,6 +186,8 @@ SECRET:
     - name: Environment Variable or File Path
       required: true
       description: Environment variable name or file path to store secret.
+        FILE paths must be under /tmp (or the directory set by the
+        OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
         Note that if you use the Option Name to set an option to the secret value,
         this value doesn't really matter as long as it is unique.
       values: .*
@@ -284,3 +286,103 @@ SHARD:
       values: \d+
   example: |
     SHARD 0
+BRIDGE:
+  summary: Name of the bridge to run this interface on
+  description: Run this interface on a bridge host rather than within COSMOS. Note only python is supported.
+  since: 7.4.0
+  parameters:
+    - name: Bridge Name
+      required: true
+      description: Bridge Name - Typically DEFAULT
+      values: .+
+  example: |
+    BRIDGE DEFAULT
+BRIDGE_PROTOCOL:
+  summary: Bridge Protocols modify the bridge interface by processing the data
+  description:
+    Protocols can be either READ, WRITE, or READ_WRITE. READ protocols act on the data
+    received by the interface while write acts on the data before it is sent out. READ_WRITE applies
+    the protocol to both reading and writing.<br/><br/>
+    For information on creating your own custom protocol please see [Protocols](../configuration/protocols.md)
+  since: 7.4.0
+  parameters:
+    - name: Type
+      required: true
+      description: Whether to apply the protocol on incoming data, outgoing data, or both
+      values: ["READ", "WRITE", "READ_WRITE"]
+    - name: Protocol Filename or Classname
+      required: true
+      description: Ruby or Python filename or class name which implements the protocol
+      values: .*
+    - name: Protocol specific parameters
+      required: false
+      description: Additional parameters used by the protocol
+  python_example: |
+    INTERFACE DATA_INT openc3/interfaces/tcpip_client_interface.py host.docker.internal 8080 8081 10.0 nil BURST
+      MAP_TARGET DATA
+      BRIDGE_PROTOCOL READ openc3/interfaces/protocols/ignore_packet_protocol.py INST IMAGE # Drop all INST IMAGE packets
+BRIDGE_OPTION:
+  summary: Set a parameter on a bridged interface
+  description:
+    When a bridge option is set the bridge interface class calls the set_option method.
+    Custom interfaces can override set_option to handle any additional options they want.
+  since: 7.4.0
+  parameters:
+    - name: Name
+      required: true
+      description:
+        The option to set. OpenC3 defines several options on the core provided
+        interfaces. The SerialInterface defines FLOW_CONTROL which can be NONE (default) or RTSCTS
+        and DATA_BITS which changes the data bits of the serial interface.
+        The TcpipServerInterface and HttpServerInterface define LISTEN_ADDRESS which is the IP address to accept
+        connections on (default 0.0.0.0).
+      values: .*
+    - name: Parameters
+      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
+      BRIDGE DEFAULT
+      BRIDGE_OPTION FLOW_CONTROL RTSCTS
+      BRIDGE_OPTION DATA_BITS 8
+BRIDGE_SECRET:
+  summary: Define a bridge secret needed by this bridge interface
+  description:
+    Defines a bridge secret for this bridge interface and optionally assigns its value to an option.
+    For more information see [Admin Secrets](/docs/tools/admin#secrets).
+  since: 7.4.0
+  parameters:
+    - name: Type
+      required: true
+      description:
+        ENV or FILE.  ENV will mount the secret into an environment variable.
+        FILE mounts the secret into a file.
+      values: .*
+    - name: Secret Name
+      required: true
+      description:
+        The name of the secret to retrieve from the Admin / Secrets tab.
+        For more information see [Admin Secrets](/docs/tools/admin#secrets).
+      values: .*
+    - name: Environment Variable or File Path
+      required: true
+      description: Environment variable name or file path to store secret.
+        FILE paths must be under /tmp (or the directory set by the
+        OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
+        Note that if you use the Option Name to set an option to the secret value,
+        this value doesn't really matter as long as it is unique.
+      values: .*
+    - name: Option Name
+      required: false
+      description: Interface option to pass the secret value. This is the primary way to pass secrets to interfaces.
+      values: .*
+    - name: Secret Store Name
+      required: false
+      description: Name of the secret store for stores with multipart keys
+      values: .*
+  example: |
+    INTERFACE SERIAL_INT serial_interface.rb COM1 COM1 115200 NONE 1 10.0 nil
+      BRIDGE DEFAULT
+      BRIDGE_SECRET ENV USERNAME ENV_USERNAME USERNAME
+      BRIDGE_SECRET FILE KEY "/tmp/DATA/cert" KEY

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,12 @@ 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 the [Secrets guide](/docs/guides/secrets)
+        and [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
@@ -134,7 +139,9 @@ MICROSERVICE:
           values: .*
         - name: Environment Variable or File Path
           required: true
-          description: Environment variable name or file path to store secret
+          description: Environment variable name or file path to store secret.
+            FILE paths must be under /tmp (or the directory set by the
+            OPENC3_SECRET_FILE_DIR environment variable); paths outside of it are rejected.
           values: .*
         - name: Secret Store Name
           required: false

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:

data/data/config/telemetry_modifiers.yaml

@@ -274,6 +274,8 @@ TEMPLATE_FILE:
     - name: Template File Path
       required: true
       description: The relative path to the template file. Filename should generally start with an underscore.
+        Absolute paths and paths containing '..' are not allowed. The file must be inside the directory
+        containing the definition file.
       values: .+
   since: 5.0.10
 IGNORE_OVERLAP:

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

data/data/config/widgets.yaml

@@ -206,6 +206,9 @@ Decoration Widgets:
         END
     FILEDISPLAY:
       summary: Displays the contents of a target file with syntax highlighting
+      description: Files are read from the COSMOS bucket, either the target's installed files or the modified
+        copy under targets_modified. In local mode a file created only on the local filesystem
+        (plugins/SCOPE/targets_modified) is not in the bucket and cannot be read.
       since: 6.10.3
       parameters:
         - name: File path
@@ -224,6 +227,9 @@ Decoration Widgets:
         FILEDISPLAY "INST/data/sample.json" 400 200
     FILECHECKSUM:
       summary: Displays SHA-256 checksum of one or more files, with comparison if multiple
+      description: Files are read from the COSMOS bucket, either the target's installed files or the modified
+        copy under targets_modified. In local mode a file created only on the local filesystem
+        (plugins/SCOPE/targets_modified) is not in the bucket and cannot be read.
       since: 6.10.3
       parameters:
         - name: File path
@@ -1442,6 +1448,19 @@ Interactive Widgets:
         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'})`
+
+        For security, button code does NOT run in the main application. It runs in an isolated,
+        sandboxed browser context that has no access to your login session, browser storage, or
+        the page, and no network access of its own. The `api`, `screen`, `runScript` and `alert`
+        objects still work exactly as before (the real work is performed by the application on the
+        button code's behalf). A few consequences of this isolation:
+
+        - `alert()` no longer pauses code execution while the alert is displayed.
+        - `screen.getNamedWidget("WIDGET_NAME").text()` (and `selected()` / `checked()` / `value`)
+          return the widget's value as it was when the button was clicked; a `.value =` assignment
+          made earlier in the same button click is not guaranteed to be visible to a later read in
+          that same click.
+        - The `self` variable (the internal widget component) is no longer available to button code.
       parameters:
         - name: Button Text
           required: true
@@ -1613,7 +1632,7 @@ Canvas Widgets:
               description: Blue value of the RGB value
               values: .+
       example: |
-        CANVAS 100 50
+        CANVAS 150 50
           SETTING BACKCOLOR 17 21 28
           CANVASLABEL 5 30 "Dark canvas" 18 white
         END
@@ -1682,8 +1701,8 @@ Canvas Widgets:
           values: <%= %w(RAW CONVERTED FORMATTED) %>
       example: |
         CANVAS 200 100
-          CANVASLABELVALUE INST HEALTH_STATUS TEMP1 5 34 12 red
-          CANVASLABELVALUE INST HEALTH_STATUS TEMP2 5 70 10 blue FORMATTED
+          CANVASLABELVALUE INST HEALTH_STATUS TEMP1 5 34 20 red
+          CANVASLABELVALUE INST HEALTH_STATUS TEMP2 5 70 16 blue FORMATTED
         END
     CANVASIMAGE:
       summary: Displays an image on the canvas