cosmos 3.0.0

data/lib/cosmos/packets/commands.rb

@@ -0,0 +1,291 @@
+# encoding: ascii-8bit
+
+# Copyright 2014 Ball Aerospace & Technologies Corp.
+# All Rights Reserved.
+#
+# This program is free software; you can modify and/or redistribute it
+# under the terms of the GNU General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+
+require 'cosmos/packets/packet_config'
+
+module Cosmos
+
+  # Commands uses PacketConfig to parse the command and telemetry
+  # configuration files. It contains all the knowledge of which command packets
+  # exist in the system and how to access them. This class is the API layer
+  # which other classes use to access commands.
+  #
+  # This should not be confused with the Api module which implements the JSON
+  # API that is used by tools when accessing the Server. The Api module always
+  # provides Ruby primatives where the PacketDefinition class can return actual
+  # Packet or PacketItem objects. While there are some overlapping methods between
+  # the two, these are separate interfaces into the system.
+  class Commands
+    attr_accessor :config
+
+    LATEST_PACKET_NAME = 'LATEST'.freeze
+
+    # @param config [PacketConfig] Packet configuration to use to access the
+    #  commands
+    def initialize(config)
+      @config = config
+    end
+
+    # (see PacketConfig#warnings)
+    def warnings
+      return @config.warnings
+    end
+
+    # @return [Array<String>] The command target names
+    def target_names
+      return @config.commands.keys.sort
+    end
+
+    # @param target_name [String] The target name
+    # @return [Hash<packet_name=>Packet>] Hash of the command packets for the given
+    #   target name keyed by the packet name
+    def packets(target_name)
+      target_packets = @config.commands[target_name.to_s.upcase]
+      raise "Command target '#{target_name.to_s.upcase}' does not exist" unless target_packets
+      target_packets
+    end
+
+    # @param target_name [String] The target name
+    # @param packet_name [String] The packet name. Must be a defined packet name
+    #   and not 'LATEST'.
+    # @return [Packet] The command packet for the given target and packet name
+    def packet(target_name, packet_name)
+      target_packets = packets(target_name)
+      packet = target_packets[packet_name.to_s.upcase]
+      raise "Command packet '#{target_name.to_s.upcase} #{packet_name.to_s.upcase}' does not exist" unless packet
+      packet
+    end
+
+    # @param target_name (see #packet)
+    # @param packet_name (see #packet)
+    # @return [Array<PacketItem>] The command parameters for the given target and packet name
+    def params(target_name, packet_name)
+      return packet(target_name, packet_name).sorted_items
+    end
+
+    # Identifies an unknown buffer of data as a defined command and sets the
+    # commands's data to the given buffer. Identifying a command uses the fields
+    # marked as ID_PARAMETER to identify if the buffer passed represents the
+    # command defined. Incorrectly sized buffers are still processed but an
+    # error is logged.
+    #
+    # Note: Subsequent requests for the command (using packet) will return
+    # an uninitialized copy of the command. Thus you must use the return value
+    # of this method.
+    #
+    # @param (see #identify_tlm!)
+    # @return (see #identify_tlm!)
+    def identify(packet_data, target_names = nil)
+      identified_packet = nil
+
+      target_names = target_names() unless target_names
+
+      target_names.each do |target_name|
+        target_packets = nil
+        begin
+          target_packets = packets(target_name)
+        rescue RuntimeError
+          # No commands for this target
+          next
+        end
+
+        # Iterate through the packets and see if any represent the buffer
+        target_packets.each do |packet_name, packet|
+          if (packet.identify?(packet_data))
+            identified_packet = packet.clone
+            identified_packet.received_time  = nil
+            identified_packet.received_count = 0
+            identified_packet.buffer = packet_data
+            break
+          end
+        end
+
+        break if identified_packet
+      end
+
+      return identified_packet
+    end
+
+    # Returns a copy of the specified command packet with the parameters
+    # initialzed to the given params values.
+    #
+    # @param target_name (see #packet)
+    # @param packet_name (see #packet)
+    # @param params [Hash<param_name=>param_value>] Parameter items to override
+    #   in the given command.
+    # @param range_checking [Boolean] Whether to perform range checking on the
+    #   passed in parameters.
+    # @param raw [Boolean] Indicates whether or not to run conversions on command parameters
+    def build_cmd(target_name, packet_name, params = {}, range_checking = true, raw = false)
+      target_upcase = target_name.to_s.upcase
+      packet_upcase = packet_name.to_s.upcase
+
+      # Lookup the command and create a light weight copy
+      command = packet(target_upcase, packet_upcase).clone
+
+      # Set time, parameters, and restore defaults
+      command.received_time = Time.now
+      command.given_values = params
+      command.restore_defaults
+      command.raw = raw
+
+      # Set any parameters
+      given_item_names = []
+      params.each do |item_name, value|
+        item_upcase = item_name.to_s.upcase
+        item = command.get_item(item_upcase)
+        range_check_value = value
+
+        # Convert from state to value if possible
+        if item.states and item.states[value.to_s.upcase]
+          range_check_value = item.states[value.to_s.upcase]
+        end
+
+        if range_checking
+          range = item.range
+          if range
+            # Perform Range Check on command parameter
+            if not range.include?(range_check_value)
+              range_check_value = "'#{range_check_value}'" if String === range_check_value
+              raise "Command parameter '#{target_upcase} #{packet_upcase} #{item_upcase}' = #{range_check_value} not in valid range of #{range.first} to #{range.last}"
+            end
+          end
+        end
+
+        # Update parameter in command
+        if raw
+          command.write(item_upcase, value, :RAW)
+        else
+          command.write(item_upcase, value, :CONVERTED)
+        end
+
+        given_item_names << item_upcase
+      end # cmd_params.each
+
+      # Script Runner could call this command with only some parameters
+      # so make sure any required parameters were actually passed in.
+      item_defs = command.items
+      item_defs.each do |item_name, item_def|
+        if item_def.required and not given_item_names.include? item_name
+          raise "Required command parameter '#{target_upcase} #{packet_upcase} #{item_name}' not given"
+        end
+      end
+
+      return command
+    end
+
+    # Formatted version of a command
+    def format(packet, ignored_parameters = [])
+      first = true
+      if packet.raw
+        items = packet.read_all(:RAW)
+        string = "cmd_raw('#{packet.target_name} #{packet.packet_name}"
+      else
+        items = packet.read_all(:FORMATTED)
+        string = "cmd('#{packet.target_name} #{packet.packet_name}"
+      end
+      items.each do |item_name, item_value|
+        unless ignored_parameters.include?(item_name)
+          if first
+            string << ' with '
+            first = false
+          else
+            string << ', '
+          end
+
+          item = packet.get_item(item_name)
+          if item.data_type ==:STRING or item.data_type == :BLOCK
+            item_value = item_value.inspect
+            if item_value.length > 256
+              item_value = item_value[0..255] + '..."'
+            end
+            string << "#{item_name} #{item_value}"
+          else
+            if (Array === item_value) && (!packet.raw)
+              string << "#{item_name} [#{item_value.join(", ")}]"
+            else
+              string << "#{item_name} #{item_value}"
+            end
+          end
+        end
+      end
+      string << "')"
+      string
+    end
+
+    # Returns whether the given command is hazardous. Commands are hazardous
+    # if they are marked hazardous overall or if any of their hardardous states
+    # are set. Thus any given parameter values are first applied to the command
+    # and then checked for hazardous states.
+    #
+    # @param target_name (see #packet)
+    # @param packet_name (see #packet)
+    # @param params (see #build_cmd)
+    def cmd_hazardous?(target_name, packet_name, params = {})
+      target_upcase = target_name.to_s.upcase
+      packet_upcase = packet_name.to_s.upcase
+
+      # Lookup the command
+      command = packet(target_upcase, packet_upcase)
+
+      # Overall command hazardous check
+      return [true, command.hazardous_description] if command.hazardous
+
+      # Create a light weight copy of command
+      command = command.clone()
+      # Set given command parameters and restore defaults
+      command.given_values = params
+      command.restore_defaults()
+
+      # Set any parameters
+      params.each do |item_name, value|
+        item_upcase = item_name.to_s.upcase
+        item = command.get_item(item_upcase)
+
+        if item.states
+          state_value = item.states[value.to_s.upcase]
+          value = state_value if state_value
+        end
+
+        # Update parameter in command
+        command.write(item_upcase, value)
+      end
+
+      # Check each item for hazardous states
+      item_defs = command.items
+      item_defs.each do |item_name, item_def|
+        if item_def.hazardous
+          state_name = command.read(item_name)
+          # Nominally the command.read will return a valid state_name
+          # If it doesn't, the if check will fail and we'll fall through to
+          # the bottom where we return [false, nil] which means this
+          # command is not hazardous.
+          return [true, item_def.hazardous[state_name]] if item_def.hazardous[state_name]
+        end
+      end
+
+      return [false, nil]
+    end
+
+    def clear_counters
+      @config.commands.each do |target_name, target_packets|
+        target_packets.each do |packet_name, packet|
+          packet.received_count = 0
+        end
+      end
+    end
+
+    def all
+      @config.commands
+    end
+
+  end # class Commands
+
+end # module Cosmos

