cosmos 3.9.2 → 4.0.0

data/lib/cosmos/{streams/length_stream_protocol.rb → interfaces/protocols/length_protocol.rb}

@@ -1,6 +1,6 @@
 # encoding: ascii-8bit
 
-# Copyright 2014 Ball Aerospace & Technologies Corp.
+# Copyright 2017 Ball Aerospace & Technologies Corp.
 # All Rights Reserved.
 #
 # This program is free software; you can modify and/or redistribute it
@@ -9,29 +9,27 @@
 # attribution addendums as found in the LICENSE.txt
 
 require 'cosmos/packets/binary_accessor'
-require 'cosmos/streams/stream_protocol'
+require 'cosmos/interfaces/protocols/burst_protocol'
 require 'cosmos/config/config_parser'
 
 module Cosmos
-
-  # This StreamProtocol delineates packets using a length field at a fixed
+  # Protocol which delineates packets using a length field at a fixed
   # location in each packet.
-  class LengthStreamProtocol < StreamProtocol
-
+  class LengthProtocol < BurstProtocol
     # @param length_bit_offset [Integer] The bit offset of the length field
     # @param length_bit_size [Integer] The size in bits of the length field
     # @param length_value_offset [Integer] The offset to apply to the length
     #   value once it has been read from the packet. The value in the length
-    #   field itself plus the length value offset MUST equal the total bytes in
-    #   the stream including any discarded bytes.
+    #   field itself plus the length value offset MUST equal the total bytes
+    #   including any discarded bytes.
     #   For example: if your length field really means "length - 1" this value should be 1.
     # @param length_bytes_per_count [Integer] The number of bytes per each
     #   length field 'count'. This is used if the units of the length field is
     #   something other than bytes, for example words.
     # @param length_endianness [String] The endianness of the length field.
     #   Must be either BIG_ENDIAN or LITTLE_ENDIAN.
-    # @param discard_leading_bytes (see StreamProtocol#initialize)
-    # @param sync_pattern (see StreamProtocol#initialize)
+    # @param discard_leading_bytes (see BurstProtocol#initialize)
+    # @param sync_pattern (see BurstProtocol#initialize)
     # @param max_length [Integer] The maximum allowed value of the length field
     # @param fill_length_and_sync_pattern [Boolean] Fill the length field and sync
     #    pattern when writing packets
@@ -75,45 +73,57 @@ module Cosmos
       @max_length = Integer(@max_length) if @max_length
     end
 
-    # See StreamProtocol#pre_write_packet
-    def pre_write_packet(packet)
-      data = super(packet)
-      if @fill_sync_pattern # and length
-        # Fill the length field
-        length = (data.length - @length_value_offset) / @length_bytes_per_count
-        BinaryAccessor.write(length,
-          @length_bit_offset,
-          @length_bit_size,
-          :UINT,
-          data,
-          @length_endianness,
-          :ERROR)
-
-        # Also write the new length field into the packet that will be logged if it exists in the packet
-        if @discard_leading_bytes > 0
-          # The write above did not write into the original packet
-          original_length_bit_offset = @length_bit_offset - (@discard_leading_bytes * 8)
-          if original_length_bit_offset >= 0
-            original_data = packet.buffer(false)
-            BinaryAccessor.write(length,
-              original_length_bit_offset,
-              @length_bit_size,
-              :UINT,
-              original_data,
-              @length_endianness,
-              :ERROR)
-          end
+    # Called to perform modifications on a command packet before it is send
+    #
+    # @param packet [Packet] Original packet
+    # @return [Packet] Potentially modified packet
+    def write_packet(packet)
+      if @fill_fields
+        # If the start of the length field is past what we discard, then the
+        # length field is inside the packet
+        if @length_bit_offset >= (@discard_leading_bytes * 8)
+          length = calculate_length(packet.buffer.length + @discard_leading_bytes)
+          # Subtract off the discarded bytes since they haven't been added yet
+          # Adding bytes happens in the write_data method
+          offset = @length_bit_offset - (@discard_leading_bytes * 8)
+          # Directly write the packet buffer and fill in the length
+          BinaryAccessor.write(length, offset, @length_bit_size, :UINT,
+                               packet.buffer(false), @length_endianness, :ERROR)
+        end
+      end
+      return super(packet) # Allow burst_protocol to set the sync if needed
+    end
+
+    # Called to perform modifications on write data before making it into a packet
+    #
+    # @param data [String] Raw packet data
+    # @return [String] Potentially modified packet data
+    def write_data(data)
+      data = super(data)
+      if @fill_fields
+        # If the start of the length field is before what we discard, then the
+        # length field is outside the packet
+        if @length_bit_offset < (@discard_leading_bytes * 8)
+          BinaryAccessor.write(calculate_length(data.length), @length_bit_offset, @length_bit_size, :UINT,
+                               data, @length_endianness, :ERROR)
         end
       end
