esphome 1.0.0 → 1.1.1

data/lib/esphome/serial_proxy.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+# this file is often required in isolation
+require "esphome"
+require "timeout"
+require "uri"
+
+module ESPHome
+  class SerialProxy
+    class WaitReadable < RuntimeError
+      include ::IO::WaitReadable
+    end
+
+    attr_reader :device,
+                :name,
+                :instance,
+                :port_type,
+                :baud,
+                :data_bits,
+                :parity,
+                :stop_bits
+
+    class << self
+      def open(address, encryption_key = nil, instance = nil, **kwargs)
+        if address.is_a?(URI) && encryption_key.nil? && instance.nil?
+          encryption_key = address.password
+          instance = address.path[1..]
+          instance = nil if instance.empty?
+          address = address.host
+        end
+        raise ArgumentError, "missing encryption key" unless encryption_key
+
+        device = Device.new(address, encryption_key)
+        device.connect
+
+        instance ||= 0
+        io = device.serial_proxies[instance]
+        begin
+          io ||= device.serial_proxies[Integer(instance)]
+        rescue ArgumentError
+          # ignore; will raise below anyway
+        end
+
+        raise NoSuchSerialProxyError, "No serial proxy #{instance.inspect}" unless io
+
+        io.set_modem_params(**kwargs) unless kwargs.empty?
+        loop_thread = io.instance_variable_set(:@loop_thread, Thread.new do
+          Thread.current.report_on_exception = false
+          device.loop
+        rescue IOError
+          raise unless io.closed?
+        end)
+        io.open
+
+        if block_given?
+          begin
+            yield io
+          ensure
+            io.close
+            device.disconnect
+            loop_thread.join
+          end
+          nil
+        else
+          io
+        end
+      end
+    end
+
+    # @!visibility private
+    def initialize(device, name, instance, port_type)
+      @device = device
+      @name = name
+      @instance = instance
+      @port_type = port_type
+      @buffer = "".b
+      @mutex = Mutex.new
+      @data_ready = ConditionVariable.new
+      @request_mutex = Mutex.new
+      @closed = true
+      @baud = nil
+      @data_bits = nil
+      @parity = nil
+      @stop_bits = nil
+      @queue = Queue.new
+
+      @on_connect_callback = device.on_connect do
+        open unless closed?
+      end
+
+      @on_disconnect_callback = device.on_disconnect do
+        @queue << nil
+        @mutex.synchronize do
+          @data_ready.broadcast
+        end
+      end
+
+      @on_message_callback = device.on_message do |message|
+        case message
+        when Api::SerialProxyDataReceived
+          next unless message.instance == instance
+
+          @mutex.synchronize do
+            next if @closed
+
+            @buffer << message.data.b
+            @data_ready.broadcast
+          end
+        when Api::SerialProxyRequestResponse
+          next unless message.instance == instance
+
+          @queue << message
+        end
+      end
+    end
+
+    def set_modem_params(baud: nil, data_bits: nil, parity: nil, stop_bits: nil)
+      raise ArgumentError, "Parity must be :none, :even, or :odd" if !parity.nil? && !%i[none even odd].include?(parity)
+      raise MissingProxyError unless device
+
+      current_baud = nil
+      current_data_bits = nil
+      current_parity = nil
+      current_stop_bits = nil
+      @mutex.synchronize do
+        @baud = baud || @baud || 115_200
+        @data_bits = data_bits || @data_bits || 8
+        @parity = parity || @parity || :none
+        @stop_bits = stop_bits || @stop_bits || 1
+        current_baud = @baud
+        current_data_bits = @data_bits
+        current_parity = @parity
+        current_stop_bits = @stop_bits
+      end
+
+      return unless device.connected?
+
+      device.send(Api::SerialProxyConfigureRequest.new(instance:,
+                                                       baudrate: current_baud,
+                                                       flow_control: false,
+                                                       parity: normalize_serial_proxy_parity(current_parity),
+                                                       stop_bits: current_stop_bits,
+                                                       data_size: current_data_bits))
+    end
+
+    def open
+      raise MissingProxyError unless device
+
+      @request_mutex.synchronize do
+        @mutex.synchronize do
+          return self unless @closed
+
+          @closed = false
+          @data_ready.broadcast
+        end
+
+        return self unless device.connected?
+
+        device.send(Api::SerialProxyRequest.new(instance:,
+                                                type: :SERIAL_PROXY_REQUEST_TYPE_SUBSCRIBE))
+      end
+
+      self
+    rescue
+      @mutex.synchronize do
+        @closed = true
+        @data_ready.broadcast
+      end
+      raise
+    end
+
+    def close
+      loop_thread = @mutex.synchronize do
+        already_closed = @closed
+        @closed = true
+        @data_ready.broadcast
+        [already_closed, @loop_thread]
+      end
+
+      return if loop_thread.first
+
+      # We're in a SerialProxy.open block; just close the connection without unsubscribing
+      if loop_thread.last
+        device&.disconnect
+        loop_thread.last.join
+        @mutex.synchronize do
+          @loop_thread = nil
+        end
+        return
+      end
+      return unless device&.connected?
+
+      @request_mutex.synchronize do
+        return unless device&.connected?
+
+        device.send(Api::SerialProxyRequest.new(instance:,
+                                                type: :SERIAL_PROXY_REQUEST_TYPE_UNSUBSCRIBE))
+      end
+    end
+
+    def write(data)
+      raise EOFError, "closed stream" if closed?
+      raise MissingDeviceError unless device
+      raise EOFError, "serial proxy disconnected" unless device.connected?
+
+      encoded = String(data).b
+      device.send(Api::SerialProxyWriteRequest.new(instance:, data: encoded))
+      encoded.bytesize
+    end
+
+    def flush
+      raise EOFError, "closed stream" if closed?
+      raise MissingDeviceError unless device
+      raise EOFError, "serial proxy disconnected" unless device.connected?
+
+      @request_mutex.synchronize do
+        wait(:SERIAL_PROXY_REQUEST_TYPE_FLUSH) do
+          device.send(Api::SerialProxyRequest.new(instance:,
+                                                  type: :SERIAL_PROXY_REQUEST_TYPE_FLUSH))
+        end
+      end
+    end
+
+    def read(length, outbuf = +"")
+      readpartial(length, outbuf)
+      outbuf.concat(readpartial(length - outbuf.bytesize)) while outbuf.bytesize < length
+      outbuf
+    end
+
+    def readbyte
+      read(1)&.getbyte(0)
+    end
+    alias_method :getbyte, :readbyte
+
+    def readpartial(maxlen, outbuf = +"")
+      raise ArgumentError, "maxlen must be non-negative" unless maxlen >= 0
+
+      data = wait_for_data do
+        raise EOFError if @closed && @buffer.empty?
+        break +"".b if maxlen.zero?
+        break @buffer.slice!(0, maxlen) unless @buffer.empty?
+      end
+
+      apply_outbuf(outbuf, data)
+    end
+
+    def read_nonblock(maxlen, outbuf = +"", options = {})
+      raise ArgumentError, "maxlen must be non-negative" unless maxlen >= 0
+
+      if outbuf == ({ exception: false })
+        options = outbuf
+        outbuf = +""
+      end
+
+      return apply_outbuf(outbuf, +"".b) if maxlen.zero?
+
+      loop do
+        data = @mutex.synchronize do
+          raise EOFError if @closed && @buffer.empty?
+
+          @buffer.slice!(0, maxlen) unless @buffer.empty?
+        end
+        return apply_outbuf(outbuf, data) if data
+
+        result = wait_readable(0)
+        if result.nil?
+          raise WaitReadable unless options[:exception] == false
+
+          return :wait_readable
+        end
+
+        next
+      end
+    end
+
+    def wait_readable(timeout = nil)
+      return self unless @buffer.empty?
+
+      @mutex.synchronize do
+        return self unless @buffer.empty?
+
+        deadline = monotonic_time + timeout if timeout
+        Kernel.loop do
+          return nil if @closed || !device.connected?
+
+          remaining = deadline && (deadline - monotonic_time)
+          return nil if deadline && remaining <= 0
+
+          @data_ready.wait(@mutex, remaining)
+          return self unless @buffer.empty?
+        end
+      end
+    end
+
+    def ready?
+      !wait_readable(0).nil?
+    end
+
+    def ungetbyte(byte)
+      @mutex.synchronize do
+        @buffer.insert(0, Integer(byte).chr)
+        @data_ready.broadcast
+      end
+    end
+
+    def ungetc(char)
+      @mutex.synchronize do
+        @buffer.insert(0, String(char))
+        @data_ready.broadcast
+      end
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    private
+
+    def normalize_serial_proxy_parity(parity)
+      return parity if parity.to_s.start_with?("SERIAL_PROXY_PARITY_")
+
+      :"SERIAL_PROXY_PARITY_#{parity.to_s.upcase}"
+    end
+
+    def wait(request_type)
+      @queue.clear
+      yield
+      message = @queue.pop
+      raise EOFError unless message
+
+      unless message.type == request_type
+        raise UnexpectedMessage,
+              "Unexpected serial proxy response to request type #{message.type}"
+      end
+
+      case message.status
+      when :SERIAL_PROXY_STATUS_OK, :SERIAL_PROXY_STATUS_ASSUMED_SUCCESS
+        message.status
+      when :SERIAL_PROXY_STATUS_TIMEOUT
+        raise Timeout::Error
+      when :SERIAL_PROXY_STATUS_NOT_SUPPORTED
+        raise NotImplementedError
+      when :SERIAL_PROXY_STATUS_ERROR
+        raise SerialProxyError, message.error_message
+      else
+        raise SerialProxyError, "Unrecognized serial proxy status #{message.status.inspect}"
+      end
+    end
+
+    def apply_outbuf(outbuf, data)
+      return data unless outbuf
+
+      outbuf.replace(data)
+    end
+
+    def wait_for_data
+      @mutex.synchronize do
+        Kernel.loop do
+          raise EOFError if @closed
+
+          result = yield
+          return result unless result.nil?
+
+          @data_ready.wait(@mutex)
+        end
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/esphome/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ESPHome
+  VERSION = "1.1.1"
+end

