rtlsdr 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b12c3758778bb23282dd45b6fd7a7875ab966902921da11a01e20e091e695f3
-  data.tar.gz: 9d89756d0d0777d2f60e650809c38c5aad56a33e115e873e6557bb5586720b02
+  metadata.gz: 476e8a7b2e6fbc8f34a9522b3bcd203033fa8aa031c87ff9f6a8d65c447520c1
+  data.tar.gz: 97ccaa1da588545b2a3e4e739825757cde0364775b660a1bc644034c94bc4a7d
 SHA512:
-  metadata.gz: 57cfd89abe99c55d86e66e3fee3b0da12da94f6feceab7860be79871cd9611bf31ce3f9a2fb8235f1cb2f5ae06bb353df56c3bae3df5c2b4f3affc0267d3bce9
-  data.tar.gz: 1f9c2f119f049eaa84aff2c4afbef95854ebcd3a241441d0676a0f9220b064730b91ee6e95b7d6afbbcdfc40e673418de1f8a70ae1ffea041a65bde26b7c047c
+  metadata.gz: 2b8dd3cf3f66bce9c6d76dfb5d6fe83285bf5febcd4a84d673340dbd9d1402f87d30de4f352f514391a86707a468d3e191f33a7cd4e88c06a9cbe0bb7e4292de
+  data.tar.gz: d45d8464b357cadea1a6125aaa23e5ef710ce2ea45823a22af014b28d5541fe3162d42e4b66de7f4e7d70974bd7e894c3678dd0f4de3de49268e56195f2cfa11

data/.rubocop.yml

@@ -18,10 +18,22 @@ Metrics/ClassLength:
   Max: 500
 Metrics/MethodLength:
   Max: 20
+  Exclude:
+    - 'lib/rtlsdr/fftw.rb'
+    - 'lib/rtlsdr/demod.rb'
 Metrics/BlockLength:
   Max: 20
 Metrics/AbcSize:
   Max: 25
+  Exclude:
+    - 'lib/rtlsdr/fftw.rb'
+    - 'lib/rtlsdr/demod.rb'
+    - 'lib/rtlsdr/dsp.rb'
+    - 'lib/rtlsdr/dsp/filter.rb'
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/rtlsdr/demod.rb'
+    - 'lib/rtlsdr/dsp.rb'
 Metrics/PerceivedComplexity:
   Max: 20
 Metrics/CyclomaticComplexity:
@@ -32,3 +44,16 @@ Naming/MethodParameterName:
 
 RSpec/MultipleExpectations:
   Enabled: false
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MessageSpies:
+  Enabled: false
+RSpec/StubbedMock:
+  Enabled: false
+RSpec/MultipleDescribes:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+Style/ExponentialNotation:
+  Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-01-06
+
+### Added
+
+- `RTLSDR::TcpClient` - Connect to remote RTL-SDR devices via rtl_tcp
+- `RTLSDR.connect(host, port)` - Factory method for TCP connections
+- `RTLSDR::ConnectionError` - Exception for network connection failures
+- Full API compatibility between `Device` and `TcpClient`
+
+### Changed
+
+- Version bump to 0.3.0 (new feature)
+
 ## [0.1.13] - 2025-09-26
 
 ### Added

data/lib/rtlsdr/errors.rb

@@ -69,4 +69,12 @@ module RTLSDR
   #
   # @since 0.1.0
   class CallbackError < Error; end
+
+  # Raised when network connection fails
+  #
+  # This exception is thrown when connecting to an rtl_tcp server fails,
+  # or when the connection is lost during operation.
+  #
+  # @since 0.3.0
+  class ConnectionError < Error; end
 end

data/lib/rtlsdr/ffi.rb

@@ -144,7 +144,8 @@ module RTLSDR
     attach_function :rtlsdr_reset_buffer, [:rtlsdr_dev_t], :int
     attach_function :rtlsdr_read_sync, %i[rtlsdr_dev_t pointer int pointer], :int, blocking: true
     attach_function :rtlsdr_wait_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer], :int, blocking: true
