openc3 5.0.6

data/data/config/_items.yaml

@@ -0,0 +1,20 @@
+---
+- name: Bit Size
+  required: true
+  description: Bit size of this telemetry item. Zero or Negative values may be used
+    to indicate that a string fills the packet up to the offset from the end of
+    the packet specified by this value. If Bit Offset is 0 and Bit Size is 0 then
+    this is a derived parameter and the Data Type must be set to 'DERIVED'.
+  values: \d+
+- name: Data Type
+  required: true
+  description: Data Type of this telemetry item
+  values: <%= %w(INT UINT FLOAT STRING BLOCK DERIVED) %>
+- name: Description
+  required: false
+  description: Description for this telemetry item which must be enclosed with quotes
+  values: "['\"].*['\"]"
+- name: Endianness
+  required: false
+  description: Indicates if the item is to be interpreted in Big Endian or Little Endian format
+  values: <%= %w(BIG_ENDIAN LITTLE_ENDIAN) %>

data/data/config/_params.yaml

@@ -0,0 +1,60 @@
+---
+- name: Bit Size
+  required: true
+  description: Bit size of this parameter. Zero or Negative values may be used
+    to indicate that a string fills the packet up to the offset from the end of
+    the packet specified by this value. If Bit Offset is 0 and Bit Size is 0 then
+    this is a derived parameter and the Data Type must be set to 'DERIVED'.
+  values: \d+
+- name: Data Type
+  required: true
+  description: Data Type of this parameter
+  values:
+    INT:
+      parameters: &params
+        - name: Minimum Value
+          required: true
+          description: Minimum allowed value for this parameter
+          values: .*
+        - name: Maximum Value
+          required: true
+          description: Maximum allowed value for this parameter
+          values: .*
+        - name: Default Value
+          required: true
+          description:
+            Default value for this parameter. You must provide a default
+            but if you mark the parameter REQUIRED then scripts will be forced to specify a value.
+          values: .*
+        - name: Description
+          required: false
+          description: Description for this parameter which must be enclosed with quotes
+          values: '[''"].*[''"]'
+        - name: Endianness
+          required: false
+          description: Indicates if the data in this command is to be sent in Big Endian or Little Endian format
+          values: <%= %w(BIG_ENDIAN LITTLE_ENDIAN) %>
+    UINT:
+      parameters: *params
+    FLOAT:
+      parameters: *params
+    DERIVED:
+      parameters: *params
+    STRING:
+      parameters: &sparams
+        - name: Default Value
+          required: true
+          description:
+            Default value for this parameter. You must provide a default
+            but if you mark the parameter REQUIRED then scripts will be forced to specify a value.
+          values: .*
+        - name: Description
+          required: false
+          description: Description for this parameter which must be enclosed with quotes
+          values: '[''"].*[''"]'
+        - name: Endianness
+          required: false
+          description: Indicates if the data in this command is to be sent in Big Endian or Little Endian format
+          values: <%= %w(BIG_ENDIAN LITTLE_ENDIAN) %>
+    BLOCK:
+      parameters: *sparams

data/data/config/cmd_tlm_server.yaml