data/lib/esphome.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "esphome/error"
+require_relative "esphome/device"
+require_relative "esphome/version"

data/lib/httpx/plugins/websocket.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "websocket/driver"
+require "websocket/driver/httpx"
+
+module HTTPX
+  module Plugins
+    module Websocket
+      class << self
+        def load_dependencies(klass)
+          klass.plugin(:upgrade)
+        end
+
+        def call(connection, request, response)
+          return unless (driver = request.driver)
+
+          return unless driver.send(:validate_handshake, response.headers)
+
+          connection.hijack_io
+          response.instance_variable_set(:@driver, driver)
+          driver.instance_variable_set(:@initial_response, response.body.to_s)
+        end
+
+        def extra_options(options)
+          options.merge(max_concurrent_requests: 1,
+                        upgrade_handlers: options.upgrade_handlers.merge("websocket" => self))
+        end
+      end
+
+      module ConnectionMethods
+        def send(request)
+          request.init_websocket(self) unless request.driver || @upgrade_protocol
+
+          super
+        end
+      end
+
+      module RequestMethods
+        attr_reader :driver
+
+        def init_websocket(connection)
+          if connection.state == :open
+            socket = connection.to_io
+            @driver = WebSocket::Driver::HTTPX.new(socket, @headers, { masking: true })
+          else
+            connection.once(:open) do
+              socket = connection.to_io
+              @driver = WebSocket::Driver::HTTPX.new(socket, @headers, { masking: true })
+            end
+          end
+        end
+      end
+
+      module ResponseMethods
+        attr_reader :driver
+      end
+    end
+
+    register_plugin(:websocket, Websocket)
+  end
+end