-    attach_function :rtlsdr_read_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer uint32 uint32], :int, blocking: true
+    attach_function :rtlsdr_read_async, %i[rtlsdr_dev_t rtlsdr_read_async_cb_t pointer uint32 uint32], :int,
+                    blocking: true
     attach_function :rtlsdr_cancel_async, [:rtlsdr_dev_t], :int
 
     # Bias tee functions

data/lib/rtlsdr/tcp_client.rb

@@ -0,0 +1,629 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module RTLSDR
+  # TCP client for connecting to rtl_tcp servers
+  #
+  # TcpClient provides a network interface to RTL-SDR devices that are shared
+  # over the network using the rtl_tcp utility. It implements the same interface
+  # as RTLSDR::Device, allowing seamless switching between local and remote
+  # devices.
+  #
+  # rtl_tcp is a utility that makes RTL-SDR devices available over TCP/IP.
+  # Run it on a remote machine with: rtl_tcp -a 0.0.0.0
+  #
+  # @example Connect to remote device
+  #   device = RTLSDR.connect("192.168.1.100", 1234)
+  #   device.sample_rate = 2_048_000
+  #   device.center_freq = 100_000_000
+  #   device.gain = 400
+  #   samples = device.read_samples(1024)
+  #   device.close
+  #
+  # @example Using configure method
+  #   device = RTLSDR.connect("localhost")
+  #   device.configure(
+  #     frequency: 100_000_000,
+  #     sample_rate: 2_048_000,
+  #     gain: 400
+  #   )
+  #
+  # @since 0.3.0
+  class TcpClient
+    include Enumerable
+
+    # rtl_tcp command codes
+    CMD_SET_FREQUENCY       = 0x01
+    CMD_SET_SAMPLE_RATE     = 0x02
+    CMD_SET_GAIN_MODE       = 0x03
+    CMD_SET_GAIN            = 0x04
+    CMD_SET_FREQ_CORRECTION = 0x05
+    CMD_SET_IF_GAIN         = 0x06
+    CMD_SET_TEST_MODE       = 0x07
+    CMD_SET_AGC_MODE        = 0x08
+    CMD_SET_DIRECT_SAMPLING = 0x09
+    CMD_SET_OFFSET_TUNING   = 0x0a
+    CMD_SET_RTL_XTAL        = 0x0b
+    CMD_SET_TUNER_XTAL      = 0x0c
+    CMD_SET_GAIN_BY_INDEX   = 0x0d
+    CMD_SET_BIAS_TEE        = 0x0e
+
+    # Default rtl_tcp port
+    DEFAULT_PORT = 1234
+
+    # @return [String] Remote host address
+    attr_reader :host
+    # @return [Integer] Remote port number
+    attr_reader :port
+    # @return [Integer] Tuner type from server
+    attr_reader :tuner_type
+    # @return [Integer] Number of gain values supported
+    attr_reader :gain_count
+
+    # Create a new TCP client connection to an rtl_tcp server
+    #
+    # @param host [String] Hostname or IP address of rtl_tcp server
+    # @param port [Integer] Port number (default: 1234)
+    # @param timeout [Integer] Connection timeout in seconds (default: 10)
+    # @raise [ConnectionError] if connection fails
+    # @raise [ConnectionError] if server sends invalid header
+    def initialize(host, port = DEFAULT_PORT, timeout: 10)
+      @host = host
+      @port = port
+      @timeout = timeout
+      @socket = nil
+      @streaming = false
+      @mutex = Mutex.new
+
+      # Cached configuration values (rtl_tcp doesn't support reading back)
+      @center_freq = 0
+      @sample_rate = 0
+      @tuner_gain = 0
+      @freq_correction = 0
+      @direct_sampling = 0
+      @offset_tuning = false
+      @agc_mode = false
+      @test_mode = false
+      @gain_mode_manual = false
+
+      connect_to_server
+    end
+
+    # Check if connected to server
+    #
+    # @return [Boolean] true if connected
+    def open?
+      !@socket.nil? && !@socket.closed?
+    end
+
+    # Close the connection
+    #
+    # @return [void]
+    def close
+      return unless open?
+
+      @streaming = false
+      @socket.close
+      @socket = nil
+    end
+
+    # Check if connection is closed
+    #
+    # @return [Boolean] true if closed
+    def closed?
+      !open?
+    end
+
+    # Device information
+    def name
+      "rtl_tcp://#{@host}:#{@port}"
+    end
+
+    # Get USB device strings (not available via TCP)
+    #
+    # @return [Hash] Hash with placeholder values
+    def usb_strings
+      {
+        manufacturer: "rtl_tcp",
+        product: "Remote RTL-SDR",
+        serial: "#{@host}:#{@port}"
+      }
+    end
+
+    # Get human-readable tuner name
+    #
+    # @return [String] Tuner name based on type code
+    def tuner_name
+      case @tuner_type
+      when 1 then "Elonics E4000"
+      when 2 then "Fitipower FC0012"
+      when 3 then "Fitipower FC0013"
+      when 4 then "FCI FC2580"
+      when 5 then "Rafael Micro R820T"
+      when 6 then "Rafael Micro R828D"
+      else "Unknown"
+      end
+    end
+
+    # Frequency control
+
+    # Set center frequency
+    #
+    # @param freq [Integer] Frequency in Hz
+    def center_freq=(freq)
+      send_command(CMD_SET_FREQUENCY, freq)
+      @center_freq = freq
+    end
+
+    # Get center frequency
+    #
+    # @return [Integer] Last set frequency in Hz
+    attr_reader :center_freq
+
+    alias frequency center_freq
+    alias frequency= center_freq=
+
+    # Set frequency correction in PPM
+    #
+    # @param ppm [Integer] Frequency correction in parts per million
+    def freq_correction=(ppm)
+      send_command(CMD_SET_FREQ_CORRECTION, ppm)
+      @freq_correction = ppm
+    end
+
+    # Get frequency correction
+    #
+    # @return [Integer] Last set frequency correction in PPM
+    attr_reader :freq_correction
+
+    # Crystal oscillator frequencies (not fully supported via TCP)
+    def set_xtal_freq(rtl_freq, tuner_freq)
+      send_command(CMD_SET_RTL_XTAL, rtl_freq)
+      send_command(CMD_SET_TUNER_XTAL, tuner_freq)
+      [rtl_freq, tuner_freq]
+    end
+
+    # Get crystal frequencies (returns zeros - not readable via TCP)
+    #
+    # @return [Array<Integer>] Array of [0, 0]
+    def xtal_freq
+      [0, 0]
+    end
+
+    # Gain control
+
+    # Get available tuner gains (not queryable via TCP, returns common values)
+    #
+    # @return [Array<Integer>] Common R820T gain values in tenths of dB
+    def tuner_gains
+      # Return common R820T gains as a reasonable default
+      [0, 9, 14, 27, 37, 77, 87, 125, 144, 157, 166, 197, 207, 229, 254,
+       280, 297, 328, 338, 364, 372, 386, 402, 421, 434, 439, 445, 480, 496]
+    end
+
+    # Set tuner gain in tenths of dB
+    #
+    # @param gain [Integer] Gain in tenths of dB (e.g., 496 = 49.6 dB)
+    def tuner_gain=(gain)
+      send_command(CMD_SET_GAIN, gain)
+      @tuner_gain = gain
+    end
+
+    # Get current tuner gain
+    #
+    # @return [Integer] Last set gain in tenths of dB
+    attr_reader :tuner_gain
+
+    alias gain tuner_gain
+    alias gain= tuner_gain=
+
+    # Set gain mode (manual or automatic)
+    #
+    # @param manual [Boolean] true for manual, false for automatic
+    def tuner_gain_mode=(manual)
+      mode = manual ? 1 : 0
+      send_command(CMD_SET_GAIN_MODE, mode)
+      @gain_mode_manual = manual
+    end
+
+    # Enable manual gain mode
+    #
+    # @return [Boolean] true
+    def manual_gain_mode!
+      self.tuner_gain_mode = true
+    end
+
+    # Enable automatic gain mode
+    #
+    # @return [Boolean] false
+    def auto_gain_mode!
+      self.tuner_gain_mode = false
+    end
+
+    # Set IF gain for specific stage
+    #
+    # @param stage [Integer] IF stage number
+    # @param gain [Integer] Gain value in tenths of dB
+    # @return [Integer] The gain value that was set
+    def set_tuner_if_gain(stage, gain)
+      param = (stage << 16) | (gain & 0xFFFF)
+      send_command(CMD_SET_IF_GAIN, param)
+      gain
+    end
+
+    # Set tuner bandwidth (not supported via rtl_tcp)
+    #
+    # @param _bw [Integer] Bandwidth in Hz (ignored)
+    def tuner_bandwidth=(_bw)
+      # rtl_tcp doesn't support bandwidth command
+    end
+
+    # Sample rate control
+
+    # Set sample rate
+    #
+    # @param rate [Integer] Sample rate in Hz
+    def sample_rate=(rate)
+      send_command(CMD_SET_SAMPLE_RATE, rate)
+      @sample_rate = rate
+    end
+
+    # Get current sample rate
+    #
+    # @return [Integer] Last set sample rate in Hz
+    attr_reader :sample_rate
+
+    alias samp_rate sample_rate
+    alias samp_rate= sample_rate=
+
+    # Mode control
+
+    # Set test mode
+    #
+    # @param enabled [Boolean] true to enable test mode
+    def test_mode=(enabled)
+      mode = enabled ? 1 : 0
+      send_command(CMD_SET_TEST_MODE, mode)
+      @test_mode = enabled
+    end
+
+    # Enable test mode
+    #
+    # @return [Boolean] true
+    def test_mode!
+      self.test_mode = true
+    end
+
+    # Set AGC mode
+    #
+    # @param enabled [Boolean] true to enable AGC
+    def agc_mode=(enabled)
+      mode = enabled ? 1 : 0
+      send_command(CMD_SET_AGC_MODE, mode)
+      @agc_mode = enabled
+    end
+
+    # Enable AGC mode
+    #
+    # @return [Boolean] true
+    def agc_mode!
+      self.agc_mode = true
+    end
+
+    # Set direct sampling mode
+    #
+    # @param mode [Integer] Direct sampling mode (0=off, 1=I-ADC, 2=Q-ADC)
+    def direct_sampling=(mode)
+      send_command(CMD_SET_DIRECT_SAMPLING, mode)
+      @direct_sampling = mode
+    end
+
+    # Get direct sampling mode
+    #
+    # @return [Integer] Last set direct sampling mode
+    attr_reader :direct_sampling
+
+    # Set offset tuning mode
+    #
+    # @param enabled [Boolean] true to enable offset tuning
+    def offset_tuning=(enabled)
+      mode = enabled ? 1 : 0
+      send_command(CMD_SET_OFFSET_TUNING, mode)
+      @offset_tuning = enabled
+    end
+
+    # Get offset tuning mode
+    #
+    # @return [Boolean] Last set offset tuning state
+    attr_reader :offset_tuning
+
+    # Enable offset tuning
+    #
+    # @return [Boolean] true
+    def offset_tuning!
+      self.offset_tuning = true
+    end
+
+    # Bias tee control
+
+    # Set bias tee state
+    #
+    # @param enabled [Boolean] true to enable bias tee
+    def bias_tee=(enabled)
+      mode = enabled ? 1 : 0
+      send_command(CMD_SET_BIAS_TEE, mode)
+    end
+
+    # Enable bias tee
+    #
+    # @return [Boolean] true
+    def enable_bias_tee
+      self.bias_tee = true
+    end
+
+    # Disable bias tee
+    #
+    # @return [Boolean] false
+    def disable_bias_tee
+      self.bias_tee = false
+    end
+
+    # Enable bias tee (alias)
+    #
+    # @return [Boolean] true
+    def bias_tee!
+      enable_bias_tee
+    end
+
+    # Bias tee GPIO not supported via TCP
+    def set_bias_tee_gpio(_gpio, enabled)
+      self.bias_tee = enabled
+    end
+
+    # EEPROM not accessible via TCP
+
+    # Read EEPROM (not supported via TCP)
+    #
+    # @raise [OperationFailedError] always
+    def read_eeprom(_offset, _length)
+      raise OperationFailedError, "EEPROM access not supported via TCP"
+    end
+
+    # Write EEPROM (not supported via TCP)
+    #
+    # @raise [OperationFailedError] always
+    def write_eeprom(_data, _offset)
+      raise OperationFailedError, "EEPROM access not supported via TCP"
+    end
+
+    # Dump EEPROM (not supported via TCP)
+    #
+    # @raise [OperationFailedError] always
+    def dump_eeprom
+      raise OperationFailedError, "EEPROM access not supported via TCP"
+    end
+
+    # Buffer reset (no-op for TCP)
+    def reset_buffer
+      # rtl_tcp doesn't have a reset buffer command
+      # Data is continuously streamed
+    end
+
+    # Read raw IQ data synchronously
+    #
+    # @param length [Integer] Number of bytes to read
+    # @return [Array<Integer>] Array of 8-bit unsigned integers
+    # @raise [ConnectionError] if read fails
+    def read_sync(length)
+      raise ConnectionError, "Not connected" unless open?
+
+      data = +""
+      remaining = length
+
+      while remaining.positive?
+        chunk = @socket.read(remaining)
+        raise ConnectionError, "Connection closed by server" if chunk.nil? || chunk.empty?
+
+        data << chunk
+        remaining -= chunk.bytesize
+      end
+
+      data.unpack("C*")
+    end
+
+    # Read complex samples synchronously
+    #
+    # @param count [Integer] Number of complex samples to read
+    # @return [Array<Complex>] Array of complex samples
+    def read_samples(count = 1024)
+      # RTL-SDR outputs 8-bit I/Q samples, so we need 2 bytes per complex sample
+      data = read_sync(count * 2)
+
+      # Convert to complex numbers (I + jQ)
+      samples = []
+      (0...data.length).step(2) do |i|
+        i_sample = (data[i] - 128) / 128.0
+        q_sample = (data[i + 1] - 128) / 128.0
+        samples << Complex(i_sample, q_sample)
+      end
+
+      samples
+    end
+
+    # Check if streaming
+    #
+    # @return [Boolean] true if streaming
+    def streaming?
+      @streaming
+    end
+
+    # Read raw IQ data asynchronously
+    #
+    # @param buffer_count [Integer] Ignored for TCP
+    # @param buffer_length [Integer] Buffer size in bytes
+    # @yield [Array<Integer>] Block called with each buffer
+    # @return [Thread] Background reading thread
+    def read_async(buffer_count: 15, buffer_length: 262_144, &block)
+      raise ArgumentError, "Block required for async reading" unless block_given?
+      raise OperationFailedError, "Already streaming" if streaming?
+
+      _ = buffer_count # unused for TCP
+      @streaming = true
+
+      Thread.new do
+        while @streaming && open?
+          begin
+            data = read_sync(buffer_length)
+            block.call(data)
+          rescue ConnectionError => e
+            @streaming = false
+            raise e unless e.message.include?("closed")
+          rescue StandardError => e
+            puts "Error in async callback: #{e.message}"
+            @streaming = false
+          end
+        end
+      end
+    end
+
+    # Read complex samples asynchronously
+    #
+    # @param buffer_count [Integer] Ignored for TCP
+    # @param buffer_length [Integer] Buffer size in bytes
+    # @yield [Array<Complex>] Block called with complex samples
+    # @return [Thread] Background reading thread
+    def read_samples_async(buffer_count: 15, buffer_length: 262_144, &block)
+      raise ArgumentError, "Block required for async reading" unless block_given?
+
+      read_async(buffer_count: buffer_count, buffer_length: buffer_length) do |data|
+        samples = []
+        (0...data.length).step(2) do |i|
+          i_sample = (data[i] - 128) / 128.0
+          q_sample = (data[i + 1] - 128) / 128.0
+          samples << Complex(i_sample, q_sample)
+        end
+
+        block.call(samples)
+      end
+    end
+
+    # Cancel asynchronous reading
+    #
+    # @return [void]
+    def cancel_async
+      @streaming = false
+    end
+
+    # Enumerable interface
+    def each(samples_per_read: 1024)
+      return enum_for(:each, samples_per_read: samples_per_read) unless block_given?
+
+      loop do
+        samples = read_samples(samples_per_read)
+        yield samples
+      rescue StandardError => e
+        break if e.is_a?(Interrupt) || e.is_a?(ConnectionError)
+
+        raise
+      end
+    end
+
+    # Configuration shortcut
+    def configure(frequency: nil, sample_rate: nil, gain: nil, **options)
+      self.center_freq = frequency if frequency
+      self.sample_rate = sample_rate if sample_rate
+
+      if gain
+        manual_gain_mode!
+        self.tuner_gain = gain
+      end
+
+      options.each do |key, value|
+        case key
+        when :freq_correction then self.freq_correction = value
+        when :agc_mode then self.agc_mode = value
+        when :test_mode then self.test_mode = value
+        when :bias_tee then self.bias_tee = value
+        when :direct_sampling then self.direct_sampling = value
+        when :offset_tuning then self.offset_tuning = value
+        end
+      end
+
+      self
+    end
+
+    # Device info as hash
+    def info
+      {
+        host: @host,
+        port: @port,
+        name: name,
+        usb_strings: usb_strings,
+        tuner_type: @tuner_type,
+        tuner_name: tuner_name,
+        center_freq: center_freq,
+        sample_rate: sample_rate,
+        tuner_gain: tuner_gain,
+        tuner_gains: tuner_gains,
+        freq_correction: freq_correction,
+        direct_sampling: direct_sampling,
+        offset_tuning: offset_tuning
+      }
+    end
+
+    # String representation
+    def inspect
+      if open?
+        "#<RTLSDR::TcpClient:#{object_id.to_s(16)} #{name} tuner=\"#{tuner_name}\" " \
+          "freq=#{center_freq}Hz rate=#{sample_rate}Hz>"
+      else
+        "#<RTLSDR::TcpClient:#{object_id.to_s(16)} #{name} closed>"
+      end
+    end
+
+    private
+
+    # Connect to rtl_tcp server and read header
+    #
+    # @raise [ConnectionError] if connection or header validation fails
+    def connect_to_server
+      @socket = Socket.tcp(@host, @port, connect_timeout: @timeout)
+      @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+
+      # Read 12-byte header: "RTL0" + tuner_type(4) + gain_count(4)
+      header = @socket.read(12)
+      raise ConnectionError, "Failed to read header from rtl_tcp server" if header.nil? || header.length < 12
+
+      magic = header[0, 4]
+      raise ConnectionError, "Invalid rtl_tcp header magic: expected 'RTL0', got '#{magic}'" unless magic == "RTL0"
+
+      @tuner_type = header[4, 4].unpack1("N")
+      @gain_count = header[8, 4].unpack1("N")
+    rescue Errno::ECONNREFUSED
+      raise ConnectionError, "Connection refused to #{@host}:#{@port} - is rtl_tcp running?"
+    rescue Errno::ETIMEDOUT, Errno::EHOSTUNREACH => e
+      raise ConnectionError, "Cannot reach #{@host}:#{@port}: #{e.message}"
+    rescue SocketError => e
+      raise ConnectionError, "Socket error connecting to #{@host}:#{@port}: #{e.message}"
+    end
+
+    # Send a command to the rtl_tcp server
+    #
+    # @param cmd [Integer] Command code
+    # @param param [Integer] Command parameter
+    # @raise [ConnectionError] if send fails
+    def send_command(cmd, param)
+      raise ConnectionError, "Not connected" unless open?
+
+      # Command is 5 bytes: 1 byte command + 4 bytes big-endian parameter
+      packet = [cmd, param].pack("CN")
+      @mutex.synchronize do
+        @socket.write(packet)
+      end
+    rescue Errno::EPIPE, Errno::ECONNRESET => e
+      @socket = nil
+      raise ConnectionError, "Connection lost: #{e.message}"
+    end
+  end
+end

