openc3 5.0.6

data/lib/openc3/interfaces/protocols/preidentified_protocol.rb

@@ -0,0 +1,206 @@
+# 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/interfaces/protocols/burst_protocol'
+
+module OpenC3
+  # Delineates packets using the OpenC3 preidentification system
+  class PreidentifiedProtocol < BurstProtocol
+    COSMOS4_STORED_FLAG_MASK = 0x80
+    COSMOS4_EXTRA_FLAG_MASK = 0x40
+
+    # @param sync_pattern (see BurstProtocol#initialize)
+    # @param max_length [Integer] The maximum allowed value of the length field
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(sync_pattern = nil, max_length = nil, mode = 4, allow_empty_data = nil)
+      super(0, sync_pattern, false, allow_empty_data)
+      @max_length = ConfigParser.handle_nil(max_length)
+      @max_length = Integer(@max_length) if @max_length
+      @mode = Integer(mode)
+    end
+
+    def reset
+      super()
+      @reduction_state = :START
+    end
+
+    def read_packet(packet)
+      packet.received_time = @read_received_time
+      packet.target_name = @read_target_name
+      packet.packet_name = @read_packet_name
+      if @mode == 4 # COSMOS4.3+ Protocol
+        packet.stored = @read_stored
+        packet.extra = @read_extra
+      end
+      return packet
+    end
+
+    def write_packet(packet)
+      received_time = packet.received_time
+      received_time = Time.now unless received_time
+      @write_time_seconds = [received_time.tv_sec].pack('N') # UINT32
+      @write_time_microseconds = [received_time.tv_usec].pack('N') # UINT32
+      @write_target_name = packet.target_name
+      @write_target_name = 'UNKNOWN' unless @write_target_name
+      @write_packet_name = packet.packet_name
+      @write_packet_name = 'UNKNOWN' unless @write_packet_name
+      if @mode == 4 # COSMOS4.3+ Protocol
+        @write_flags = 0
+        @write_flags |= COSMOS4_STORED_FLAG_MASK if packet.stored
+        @write_extra = nil
+        if packet.extra
+          @write_flags |= COSMOS4_EXTRA_FLAG_MASK
+          @write_extra = packet.extra.as_json(:allow_nan => true).to_json(:allow_nan => true)
+        end
+      end
+      return packet
+    end
+
+    def write_data(data)
+      data_length = [data.length].pack('N') # UINT32
+      data_to_send = ''
+      data_to_send << @sync_pattern if @sync_pattern
+      if @mode == 4 # COSMOS4.3+ Protocol
+        data_to_send << @write_flags
+        if @write_extra
+          data_to_send << [@write_extra.length].pack('N')
+          data_to_send << @write_extra
+        end
+      end
+      data_to_send << @write_time_seconds
+      data_to_send << @write_time_microseconds
+      data_to_send << @write_target_name.length
+      data_to_send << @write_target_name
+      data_to_send << @write_packet_name.length
+      data_to_send << @write_packet_name
+      data_to_send << data_length
+      data_to_send << data
+      return data_to_send
+    end
+
+    protected
+
+    def read_length_field_followed_by_string(length_num_bytes)
+      # Read bytes for string length
+      return :STOP if @data.length < length_num_bytes
+
+      string_length = @data[0..(length_num_bytes - 1)]
+
+      case length_num_bytes
+      when 1
+        string_length = string_length.unpack('C')[0] # UINT8
+      when 2
+        string_length = string_length.unpack('n')[0] # UINT16
+      when 4
+        string_length = string_length.unpack('N')[0] # UINT32
+        raise "Length value received larger than max_length: #{string_length} > #{@max_length}" if @max_length and string_length > @max_length
+      else
+        raise "Unsupported length given to read_length_field_followed_by_string: #{length_num_bytes}"
+      end
+
+      # Read String
+      return :STOP if @data.length < (string_length + length_num_bytes)
+
+      next_index = string_length + length_num_bytes
+      string = @data[length_num_bytes..(next_index - 1)]
+
+      # Remove data from current_data
+      @data.replace(@data[next_index..-1])
+
+      return string
+    end
+
+    def reduce_to_single_packet
+      # Discard sync pattern if present
+      if @sync_pattern
+        if @reduction_state == :START
+          return :STOP if @data.length < @sync_pattern.length
+
+          @data.replace(@data[(@sync_pattern.length)..-1])
+          @reduction_state = :SYNC_REMOVED
+        end
+      elsif @reduction_state == :START
+        @reduction_state = :SYNC_REMOVED
+      end
+
+      if @reduction_state == :SYNC_REMOVED and @mode == 4
+        # Read and remove flags
+        return :STOP if @data.length < 1
+
+        flags = @data[0].unpack('C')[0] # byte
+        @data.replace(@data[1..-1])
+        @read_stored = false
+        @read_stored = true if (flags & COSMOS4_STORED_FLAG_MASK) != 0
+        @read_extra = nil
+        if (flags & COSMOS4_EXTRA_FLAG_MASK) != 0
+          @reduction_state = :NEED_EXTRA
+        else
+          @reduction_state = :FLAGS_REMOVED
+        end
+      end
+
+      if @reduction_state == :NEED_EXTRA
+        # Read and remove extra
+        @read_extra = read_length_field_followed_by_string(4)
+        return :STOP if @read_extra == :STOP
+
+        @read_extra = JSON.parse(@read_extra, :allow_nan => true, :create_additions => true)
+        @reduction_state = :FLAGS_REMOVED
+      end
+
+      if @reduction_state == :FLAGS_REMOVED or (@reduction_state == :SYNC_REMOVED and @mode != 4)
+        # Read and remove packet received time
+        return :STOP if @data.length < 8
+
+        time_seconds = @data[0..3].unpack('N')[0] # UINT32
+        time_microseconds = @data[4..7].unpack('N')[0] # UINT32
+        @read_received_time = Time.at(time_seconds, time_microseconds).sys
+        @data.replace(@data[8..-1])
+        @reduction_state = :TIME_REMOVED
+      end
+
+      if @reduction_state == :TIME_REMOVED
+        # Read and remove the target name
+        @read_target_name = read_length_field_followed_by_string(1)
+        return :STOP if @read_target_name == :STOP
+
+        @reduction_state = :TARGET_NAME_REMOVED
+      end
+
+      if @reduction_state == :TARGET_NAME_REMOVED
+        # Read and remove the packet name
+        @read_packet_name = read_length_field_followed_by_string(1)
+        return :STOP if @read_packet_name == :STOP
+
+        @reduction_state = :PACKET_NAME_REMOVED
+      end
+
+      if @reduction_state == :PACKET_NAME_REMOVED
+        # Read packet data and return
+        packet_data = read_length_field_followed_by_string(4)
+        return :STOP if packet_data == :STOP
+
+        @reduction_state = :START
+        return packet_data
+      end
+
+      raise "Error should never reach end of method #{@reduction_state}"
+    end
+  end
+end

