openc3 5.19.0 → 6.0.0

data/lib/openc3/interfaces/file_interface.rb

@@ -0,0 +1,198 @@
+# encoding: ascii-8bit
+
+# Copyright 2024 OpenC3, Inc.
+# 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.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+require 'openc3/interfaces/interface'
+require 'openc3/config/config_parser'
+require 'thread'
+require 'listen'
+require 'fileutils'
+
+module OpenC3
+  class FileInterface < Interface
+    # @param command_write_folder [String] Folder to write command files to - Set to nil to disallow writes
+    # @param telemetry_read_folder [String] Folder to read telemetry files from - Set to nil to disallow reads
+    # @param telemetry_archive_folder [String] Folder to move read telemetry files to - Set to DELETE to delete files
+    # @param file_read_size [Integer] Number of bytes to read from the file at a time
+    # @param stored [Boolean] Whether to set stored flag on read telemetry
+    # @param protocol_type [String] Name of the protocol to use
+    #   with this interface
+    # @param protocol_args [Array<String>] Arguments to pass to the protocol
+    def initialize(
+      command_write_folder,
+      telemetry_read_folder,
+      telemetry_archive_folder,
+      file_read_size = 65536,
+      stored = true,
+      protocol_type = nil,
+      *protocol_args
+    )
+      super()
+
+      @protocol_type = ConfigParser.handle_nil(protocol_type)
+      @protocol_args = protocol_args
+      if @protocol_type
+        protocol_class_name = protocol_type.to_s.capitalize << 'Protocol'
+        klass = OpenC3.require_class(protocol_class_name.class_name_to_filename)
+        add_protocol(klass, protocol_args, :PARAMS)
+      end
+
+      @command_write_folder = ConfigParser.handle_nil(command_write_folder)
+      @telemetry_read_folder = ConfigParser.handle_nil(telemetry_read_folder)
+      @telemetry_archive_folder = ConfigParser.handle_nil(telemetry_archive_folder)
+      @file_read_size = Integer(file_read_size)
+      @stored = ConfigParser.handle_true_false(stored)
+
+      @read_allowed = false unless @telemetry_read_folder
+      @write_allowed = false unless @command_write_folder
+      @write_raw_allowed = false unless @command_write_folder
+
+      @file = nil
+      @listener = nil
+      @connected = false
+      @extension = ".bin"
+      @label = "command"
+      @queue = Queue.new
+      @polling = false
+      @recursive = false
+    end
+
+    def connect
+      super()
+
+      if @telemetry_read_folder
+        @listener = Listen.to(@telemetry_read_folder, force_polling: @polling) do |modified, added, removed|
+          @queue << added if added
+        end
+        @listener.start # starts a listener thread--does not block
+      end
+
+      @connected = true
+    end
+
+    def connected?
+      return @connected
+    end
+
+    def disconnect
+      @file.close if @file and not @file.closed?
+      @file = nil
+      @listener.stop if @listener
+      @listener = nil
+      @queue << nil
+      super()
+      @connected = false
+    end
+
+    def read_interface
+      while true
+        if @file
+          # Read more data from existing file
+          data = @file.read(@file_read_size)
+          if data and data.length > 0
+            read_interface_base(data, nil)
+            return data, nil
+          else
+            finish_file()
+          end
+        end
+
+        # Find the next file to read
+        file = get_next_telemetry_file()
+        if file
+          @file = File.open(file, 'rb')
+          next
+        end
+
+        # Wait for a file to read
+        result = @queue.pop
+        return nil, nil unless result
+      end
+    end
+
+    def write_interface(data, extra = nil)
+      # Write this data into its own file
+      File.open(create_unique_filename(), 'wb') do |file|
+        file.write(data)
+      end
+
+      write_interface_base(data, extra)
+      return data, extra
+    end
+
+    def convert_data_to_packet(data, extra = nil)
+      packet = super(data, extra)
+      if packet and @stored
+        packet.stored = true
+      end
+      return packet
+    end
+
+    # Supported Options
+    # LABEL - Label to add to written files
+    # EXTENSION - Extension to add to written files
+    # (see Interface#set_option)
+    def set_option(option_name, option_values)
+      super(option_name, option_values)
+      case option_name.upcase
+      when 'LABEL'
+        @label = option_values[0]
+      when 'EXTENSION'
+        @extension = option_values[0]
+      when 'POLLING'
+        @polling = ConfigParser.handle_true_false(option_values[0])
+      when 'RECURSIVE'
+        @recursive = ConfigParser.handle_true_false(option_values[0])
+      end
+    end
+
+    def finish_file
+      path = @file.path
+      @file.close
+      @file = nil
+
+      # Archive (or DELETE) complete file
+      if @telemetry_archive_folder == "DELETE"
+        FileUtils.rm(path)
+      else
+        FileUtils.mv(path, @telemetry_archive_folder)
+      end
+    end
+
+    def get_next_telemetry_file
+      if @recursive
+        return Dir.glob("#{@telemetry_read_folder}/**/*").sort[0]
+      else
+        return Dir.glob("#{@telemetry_read_folder}/*").sort[0]
+      end
+    end
+
+    def create_unique_filename
+      # Create a filename that doesn't exist
+      attempt = nil
+      while true
+        filename = File.join(@command_write_folder, File.build_timestamped_filename([@label, attempt], @extension))
+        if File.exist?(filename)
+          attempt ||= 0
+          attempt += 1
+        else
+          return filename
+        end
+      end
+    end
+  end
+end