data/lib/rtlsdr/version.rb

@@ -12,5 +12,5 @@ module RTLSDR
   #
   # @return [String] Current gem version
   # @since 0.1.0
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/rtlsdr.rb

@@ -4,6 +4,7 @@ require_relative "rtlsdr/version"
 require_relative "rtlsdr/ffi"
 require_relative "rtlsdr/fftw"
 require_relative "rtlsdr/device"
+require_relative "rtlsdr/tcp_client"
 require_relative "rtlsdr/errors"
 require_relative "rtlsdr/dsp"
 require_relative "rtlsdr/dsp/filter"
@@ -25,7 +26,7 @@ require_relative "rtlsdr/scanner"
 # * Frequency scanning and spectrum analysis
 # * EEPROM reading/writing and bias tee control
 #
-# @example Basic usage
+# @example Basic usage with local device
 #   device = RTLSDR.open(0)
 #   device.sample_rate = 2_048_000
 #   device.center_freq = 100_000_000
@@ -33,6 +34,13 @@ require_relative "rtlsdr/scanner"
 #   samples = device.read_samples(1024)
 #   device.close
 #
+# @example Connect to remote rtl_tcp server
+#   device = RTLSDR.connect("192.168.1.100", 1234)
+#   device.sample_rate = 2_048_000
+#   device.center_freq = 100_000_000
+#   samples = device.read_samples(1024)
+#   device.close
+#
 # @example List all devices
 #   RTLSDR.devices.each do |dev|
 #     puts "#{dev[:index]}: #{dev[:name]}"