data/lib/websocket/driver/httpx.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module WebSocket
+  class Driver
+    # WebSocket driver with HTTPX handling the HTTP negotiation
+    class HTTPX < Hybi
+      def initialize(socket, headers, options = {})
+        super(socket, options)
+        @headers = headers
+        @closed = false
+
+        @key = Client.generate_key
+        @accept = Driver::Hybi.generate_accept(@key)
+
+        @headers["upgrade"]               = "websocket"
+        @headers["connection"]            = "Upgrade"
+        @headers["sec-websocket-key"]     = @key
+        @headers["sec-websocket-version"] = VERSION
+
+        @headers["Sec-WebSocket-Protocol"] = @protocols * ", " if @protocols.size.positive?
+
+        extensions = @extensions.generate_offer
+        @headers["Sec-WebSocket-Extensions"] = extensions if extensions
+      end
+
+      def start
+        open
+        parse(@initial_response)
+      end
+
+      def run
+        closed = false
+        on(:close) do
+          closed = true
+        end
+
+        until closed
+          bytes = @socket.read(1)
+          parse(bytes)
+        end
+      end
+
+      private
+
+      def fail_handshake(message) # rubocop:disable Naming/PredicateMethod
+        message = "Error during WebSocket handshake: #{message}"
+        @ready_state = 3
+        emit(:error, message)
+        emit(:close, Driver::CloseEvent.new(Driver::Hybi::ERRORS[:protocol_error], message))
+        false
+      end
+
+      def validate_handshake(headers)
+        accept     = headers["sec-websocket-accept"]
+        protocol   = headers["sec-websocket-protocol"]
+
+        return fail_handshake("Sec-WebSocket-Accept mismatch") unless accept == @accept
+
+        if protocol && !protocol.empty?
+          return fail_handshake("Sec-WebSocket-Protocol mismatch") unless @protocols.include?(protocol)
+
+          @protocol = protocol
+        end
+
+        begin
+          @extensions.activate(@headers["Sec-WebSocket-Extensions"])
+        rescue ::WebSocket::Extensions::ExtensionError => e
+          return fail_handshake(e.message)
+        end
+        true
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: esphome
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Cody Cutrer
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curses
@@ -97,10 +97,62 @@ email:
 - cody@cutrer.us
 executables:
 - esphome-monitor