data/lib/openc3/interfaces/http_client_interface.rb

@@ -29,7 +29,8 @@ module OpenC3
     # @param hostname [String] HTTP/HTTPS server to connect to
     # @param port [Integer] HTTP/HTTPS port
     # @param protocol [String] http or https
-    def initialize(hostname, port = 80, protocol = 'http', write_timeout = 5, read_timeout = nil, connect_timeout = 5, include_request_in_response = false)
+    def initialize(hostname, port = 80, protocol = 'http', write_timeout = 5, read_timeout = nil,
+                   connect_timeout = 5, include_request_in_response = false)
       super()
       @hostname = hostname
       @port = Integer(port)
@@ -46,7 +47,6 @@ module OpenC3
       @connect_timeout = ConfigParser.handle_nil(connect_timeout)
       @connect_timeout = Float(@connect_timeout) if @connect_timeout
       @include_request_in_response = ConfigParser.handle_true_false(include_request_in_response)
-
       @response_queue = Queue.new
     end
 
@@ -72,6 +72,8 @@ module OpenC3
       super()
     end
 
+    # Whether the interface is connected to its target(s)
+    # But in this case it is basically whether connect was called
     def connected?
       if @http
         return true
@@ -84,25 +86,32 @@ module OpenC3
     def disconnect
       @http.close if @http
       @http = nil
+      # Clear the response queue
       while @response_queue.length > 0
         @response_queue.pop
       end
       super()
+      # Push nil to cause read_interface to return nil
       @response_queue.push(nil)
     end
 
-    # Reads from the socket if the read_port is defined
-    def read_interface
-      # Get the Faraday Response
-      data, extra = @response_queue.pop
-      return nil if data.nil?
-
-      read_interface_base(data, extra)
+    # Called to convert a packet into a data buffer. Write protocols then
+    # potentially modify the data in their write_data methods. Finally
+    # write_interface is called to send the data to the target.
+    #
+    # @param packet [Packet] Packet to extract data from
+    # @return data, extra
+    def convert_packet_to_data(packet)
+      extra = packet.extra
+      extra ||= {}
+      data = packet.buffer(true) # Copy buffer so logged command isn't modified
+      extra['HTTP_URI'] = URI("#{@url}#{packet.read('HTTP_PATH')}").to_s
+      # Store the target name for use in identifying the response
+      extra['HTTP_REQUEST_TARGET_NAME'] = packet.target_name
       return data, extra
     end
 
