openc3 5.0.6

data/lib/openc3/packets/parsers/packet_item_parser.rb

@@ -0,0 +1,272 @@
+# encoding: ascii-8bit
+
+# Copyright 2022 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 Affero General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# Modified by OpenC3, Inc.
+# All changes Copyright 2022, OpenC3, Inc.
+# All Rights Reserved
+
+require 'openc3/packets/packet_item'
+
+module OpenC3
+  # Parses a packet item definition and creates a new PacketItem
+  class PacketItemParser
+    # This number is a little arbitrary but there are definitely issues at
+    # 1 million and you really shouldn't be doing anything this big anyway
+    BIG_ARRAY_SIZE = 100_000
+
+    # @param parser [ConfigParser] Configuration parser
+    # @param packet [Packet] The packet the item should be added to
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    # @param warnings [Array<String>] Array of warning strings from PacketConfig
+    def self.parse(parser, packet, cmd_or_tlm, warnings)
+      parser = PacketItemParser.new(parser, warnings)
+      parser.verify_parameters(cmd_or_tlm)
+      parser.create_packet_item(packet, cmd_or_tlm)
+    end
+
+    # @param parser [ConfigParser] Configuration parser
+    # @param warnings [Array<String>] Array of warning strings from PacketConfig
+    def initialize(parser, warnings)
+      @parser = parser
+      @warnings = warnings
+      @usage = get_usage()
+    end
+
+    def verify_parameters(cmd_or_tlm)
+      if @parser.keyword.include?('ITEM') && cmd_or_tlm == PacketConfig::COMMAND
+        raise @parser.error("ITEM types are only valid with TELEMETRY", @usage)
+      elsif @parser.keyword.include?('PARAMETER') && cmd_or_tlm == PacketConfig::TELEMETRY
+        raise @parser.error("PARAMETER types are only valid with COMMAND", @usage)
+      end
+
+      # The usage is formatted with brackets <XXX> around each option so
+      # count the number of open brackets to determine the number of options
+      max_options = @usage.count("<")
+      # The last two options (description and endianness) are optional
+      @parser.verify_num_parameters(max_options - 2, max_options, @usage)
+      @parser.verify_parameter_naming(1) # Item name is the 1st parameter
+    end
+
+    def create_packet_item(packet, cmd_or_tlm)
+      item_name = @parser.parameters[0].upcase
+      if packet.items[item_name]
+        msg = "#{packet.target_name} #{packet.packet_name} #{item_name} redefined."
+        Logger.instance.warn msg
+        @warnings << msg
+      end
+      item = PacketItem.new(item_name,
+                            get_bit_offset(),
+                            get_bit_size(),
+                            get_data_type(),
+                            get_endianness(packet),
+                            get_array_size(),
+                            :ERROR) # overflow
+      if cmd_or_tlm == PacketConfig::COMMAND
+        item.range = get_range()
+        item.default = get_default()
+      end
+      item.id_value = get_id_value()
+      item.description = get_description()
+      if append?
+        item = packet.append(item)
+      else
+        item = packet.define(item)
+      end
+      item
+    rescue => err
+      raise @parser.error(err, @usage)
+    end
+
+    private
+
+    def append?
+      @parser.keyword.include?("APPEND")
+    end
+
+    def get_data_type
+      index = append? ? 2 : 3
+      @parser.parameters[index].upcase.to_sym
+    end
+
+    def get_bit_offset
+      return 0 if append?
+
+      Integer(@parser.parameters[1])
+    rescue => err # In case Integer fails
+      raise @parser.error(err, @usage)
+    end
+
+    def get_bit_size
+      index = append? ? 1 : 2
+      Integer(@parser.parameters[index])
+    rescue => err
+      raise @parser.error(err, @usage)
+    end
+
+    def get_array_size
+      return nil unless @parser.keyword.include?('ARRAY')
+
+      index = append? ? 3 : 4
+      array_bit_size = Integer(@parser.parameters[index])
+      items = array_bit_size / get_bit_size()
+      if items >= BIG_ARRAY_SIZE
+        warning = "Performance Issue!\n"\
+                  "In #{@parser.filename}:#{@parser.line_number} your definition of:\n"\
+                  "#{@parser.line}\n"\
+                  "creates an array with #{items} elements. Consider creating a BLOCK if this is binary data."
+        Logger.warn(warning)
+        @warnings << warning
+      end
+      array_bit_size
+    rescue => err
+      raise @parser.error(err, @usage)
+    end
+
+    def get_endianness(packet)
+      params = @parser.parameters
+      max_options = @usage.count("<")
+      if params[max_options - 1]
+        endianness = params[max_options - 1].to_s.upcase.intern
+        if endianness != :BIG_ENDIAN and endianness != :LITTLE_ENDIAN
+          raise @parser.error("Invalid endianness #{endianness}. Must be BIG_ENDIAN or LITTLE_ENDIAN.", @usage)
+        end
+      else
+        endianness = packet.default_endianness
+      end
+      endianness
+    end
+
+    def get_range
+      return nil if @parser.keyword.include?('ARRAY')
+
+      data_type = get_data_type()
+      return nil if data_type == :STRING or data_type == :BLOCK
+
+      index = append? ? 3 : 4
+      min = ConfigParser.handle_defined_constants(
+        @parser.parameters[index].convert_to_value, get_data_type(), get_bit_size()
+      )
+      max = ConfigParser.handle_defined_constants(
+        @parser.parameters[index + 1].convert_to_value, get_data_type(), get_bit_size()
+      )
+      min..max
+    end
+
+    def get_default
+      return [] if @parser.keyword.include?('ARRAY')
+
+      index = append? ? 3 : 4
+      data_type = get_data_type()
+      if data_type == :STRING or data_type == :BLOCK
+        # If the default value is 0x<data> (no quotes), it is treated as
+        # binary data.  Otherwise, the default value is considered to be a string.
+        if @parser.parameters[index].upcase.start_with?("0X") and
+           !@parser.line.include?("\"#{@parser.parameters[index]}\"") and
+           !@parser.line.include?("\'#{@parser.parameters[index]}\'")
+          return @parser.parameters[index].hex_to_byte_string
+        else
+          return @parser.parameters[index]
+        end
+      else
+        return ConfigParser.handle_defined_constants(
+          @parser.parameters[index + 2].convert_to_value, get_data_type(), get_bit_size()
+        )
+      end
+    end
+
+    def get_id_value
+      return nil unless @parser.keyword.include?('ID_')
+
+      data_type = get_data_type
+      if @parser.keyword.include?('ITEM')
+        index = append? ? 3 : 4
+      else # PARAMETER
+        index = append? ? 5 : 6
+        # STRING and BLOCK PARAMETERS don't have min and max values
+        index -= 2 if data_type == :STRING || data_type == :BLOCK
+      end
+      if data_type == :DERIVED
+        raise @parser.error("DERIVED data type not allowed for Identifier")
+      end
+
+      @parser.parameters[index]
+    end
+
+    def get_description
+      max_options = @usage.count("<")
+      @parser.parameters[max_options - 2] if @parser.parameters[max_options - 2]
+    end
+
+    # There are many different usages of the ITEM and PARAMETER keywords so
+    # parse the keyword and parameters to generate the correct usage information.
+    def get_usage
+      usage = "#{@parser.keyword} <ITEM NAME> "
+      usage << "<BIT OFFSET> " unless @parser.keyword.include?("APPEND")
+      usage << bit_size_usage()
+      usage << type_usage()
+      usage << "<TOTAL ARRAY BIT SIZE> " if @parser.keyword.include?("ARRAY")
+      usage << id_usage()
+      usage << "<DESCRIPTION (Optional)> <ENDIANNESS (Optional)>"
+      usage
+    end
+
+    def bit_size_usage
+      if @parser.keyword.include?("ARRAY")
+        "<ARRAY ITEM BIT SIZE> "
+      else
+        "<BIT SIZE> "
+      end
+    end
+
+    def type_usage
+      keyword = @parser.keyword
+      # Item type usage is simple so just return it
+      return "<TYPE: INT/UINT/FLOAT/STRING/BLOCK/DERIVED> " if keyword.include?("ITEM")
+
+      # Build up the parameter type usage based on the keyword
+      usage = "<TYPE: "
+      # ARRAY types don't have min or max or default values
+      if keyword.include?("ARRAY")
+        usage << "INT/UINT/FLOAT/STRING/BLOCK> "
+      else
+        begin
+          data_type = get_data_type()
+        rescue
+          # If the data type could not be determined set something
+          data_type == :INT
+        end
+        # STRING and BLOCK types do not have min or max values
+        if data_type == :STRING || data_type == :BLOCK
+          usage << "STRING/BLOCK> "
+        else
+          usage << "INT/UINT/FLOAT> <MIN VALUE> <MAX VALUE> "
+        end
+        # ID Values do not have default values
+        usage << "<DEFAULT_VALUE> " unless keyword.include?("ID")
+      end
+      usage
+    end
+
+    def id_usage
+      return '' unless @parser.keyword.include?("ID")
+
+      if @parser.keyword.include?("PARAMETER")
+        "<DEFAULT AND ID VALUE> "
+      else
+        "<ID VALUE> "
+      end
+    end
+  end
+end