data/lib/openc3/interfaces/protocols/protocol.rb

@@ -0,0 +1,82 @@
+# 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/config/config_parser'
+require 'thread'
+
+module OpenC3
+  # Base class for all OpenC3 protocols which defines a framework which must be
+  # implemented by a subclass.
+  class Protocol
+    attr_accessor :interface
+    attr_accessor :allow_empty_data
+
+    # @param allow_empty_data [true/false/nil] Whether or not this protocol will allow an empty string
+    # to be passed down to later Protocols (instead of returning :STOP). Can be true, false, or nil, where
+    # nil is interpreted as true unless the Protocol is the last Protocol of the chain.
+    def initialize(allow_empty_data = nil)
+      @interface = nil
+      @allow_empty_data = ConfigParser.handle_true_false_nil(allow_empty_data)
+      reset()
+    end
+
+    def reset
+    end
+
+    def connect_reset
+      reset()
+    end
+
+    def disconnect_reset
+      reset()
+    end
+
+    # Ensure we have some data in case this is the only protocol
+    def read_data(data)
+      if data.length <= 0
+        if @allow_empty_data.nil?
+          if @interface and @interface.read_protocols[-1] == self
+            # Last read interface in chain with auto @allow_empty_data
+            return :STOP
+          end
+        elsif !@allow_empty_data
+          # Don't @allow_empty_data means STOP
+          return :STOP
+        end
+      end
+      data
+    end
+
+    def read_packet(packet)
+      return packet
+    end
+
+    def write_packet(packet)
+      return packet
+    end
+
+    def write_data(data)
+      return data
+    end
+
+    def post_write_interface(packet, data)
+      return packet, data
+    end
+  end
+end

data/lib/openc3/interfaces/protocols/template_protocol.rb

@@ -0,0 +1,261 @@
+# 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/config/config_parser'
+require 'openc3/interfaces/protocols/terminated_protocol'
+require 'thread' # For Queue
+require 'timeout' # For Timeout::Error
+
+module OpenC3
+  # Protocol which delineates packets using delimiter characters. Designed for
+  # text based protocols which expect a command and send a response. The
+  # protocol handles sending the command and capturing the response.
+  class TemplateProtocol < TerminatedProtocol
+    # @param write_termination_characters (see TerminatedProtocol#initialize)
+    # @param read_termination_characters (see TerminatedProtocol#initialize)
+    # @param ignore_lines [Integer] Number of newline terminated reads to
+    #   ignore when processing the response
+    # @param initial_read_delay [Integer] Initial delay when connecting before
+    #   trying to read
+    # @param response_lines [Integer] Number of newline terminated lines which
+    #   comprise the response
+    # @param strip_read_termination (see TerminatedProtocol#initialize)
+    # @param discard_leading_bytes (see TerminatedProtocol#initialize)
+    # @param sync_pattern (see TerminatedProtocol#initialize)
+    # @param fill_fields (see TerminatedProtocol#initialize)
+    # @param response_timeout [Float] Number of seconds to wait before timing out
+    #   when waiting for a response
+    # @param response_polling_period [Float] Number of seconds to wait between polling
+    #   for a response
+    # @param raise_exceptions [String] Whether to raise exceptions when errors
+    #   occur in the protocol like unexpected responses or response timeouts.
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(
+      write_termination_characters,
+      read_termination_characters,
+      ignore_lines = 0,
+      initial_read_delay = nil,
+      response_lines = 1,
+      strip_read_termination = true,
+      discard_leading_bytes = 0,
+      sync_pattern = nil,
+      fill_fields = false,
+      response_timeout = 5.0,
+      response_polling_period = 0.02,
+      raise_exceptions = false,
+      allow_empty_data = nil
+    )
+      super(
+        write_termination_characters,
+        read_termination_characters,
+        strip_read_termination,
+        discard_leading_bytes,
+        sync_pattern,
+        fill_fields,
+        allow_empty_data)
+      @response_template = nil
+      @response_packet = nil
+      @response_target_name = nil
+      @response_packets = []
+      @write_block_queue = Queue.new
+      @ignore_lines = ignore_lines.to_i
+      @response_lines = response_lines.to_i
+      @initial_read_delay = ConfigParser.handle_nil(initial_read_delay)
+      @initial_read_delay = @initial_read_delay.to_f if @initial_read_delay
+      @response_timeout = ConfigParser.handle_nil(response_timeout)
+      @response_timeout = @response_timeout.to_f if @response_timeout
+      @response_polling_period = response_polling_period.to_f
+      @connect_complete_time = nil
+      @raise_exceptions = ConfigParser.handle_true_false(raise_exceptions)
+    end
+
+    def reset
+      super()
+      @initial_read_delay_needed = true
+    end
+
+    def connect_reset
+      super()
+      begin
+        @write_block_queue.pop(true) while @write_block_queue.length > 0
+      rescue
+      end
+
+      @connect_complete_time = Time.now + @initial_read_delay if @initial_read_delay
+    end
+
+    def disconnect_reset
+      super()
+      @write_block_queue << nil # Unblock the write block queue
+    end
+
+    def read_data(data)
+      return super(data) if data.length <= 0
+
+      # Drop all data until the initial_read_delay is complete.
+      # This gets rid of unused welcome messages,
+      # prompts, and other junk on initial connections
+      if @initial_read_delay and @initial_read_delay_needed and @connect_complete_time
+        return :STOP if Time.now < @connect_complete_time
+
+        @initial_read_delay_needed = false
+      end
+      super(data)
+    end
+
+    def read_packet(packet)
+      if @response_template && @response_packet
+        # If lines make it this far they are part of a response
+        @response_packets << packet
+        return :STOP if @response_packets.length < (@ignore_lines + @response_lines)
+
+        @ignore_lines.times do
+          @response_packets.shift
+        end
+        response_string = ''
+        @response_lines.times do
+          response = @response_packets.shift
+          response_string << response.buffer
+        end
+
+        # Grab the response packet specified in the command
+        result_packet = System.telemetry.packet(@response_target_name, @response_packet).clone
+        result_packet.received_time = nil
+        result_packet.id_items.each do |item|
+          result_packet.write_item(item, item.id_value, :RAW)
+        end
+
+        # Convert the response template into a Regexp
+        response_item_names = []
+        response_template = @response_template.clone
+        response_template_items = @response_template.scan(/<.*?>/)
+
+        response_template_items.each do |item|
+          response_item_names << item[1..-2]
+          response_template.gsub!(item, "(.*)")
+        end
+        response_regexp = Regexp.new(response_template)
+
+        # Scan the response for the variables in brackets <VARIABLE>
+        # Write the packet value with each of the values received
+        response_values = response_string.scan(response_regexp)[0]
+        if !response_values || (response_values.length != response_item_names.length)
+          handle_error("#{@interface ? @interface.name : ""}: Unexpected response: #{response_string}")
+        else
+          response_values.each_with_index do |value, i|
+            result_packet.write(response_item_names[i], value)
+          rescue => error
+            handle_error("#{@interface ? @interface.name : ""}: Could not write value #{value} due to #{error.message}")
+            break
+          end
+        end
+
+        @response_packets.clear
+
+        # Release the write
+        if @response_template && @response_packet
+          @write_block_queue << nil
+        end
+
+        return result_packet
+      else
+        return packet
+      end
+    end
+
+    def write_packet(packet)
+      # Make sure we are past the initial data dropping period
+      if @initial_read_delay and @initial_read_delay_needed and @connect_complete_time and Time.now < @connect_complete_time
+        delay_needed = @connect_complete_time - Time.now
+        sleep(delay_needed) if delay_needed > 0
+      end
+
+      # First grab the response template and response packet (if there is one)
+      begin
+        @response_template = packet.read("RSP_TEMPLATE").strip
+        @response_packet = packet.read("RSP_PACKET").strip
+        @response_target_name = packet.target_name
+        # If the template or packet are empty set them to nil. This allows for
+        # the user to remove the RSP_TEMPLATE and RSP_PACKET values and avoid
+        # any response timeouts
+        if @response_template.empty? || @response_packet.empty?
+          @response_template = nil
+          @response_packet = nil
+          @response_target_name = nil
+        end
+      rescue
+        # If there is no response template we set to nil
+        @response_template = nil
+        @response_packet = nil
+        @response_target_name = nil
+      end
+
+      # Grab the command template because that is all we eventually send
+      @template = packet.read("CMD_TEMPLATE")
+      # Create a new packet to populate with the template
+      raw_packet = Packet.new(nil, nil)
+      raw_packet.buffer = @template
+      raw_packet = super(raw_packet)
+      return raw_packet if Symbol === raw_packet
+
+      data = raw_packet.buffer(false)
+      # Scan the template for variables in brackets <VARIABLE>
+      # Read these values from the packet and substitute them in the template
+      # and in the @response_packet name
+      @template.scan(/<(.*?)>/).each do |variable|
+        value = packet.read(variable[0], :RAW).to_s
+        data.gsub!("<#{variable[0]}>", value)
+        @response_packet.gsub!("<#{variable[0]}>", value) if @response_packet
+      end
+
+      return raw_packet
+    end
+
+    def post_write_interface(packet, data)
+      if @response_template && @response_packet
+        if @response_timeout
+          response_timeout_time = Time.now + @response_timeout
+        else
+          response_timeout_time = nil
+        end
+
+        # Block the write until the response is received
+        begin
+          @write_block_queue.pop(true)
+        rescue
+          sleep(@response_polling_period)
+          retry if !response_timeout_time
+          retry if response_timeout_time and Time.now < response_timeout_time
+          handle_error("#{@interface ? @interface.name : ""}: Timeout waiting for response")
+        end
+
+        @response_template = nil
+        @response_packet = nil
+        @response_target_name = nil
+        @response_packets.clear
+      end
+      return super(packet, data)
+    end
+
+    def handle_error(msg)
+      Logger.error(msg)
+      raise msg if @raise_exceptions
+    end
+  end
+end

data/lib/openc3/interfaces/protocols/terminated_protocol.rb

@@ -0,0 +1,93 @@
+# 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/config/config_parser'
+require 'openc3/interfaces/protocols/burst_protocol'
+
+module OpenC3
+  # Protocol which delineates packets using termination characters at
+  # the end of the data.
+  class TerminatedProtocol < BurstProtocol
+    # @param write_termination_characters [String] The characters to write
+    #   after writing the Packet buffer. Must be given as a
+    #   hexadecimal string such as '0xABCD'.
+    # @param read_termination_characters [String] The characters at the end of
+    #   the data which delineate the end of a Packet. Must be given as a
+    #   hexadecimal string such as '0xABCD'.
+    # @param strip_read_termination [Boolean] Whether to remove the
+    #   read_termination_characters before turning the data into a
+    #   Packet.
+    # @param discard_leading_bytes (see BurstProtocol#initialize)
+    # @param sync_pattern (see BurstProtocol#initialize)
+    # @param fill_fields (see BurstProtocol#initialize)
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(
+      write_termination_characters,
+      read_termination_characters,
+      strip_read_termination = true,
+      discard_leading_bytes = 0,
+      sync_pattern = nil,
+      fill_fields = false,
+      allow_empty_data = nil
+    )
+      @write_termination_characters = write_termination_characters.hex_to_byte_string
+      @read_termination_characters = read_termination_characters.hex_to_byte_string
+      @strip_read_termination = ConfigParser.handle_true_false(strip_read_termination)
+
+      super(discard_leading_bytes, sync_pattern, fill_fields, allow_empty_data)
+    end
+
+    def write_data(data)
+      raise "Packet contains termination characters!" if data.index(@write_termination_characters)
+
+      data = super(data)
+      @write_termination_characters.each_byte do |byte|
+        data << byte
+      end
+      return data
+    end
+
+    protected
+
+    def reduce_to_single_packet
+      index = @data.index(@read_termination_characters)
+
+      # Reduce to packet data and setup current_data for next packet
+      if index
+        if index > 0
+          if @strip_read_termination
+            packet_data = @data[0..(index - 1)]
+          else
+            packet_data = @data[0..(index + @read_termination_characters.length - 1)]
+          end
+        else # @data begins with the termination characters
+          if @strip_read_termination
+            packet_data = ''
+          else # Keep everything
+            packet_data = @data[0..(@read_termination_characters.length - 1)]
+          end
+        end
+        @data.replace(@data[(index + @read_termination_characters.length)..-1])
+        return packet_data
+      else
+        return :STOP
+      end
+    end
+  end
+end