cosmos 4.0.3-java

data/lib/cosmos/packets/commands.rb

@@ -0,0 +1,318 @@
+# 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 (excluding UNKNOWN)
+    def target_names
+      result = @config.commands.keys.sort
+      result.delete('UNKNOWN'.freeze)
+      return result
+    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
+    # @param check_required_params [Boolean] Indicates whether or not to check
+    #   that the required command parameters are present
+    def build_cmd(target_name, packet_name, params = {}, range_checking = true, raw = false, check_required_params = true)
+      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
+
+      # Restore the command's buffer to a zeroed string of defined length
+      # This will undo any side effects from earlier commands that may have altered the size
+      # of the buffer
+      command.buffer = "\x00" * command.defined_length
+
+      # Set time, parameters, and restore defaults
+      command.received_time = Time.now.sys
+      command.given_values = params
+      command.restore_defaults(command.buffer(false), params.keys)
+      command.raw = raw
+
+      given_item_names = set_parameters(command, params, range_checking)
+      check_required_params(command, given_item_names) if check_required_params
+
+      return command
+    end
+
+    # Formatted version of a command
+    def format(packet, ignored_parameters = [])
+      if packet.raw
+        items = packet.read_all(:RAW)
+        raw = true
+      else
+        items = packet.read_all(:FORMATTED)
+        raw = false
+      end
+      items.delete_if {|item_name, item_value| ignored_parameters.include?(item_name)}
+      return build_cmd_output_string(packet.target_name, packet.packet_name, items, raw)
+    end
+
+    def build_cmd_output_string(target_name, cmd_name, cmd_params, raw = false)
+      if raw
+        output_string = 'cmd_raw("'
+      else
+        output_string = 'cmd("'
+      end
+      output_string << target_name + ' ' + cmd_name
+      if cmd_params.nil? or cmd_params.empty?
+        output_string << '")'
+      else
+        begin
+          command_items = packet(target_name, cmd_name).items
+        rescue
+        end
+
+        params = []
+        cmd_params.each do |key, value|
+
+          begin
+            item_type = command_items[key].data_type
+          rescue
+            item_type = nil
+          end
+
+          if value.is_a?(String)
+            value = value.dup
+            if item_type == :BLOCK or item_type == :STRING
+              if !value.is_printable?
+                value = "0x" + value.simple_formatted
+              else
+                value = value.inspect
+              end
+            else
+              value = value.convert_to_value.to_s
+            end
+            if value.length > 256
+              value = value[0..255] + "...'"
+            end
+            value.tr!('"',"'")
+          elsif value.is_a?(Array)
+            value = "[#{value.join(", ")}]"
+          end
+          params << "#{key} #{value}"
+        end
+        params = params.join(", ")
+        output_string << ' with ' + params + '")'
+      end
+      return output_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 command [Packet] The command to check for hazardous
+    def cmd_pkt_hazardous?(command)
+      return [true, command.hazardous_description] if command.hazardous
+
+      # 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
+
+    # 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 = {})
+      # Build a command without range checking, perform conversions, and don't
+      # check required parameters since we're not actually using the command.
+      cmd_pkt_hazardous?(build_cmd(target_name, packet_name, params, false, false, false))
+    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
+
+    protected
+
+    def set_parameters(command, params, range_checking)
+      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 '#{command.target_name} #{command.packet_name} #{item_upcase}' = #{range_check_value} not in valid range of #{range.first} to #{range.last}"
+            end
+          end
+        end
+
+        # Update parameter in command
+        if command.raw
+          command.write(item_upcase, value, :RAW)
+        else
+          command.write(item_upcase, value, :CONVERTED)
+        end
+
+        given_item_names << item_upcase
+      end
+      given_item_names
+    end
+
+    def check_required_params(command, given_item_names)
+      # 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 '#{command.target_name} #{command.packet_name} #{item_name}' not given"
+        end
+      end
+    end
+
+  end # class Commands
+
+end # module Cosmos

data/lib/cosmos/packets/limits.rb

@@ -0,0 +1,264 @@
+# 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
+
+    # @param ignored_items [Array<Array<String, String, String>>] 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)
+      item = packet.get_item(item_name)
+      limits = item.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(item)
+      @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?(ignored_items, target_name, packet_name, item_name)
+      ignored_items.each do |array_target_name, array_packet_name, array_item_name|
+        if ((array_target_name == target_name) &&
+            (array_packet_name == packet_name) &&
+            # If the item name is nil we're ignoring an entire packet
+            (array_item_name == item_name || array_item_name.nil?))
+          return true
+        end
+      end
+      return false
+    end
+  end
+end