+- esphome-serial-proxy
 extensions: []
 extra_rdoc_files: []
 files:
 - exe/esphome-monitor
+- exe/esphome-serial-proxy
+- lib/esphome.rb
+- lib/esphome/action.rb
+- lib/esphome/api.rb
+- lib/esphome/api/README.md
+- lib/esphome/api/api.proto
+- lib/esphome/api/api_options.proto
+- lib/esphome/api/api_options_pb.rb
+- lib/esphome/api/api_pb.rb
+- lib/esphome/cli/colors.rb
+- lib/esphome/cli/completion.rb
+- lib/esphome/cli/entities/button.rb
+- lib/esphome/cli/entities/climate.rb
+- lib/esphome/cli/entities/cover.rb
+- lib/esphome/cli/entities/date.rb
+- lib/esphome/cli/entities/date_time.rb
+- lib/esphome/cli/entities/form.rb
+- lib/esphome/cli/entities/lock.rb
+- lib/esphome/cli/entities/menu.rb
+- lib/esphome/cli/entities/number.rb
+- lib/esphome/cli/entities/select.rb
+- lib/esphome/cli/entities/subfields.rb
+- lib/esphome/cli/entities/switch.rb
+- lib/esphome/cli/entities/text.rb
+- lib/esphome/cli/entities/time.rb
+- lib/esphome/cli/entity.rb
+- lib/esphome/cli/monitor.rb
+- lib/esphome/dashboard.rb
+- lib/esphome/device.rb
+- lib/esphome/entities/binary_sensor.rb
+- lib/esphome/entities/button.rb
+- lib/esphome/entities/climate.rb
+- lib/esphome/entities/cover.rb
+- lib/esphome/entities/date.rb
+- lib/esphome/entities/date_time.rb
+- lib/esphome/entities/fan.rb
+- lib/esphome/entities/light.rb
+- lib/esphome/entities/lock.rb
+- lib/esphome/entities/number.rb
+- lib/esphome/entities/select.rb
+- lib/esphome/entities/sensor.rb
+- lib/esphome/entities/switch.rb
+- lib/esphome/entities/text.rb
+- lib/esphome/entities/text_sensor.rb
+- lib/esphome/entities/time.rb
+- lib/esphome/entity.rb
+- lib/esphome/error.rb
+- lib/esphome/serial_proxy.rb
+- lib/esphome/version.rb
+- lib/httpx/plugins/websocket.rb
+- lib/websocket/driver/httpx.rb
 homepage: https://github.com/ccutrer/esphome-ruby
 licenses:
 - MIT