-    # Writes to the socket
-    # @param data [Hash] For the HTTP Interface, data is a hash with the needed request info
+    # Calls the appropriate HTTP method using Faraday
     def write_interface(data, extra = nil)
       extra ||= {}
       queries = extra['HTTP_QUERIES']
@@ -115,7 +124,10 @@ module OpenC3
       resp = nil
       case method
       when 'get'
-        resp = @http.get(uri, queries, headers)
+        resp = @http.get(uri) do |req|
+          req.params = queries
+          req.headers = headers
+        end
       when 'put'
         resp = @http.put(uri) do |req|
           req.params = queries
@@ -123,19 +135,27 @@ module OpenC3
           req.body = data
         end
       when 'delete'
-        resp = @http.delete(uri, queries, headers)
-      else # 'post'
+        resp = @http.delete(uri) do |req|
+          req.params = queries
+          req.headers = headers
+        end
+      when 'post'
         resp = @http.post(uri) do |req|
           req.params = queries
           req.headers = headers
           req.body = data
         end
+      else
+        raise "Unsupported HTTP Method: #{method}"
       end
 
       # Normalize Response into simple hash
       response_data = nil
       response_extra = {}
       if resp
+        # We store the request data and extra under HTTP_REQUEST
+        # This can optionally be returned in the response
+        # but is also used to identify the response target
         response_extra['HTTP_REQUEST'] = [data, extra]
         if resp.headers and resp.headers.length > 0
           response_extra['HTTP_HEADERS'] = resp.headers
@@ -151,20 +171,50 @@ module OpenC3
       return data, extra
     end
 
+    # Returns the response data and extra from the interface
+    # which was queued up by the write_interface method.
+    # Read protocols can then potentially modify the data in their read_data methods.
+    # Then convert_data_to_packet is called to convert the data into a Packet object.
+    # Finally the read protocols read_packet methods are called.
+    def read_interface
+      # This blocks until a response is available
+      data, extra = @response_queue.pop
+      return nil if data.nil?
+
+      read_interface_base(data, extra)
+      return data, extra
+    end
+
     # Called to convert the read data into a OpenC3 Packet object
     #
     # @param data [String] Raw packet data
+    # @param extra [Hash] Contains the following keys:
+    #   HTTP_HEADERS - Hash of response headers
+    #   HTTP_STATUS - Integer response status code
+    #   HTTP_REQUEST - [data, extra]
+    #     where data is the request data and extra contains:
+    #       HTTP_REQUEST_TARGET_NAME - String request target name
+    #       HTTP_URI - String request URI based on HTTP_PATH
+    #       HTTP_PATH - String request path
+    #       HTTP_METHOD - String request method
+    #       HTTP_PACKET - String response packet name
+    #       HTTP_ERROR_PACKET - Optional string error packet name
+    #       HTTP_QUERIES - Optional hash of request queries
+    #       HTTP_HEADERS - Optional hash of request headers
     # @return [Packet] OpenC3 Packet with buffer filled with data
     def convert_data_to_packet(data, extra = nil)
       packet = Packet.new(nil, nil, :BIG_ENDIAN, nil, data.to_s)
       packet.accessor = HttpAccessor.new(packet)
-      if extra
-        # Identify the response
-        request_target_name = extra['HTTP_REQUEST_TARGET_NAME']
+      # Grab the request extra set in the write_interface method
+      request_extra = extra['HTTP_REQUEST'][1] if extra and extra['HTTP_REQUEST']
+      if request_extra
+        # Identify the response target
+        request_target_name = request_extra['HTTP_REQUEST_TARGET_NAME']
         if request_target_name
           request_target_name = request_target_name.to_s.upcase
