OpenC3/cosmos

---
<%= MetaConfigParser.load('param_item_modifiers.yaml').to_meta_config_yaml(0) %>
REQUIRED:
  summary: Parameter is required to be populated in scripts
  description: When sending the command via Script Runner a value must always be
    given for the current command parameter. This prevents the user from relying
    on a default value. Note that this does not affect Command Sender which will
    still populate the field with the default value provided in the PARAMETER definition.
MINIMUM_VALUE:
  summary: Override the defined minimum value
  parameters:
    - name: Value
      required: true
      description: The new minimum value for the parameter
      values: .*
MAXIMUM_VALUE:
  summary: Override the defined maximum value
  parameters:
    - name: Value
      required: true
      description: The new maximum value for the parameter
      values: .*
DEFAULT_VALUE:
  summary: Override the defined default value
  parameters:
    - name: Value
      required: true
      description: The new default value for the parameter
      values: .*
STATE:
  summary: Defines a key/value pair for the current command parameter
  description: Key value pairs allow for user friendly strings. For example,
    you might define states for ON = 1 and OFF = 0. This allows the word ON to be
    used rather than the number 1 when sending the command parameter and allows
    for much greater clarity and less chance for user error.
  example: |
    APPEND_PARAMETER ENABLE 32 UINT 0 1 0 "Enable setting"
      STATE FALSE 0
      STATE TRUE 1
    APPEND_PARAMETER STRING 1024 STRING "NOOP" "String parameter"
      STATE "NOOP" "NOOP" DISABLE_MESSAGES
      STATE "ARM LASER" "ARM LASER" HAZARDOUS "Arming the laser is an eye safety hazard"
      STATE "FIRE LASER" "FIRE LASER" HAZARDOUS "WARNING! Laser will be fired!"
  parameters:
    - name: Key
      required: true
      description: The string state name
      values: .*
    - name: Value
      required: true
      description: The numerical state value
      values: .*
    - name: Hazardous / Disable Messages
      required: false
      description: Indicates the state is hazardous. This will cause a popup
        to ask for user confirmation when sending this command. For non-hazardous
        states you can also set DISABLE_MESSAGES which will not print the command
        when using that state.
      values: ['HAZARDOUS']
    - name: Hazardous Description
      required: false
      description: String describing why this state is hazardous
      values: "['\"].*['\"]"
WRITE_CONVERSION:
  summary: Applies a conversion when writing the current command parameter
  description: |
    Conversions are implemented in a custom Ruby or Python file which should be
    located in the target's lib folder. The class must inherit from Conversion.
    It must implement the `initialize` (Ruby) or `__init__` (Python) method if it
    takes extra parameters and must always implement the `call` method. The conversion
    factor is applied to the value entered by the user before it is written into
    the binary command packet and sent.

    :::info Multiple write conversions on command parameters
    When a command is built, each item gets written (and write conversions are run)
    to set the default value. Then items are written (again write conversions are run)
    with user provided values. Thus write conversions can be run twice. Also there are
    no guarantees which parameters have already been written. The packet itself has a
    given_values() method which can be used to retrieve a hash of the user provided
    values to the command. That can be used to check parameter values passed in.
    :::
  ruby_example: |
    WRITE_CONVERSION the_great_conversion.rb 1000

    Defined in the_great_conversion.rb:

    require 'openc3/conversions/conversion'
    module OpenC3
      class TheGreatConversion < Conversion
        def initialize(multiplier)
          super()
          @multiplier = multiplier.to_f
        end
        def call(value, packet, buffer)
          return value * multiplier
        end
      end
    end
  python_example: |
    WRITE_CONVERSION the_great_conversion.py 1000

    Defined in the_great_conversion.py:

    from openc3.conversions.conversion import Conversion
    class TheGreatConversion(Conversion):
        def __init__(self, multiplier):
            super().__init__()
            self.multiplier = float(multiplier)
        def call(self, value, packet, buffer):
            return value * multiplier
  parameters:
    - name: Class Filename
      required: true
      description: The filename which contains the Ruby or Python class. The filename must
        be named after the class such that the class is a CamelCase version of the
        underscored filename. For example, 'the_great_conversion.rb' should contain
        'class TheGreatConversion'.
      values: .*
    - name: Parameter
      required: false
      description: Additional parameter values for the conversion which are passed
        to the class constructor.
      values: .*
POLY_WRITE_CONVERSION:
  summary: Adds a polynomial conversion factor to the current command parameter
  description: The conversion factor is applied to the value entered by the user
    before it is written into the binary command packet and sent.
  example: POLY_WRITE_CONVERSION 10 0.5 0.25
  parameters:
    - name: C0
      required: true
      description: Coefficient
      values: .*
    - name: Cx
      required: false
      description: Additional coefficient values for the conversion. Any order
        polynomial conversion may be used so the value of 'x' will vary with the
        order of the polynomial. Note that larger order polynomials take longer
        to process than shorter order polynomials, but are sometimes more accurate.
      values: .*
SEG_POLY_WRITE_CONVERSION:
  summary: Adds a segmented polynomial conversion factor to the current command parameter
  description: This conversion factor is applied to the value entered by the user
    before it is written into the binary command packet and sent.
  example: |
    SEG_POLY_WRITE_CONVERSION 0 10 0.5 0.25 # Apply the conversion to all values < 50
    SEG_POLY_WRITE_CONVERSION 50 11 0.5 0.275 # Apply the conversion to all values >= 50 and < 100
    SEG_POLY_WRITE_CONVERSION 100 12 0.5 0.3 # Apply the conversion to all values >= 100
  parameters:
    - name: Lower Bound
      required: true
      description: Defines the lower bound of the range of values that this segmented
        polynomial applies to. Is ignored for the segment with the smallest lower bound.
      values: .*
    - name: C0
      required: true
      description: Coefficient
      values: .*
    - name: Cx
      required: false
      description: Additional coefficient values for the conversion. Any order
        polynomial conversion may be used so the value of 'x' will vary with the
        order of the polynomial. Note that larger order polynomials take longer
        to process than shorter order polynomials, but are sometimes more accurate.
      values: .*
GENERIC_WRITE_CONVERSION_START:
  summary: Start a generic write conversion
  description: |
    Adds a generic conversion function to the current command parameter.
    This conversion factor is applied to the value entered by the user before it
    is written into the binary command packet and sent. The conversion is specified
    as Ruby or Python code that receives two implied parameters. 'value' which is the raw
    value being written and 'packet' which is a reference to the command packet
    class (Note, referencing the packet as 'myself' is still supported for backwards
    compatibility). The last line of code should return the converted
    value. The GENERIC_WRITE_CONVERSION_END keyword specifies that all lines of
    code for the conversion have been given.

    :::info Multiple write conversions on command parameters
    When a command is built, each item gets written (and write conversions are run)
    to set the default value. Then items are written (again write conversions are run)
    with user provided values. Thus write conversions can be run twice. Also there are
    no guarantees which parameters have already been written. The packet itself has a
    given_values() method which can be used to retrieve a hash of the user provided
    values to the command. That can be used to check parameter values passed in.
    :::
  warning: Generic conversions are not a good long term solution. Consider creating
    a conversion class and using WRITE_CONVERSION instead. WRITE_CONVERSION is easier
    to debug and higher performance.
  ruby_example: |
    APPEND_PARAMETER ITEM1 32 UINT 0 0xFFFFFFFF 0
      GENERIC_WRITE_CONVERSION_START
        return (value * 1.5).to_i # Convert the value by a scale factor
      GENERIC_WRITE_CONVERSION_END
  python_example: |
    APPEND_PARAMETER ITEM1 32 UINT 0 0xFFFFFFFF 0
      GENERIC_WRITE_CONVERSION_START
        return int(value * 1.5) # Convert the value by a scale factor
      GENERIC_WRITE_CONVERSION_END
GENERIC_WRITE_CONVERSION_END:
  summary: Complete a generic write conversion
OVERFLOW:
  summary: Set the behavior when writing a value overflows the type
  description: By default OpenC3 throws an error if you try to write a value
    which overflows its specified type, e.g. writing 255 to a 8 bit signed value.
    Setting the overflow behavior also allows for OpenC3 to 'TRUNCATE'
    the value by eliminating any high order bits. You can also set 'SATURATE' which
    causes OpenC3 to replace the value with the maximum or minimum allowable value
    for that type. Finally you can specify 'ERROR_ALLOW_HEX' which will allow for
    a maximum hex value to be written, e.g. you can successfully write 255 to a 8
    bit signed value.
  example: OVERFLOW TRUNCATE
  parameters:
    - name: Behavior
      required: true
      description: How OpenC3 treats an overflow value. Only applies to signed and
        unsigned integer data types.
      values: <%= %w(ERROR ERROR_ALLOW_HEX TRUNCATE SATURATE) %>