Merge pull request #561 from BallAerospace/meta_example

Add examples to meta

data/config/_id_items.yaml

@@ -9,7 +9,7 @@
 - name: Data Type
   required: true
   description: Data Type of this telemetry item
-  values: <%= %w(INT UINT FLOAT STRING BLOCK DERVIED) %>
+  values: <%= %w(INT UINT FLOAT STRING BLOCK DERIVED) %>
 - name: ID Value
   required: true
   description: The value of this telemetry item that uniquely identifies this telemetry packet

data/config/_id_params.yaml

@@ -37,7 +37,7 @@
       parameters: *params
     FLOAT:
       parameters: *params
-    DERVIED:
+    DERIVED:
       parameters: *params
     STRING:
       parameters: &sparams

data/config/_items.yaml

@@ -9,7 +9,7 @@
 - name: Data Type
   required: true
   description: Data Type of this telemetry item
-  values: <%= %w(INT UINT FLOAT STRING BLOCK DERVIED) %>
+  values: <%= %w(INT UINT FLOAT STRING BLOCK DERIVED) %>
 - name: Description
   required: false
   description: Description for this telemetry item which must be enclosed with quotes

data/config/_params.yaml

@@ -37,7 +37,7 @@
       parameters: *params
     FLOAT:
       parameters: *params
-    DERVIED:
+    DERIVED:
       parameters: *params
     STRING:
       parameters: &sparams

data/config/cmd_tlm_server.yaml

@@ -17,6 +17,12 @@ PACKET_LOG_WRITER:
     to create log files.
   warning: You should NOT override the default without consulting a COSMOS 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>_cosmostlm.bin and will create a new log every 1MB
+    PACKET_LOG_WRITER DEFAULT packet_log_writer.rb cosmos true nil 1000000
+    # Create a logger named COSMOS_LOG which creates a new log every 5 min (600s)
+    PACKET_LOG_WRITER COSMOS_LOG packet_log_writer.rb cosmos true 600
   parameters:
     - name: Log Writer Name
       required: true
@@ -40,6 +46,9 @@ AUTO_INTERFACE_TARGETS:
     INTERFACE_TARGET or INTERFACE keyword.
 INTERFACE_TARGET:
   summary: Load the specified target's cmd_tlm_server.txt configuration file
+  example: |
+    INTERFACE_TARGET COSMOS # Look in the COSMOS target directory for cmd_tlm_server.txt
+    INTERFACE_TARGET COSMOS config.txt # Look in the COSMOS target directory for config.txt
   parameters:
     - name: Target Name
       required: true
@@ -71,6 +80,8 @@ INTERFACE:
       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/interfaces)
+        documentation for more details.
 ROUTER:
   modifiers:
     <%= MetaConfigParser.load('interface_modifiers.yaml').to_meta_config_yaml(4) %>
@@ -89,6 +100,8 @@ ROUTER:
       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/interfaces)
+        documentation for more details.
 COLLECT_METADATA:
   summary: Prompts the user for meta data when starting the Command and Telemetry Server
 BACKGROUND_TASK:
@@ -98,6 +111,7 @@ BACKGROUND_TASK:
     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

data/config/command.yaml

@@ -3,6 +3,7 @@ COMMAND:
   modifiers:
     <%= MetaConfigParser.load('command_modifiers.yaml').to_meta_config_yaml(4) %>
   summary: Defines a new command packet
+  example: COMMAND SYSTEM STARTLOGGING BIG_ENDIAN "Starts logging both commands and telemetry for an interface"
   parameters:
     - name: Target
       required: true
@@ -27,6 +28,7 @@ SELECT_COMMAND:
   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 SYSTEM STARTLOGGING
   parameters:
     - name: Target Name
       required: true

data/config/command_modifiers.yaml

@@ -3,6 +3,12 @@ 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 "COSMOS" "The label to apply"
+    PARAMETER BLOCK 192 0 BLOCK '' "Block of binary data"
   parameters:
     - name: Name
       required: true
@@ -19,6 +25,10 @@ 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 "COSMOS" "The label to apply"
   parameters:
     - name: Name
       required: true
@@ -32,6 +42,7 @@ ID_PARAMETER:
   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
@@ -51,6 +62,7 @@ APPEND_ID_PARAMETER:
   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
@@ -61,6 +73,7 @@ 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
@@ -77,6 +90,7 @@ 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
@@ -87,6 +101,9 @@ SELECT_PARAMETER:
   modifiers:
     <%= MetaConfigParser.load('parameter_modifiers.yaml').to_meta_config_yaml(4) %>
   summary: Selects an existing command parameter for editing