data/lib/openc3/packets/parsers/packet_parser.rb

@@ -0,0 +1,134 @@
+# encoding: ascii-8bit
+
+# Copyright 2022 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 Affero General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# Modified by OpenC3, Inc.
+# All changes Copyright 2022, OpenC3, Inc.
+# All Rights Reserved
+
+require 'openc3/packets/packet'
+
+module OpenC3
+  class PacketParser
+    # @param parser [ConfigParser] Configuration parser
+    # @param target_name [String] The name of the target to create the packet
+    #   under. If the target name is 'SYSTEM' the keyword parameter will be
+    #   used instead of this parameter.
+    # @param commands [Hash] Hash of the currently defined commands
+    # @param warnings [Array<String>] Any warning strings generated while
+    #   parsing this command will be appened to this array
+    def self.parse_command(parser, target_name, commands, warnings)
+      parser = PacketParser.new(parser)
+      parser.verify_parameters()
+      parser.create_command(target_name, commands, warnings)
+    end
+
+    # @param parser [ConfigParser] Configuration parser
+    # @param target_name [String] The name of the target to create the packet
+    #   under. If the target name is 'SYSTEM' the keyword parameter will be
+    #   used instead of this parameter.
+    # @param telemetry [Hash] Hash of the currently defined telemetry packets
+    # @param latest_data [Hash<String=>Hash<String=>Array(Packet)>>] Hash of hashes keyed
+    #   first by the target name and then by the item name. This results in an
+    #   array of packets containing that target and item. This structure is
+    #   used to perform lookups when the packet and item are known but the
+    #   packet is not.
+    # @param warnings [Array<String>] Any warning strings generated while
+    #   parsing this command will be appened to this array
+    def self.parse_telemetry(parser, target_name, telemetry, latest_data, warnings)
+      parser = PacketParser.new(parser)
+      parser.verify_parameters()
+      parser.create_telemetry(target_name, telemetry, latest_data, warnings)
+    end
+
+    # @param packet [Packet] Packet to check all default and range items for
+    #   appropriate data types. Only applicable to COMMAND packets.
+    def self.check_item_data_types(packet)
+      packet.sorted_items.each do |item|
+        item.check_default_and_range_data_types()
+      end
+    rescue
+      # Add the target name and packet name to the error message so the user
+      # can debug where the error occurred
+      raise $!, "#{packet.target_name} #{packet.packet_name} #{$!}", $!.backtrace
+    end
+
+    # @param parser [ConfigParser] Configuration parser
+    def initialize(parser)
+      @parser = parser
+    end
+
+    def verify_parameters
+      @usage = "#{@parser.keyword} <TARGET NAME> <PACKET NAME> <ENDIANNESS: BIG_ENDIAN/LITTLE_ENDIAN> <DESCRIPTION (Optional)>"
+      @parser.verify_num_parameters(3, 4, @usage)
+      @parser.verify_parameter_naming(2) # Packet name is the 2nd parameter
+    end
+
+    def create_command(target_name, commands, warnings)
+      packet = create_packet(target_name)
+      PacketParser.finish_create_command(packet, commands, warnings)
+    end
+
+    def create_telemetry(target_name, telemetry, latest_data, warnings)
+      packet = create_packet(target_name)
+      PacketParser.finish_create_telemetry(packet, telemetry, latest_data, warnings)
+    end
+
+    # private
+
+    def create_packet(target_name)
+      params = @parser.parameters
+      target_name = params[0].to_s.upcase if target_name == 'SYSTEM'
+      packet_name = params[1].to_s.upcase
+      endianness = params[2].to_s.upcase.to_sym
+      description = params[3].to_s
+      if endianness != :BIG_ENDIAN and endianness != :LITTLE_ENDIAN
+        raise @parser.error("Invalid endianness #{params[2]}. Must be BIG_ENDIAN or LITTLE_ENDIAN.", @usage)
+      end
+
+      Packet.new(target_name, packet_name, endianness, description)
+    end
+
+    def self.check_for_duplicate(type, list, packet)
+      msg = nil
+      if list[packet.target_name]
+        if list[packet.target_name][packet.packet_name]
+          msg = "#{type} Packet #{packet.target_name} #{packet.packet_name} redefined."
+          Logger.instance.warn msg
+        end
+      end
+      msg
+    end
+
+    def self.finish_create_command(packet, commands, warnings)
+      warning = PacketParser.check_for_duplicate('Command', commands, packet)
+      warnings << warning if warning
+      packet.define_reserved_items()
+      commands[packet.target_name] ||= {}
+      packet
+    end
+
+    def self.finish_create_telemetry(packet, telemetry, latest_data, warnings)
+      warning = PacketParser.check_for_duplicate('Telemetry', telemetry, packet)
+      warnings << warning if warning
+      packet.define_reserved_items()
+
+      unless telemetry[packet.target_name]
+        telemetry[packet.target_name] = {}
+        latest_data[packet.target_name] = {}
+      end
+      packet
+    end
+  end
+end