-          response_packet_name = extra['HTTP_PACKET']
-          error_packet_name = extra['HTTP_ERROR_PACKET']
+          response_packet_name = request_extra['HTTP_PACKET']
+          error_packet_name = request_extra['HTTP_ERROR_PACKET']
+          # HTTP_STATUS was set in the base extra
           status = extra['HTTP_STATUS'].to_i
           if status >= 300 and error_packet_name
             # Handle error special case response packet
@@ -177,30 +227,12 @@ module OpenC3
             end
           end
         end
-
-        if not @include_request_in_response
+        unless @include_request_in_response
           extra.delete("HTTP_REQUEST")
         end
-        extra.delete("HTTP_REQUEST_TARGET_NAME")
-        extra.delete("HTTP_REQUEST_PACKET_NAME")
-        packet.extra = extra
       end
-
+      packet.extra = extra
       return packet
     end
-
-    # Called to convert a packet into the data to send
-    #
-    # @param packet [Packet] Packet to extract data from
-    # @return data
-    def convert_packet_to_data(packet)
-      extra = packet.extra
-      extra ||= {}
-      data = packet.buffer(true) # Copy buffer so logged command isn't modified
-      extra['HTTP_URI'] = URI("#{@url}#{packet.read('HTTP_PATH')}").to_s
-      extra['HTTP_REQUEST_TARGET_NAME'] = packet.target_name
-      extra['HTTP_REQUEST_PACKET_NAME'] = packet.packet_name
-      return data, extra
-    end
   end
 end

data/lib/openc3/interfaces/http_server_interface.rb

@@ -37,8 +37,7 @@ module OpenC3
     # (see Interface#set_option)
     def set_option(option_name, option_values)
       super(option_name, option_values)
-      case option_name.upcase
-      when 'LISTEN_ADDRESS'
+      if option_name.upcase == 'LISTEN_ADDRESS'
         @listen_address = option_values[0]
       end
     end
@@ -150,7 +149,6 @@ module OpenC3
       @request_queue.push(nil)
     end
 
-    # Reads from the socket if the read_port is defined
     def read_interface
       # Get the Faraday Response
       data, extra = @request_queue.pop
@@ -160,8 +158,6 @@ module OpenC3
       return data, extra
     end
 
-    # Writes to the socket
-    # @param data [Hash] For the HTTP Interface, data is a hash with the needed request info
     def write_interface(_data, _extra = nil)
       raise "Commands cannot be sent to HttpServerInterface"
     end
@@ -189,10 +185,6 @@ module OpenC3
       return packet
     end
 
-    # Called to convert a packet into the data to send
-    #
-    # @param packet [Packet] Packet to extract data from
-    # @return data
     def convert_packet_to_data(_packet)
       raise "Commands cannot be sent to HttpServerInterface"
     end

data/lib/openc3/interfaces/interface.rb

@@ -499,6 +499,8 @@ module OpenC3
     def set_option(option_name, option_values)
       option_name_upcase = option_name.upcase
 
+      # PERIODIC_CMD is special because there could be more than 1 periodic command
+      # so we store them in an array for processing during connect()
       if option_name_upcase == 'PERIODIC_CMD'
         # OPTION PERIODIC_CMD LOG/DONT_LOG 1.0 "INST COLLECT with TYPE NORMAL"
         @options[option_name_upcase] ||= []
@@ -574,8 +576,7 @@ module OpenC3
     end
 
     def interface_cmd(cmd_name, *_cmd_args)
-      case cmd_name
-      when 'clear_counters'
+      if cmd_name == 'clear_counters'
         @write_queue_size = 0
         @read_queue_size = 0
         @bytes_written = 0

data/lib/openc3/interfaces/mqtt_interface.rb

@@ -18,6 +18,7 @@
 
 # You can quickly setup an unauthenticated MQTT server in Docker with
 # docker run -it -p 1883:1883 eclipse-mosquitto:2.0.15 mosquitto -c /mosquitto-no-auth.conf
+# You can also test against encrypted and authenticated servers at https://test.mosquitto.org/
 
 require 'openc3/interfaces/interface'
 require 'openc3/config/config_parser'