+  example: |
+    SELECT_COMMAND SYSTEM STARTLOGGING
+      SELECT_PARAMETER LABEL
   parameters:
     - name: Parameter
       required: true
@@ -107,6 +124,7 @@ META:
   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

data/config/item_modifiers.yaml

@@ -6,6 +6,14 @@ STATE:
     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.
+  example: |
+    APPEND_ITEM ENABLE 32 UINT "Enable setting"
+      STATE FALSE 0
+      STATE TRUE 1
+    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
@@ -29,6 +37,23 @@ READ_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: |
+    READ_CONVERSION the_great_conversion.rb 1000
+
+    Defined in the_great_conversion.rb:
+
+    require 'cosmos/conversions/conversion'
+    module Cosmos
+      class TheGreatConversion < Conversion
+        def initialize(multiplier)
+          super()
+          @multiplier = multiplier
+        end
+        def call(value, packet, buffer)
+          return value * multiplier
+        end
+      end
+    end
   parameters:
     - name: Class File Name
       required: true
@@ -47,6 +72,7 @@ POLY_READ_CONVERSION:
   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
@@ -64,6 +90,10 @@ SEG_POLY_READ_CONVERSION:
   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
@@ -96,6 +126,11 @@ GENERIC_READ_CONVERSION_START:
   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 higher performance.
+  example: |
+    APPEND_ITEM ITEM1 32 UINT
+      GENERIC_READ_CONVERSION_START
+        value * 1.5  # Convert the value by a scale factor
+      GENERIC_READ_CONVERSION_END
 GENERIC_READ_CONVERSION_END:
   summary: Complete a generic write conversion
 LIMITS:
@@ -106,6 +141,9 @@ LIMITS:
     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
@@ -159,6 +197,7 @@ LIMITS:
       values: .+
 LIMITS_RESPONSE:
   summary: Defines a response class that is called when the limits state of the current item changes
+  example: LIMITS_RESPONSE example_limits_response.rb 10
   parameters:
     - name: Response Class Filename
       required: true

data/config/param_item_modifiers.yaml

@@ -1,6 +1,7 @@
 ---
 FORMAT_STRING:
   summary: Adds printf style formatting
+  example: FORMAT_STRING "0x%0X"
   parameters:
     - name: Format
       required: true
@@ -9,6 +10,9 @@ FORMAT_STRING:
       values: .*
 UNITS:
   summary: Add displayed units
+  example: |
+    UNITS Celcius C
+    UNITS Kilometers KM
   parameters:
     - name: Full Name
       required: true
@@ -30,6 +34,7 @@ META:
   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 TEST "This parameter is for test purposes only"
   parameters:
     - name: Meta Name
       required: true

data/config/parameter_modifiers.yaml

@@ -33,6 +33,14 @@ STATE:
     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"
+      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
@@ -60,6 +68,23 @@ WRITE_CONVERSION:
     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.
+  example: |
+    WRITE_CONVERSION the_great_conversion.rb 1000
+
+    Defined in the_great_conversion.rb:
+
+    require 'cosmos/conversions/conversion'
+    module Cosmos
+      class TheGreatConversion < Conversion
+        def initialize(multiplier)
+          super()
+          @multiplier = multiplier
+        end
+        def call(value, packet, buffer)
+          return value * multiplier
+        end
+      end
+    end
   parameters:
     - name: Class File Name
       required: true
@@ -77,6 +102,7 @@ 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
@@ -93,6 +119,10 @@ 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
@@ -124,6 +154,11 @@ GENERIC_WRITE_CONVERSION_START:
   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.
+  example: |
+    APPEND_PARAMETER ITEM1 32 UINT 0 0xFFFFFFFF 0
+      GENERIC_WRITE_CONVERSION_START
+        (value * 1.5).to_i # Convert the value by a scale factor
+      GENERIC_WRITE_CONVERSION_END
 GENERIC_WRITE_CONVERSION_END:
   summary: Complete a generic write conversion
 OVERFLOW:
@@ -136,6 +171,7 @@ OVERFLOW:
     for that type. Finally you can specify 'ERROR_ALLOW_HEX' which will allow for
     a maximum hex value to be writen, e.g. you can successfully write 255 to a 8
     bit signed value.
+  example: OVERFLOW TRUNCATE
   parameters:
     - name: Behavior
       required: true