@@ -0,0 +1,136 @@
+---
+TITLE:
+  summary: Sets the Command and Telemetry Server window title
+  parameters:
+  - name: Text
+    required: true
+    description: Text to put in the title of the Command and Telemetry Server window
+    values: .+
+PACKET_LOG_WRITER:
+  summary: Declare a packet log writer
+  description: Packet log writer is used to declare a packet log writer class and
+    give it a name which can be referenced by an interface. This is required if you
+    want interfaces to have their own dedicated log writers or want to combine
+    various interfaces into a single log file. By default, OpenC3 logs all data
+    on all interfaces into a single command log and a single telemetry log.
+    This keyword can also be used if you want to declare a different log file class
+    to create log files.
+  warning: You should NOT override the default without consulting a OpenC3 expert
+    as this may break the ability to successfully read and write log files.
+  example: |
+    PACKET_LOG_WRITER DEFAULT packet_log_writer.rb # Default
+    # The default logger filename will be <DATE>_openc3tlm.bin and will create a new log every 1MB
+    PACKET_LOG_WRITER DEFAULT packet_log_writer.rb openc3 true nil 1000000
+    # Create a logger named OPENC3_LOG which creates a new log every 5 min (600s)
+    PACKET_LOG_WRITER OPENC3_LOG packet_log_writer.rb openc3 true 600
+  parameters:
+    - name: Log Writer Name
+      required: true
+      description: The name of the log writer as reference by other cmd_tlm_server keywords.
+        This name also appears in the Logging tab on the Command and Telemetry Server.
+      values: .+
+    - name: Filename
+      required: true
+      description: Ruby file to use when instantiating a new log writer
+      values: '.+\.rb'
+    - name: Parameters
+      required: false
+      description: Optional parameters to pass to the log writer class when instantiating it.
+AUTO_INTERFACE_TARGETS:
+  summary: Automatically use each target's cmd_tlm_server.txt file to define the interface
+  description: Look for a cmd_tlm_server.txt file at the top level
+    of each target directory and use this file to configure the interface for that target.
+    This is a good way of keeping the knowledge of how to interface to a target
+    within that target. However, if you use substitute target names (by using DECLARE_TARGET)
+    or use different IP addresses then this will not work and you'll have to use the
+    INTERFACE_TARGET or INTERFACE keyword.
+INTERFACE_TARGET:
+  summary: Load the specified target's cmd_tlm_server.txt configuration file
+  example: |
+    INTERFACE_TARGET OPENC3 # Look in the OPENC3 target directory for cmd_tlm_server.txt
+    INTERFACE_TARGET OPENC3 config.txt # Look in the OPENC3 target directory for config.txt
+  parameters:
+    - name: Target Name
+      required: true
+      description: Name of the target
+      values: .+
+    - name: Configuration File
+      required: false
+      description: Configuration filename which contains the interface configuration.
+        Defaults to 'cmd_tlm_server.txt'.
+      values: .+
+INTERFACE:
+  modifiers:
+    <%= MetaConfigParser.load('interface_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a connection to a physical target
+  description: Interfaces are what OpenC3 uses to talk to a particular piece
+    of hardware. Interfaces require a Ruby file which implements all the interface
+    methods necessary to talk to the hardware. OpenC3 defines many built in interfaces
+    or you can define your own as long as it implements the interface protocol.
+  parameters:
+    - name: Interface Name
+      required: true
+      description: Name of the interface. This name will appear in the
+        Interfaces tab of the Server and is also referenced by other keywords.
+        The OpenC3 convention is to name interfaces after their targets with
+        '_INT' appended to the name, e.g. INST_INT for the INST target.
+      values: \D\S*
+    - name: Filename
+      required: true
+      description: Ruby file to use when instantiating the interface.
+      values:
+        <%= MetaConfigParser.load('_interfaces.yaml').to_meta_config_yaml(8) %>
+      documentation: Additional parameters are required. Please see the [Interfaces](/docs/v5/interfaces)
+        documentation for more details.
+ROUTER:
+  modifiers:
+    ROUTE:
+      summary: Map an interface to a router
+      description: Once an interface has been mapped to a router, all its received telemetry
+        will be sent out through the router.
+      parameters:
+        - name: Interface
+          required: true
+          description: Name of the interface
+          values: .+
+    <%= MetaConfigParser.load('interface_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Create an interface which reverses cmd/tlm data
+  description: Router creates an interface which receives command packets from
+    their remote targets and send them out their interfaces. They receive telemetry
+    packets from their interfaces and send them to their remote targets. This allows
+    routers to be intermediaries between an external client and an actual device.
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the router
+      values: .+
+    - name: Filename
+      required: true
+      description: Ruby file to use when instantiating the interface.
+      values:
+        <%= MetaConfigParser.load('_interfaces.yaml').to_meta_config_yaml(8) %>
+      documentation: Additional parameters are required. Please see the [Interfaces](/docs/v5/interfaces)
+        documentation for more details.
+COLLECT_METADATA:
+  summary: Prompts the user for meta data when starting the Command and Telemetry Server
+BACKGROUND_TASK:
+  modifiers:
+    STOPPED:
+      summary: Indicate the background task should not be automatically started
+  summary: Create a background task in the Command and Telemetry Server
+  description: The Server instantiates the class which must inherit from BackgroundTask
+    and then calls the call() method which the class must implement. The call() method
+    is only called once so if your background task is supposed to live on while the
+    Server is running, you must implement your code in a loop with a sleep to not
+    use all the CPU.
+  example: BACKGROUND_TASK example_background_task.rb
+  parameters:
+    - name: Filename
+      required: true
+      description: Ruby file which contains the background task implementation.
+        Must inherit from BackgroundTask and implement the call method.
+      values: '.+\.rb'
+    - name: Optional Arguments
+      required: false
+      description: Optional arguments to the background task constructor
+      values: .+

data/data/config/command.yaml

@@ -0,0 +1,44 @@
+---
+COMMAND:
+  # Prevent prettier from removing the newline after modifiers:
+  # prettier-ignore
+  modifiers:
+    <%= MetaConfigParser.load('command_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a new command packet
+  example: COMMAND INST COLLECT BIG_ENDIAN "Start collect"
+  parameters:
+    - name: Target
+      required: true
+      description: Name of the target this command is associated with
+      values: .+
+    - name: Command
+      required: true
+      description: Name of this command. Also referred to as its mnemonic.
+        Must be unique to commands to this target. Ideally will be as short and clear as possible.
+      values: \D\S*
+    - name: Endianness
+      required: true
+      description: Indicates if the data in this command is to be sent in Big Endian or Little Endian format
+      values: ["BIG_ENDIAN", "LITTLE_ENDIAN"]
+    - name: Description
+      required: false
+      description: Description of this command which must be enclosed with quotes
+      values: '[''"].*[''"]'
+SELECT_COMMAND:
+  # prettier-ignore
+  modifiers:
+    <%= MetaConfigParser.load('command_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Selects an existing command packet for editing
+  description:
+    Typically used in a separate configuration file from where the original
+    command is defined to override or add to the existing command definition
+  example: SELECT_COMMAND INST COLLECT
+  parameters:
+    - name: Target Name
+      required: true
+      description: Name of the target this command is associated with
+      values: .+
+    - name: Command Name
+      required: true
+      description: Name of the command to select
+      values: .*

data/data/config/command_modifiers.yaml

@@ -0,0 +1,160 @@
+---
+PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a command parameter in the current command packet
+  example: |
+    PARAMETER SYNC 0 32 UINT 0xDEADBEEF 0xDEADBEEF 0xDEADBEEF "Sync pattern"
+    PARAMETER DATA 32 32 INT MIN MAX 0 "Data value"
+    PARAMETER VALUE 64 32 FLOAT 0 10.5 2.5
+    PARAMETER LABEL 96 96 STRING "OPENC3" "The label to apply"
+    PARAMETER BLOCK 192 0 BLOCK 0x0 "Block of binary data"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: '\D\S*'
+    - name: Bit Offset
+      required: true
+      description: Bit offset into the command packet of the Most Significant Bit of this parameter.
+        May be negative to indicate on offset from the end of the packet.
+        Always use a bit offset of 0 for derived parameters.
+      values: '[-]?\d+'
+    <%= MetaConfigParser.load('_params.yaml').to_meta_config_yaml(4) %>
+APPEND_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a command parameter in the current command packet
+  example: |
+    APPEND_PARAMETER SYNC 32 UINT 0xDEADBEEF 0xDEADBEEF 0xDEADBEEF "Sync pattern"
+    APPEND_PARAMETER VALUE 32 FLOAT 0 10.5 2.5
+    APPEND_PARAMETER LABEL 0 STRING "OPENC3" "The label to apply"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: .+
+    <%= MetaConfigParser.load('_params.yaml').to_meta_config_yaml(4) %>
+ID_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines an identification command parameter in the current command packet
+  description: ID parameters are used to identify the binary block of data as a
+    particular command. A command packet may have one or more ID_PARAMETERs and all
+    must match the binary data for the command to be identified.
+  example: ID_PARAMETER OPCODE 32 32 UINT 2 2 2 "Opcode identifier"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: .+
+    - name: Bit Offset
+      required: true
+      description: Bit offset into the command packet of the Most Significant Bit of this parameter.
+        May be negative to indicate on offset from the end of the packet.
+        Always use a bit offset of 0 for derived parameters.
+      values: '[-]?\d+'
+    <%= MetaConfigParser.load('_id_params.yaml').to_meta_config_yaml(4) %>
+APPEND_ID_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines an identification command parameter in the current command packet
+  description: ID parameters are used to identify the binary block of data as a
+    particular command. A command packet may have one or more ID_PARAMETERs and all
+    must match the binary data for the command to be identified.
+  example: APPEND_ID_PARAMETER OPCODE 32 UINT 2 2 2 "Opcode identifier"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: .+
+    <%= MetaConfigParser.load('_id_params.yaml').to_meta_config_yaml(4) %>
+ARRAY_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a command parameter in the current command packet that is an array
+  example: ARRAY_PARAMETER ARRAY 64 64 FLOAT 640 "Array of 10 64bit floats"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: \'
+    - name: Bit Offset
+      required: true
+      description: Bit offset into the command packet of the Most Significant Bit of this parameter.
+        May be negative to indicate on offset from the end of the packet.
+        Always use a bit offset of 0 for derived parameters.
+      values: '[-]?\d+'
+    <%= MetaConfigParser.load('_array_params.yaml').to_meta_config_yaml(4) %>
+APPEND_ARRAY_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Defines a command parameter in the current command packet that is an array
+  example: APPEND_ARRAY_PARAMETER ARRAY 64 FLOAT 640 "Array of 10 64bit floats"
+  parameters:
+    - name: Name
+      required: true
+      description: Name of the parameter. Must be unique within the command.
+      values: '\D\S*'
+    <%= MetaConfigParser.load('_array_params.yaml').to_meta_config_yaml(4) %>
+SELECT_PARAMETER:
+  modifiers:
+    <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
+  summary: Selects an existing command parameter for editing
+  example: |
+    SELECT_COMMAND INST COLLECT
+      SELECT_PARAMETER DURATION
+  parameters:
+    - name: Parameter
+      required: true
+      description: Name of the parameter to select for modification
+      values: .+
+DELETE_PARAMETER:
+  summary: Deletes an existing command parameter from the packet definition
+  description: Deleting a parameter from the command definition does not remove the
+    defined space for that parameter. Thus unless you redefine a new parameter, there
+    will be a "hole" in the packet where the data is not accessible. You can
+    use SELECT_COMMAND and then PARAMETER to define a new parameter.
+  example: |
+    SELECT_COMMAND INST COLLECT
+      DELETE_PARAMETER DURATION
+  since: 4.4.1
+  parameters:
+    - name: Parameter
+      required: true
+      description: Name of the parameter to delete
+      values: .+
+HIDDEN:
+  summary: Hides this command from all OpenC3 tools such as Command Sender and Handbook Creator
+  description: Hidden commands do not appear in the Script Runner popup helper when writing scripts.
+    The command still exists in the system and can be sent by scripts.
+DISABLED:
+  summary: Disables this command from being sent
+  description: Hides the command and also disables it from being sent by scripts.
+    Attempts to send DISABLED commands result in an error message.
+DISABLE_MESSAGES:
+  summary: Disable the Server from printing cmd(...) messages. Commands are still logged.
+META:
+  summary: Stores metadata for the current command
+  description: Meta data is user specific data that can be used by custom tools
+    for various purposes. One example is to store additional information needed
+    to generate source code header files.
+  example: META FSW_TYPE "struct command"
+  parameters:
+    - name: Meta Name
+      required: true
+      description: Name of the metadata to store
+      values: .*
+    - name: Meta Values
+      required: false
+      description: One or more values to be stored for this Meta Name
+      values: .*
+HAZARDOUS:
+  summary: Designates the current command as hazardous
+  description: Sending a hazardous command causes a dialog asking for confirmation
+    before sending the command
+  parameters:
+    - name: Description
+      required: false
+      description: Description for why the command is hazardous which must be enclosed with quotes
+      values: "['\"].*['\"]"

data/data/config/command_telemetry.yaml

@@ -0,0 +1,3 @@
+---
+<%= MetaConfigParser.load('command.yaml').to_meta_config_yaml(0) %>
+<%= MetaConfigParser.load('telemetry.yaml').to_meta_config_yaml(0) %>

data/data/config/interface_modifiers.yaml

@@ -0,0 +1,104 @@
+---
+MAP_TARGET:
+  summary: Maps a target name to an interface
+  parameters:
+    - name: Target Name
+      required: true
+      description: Target name to map to this interface
+      values: .+
+DONT_CONNECT:
+  summary: Server will not automatically try to connect to the interface at startup
+DONT_RECONNECT:
+  summary: Server will not try to reconnect to the interface if the connection is lost
+RECONNECT_DELAY:
+  summary: Reconnect delay in seconds
+  description:
+    If DONT_RECONNECT is not present the Server will try to reconnect to an
+    interface if the connection is lost. Reconnect delay sets the interval in seconds
+    between reconnect tries.
+  parameters:
+    - name: Delay
+      required: true
+      description: Delay in seconds between reconnect attempts. The default is 15 seconds.
+      values: ([0-9]*[.])?[0-9]+
+DISABLE_DISCONNECT:
+  summary: Disable the Disconnect button on the Interfaces tab in the Server
+  description:
+    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.
+LOG:
+  summary: Enable logging on the interface by the specified log writer
+  description:
+    LOG is only required if you want a log writer other than the default
+    to log commands and telemetry on this interface
+  warning: Choosing a custom log writer can prevent OpenC3 from reading back your log files
+  parameters:
+    - name: Name
+      required: true
+      description: Log writer name as defined by PACKET_LOG_WRITER
+      values: \D\S*
+LOG_STORED:
+  summary: Enable logging of stored telemetry on the interface by the specified log writer
+  description:
+    LOG_STORED allows you to specify a different log writer for stored telemetry
+    (telemetry which has the 'stored' flag set in the packet). By default the stored telemetry
+    is intermingled in the normal log file.
+  warning: Choosing a custom log writer can prevent OpenC3 from reading back your log files
+  parameters:
+    - name: Name
+      required: true
+      description: Log writer name as defined by PACKET_LOG_WRITER
+      values: \D\S*
+DONT_LOG:
+  summary: Disable logging commands and telemetry on this interface
+LOG_RAW:
+  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.
+    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.
+PROTOCOL:
+  summary: Protocols modify the 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/>
+    There is only one built in protocol implemented by override_protocol.rb.
+    This protocol allows for Scripts to use the override_tlm() and normalize_tlm() methods to permanently
+    change a telemetry value. Note, this differs from set_tlm() as set_tlm() is over-written by new
+    incoming telemetry.<br/><br/>
+    For information on creating your own custom protocol please see <a href="https://openc3.com/docs/v5/protocols">https://openc3.com/docs/v5/protocols</a>
+  since: 4.0.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 filename or class name which implements the protocol
+      values: .*
+    - name: Protocol specific parameters
+      required: false
+      description: Additional parameters used by the protocol
+OPTION:
+  summary: Set a parameter on an interface
+  description:
+    When an option is set the interface class calls the set_option method.
+    Custom interfaces can override set_option to handle any additional options they want.
+  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 defines LISTEN_ADDRESS which is the IP address to accept
+        connections on (default 0.0.0.0) and AUTO_SYSTEM_META which will automatically send
+        SYSTEM META when the interface connects (default false).
+      values: .*
+    - name: Parameters
+      required: false
+      description: Parameters to pass to the option
+      values: .*