openc3 5.0.6

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

@@ -0,0 +1,193 @@
+# 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/protocol'
+require 'openc3/utilities/crc'
+require 'thread'
+
+module OpenC3
+  # Creates a CRC on write and verifies a CRC on read
+  class CrcProtocol < Protocol
+    ERROR = "ERROR" # on CRC mismatch
+    DISCONNECT = "DISCONNECT" # on CRC mismatch
+
+    # @param write_item_name [String/nil] Item to fill with calculated CRC value for outgoing packets (nil = don't fill)
+    # @param strip_crc [Boolean] Whether or not to remove the CRC from incoming packets
+    # @param bad_strategy [ERROR/DISCONNECT] How to handle CRC errors on incoming packets.  ERROR = Just log the error, DISCONNECT = Disconnect interface
+    # @param bit_offset [Integer] Bit offset of the CRC in the data.  Can be negative to indicate distance from end of packet
+    # @param bit_size [Integer] Bit size of the CRC - Must be 16, 32, or 64
+    # @param endianness [BIG_ENDIAN/LITTLE_ENDIAN] Endianness of the CRC
+    # @param poly [Integer] Polynomial to use when calculating the CRC
+    # @param seed [Integer] Seed value to start the calculation
+    # @param xor [Boolean] Whether to XOR the CRC result with 0xFFFF
+    # @param reflect [Boolean] Whether to bit reverse each byte of data before calculating the CRC
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(
+      write_item_name = nil,
+      strip_crc = false,
+      bad_strategy = "ERROR",
+      bit_offset = -32,
+      bit_size = 32,
+      endianness = 'BIG_ENDIAN',
+      poly = nil,
+      seed = nil,
+      xor = nil,
+      reflect = nil,
+      allow_empty_data = nil
+    )
+      super(allow_empty_data)
+      @write_item_name = ConfigParser.handle_nil(write_item_name)
+      @strip_crc = ConfigParser.handle_true_false(strip_crc)
+      raise "Invalid strip CRC of '#{strip_crc}'. Must be TRUE or FALSE." unless !!@strip_crc == @strip_crc
+
+      case bad_strategy
+      when ERROR, DISCONNECT
+        @bad_strategy = bad_strategy
+      else
+        raise "Invalid bad CRC strategy of #{bad_strategy}. Must be ERROR or DISCONNECT."
+      end
+
+      case endianness.to_s.upcase
+      when 'BIG_ENDIAN'
+        @endianness = :BIG_ENDIAN # Convert to symbol for use in BinaryAccessor.write
+      when 'LITTLE_ENDIAN'
+        @endianness = :LITTLE_ENDIAN # Convert to symbol for use in BinaryAccessor.write
+      else
+        raise "Invalid endianness '#{endianness}'. Must be BIG_ENDIAN or LITTLE_ENDIAN."
+      end
+
+      begin
+        @bit_offset = Integer(bit_offset)
+      rescue
+        raise "Invalid bit offset of #{bit_offset}. Must be a number."
+      end
+      raise "Invalid bit offset of #{bit_offset}. Must be divisible by 8." if @bit_offset % 8 != 0
+
+      poly = ConfigParser.handle_nil(poly)
+      begin
+        poly = Integer(poly) if poly
+      rescue
+        raise "Invalid polynomial of #{poly}. Must be a number."
+      end
+
+      seed = ConfigParser.handle_nil(seed)
+      begin
+        seed = Integer(seed) if seed
+      rescue
+        raise "Invalid seed of #{seed}. Must be a number."
+      end
+
+      xor = ConfigParser.handle_true_false_nil(xor)
+      raise "Invalid XOR value of '#{xor}'. Must be TRUE or FALSE." if xor && !!xor != xor
+
+      reflect = ConfigParser.handle_true_false_nil(reflect) if reflect
+      raise "Invalid reflect value of '#{reflect}'. Must be TRUE or FALSE." if reflect && !!reflect != reflect
+
+      # Built the CRC arguments array. All subsequent arguments are dependent
+      # on the previous ones so we build it up incrementally.
+      args = []
+      if poly
+        args << poly
+        if seed
+          args << seed
+          unless xor.nil? # Can't check raw variable because it could be false
+            args << xor
+            unless reflect.nil? # Can't check raw variable because it could be false
+              args << reflect
+            end
+          end
+        end
+      end
+
+      @bit_size = bit_size.to_i
+      case @bit_size
+      when 16
+        @pack = (@endianness == :BIG_ENDIAN) ? 'n' : 'v'
+        if args.empty?
+          @crc = Crc16.new
+        else
+          @crc = Crc16.new(*args)
+        end
+      when 32
+        @pack = (@endianness == :BIG_ENDIAN) ? 'N' : 'V'
+        if args.empty?
+          @crc = Crc32.new
+        else
+          @crc = Crc32.new(*args)
+        end
+      when 64
+        @pack = (@endianness == :BIG_ENDIAN) ? 'N' : 'V'
+        if args.empty?
+          @crc = Crc64.new
+        else
+          @crc = Crc64.new(*args)
+        end
+      else
+        raise "Invalid bit size of #{bit_size}. Must be 16, 32, or 64."
+      end
+    end
+
+    def read_data(data)
+      return super(data) if data.length <= 0
+
+      crc = BinaryAccessor.read(@bit_offset, @bit_size, :UINT, data, @endianness)
+      calculated_crc = @crc.calc(data[0...(@bit_offset / 8)])
+      if calculated_crc != crc
+        Logger.error "#{@interface ? @interface.name : ""}: Invalid CRC detected! Calculated 0x#{calculated_crc.to_s(16).upcase} vs found 0x#{crc.to_s(16).upcase}."
+        if @bad_strategy == DISCONNECT
+          return :DISCONNECT
+        end
+      end
+      if @strip_crc
+        new_data = data.dup
+        new_data = new_data[0...(@bit_offset / 8)]
+        end_range = (@bit_offset + @bit_size) / 8
+        new_data << data[end_range..-1] if end_range != 0
+        return new_data
+      end
+      return data
+    end
+
+    def write_packet(packet)
+      if @write_item_name
+        end_range = packet.get_item(@write_item_name).bit_offset / 8
+        crc = @crc.calc(packet.buffer(false)[0...end_range])
+        packet.write(@write_item_name, crc)
+      end
+      packet
+    end
+
+    def write_data(data)
+      unless @write_item_name
+        if @bit_size == 64
+          crc = @crc.calc(data)
+          data << ("\x00" * 8)
+          BinaryAccessor.write((crc >> 32), -64, 32, :UINT, data, @endianness, :ERROR)
+          BinaryAccessor.write((crc & 0xFFFFFFFF), -32, 32, :UINT, data, @endianness, :ERROR)
+        else
+          crc = @crc.calc(data)
+          data << ("\x00" * (@bit_size / 8))
+          BinaryAccessor.write(crc, -@bit_size, @bit_size, :UINT, data, @endianness, :ERROR)
+        end
+      end
+      data
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+# 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
+  # Delineates packets by identifying them and then
+  # reading out their entire fixed length. Packets lengths can vary but
+  # they must all be fixed.
+  class FixedProtocol < BurstProtocol
+    # @param min_id_size [Integer] The minimum amount of data needed to
+    #   identify a packet.
+    # @param discard_leading_bytes (see BurstProtocol#initialize)
+    # @param sync_pattern (see BurstProtocol#initialize)
+    # @param telemetry [Boolean] Whether the interface is returning
+    #   telemetry (true) or commands (false)
+    # @param fill_fields (see BurstProtocol#initialize)
+    # @param unknown_raise Whether to raise an exception on an unknown packet
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(
+      min_id_size,
+      discard_leading_bytes = 0,
+      sync_pattern = nil,
+      telemetry = true,
+      fill_fields = false,
+      unknown_raise = false,
+      allow_empty_data = nil
+    )
+      super(discard_leading_bytes, sync_pattern, fill_fields, allow_empty_data)
+      @min_id_size = Integer(min_id_size)
+      @telemetry = telemetry
+      @unknown_raise = ConfigParser.handle_true_false(unknown_raise)
+      @received_time = nil
+      @target_name = nil
+      @packet_name = nil
+    end
+
+    # Set the received_time, target_name and packet_name which we recorded when
+    # we identified this packet. The server will also do this but since we know
+    # the information here, we perform this optimization.
+    def read_packet(packet)
+      packet.received_time = @received_time
+      packet.target_name = @target_name
+      packet.packet_name = @packet_name
+      return packet
+    end
+
+    protected
+
+    # Identifies an unknown buffer of data as a Packet. The raw data is
+    # returned but the packet that matched is recorded so it can be set in the
+    # read_packet callback.
+    #
+    # @return [String|Symbol] The identified packet data or :STOP if more data
+    #   is required to build a packet
+    def identify_and_finish_packet
+      packet_data = nil
+      identified_packet = nil
+
+      @interface.target_names.each do |target_name|
+        target_packets = nil
+        unique_id_mode = false
+        begin
+          if @telemetry
+            target_packets = System.telemetry.packets(target_name)
+            target = System.targets[target_name]
+            unique_id_mode = target.tlm_unique_id_mode if target
+          else
+            target_packets = System.commands.packets(target_name)
+            target = System.targets[target_name]
+            unique_id_mode = target.cmd_unique_id_mode if target
+          end
+        rescue RuntimeError
+          # No commands/telemetry for this target
+          next
+        end
+
+        if unique_id_mode
+          target_packets.each do |packet_name, packet|
+            if packet.identify?(@data[@discard_leading_bytes..-1])
+              identified_packet = packet
+              break
+            end
+          end
+        else
+          # Do a hash lookup to quickly identify the packet
+          if target_packets.length > 0
+            packet = target_packets.first[1]
+            key = packet.read_id_values(@data[@discard_leading_bytes..-1])
+            if @telemetry
+              hash = System.telemetry.config.tlm_id_value_hash[target_name]
+            else
+              hash = System.commands.config.cmd_id_value_hash[target_name]
+            end
+            identified_packet = hash[key]
+            identified_packet = hash['CATCHALL'.freeze] unless identified_packet
+          end
+        end
+
+        if identified_packet
+          if identified_packet.defined_length + @discard_leading_bytes > @data.length
+            # Check if need more data to finish packet
+            return :STOP
+          end
+
+          # Set some variables so we can update the packet in
+          # read_packet
+          @received_time = Time.now.sys
+          @target_name = identified_packet.target_name
+          @packet_name = identified_packet.packet_name
+
+          # Get the data from this packet
+          packet_data = @data.slice!(0, identified_packet.defined_length + @discard_leading_bytes)
+          break
+        end
+      end
+
+      unless identified_packet
+        raise "Unknown data received by FixedProtocol" if @unknown_raise
+
+        # Unknown packet? Just return all the current data
+        @received_time = nil
+        @target_name = nil
+        @packet_name = nil
+        packet_data = @data.clone
+        @data.replace('')
+      end
+
+      return packet_data
+    end
+
+    def reduce_to_single_packet
+      return :STOP if @data.length < @min_id_size
+
+      identify_and_finish_packet()
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# 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/protocol'
+require 'openc3/utilities/crc'
+require 'thread'
+
+module OpenC3
+  # Ignore a specific packet by not letting it through the protocol
+  class IgnorePacketProtocol < Protocol
+    # @param target_name [String] Target name
+    # @param packet_name [String] Packet name
+    def initialize(target_name, packet_name, allow_empty_data = nil)
+      super(allow_empty_data)
+      System.telemetry.packet(target_name, packet_name)
+      @target_name = target_name
+      @packet_name = packet_name
+    end
+
+    def read_packet(packet)
+      # 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
+        if identified_packet.target_name == @target_name && identified_packet.packet_name == @packet_name
+          return :STOP
+        end
+      end
+      return super(packet)
+    end
+
+    def write_packet(packet)
+      return :STOP if packet.target_name == @target_name && packet.packet_name == @packet_name
+
+      return super(packet)
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+# 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/binary_accessor'
+require 'openc3/interfaces/protocols/burst_protocol'
+require 'openc3/config/config_parser'
+
+module OpenC3
+  # Protocol which delineates packets using a length field at a fixed
+  # location in each packet.
+  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
+    #   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 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
+    # @param allow_empty_data [true/false/nil] See Protocol#initialize
+    def initialize(
+      length_bit_offset = 0,
+      length_bit_size = 16,
+      length_value_offset = 0,
+      length_bytes_per_count = 1,
+      length_endianness = 'BIG_ENDIAN',
+      discard_leading_bytes = 0,
+      sync_pattern = nil,
+      max_length = nil,
+      fill_length_and_sync_pattern = false,
+      allow_empty_data = nil
+    )
+      super(discard_leading_bytes, sync_pattern, fill_length_and_sync_pattern, allow_empty_data)
+
+      # Save length field attributes
+      @length_bit_offset = Integer(length_bit_offset)
+      @length_bit_size = Integer(length_bit_size)
+      @length_value_offset = Integer(length_value_offset)
+      @length_bytes_per_count = Integer(length_bytes_per_count)
+
+      # Save endianness
+      if length_endianness.to_s.upcase == 'LITTLE_ENDIAN'
+        @length_endianness = :LITTLE_ENDIAN
+      else
+        @length_endianness = :BIG_ENDIAN
+      end
+
+      # Derive number of bytes required to contain entire length field
+      if @length_endianness == :BIG_ENDIAN or ((@length_bit_offset % 8) == 0)
+        length_bits_needed = @length_bit_offset + @length_bit_size
+        length_bits_needed += 8 if (length_bits_needed % 8) != 0
+        @length_bytes_needed = ((length_bits_needed - 1) / 8) + 1
+      else
+        @length_bytes_needed = (length_bit_offset / 8) + 1
+      end
+
+      # Save max length setting
+      @max_length = ConfigParser.handle_nil(max_length)
+      @max_length = Integer(@max_length) if @max_length
+    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
+      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
+      return :STOP if @data.length < @length_bytes_needed
+
+      # Determine the packet's length
+      length = BinaryAccessor.read(@length_bit_offset,
+                                   @length_bit_size,
+                                   :UINT,
+                                   @data,
+                                   @length_endianness)
+      raise "Length value received larger than max_length: #{length} > #{@max_length}" if @max_length and length > @max_length
+
+      packet_length = (length * @length_bytes_per_count) + @length_value_offset
+      # Ensure the calculated packet length is long enough to support the location of the length field
+      # without overlap into the next packet
+      if (packet_length * 8) < (@length_bit_offset + @length_bit_size)
+        raise "Calculated packet length of #{packet_length * 8} bits < (offset:#{@length_bit_offset} + size:#{@length_bit_size})"
+      end
+
+      # Make sure we have enough data for the packet
+      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])
+
+      return packet_data
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# 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/protocol'
+
+module OpenC3
+  # 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/nil] See Protocol#initialize
+    def initialize(allow_empty_data = nil)
+      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