-      data
+      return data
     end
 
     protected
 
+    def calculate_length(buffer_length)
+      length = (buffer_length / @length_bytes_per_count) - @length_value_offset
+      if @max_length && length > @max_length
+        raise "Calculated length #{length} larger than max_length #{@max_length}"
+      end
+      length
+    end
+
     def reduce_to_single_packet
       # Make sure we have at least enough data to reach the length field
-      read_minimum_size(@length_bytes_needed)
-      return nil if @data.length <= 0
+      return :STOP if @data.length < @length_bytes_needed
 
       # Determine the packet's length
       length = BinaryAccessor.read(@length_bit_offset,
@@ -125,16 +135,13 @@ module Cosmos
       packet_length = (length * @length_bytes_per_count) + @length_value_offset
 
       # Make sure we have enough data for the packet
-      read_minimum_size(packet_length)
-      return nil if @data.length <= 0
+      return:STOP if @data.length < packet_length
 
       # Reduce to packet data and setup current_data for next packet
       packet_data = @data[0..(packet_length - 1)]
       @data.replace(@data[packet_length..-1])
 
-      packet_data
+      return packet_data
     end
-
-  end # class LengthStreamProtocol
-
-end # module Cosmos
+  end
+end

data/lib/cosmos/interfaces/protocols/override_protocol.rb

@@ -0,0 +1,52 @@
+# encoding: ascii-8bit
+
+# Copyright 2017 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/interfaces/protocols/protocol'
+
+module Cosmos
+  # Protocol which permanently overrides an item value such that reading the
+  # item returns the overriden value. Methods are prefixed with underscores
+  # so the API can include the original name which calls out to these
+  # methods. Clearing the override requires calling normalize_tlm.
+  class OverrideProtocol < Protocol
+
+    # @param allow_empty_data [true/false] Whether STOP should be returned on empty data
+    def initialize(allow_empty_data = false)
+      super(allow_empty_data)
+    end
+
+    # Called to perform modifications on a read packet before it is given to the user
+    #
+    # @param packet [Packet] Original packet
+    # @return [Packet] Potentially modified packet
+    def read_packet(packet)
+      if @interface.override_tlm && !@interface.override_tlm.empty?
+        # Need to make sure packet is identified and defined
+        target_names = nil
+        target_names = @interface.target_names if @interface
+        identified_packet = System.telemetry.identify_and_define_packet(packet, target_names)
+        if identified_packet
+          packet = identified_packet
+          packets = @interface.override_tlm[packet.target_name]
+          if packets
+            items = packets[packet.packet_name]
+            if items
+              items.each do |item_name, value|
+                # This should be safe because we check at the API level it exists
+                packet.write(item_name, value[0], value[1])
+              end
+            end
+          end
+        end
+      end
+      return packet
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# encoding: ascii-8bit
+
+# Copyright 2017 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/interfaces/protocols/burst_protocol'
+
+module Cosmos
+  # Delineates packets using the COSMOS preidentification system
+  class PreidentifiedProtocol < BurstProtocol
+
+    # @param sync_pattern (see BurstProtocol#initialize)
+    # @param max_length [Integer] The maximum allowed value of the length field
+    def initialize(sync_pattern = nil, max_length = nil)
+      super(0, sync_pattern)
+      @max_length = ConfigParser.handle_nil(max_length)
+      @max_length = Integer(@max_length) if @max_length
+    end
+
+    def reset
+      super()
+      @reduction_state = :START
+    end
+
+    def read_packet(packet)
+      packet.received_time = @received_time
+      packet.target_name = @target_name
+      packet.packet_name = @packet_name
+      return packet
+    end
+
+    def write_packet(packet)
+      received_time = packet.received_time
+      received_time = Time.now unless received_time
+      @time_seconds = [received_time.tv_sec].pack('N') # UINT32
+      @time_microseconds = [received_time.tv_usec].pack('N') # UINT32
+      @target_name = packet.target_name
+      @target_name = 'UNKNOWN' unless @target_name
+      @packet_name = packet.packet_name
+      @packet_name = 'UNKNOWN' unless @packet_name
+      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
+      data_to_send << @time_seconds
+      data_to_send << @time_microseconds
+      data_to_send << @target_name.length
+      data_to_send << @target_name
+      data_to_send << @packet_name.length
+      data_to_send << @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
+
+      # Read and remove packet received time
+      if @reduction_state == :SYNC_REMOVED
+        return :STOP if @data.length < 8
+        time_seconds = @data[0..3].unpack('N')[0] # UINT32
+        time_microseconds = @data[4..7].unpack('N')[0] # UINT32
+        @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
+        @target_name = read_length_field_followed_by_string(1)
+        return :STOP if @target_name == :STOP
+        @reduction_state = :TARGET_NAME_REMOVED
+      end
+
+      if @reduction_state == :TARGET_NAME_REMOVED
+        # Read and remove the packet name
+        @packet_name = read_length_field_followed_by_string(1)
+        return :STOP if @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/cosmos/interfaces/protocols/protocol.rb

@@ -0,0 +1,60 @@
+# encoding: ascii-8bit
+
+# Copyright 2017 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/config/config_parser'
+require 'cosmos/interfaces/protocols/protocol'
+require 'thread'
+
+module Cosmos
+  class Protocol
+    attr_accessor :interface
+    attr_accessor :allow_empty_data
+
+    # @param allow_empty_data [true/false] Whether STOP should be returned on empty data
+    def initialize(allow_empty_data = false)
+      @interface = nil
+      @allow_empty_data = ConfigParser.handle_true_false(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)
+      return :STOP if (data.length <= 0) && !@allow_empty_data
+      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/cosmos/interfaces/protocols/template_protocol.rb

@@ -0,0 +1,209 @@
+# encoding: ascii-8bit
+
+# Copyright 2017 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/config/config_parser'
+require 'cosmos/interfaces/protocols/terminated_protocol'
+require 'thread' # For Queue
+require 'timeout' # For Timeout::Error
+
+module Cosmos
+  # 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)
+    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
+    )
+      super(
+        write_termination_characters,
+        read_termination_characters,
+        strip_read_termination,
+        discard_leading_bytes,
+        sync_pattern,
+        fill_fields)
+      @response_template = nil
+      @response_packet = 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
+    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)
+      # 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(@interface.target_names[0], @response_packet).clone
+        result_packet.received_time = nil
+
+        # 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]
+        raise "Unexpected response received: #{response_string}" if !response_values || (response_values.length != response_item_names.length)
+        response_values.each_with_index do |value, i|
+          result_packet.write(response_item_names[i], value)
+        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
+      rescue
+        # If there is no response template we set to nil
+        @response_template = nil
+        @response_packet = 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
+      @template.scan(/<(.*?)>/).each do |variable|
+        data.gsub!("<#{variable[0]}>", packet.read(variable[0], :RAW).to_s)
+      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
+          result = @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
+          raise Timeout::Error, "Timeout waiting for response"
+        end
+
+        @response_template = nil
+        @response_packet = nil
+        @response_packets.clear
+      end
+      return super(packet, data)
+    end
+  end
+end