data/lib/cosmos/packets/limits.rb

@@ -0,0 +1,263 @@
+# encoding: ascii-8bit
+
+# Copyright 2014 Ball Aerospace & Technologies Corp.
+# All Rights Reserved.
+#
+# This program is free software; you can modify and/or redistribute it
+# under the terms of the GNU General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+
+require 'cosmos/packets/packet_config'
+
+module Cosmos
+
+  # Limits uses PacketConfig to parse the command and telemetry
+  # configuration files. It provides the API layer which other classes use to
+  # access information about and manipulate limits. This includes getting,
+  # setting and checking individual limit items as well as manipulating limits
+  # groups.
+  class Limits
+    attr_reader :config
+
+    LATEST_PACKET_NAME = 'LATEST'.freeze
+
+    # @param config [PacketConfig] Packet configuration to use to access the
+    #   limits information
+    def initialize(config)
+      @config = config
+    end
+
+    # (see PacketConfig#warnings)
+    def warnings
+      return @config.warnings
+    end
+
+    # (see PacketConfig#limits_sets)
+    def sets
+      return @config.limits_sets
+    end
+
+    # @param config [PacketConfig] Set the packet configuration to a new
+    #   configuration. This will change everything this class returns!
+    def config=(config)
+      @config = config
+    end
+
+    # (see Cosmos::Packet#out_of_limits)
+    def out_of_limits
+      items = []
+      @config.telemetry.each do |target_name, target_packets|
+        target_packets.each do |packet_name, packet|
+          new_items = packet.out_of_limits
+          items.concat(new_items)
+        end
+      end
+      return items
+    end
+
+    # @ignored_items [Array of Arrays] Items to ignore from the consideration
+    # @return [Symbol] The overall limits state for the system
+    def overall_limits_state(ignored_items = nil)
+      overall = :GREEN
+      limits_packet_stale = false
+      items_out_of_limits = []
+      # Note: If anything with limits is stale then overall limits state cannot be green or blue
+      @config.telemetry.each do |target_name, target_packets|
+        target_packets.each do |packet_name, packet|
+          if packet.stale && !packet.limits_items.empty?
+            if ignored_items
+              all_ignored = true
+              packet.limits_items.each do |item|
+                all_ignored = false unless includes_item?(ignored_items, target_name, packet_name, item.name)
+              end
+            else
+              all_ignored = false
+            end
+            limits_packet_stale = true unless all_ignored
+          end
+          items_out_of_limits.concat(packet.out_of_limits)
+        end
+      end
+      items_out_of_limits.each do |target_name, packet_name, item_name, limits_state|
+        next if ignored_items && includes_item?(ignored_items, target_name, packet_name, item_name)
+        case overall
+        # If our overall state is currently blue or green we can go to any state
+        when :BLUE, :GREEN, :GREEN_HIGH, :GREEN_LOW
+          overall = limits_state
+        # If our overal state is yellow we can only go higher to red
+        when :YELLOW, :YELLOW_HIGH, :YELLOW_LOW
+          if limits_state == :RED || limits_state == :RED_HIGH || limits_state == :RED_LOW
+            overall = limits_state
+            break # Red is as high as we go so no need to look for more
+          end
+        end
+      end
+      overall = :GREEN if overall == :GREEN_HIGH || overall == :GREEN_LOW || overall == :BLUE
+      overall = :YELLOW if overall == :YELLOW_HIGH || overall == :YELLOW_LOW
+      overall = :RED if overall == :RED_HIGH || overall == :RED_LOW
+      overall = :STALE if (overall == :GREEN || overall == :BLUE) && limits_packet_stale
+      return overall
+    end
+
+    # @return [Hash(String, Array)] The defined limits groups
+    def groups
+      return @config.limits_groups
+    end
+
+    # Enables limit checking for all the items in the given group.
+    #
+    # @param group_name [String] Name of the group to enable
+    def enable_group(group_name)
+      group_upcase = group_name.to_s.upcase
+      limits_group = @config.limits_groups[group_upcase]
+      if limits_group
+        limits_group.each do |target_name, packet_name, item_name|
+          enable(target_name, packet_name, item_name)
+        end
+      else
+        raise "LIMITS_GROUP #{group_upcase} undefined. Ensure your telemetry definition contains the line: LIMITS_GROUP #{group_upcase}"
+      end
+    end
+
+    # Disables limit checking for all the items in the given group.
+    #
+    # @param group_name [String] Name of the group to disable
+    def disable_group(group_name)
+      group_upcase = group_name.to_s.upcase
+      limits_group = @config.limits_groups[group_upcase]
+      if limits_group
+        limits_group.each do |target_name, packet_name, item_name|
+          disable(target_name, packet_name, item_name)
+        end
+      else
+        raise "LIMITS_GROUP #{group_upcase} undefined. Ensure your telemetry definition contains the line: LIMITS_GROUP #{group_upcase}"
+      end
+    end
+
+    # Checks whether the limits are enabled for the specified item
+    #
+    # @param target_name [String] The target name
+    # @param packet_name [String] The packet name. Must be a defined packet name and not 'LATEST'.
+    # @param item_name [String] The item name
+    def enabled?(target_name, packet_name, item_name)
+      get_packet(target_name, packet_name).get_item(item_name).limits.enabled
+    end
+
+    # Enables limit checking for the specified item
+    #
+    # @param (see #enabled?)
+    def enable(target_name, packet_name, item_name)
+      get_packet(target_name, packet_name).enable_limits(item_name)
+    end
+
+    # Disables limit checking for the specified item
+    #
+    # @param (see #enabled?)
+    def disable(target_name, packet_name, item_name)
+      get_packet(target_name, packet_name).disable_limits(item_name)
+    end
+
+    # Get the limits for a telemetry item
+    #
+    # @param target_name [String] Target Name
+    # @param packet_name [String] Packet Name
+    # @param item_name [String] Item Name
+    # @param limits_set [String or Symbol or nil] Desired Limits set.  nil = current limits set
+    # @return [Array<limits_set, persistence, enabled, red_low, yellow_low, red_high, yellow_high, green_low (optional), green_high (optional)] Limits information
+    def get(target_name, packet_name, item_name, limits_set = nil)
+      limits = get_packet(target_name, packet_name).get_item(item_name).limits
+      if limits.values
+        if limits_set
+          limits_set = limits_set.to_s.upcase.intern
+        else
+          limits_set = System.limits_set
+        end
+        limits_for_set = limits.values[limits_set]
+        if limits_for_set
+          return [limits_set, limits.persistence_setting, limits.enabled, limits_for_set[0], limits_for_set[1], limits_for_set[2], limits_for_set[3], limits_for_set[4], limits_for_set[5]]
+        else
+          return [nil, nil, nil, nil, nil, nil, nil, nil, nil]
+        end
+      else
+        return [nil, nil, nil, nil, nil, nil, nil, nil, nil]
+      end
+    end
+
+    # Set the limits for a telemetry item
+    #
+    # @param target_name [String] Target Name
+    # @param packet_name [String] Packet Name
+    # @param item_name [String] Item Name
+    # @param red_low [Float] Red Low Limit
+    # @param yellow_low [Float] Yellow Low Limit
+    # @param yellow_high [Float] Yellow High Limit
+    # @param red_high [Float] Red High Limit
+    # @param green_low [Float] Green Low Limit
+    # @param green_high [Float] Green High Limit
+    # @param limits_set [String or Symbol or nil] Desired Limits set.  nil = current limits set, recommend using :CUSTOM
+    # @param persistence [Integer] The number of samples the value must be out of limits before detecting a limits change. nil = Leave unchanged
+    # @param enabled [Boolean] If limits monitoring is enabled for this item
+    # @return [Array<limits_set, persistence, enabled, red_low, yellow_low, red_high, yellow_high, green_low (optional), green_high (optional)] Limits information
+    def set(target_name, packet_name, item_name, red_low, yellow_low, yellow_high, red_high, green_low = nil, green_high = nil, limits_set = :CUSTOM, persistence = nil, enabled = true)
+      packet = get_packet(target_name, packet_name)
+      limits = packet.get_item(item_name).limits
+      if limits_set
+        limits_set = limits_set.to_s.upcase.intern
+      else
+        limits_set = System.limits_set
+      end
+      if !limits.values
+        if limits_set == :DEFAULT
+          limits.values = {:DEFAULT => []}
+        else
+          raise "DEFAULT limits must be defined for #{target_name} #{packet_name} #{item_name} before setting limits set #{limits_set}"
+        end
+      end
+      limits_for_set = limits.values[limits_set]
+      unless limits_for_set
+        limits.values[limits_set] = []
+        limits_for_set = limits.values[limits_set]
+      end
+      limits_for_set[0] = red_low.to_f
+      limits_for_set[1] = yellow_low.to_f
+      limits_for_set[2] = yellow_high.to_f
+      limits_for_set[3] = red_high.to_f
+      limits_for_set.delete_at(5) if limits_for_set[5]
+      limits_for_set.delete_at(4) if limits_for_set[4]
+      if green_low && green_high
+        limits_for_set[4] = green_low.to_f
+        limits_for_set[5] = green_high.to_f
+      end
+      limits.enabled = enabled
+      limits.persistence_setting = Integer(persistence) if persistence
+      packet.update_limits_items_cache
+      @config.limits_sets << limits_set
+      @config.limits_sets.uniq!
+      return [limits_set, limits.persistence_setting, limits.enabled, limits_for_set[0], limits_for_set[1], limits_for_set[2], limits_for_set[3], limits_for_set[4], limits_for_set[5]]
+    end
+
+    protected
+
+    def get_packet(target_name, packet_name)
+      raise "LATEST packet not valid" if packet_name.upcase == LATEST_PACKET_NAME
+      packets = @config.telemetry[target_name.to_s.upcase]
+      raise "Telemetry target '#{target_name.to_s.upcase}' does not exist" unless packets
+      packet = packets[packet_name.to_s.upcase]
+      raise "Telemetry packet '#{target_name.to_s.upcase} #{packet_name.to_s.upcase}' does not exist" unless packet
+      return packet
+    end
+
+    def includes_item?(array, target_name, packet_name, item_name)
+      array.each do |array_target_name, array_packet_name, array_item_name|
+        if ((array_target_name == target_name) && (array_packet_name == packet_name) && (array_item_name == item_name))
+          return true
+        end
+      end
+      return false
+    end
+
+  end # class Limits
+
+end
+

data/lib/cosmos/packets/limits_response.rb

@@ -0,0 +1,38 @@
+# encoding: ascii-8bit
+
+# Copyright 2014 Ball Aerospace & Technologies Corp.
+# All Rights Reserved.
+#
+# This program is free software; you can modify and/or redistribute it
+# under the terms of the GNU General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+
+# This file implements a class to handle responses to limits state changes.
+
+require 'cosmos/tools/cmd_tlm_server/api'
+
+module Cosmos
+  # This class defines a #call method which is called when a PacketItem
+  # goes out of limits. This class must be subclassed and the call method
+  # implemented. Do NOT use this class directly.
+  class LimitsResponse
+
+    include Api
+
+    # @param packet [Packet] Packet the limits response is assigned to
+    # @param item [PacketItem] PacketItem the limits response is assigned to
+    # @param old_limits_state [Symbol] Previous value of the limit. One of nil,
+    #   :GREEN_HIGH, :GREEN_LOW, :YELLOW, :YELLOW_HIGH, :YELLOW_LOW,
+    #   :RED, :RED_HIGH, :RED_LOW. nil if the previous limit state has not yet
+    #   been established.
+    def call(packet, item, old_limits_state)
+      raise "call method must be defined by subclass"
+    end
+
+    def to_s
+      self.class.to_s.split('::')[-1]
+    end
+
+  end # class LimitsResponse
+end