@@ -91,12 +92,13 @@ module OpenC3
   class MqttInterface < Interface
     # @param hostname [String] MQTT server to connect to
     # @param port [Integer] MQTT port
-    # @param ssl [Boolean] Use SSL true/false
+    # @param ssl [Boolean] Whether to use SSL
     def initialize(hostname, port = 1883, ssl = false)
       super()
       @hostname = hostname
       @port = Integer(port)
       @ssl = ConfigParser.handle_true_false(ssl)
+      @ack_timeout = 5.0
       @username = nil
       @password = nil
       @cert = nil
@@ -130,14 +132,21 @@ module OpenC3
       @write_topics = []
       @read_topics = []
       @client = MQTT::Client.new
+      @client.ack_timeout = @ack_timeout
       @client.host = @hostname
       @client.port = @port
-      @client.ssl = @ssl
       @client.username = @username if @username
       @client.password = @password if @password
-      @client.cert = @cert if @cert
-      @client.key = @key if @key
-      @client.ca_file = @ca_file.path if @ca_file
+      @client.ssl = @ssl
+      if @cert and @key
+        @client.ssl = true
+        @client.cert_file = @cert.path
+        @client.key_file = @key.path
+      end
+      if @ca_file
+        @client.ssl = true
+        @client.ca_file = @ca_file.path
+      end
       @client.connect
       @read_packets_by_topic.each do |topic, _|
         Logger.info "#{@name}: Subscribing to #{topic}"
@@ -146,9 +155,7 @@ module OpenC3
       super()
     end
 
-    # @return [Boolean] Whether the active ports (read and/or write) have
-    #   created sockets. Since UDP is connectionless, creation of the sockets
-    #   is used to determine connection.
+    # @return [Boolean] Whether the MQTT client is connected
     def connected?
       if @client
         return @client.connected?
@@ -159,8 +166,10 @@ module OpenC3
 
     # Disconnects the interface from its target(s)
     def disconnect
-      @client.disconnect
-      @client = nil
+      if @client
+        @client.disconnect
+        @client = nil
+      end
       super()
     end
 
@@ -188,12 +197,12 @@ module OpenC3
             super(packet)
           end
         else
-          raise "Command packet #{packet.target_name} #{packet.packet_name} requires a META TOPIC or TOPICS"
+          raise "Command packet '#{packet.target_name} #{packet.packet_name}' requires a META TOPIC or TOPICS"
         end
       end
     end
 
-    # Reads from the socket if the read_port is defined
+    # Reads from the client
     def read_interface
       topic, data = @client.get
       if data.nil? or data.length <= 0
@@ -209,7 +218,7 @@ module OpenC3
       return nil
     end
 
-    # Writes to the socket
+    # Writes to the client
     # @param data [String] Raw packet data
     def write_interface(data, extra = nil)
       write_interface_base(data, extra)
@@ -228,14 +237,22 @@ module OpenC3
     def set_option(option_name, option_values)
       super(option_name, option_values)
       case option_name.upcase
+      when 'ACK_TIMEOUT'
+        @ack_timeout = Float(option_values[0])
       when 'USERNAME'
         @username = option_values[0]
       when 'PASSWORD'
         @password = option_values[0]
       when 'CERT'
-        @cert = option_values[0]
+        # CERT must be given as a file
+        @cert = Tempfile.new('cert')
+        @cert.write(option_values[0])
+        @cert.close
       when 'KEY'
-        @key = option_values[0]
+        # KEY must be given as a file
+        @key = Tempfile.new('key')
+        @key.write(option_values[0])
+        @key.close
       when 'CA_FILE'
         # CA_FILE must be given as a file
         @ca_file = Tempfile.new('ca_file')

data/lib/openc3/interfaces/mqtt_stream_interface.rb

@@ -16,14 +16,20 @@
 # This file may also be used under the terms of a commercial license
 # if purchased from OpenC3, Inc.
 
