openc3/data/config/item_modifiers.yaml
---
<%= MetaConfigParser.load('param_item_modifiers.yaml').to_meta_config_yaml(0) %>
STATE:
summary: Defines a key/value pair for the current item
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 telemetry item and allows
for much greater clarity and less chance for user error. A catch all value
of ANY applies to all other values not already defined as state values.
example: |
APPEND_ITEM ENABLE 32 UINT "Enable setting"
STATE FALSE 0
STATE TRUE 1
STATE ERROR ANY # Match all other values to ERROR
APPEND_ITEM STRING 1024 STRING "String"
STATE "NOOP" "NOOP" GREEN
STATE "ARM LASER" "ARM LASER" YELLOW
STATE "FIRE LASER" "FIRE LASER" RED
parameters:
- name: Key
required: true
description: The string state name
values: .*
- name: Value
required: true
description: The numerical state value or ANY to apply the state to all other values
values: .*
- name: Color
required: false
description: The color the state should be displayed as
values: ['GREEN', 'YELLOW', 'RED']
READ_CONVERSION:
summary: Applies a conversion to the current telemetry item
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 raw value in the telemetry packet before it is displayed
to the user. The user still has the ability to see the raw unconverted value
in a details dialog.
ruby_example: |
READ_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: |
READ_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_READ_CONVERSION:
summary: Adds a polynomial conversion factor to the current telemetry item
description: The conversion factor is applied to raw value in the telemetry
packet before it is displayed to the user. The user still has the ability
to see the raw unconverted value in a details dialog.
example: POLY_READ_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_READ_CONVERSION:
summary: Adds a segmented polynomial conversion factor to the current telemetry item
description: This conversion factor is applied to the raw value in the telemetry packet
before it is displayed to the user. The user still has the ability to see the raw
unconverted value in a details dialog.
example: |
SEG_POLY_READ_CONVERSION 0 10 0.5 0.25 # Apply the conversion to all values < 50
SEG_POLY_READ_CONVERSION 50 11 0.5 0.275 # Apply the conversion to all values >= 50 and < 100
SEG_POLY_READ_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_READ_CONVERSION_START:
summary: Start a generic read conversion
description: Adds a generic conversion function to the current telemetry item.
This conversion factor is applied to the raw value in the telemetry packet
before it is displayed to the user. The user still has the ability to see the
raw unconverted value in a details dialog. The conversion is specified as
Ruby or Python code that receives two implied parameters. 'value' which is the raw
value being read and 'packet' which is a reference to the telemetry 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_READ_CONVERSION_END keyword specifies that all lines of
code for the conversion have been given.
warning: Generic conversions are not a good long term solution. Consider creating
a conversion class and using READ_CONVERSION instead. READ_CONVERSION is easier
to debug and has higher performance.
ruby_example: |
APPEND_ITEM ITEM1 32 UINT
GENERIC_READ_CONVERSION_START
return (value * 1.5).to_i # Convert the value by a scale factor
GENERIC_READ_CONVERSION_END
python_example: |
APPEND_ITEM ITEM1 32 UINT
GENERIC_READ_CONVERSION_START
return int(value * 1.5) # Convert the value by a scale factor
GENERIC_READ_CONVERSION_END
parameters:
- name: Converted Type
required: false
description: Type of the converted value
values: <%= %w(INT UINT FLOAT STRING BLOCK) %>
- name: Converted Bit Size
required: false
description: Bit size of converted value
values: \d+
GENERIC_READ_CONVERSION_END:
summary: Complete a generic read conversion
LIMITS:
summary: Defines a set of limits for a telemetry item
description: If limits are violated a message is printed in the Command and Telemetry Server
to indicate an item went out of limits. Other tools also use this information
to update displays with different colored telemetry items or other useful information.
The concept of "limits sets" is defined to allow for different limits values
in different environments. For example, you might want tighter or looser limits
on telemetry if your environment changes such as during thermal vacuum testing.
example: |
LIMITS DEFAULT 3 ENABLED -80.0 -70.0 60.0 80.0 -20.0 20.0
LIMITS TVAC 3 ENABLED -80.0 -30.0 30.0 80.0
parameters:
- name: Limits Set
required: true
description: Name of the limits set. If you have no unique limits sets use
the keyword DEFAULT.
values: .+
- name: Persistence
required: true
description: Number of consecutive times the telemetry item must be within
a different limits range before changing limits state.
values: \d+
- name: Initial State
required: true
description: Whether limits monitoring for this telemetry item is initially enabled or disabled.
Note if you have multiple LIMITS items they should all have the same initial state.
values: ['ENABLED', 'DISABLED']
- name: Red Low Limit
required: true
description: If the telemetry value is less than or equal to this value a
Red Low condition will be detected
values: .+
- name: Yellow Low Limit
required: true
description: If the telemetry value is less than or equal to this value,
but greater than the Red Low Limit, a Yellow Low condition will be detected
values: .+
- name: Yellow High Limit
required: true
description: If the telemetry value is greater than or equal to this value,
but less than the Red High Limit, a Yellow High condition will be detected
values: .+
- name: Red High Limit
required: true
description: If the telemetry value is greater than or equal to this value
a Red High condition will be detected
values: .+
- name: Green Low Limit
required: false
description: Setting the Green Low and Green High limits defines an
"operational limit" which is colored blue by OpenC3. This allows for a
distinct desired operational range which is narrower than the green safety limit.
If the telemetry value is greater than or equal to this value, but less
than the Green High Limit, a Blue operational condition will be detected.
values: .+
- name: Green High Limit
required: false
description: Setting the Green Low and Green High limits defines an
"operational limit" which is colored blue by OpenC3. This allows for a
distinct desired operational range which is narrower than the green safety limit.
If the telemetry value is less than or equal to this value, but greater
than the Green Low Limit, a Blue operational condition will be detected.
values: .+
LIMITS_RESPONSE:
summary: Defines a response class that is called when the limits state of the current item changes
ruby_example: LIMITS_RESPONSE example_limits_response.rb 10
python_example: LIMITS_RESPONSE example_limits_response.py 10
parameters:
- name: Response Class Filename
required: true
description: Name of the Ruby or Python file which implements the limits response.
This file should be in the target's lib directory.
values: .+
- name: Response Specific Options
required: false
description: Variable length number of options that will be passed to the
class constructor
values: .+