data/lib/openc3/packets/parsers/processor_parser.rb

@@ -0,0 +1,73 @@
+# encoding: ascii-8bit
+
+# Copyright 2022 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 Affero General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# Modified by OpenC3, Inc.
+# All changes Copyright 2022, OpenC3, Inc.
+# All Rights Reserved
+
+require 'openc3/processors'
+
+module OpenC3
+  class ProcessorParser
+    # @param parser [ConfigParser] Configuration parser
+    # @param packet [Packet] The current packet
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    def self.parse(parser, packet, cmd_or_tlm)
+      @parser = ProcessorParser.new(parser)
+      @parser.verify_parameters(cmd_or_tlm)
+      @parser.create_processor(packet)
+    end
+
+    # @param parser [ConfigParser] Configuration parser
+    def initialize(parser)
+      @parser = parser
+    end
+
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    def verify_parameters(cmd_or_tlm)
+      if cmd_or_tlm == PacketConfig::COMMAND
+        raise @parser.error("PROCESSOR only applies to telemetry packets")
+      end
+
+      @usage = "PROCESSOR <PROCESSOR NAME> <PROCESSOR CLASS FILENAME> <PROCESSOR SPECIFIC OPTIONS>"
+      @parser.verify_num_parameters(2, nil, @usage)
+    end
+
+    # @param packet [Packet] The packet the processor should be added to
+    def create_processor(packet)
+      # require should be performed in target.txt
+      klass = @parser.parameters[1].filename_to_class_name.to_class
+      raise @parser.error("#{@parser.parameters[1].filename_to_class_name} class not found. Did you require the file in target.txt?", @usage) unless klass
+
+      if @parser.parameters[2]
+        processor = klass.new(*@parser.parameters[2..(@parser.parameters.length - 1)])
+      else
+        processor = klass.new
+      end
+      raise ArgumentError, "processor must be a OpenC3::Processor but is a #{processor.class}" unless OpenC3::Processor === processor
+
+      processor.name = get_processor_name()
+      packet.processors[processor.name] = processor
+    rescue Exception => err
+      raise @parser.error(err, @usage)
+    end
+
+    private
+
+    def get_processor_name
+      @parser.parameters[0].to_s.upcase
+    end
+  end
+end

data/lib/openc3/packets/parsers/state_parser.rb

@@ -0,0 +1,127 @@
+# encoding: ascii-8bit
+
+# Copyright 2022 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 Affero General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# Modified by OpenC3, Inc.
+# All changes Copyright 2022, OpenC3, Inc.
+# All Rights Reserved
+
+require 'openc3/packets/packet_item'
+
+module OpenC3
+  class StateParser
+    # @param parser [ConfigParser] Configuration parser
+    # @param packet [Packet] The current packet
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    # @param item [PacketItem] The packet item to create states on
+    # @param warnings [Array<String>] Array of string warnings which will be
+    #   appended with any warnings found when parsing the limits
+    def self.parse(parser, packet, cmd_or_tlm, item, warnings)
+      raise parser.error("Items with LIMITS can't define STATE") if item.limits.values
+      raise parser.error("Items with UNITS can't define STATE") if item.units
+
+      @parser = StateParser.new(parser)
+      @parser.verify_parameters(cmd_or_tlm)
+      @parser.create_state(packet, cmd_or_tlm, item, warnings)
+    end
+
+    # @param parser [ConfigParser] Configuration parser
+    def initialize(parser)
+      @parser = parser
+    end
+
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    def verify_parameters(cmd_or_tlm)
+      @usage = "STATE <STATE NAME> <STATE VALUE> "
+      if cmd_or_tlm == PacketConfig::COMMAND
+        @usage << "<HAZARDOUS (Optional)> <Hazardous Description (Optional)>"
+        @parser.verify_num_parameters(2, 4, @usage)
+      else
+        @usage << "<COLOR: GREEN/YELLOW/RED (Optional)>"
+        @parser.verify_num_parameters(2, 3, @usage)
+      end
+    end
+
+    # @param packet [Packet] The current packet
+    # @param cmd_or_tlm [String] Whether this is a command or telemetry packet
+    # @param item [PacketItem] The packet item to create states on
+    # @param warnings [Array<String>] Array of string warnings which will be
+    #   appended with any warnings found when parsing the limits
+    def create_state(packet, cmd_or_tlm, item, warnings)
+      item.states ||= {}
+
+      state_name = get_state_name()
+      check_for_duplicate_states(item, warnings)
+      item.states[state_name] = get_state_value(item.data_type)
+      parse_additional_parameters(packet, cmd_or_tlm, item)
+    end
+
+    private
+
+    def get_state_name
+      @parser.parameters[0].upcase
+    end
+
+    def get_state_value(data_type)
+      if data_type == :STRING || data_type == :BLOCK
+        @parser.parameters[1]
+      else
+        @parser.parameters[1].convert_to_value
+      end
+    end
+
+    def check_for_duplicate_states(item, warnings)
+      if item.states[get_state_name()]
+        msg = "Duplicate state defined on line #{@parser.line_number}: #{@parser.line}"
+        Logger.instance.warn(msg)
+        warnings << msg
+      end
+    end
+
+    def parse_additional_parameters(packet, cmd_or_tlm, item)
+      return unless @parser.parameters.length > 2
+
+      if cmd_or_tlm == PacketConfig::COMMAND
+        get_hazardous(item)
+      else
+        get_state_colors(item)
+        packet.update_limits_items_cache(item)
+      end
+    end
+
+    def get_hazardous(item)
+      if @parser.parameters[2].upcase == 'HAZARDOUS'
+        item.hazardous ||= {}
+        if @parser.parameters[3]
+          item.hazardous[get_state_name()] = @parser.parameters[3]
+        else
+          item.hazardous[get_state_name()] = ""
+        end
+      else
+        raise @parser.error("HAZARDOUS expected as third parameter for this line.", @usage)
+      end
+    end
+
+    def get_state_colors(item)
+      color = @parser.parameters[2].upcase.to_sym
+      unless PacketItem::STATE_COLORS.include? color
+        raise @parser.error("Invalid state color #{color}. Must be one of #{PacketItem::STATE_COLORS.join(' ')}.", @usage)
+      end
+
+      item.limits.enabled = true
+      item.state_colors ||= {}
+      item.state_colors[get_state_name()] = color
+    end
+  end
+end