+# You can quickly setup an unauthenticated MQTT server in Docker with
+# docker run -it -p 1883:1883 eclipse-mosquitto:2.0.15 mosquitto -c /mosquitto-no-auth.conf
+# You can also test against encrypted and authenticated servers at https://test.mosquitto.org/
+
 require 'openc3/interfaces/stream_interface'
 require 'openc3/streams/mqtt_stream'
+require 'openc3/config/config_parser'
 
 module OpenC3
   class MqttStreamInterface < StreamInterface
     # @param hostname [String] MQTT server to connect to
     # @param port [Integer] MQTT port
-    # @param ssl [Boolean] Use SSL true/false
+    # @param write_topic [String] MQTT publish topic
+    # @param read_topic [String] MQTT receive topic
     def initialize(hostname, port = 1883, ssl = false, write_topic = nil, read_topic = nil, protocol_type = nil, *protocol_args)
       super(protocol_type, protocol_args)
       @hostname = hostname
@@ -31,6 +37,7 @@ module OpenC3
       @ssl = ConfigParser.handle_true_false(ssl)
       @write_topic = ConfigParser.handle_nil(write_topic)
       @read_topic = ConfigParser.handle_nil(read_topic)
+      @ack_timeout = 5.0
       @username = nil
       @password = nil
       @cert = nil
@@ -47,7 +54,7 @@ module OpenC3
 
     # Creates a new {SerialStream} using the parameters passed in the constructor
     def connect
-      @stream = MqttStream.new(@hostname, @port, @ssl, @write_topic, @read_topic)
+      @stream = MqttStream.new(@hostname, @port, @ssl, @write_topic, @read_topic, @ack_timeout)
       @stream.username = @username if @username
       @stream.password = @password if @password
       @stream.cert = @cert if @cert
@@ -66,14 +73,22 @@ module OpenC3
     def set_option(option_name, option_values)
       super(option_name, option_values)
       case option_name.upcase
+      when 'ACK_TIMEOUT'
+        @ack_timeout = Float(option_values[0])
       when 'USERNAME'
         @username = option_values[0]
       when 'PASSWORD'
         @password = option_values[0]
       when 'CERT'
-        @cert = option_values[0]
+        # CERT must be given as a file
+        @cert = Tempfile.new('cert')
+        @cert.write(option_values[0])
+        @cert.close
       when 'KEY'
-        @key = option_values[0]
+        # KEY must be given as a file
+        @key = Tempfile.new('key')
+        @key.write(option_values[0])
+        @key.close
       when 'CA_FILE'
         # CA_FILE must be given as a file
         @ca_file = Tempfile.new('ca_file')

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

@@ -121,6 +121,13 @@ module OpenC3
 
       @bit_size = bit_size.to_i
       case @bit_size
+      when 8
+        @pack = (@endianness == :BIG_ENDIAN) ? 'n' : 'v'
+        if args.empty?
+          @crc = Crc8.new
+        else
+          @crc = Crc8.new(*args)
+        end
       when 16
         @pack = (@endianness == :BIG_ENDIAN) ? 'n' : 'v'
         if args.empty?

data/lib/openc3/interfaces/serial_interface.rb

@@ -98,6 +98,7 @@ module OpenC3
 
     # Supported Options
     # FLOW_CONTROL - Flow control method NONE or RTSCTS. Defaults to NONE
+    # DATA_BITS - Number of data bits 5, 6, 7, or 8. Defaults to 8
     def set_option(option_name, option_values)
       super(option_name, option_values)
       case option_name.upcase

data/lib/openc3/interfaces/tcpip_server_interface.rb

@@ -292,8 +292,7 @@ module OpenC3
     # (see Interface#set_option)
     def set_option(option_name, option_values)
       super(option_name, option_values)
-      case option_name.upcase
-      when 'LISTEN_ADDRESS'
+      if option_name.upcase == 'LISTEN_ADDRESS'
         @listen_address = option_values[0]
       end
     end