@@ -119,6 +127,27 @@ module RTLSDR
       Device.new(index)
     end
 
+    # Connect to a remote rtl_tcp server
+    #
+    # Creates and returns a TcpClient instance connected to the specified
+    # rtl_tcp server. The client implements the same interface as Device,
+    # allowing seamless switching between local and remote devices.
+    #
+    # @param [String] host Hostname or IP address of rtl_tcp server
+    # @param [Integer] port Port number (default: 1234)
+    # @param [Integer] timeout Connection timeout in seconds (default: 10)
+    # @return [RTLSDR::TcpClient] TcpClient instance
+    # @raise [ConnectionError] if connection fails
+    # @example Connect to remote device
+    #   device = RTLSDR.connect("192.168.1.100")
+    #   device.center_freq = 100_000_000
+    # @example Connect with custom port
+    #   device = RTLSDR.connect("192.168.1.100", 5555)
+    # @since 0.3.0
+    def connect(host, port = TcpClient::DEFAULT_PORT, timeout: 10)
+      TcpClient.new(host, port, timeout: timeout)
+    end
+
     # List all available devices with their information
     #
     # Returns an array of hashes containing information about all connected

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rtlsdr
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - joshfng
@@ -57,6 +57,7 @@ files:
 - lib/rtlsdr/ffi.rb
 - lib/rtlsdr/fftw.rb
 - lib/rtlsdr/scanner.rb
+- lib/rtlsdr/tcp_client.rb
 - lib/rtlsdr/version.rb
 homepage: https://github.com/joshfng/rtlsdr
 licenses: