somfy_sdn 2.4.0 → 2.5.0

data/lib/sdn/cli/provisioner.rb

@@ -4,9 +4,28 @@ require "curses"
 
 module SDN
   module CLI
+    # @!visibility private
     class Provisioner
-      attr_reader :win, :sdn, :addr, :ns
+      # @return [Curses::Window]
+      attr_reader :win
 
+      # @return [SDN::Client]
+      attr_reader :sdn
+
+      # Selected motor address as a three-byte array.
+      #
+      # @return [(Integer, Integer, Integer)]
+      attr_reader :addr
+
+      # Message namespace used for the current motor type (regular or ILT2).
+      #
+      # @return [Module]
+      attr_reader :ns
+
+      # Builds the interactive provisioning UI for a discovered motor.
+      #
+      # @param sdn [SDN::Client] SDN client connection
+      # @param addr [String, nil] optional motor address
       def initialize(sdn, addr = nil)
         @sdn = sdn
         @reversed = false
@@ -71,6 +90,11 @@ module SDN
         end
       end
 
+      private
+
+      # Runs the key-driven event loop.
+      #
+      # @return [void]
       def process
         win.keypad = true
         print_help
@@ -188,6 +212,9 @@ module SDN
         win.refresh
       end
 
+      # Polls the motor until movement stops, allowing escape to interrupt.
+      #
+      # @return [void]
       def wait_for_stop
         win.setpos(13, 0)
         win.addstr("Moving...\n")
@@ -224,6 +251,9 @@ module SDN
         end
       end
 
+      # Refreshes the displayed motor position, limits, and direction state.
+      #
+      # @return [void]
       def refresh
         pos = sdn.ensure(ns::GetMotorPosition.new(addr))
         @pos = pos.position_pulses
@@ -256,6 +286,9 @@ module SDN
         ns == Message::ILT2
       end
 
+      # Returns the reverse-direction flag as an integer for ILT2 settings writes.
+      #
+      # @return [Integer]
       def reversed_int
         @reversed ? 1 : 0
       end

data/lib/sdn/cli/simulator.rb

@@ -2,26 +2,63 @@
 
 module SDN
   module CLI
+    # @!visibility private
     class Simulator
+      # Simulated motor implementation that responds to a subset of SDN requests.
       class MockMotor
-        attr_accessor :address,
-                      :node_type,
-                      :label,
-                      :ips,
-                      :position_pulses,
-                      :up_limit,
-                      :down_limit,
-                      :groups,
-                      :network_lock_priority,
-                      :lock_priority,
-                      :ir_channels
+        # Simulated motor address.
+        #
+        # @return [(Integer, Integer, Integer)]
+        attr_accessor :address
 
+        # @return [:st30, :lt50]
+        attr_accessor :node_type
+
+        # @return [String]
+        attr_accessor :label
+
+        # Stored intermediate positions keyed by slot index.
+        #
+        # @return [<Integer, nil>]
+        attr_accessor :ips
+
+        # Current motor position in pulses from the upper limit.
+        #
+        # @return [Integer, nil]
+        attr_accessor :position_pulses
+
+        # @return [Integer, nil]
+        attr_accessor :up_limit
+
+        # @return [Integer, nil]
+        attr_accessor :down_limit
+
+        # Stored group memberships keyed by slot index.
+        #
+        # @return [<(Integer, Integer, Integer), nil>]
+        attr_accessor :groups
+
+        # @return [Integer, nil]
+        attr_accessor :network_lock_priority
+
+        # @return [Integer, nil]
+        attr_accessor :lock_priority
+
+        # Simulated ILT2 IR channel bitmask.
+        #
+        # @return [Integer]
+        attr_accessor :ir_channels
+
+        # Absolute move target types supported by the simulator implementation.
         ALLOWED_MOVE_TYPES = %i[up_limit
                                 down_limit
                                 ip
                                 position_pulses
                                 position_percent].freeze
 
+        # Creates a simulated motor backed by an SDN client.
+        #
+        # @param client [SDN::Client] SDN client used to receive and send messages
         def initialize(client)
           @client = client
           self.address = Message.parse_address("00.00.00")
@@ -33,6 +70,11 @@ module SDN
           self.lock_priority = 0
         end
 
+        private
+
+        # Starts processing incoming SDN messages for the simulated motor.
+        #
+        # @return [void]
         def process
           loop do
             @client.receive do |message|
@@ -191,20 +233,41 @@ module SDN
           end
         end
 
+        # Converts a pulse position to a percentage using the configured down limit.
+        #
+        # @param pulses [Integer, nil] position in pulses
+        #
+        # @return [Numeric, nil]
         def to_percent(pulses)
           (pulses && down_limit) ? 100.0 * pulses / down_limit : nil
         end
 
+        # Converts a percentage to a pulse position using the configured down limit.
+        #
+        # @param percent [Numeric, nil] position in percent
+        #
+        # @return [Numeric, nil]
         def to_pulses(percent)
           (percent && down_limit) ? down_limit * percent / 100 : nil
         end
 
+        # Sends an acknowledgement for the supplied message when one was requested.
+        #
+        # @param message [SDN::Message] request message
+        #
+        # @return [void]
         def ack(message)
           return unless message.ack_requested
 
           respond(Message::Ack.new(message.dest))
         end
 
+        # Sends a negative acknowledgement for the supplied message when one was requested.
+        #
+        # @param message [SDN::Message] request message
+        # @param _error_code [nil] reserved error code argument
+        #
+        # @return [void]
         def nack(message, _error_code = nil)
           return unless message.ack_requested
 
@@ -219,6 +282,10 @@ module SDN
         end
       end
 
+      # Starts a simulator instance for a single mock motor.
+      #
+      # @param sdn [SDN::Client] SDN client connection
+      # @param address [String, nil] optional simulated motor address
       def initialize(sdn, address = nil)
         motor = MockMotor.new(sdn)
         motor.address = Message.parse_address(address) if address

data/lib/sdn/cli.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SDN
+  # @!visibility private
+  module CLI; end
+end

data/lib/sdn/client.rb

@@ -3,15 +3,22 @@
 require "io/wait"
 
 module SDN
+  # Transport client for sending and receiving SDN frames over serial, TCP, RFC2217, or PTY.
   class Client
+    # Enables or disables raw byte tracing in the client logs.
+    #
+    # @return [true, false]
     attr_writer :trace
 
+    # Opens a connection to an SDN bus over serial, TCP, RFC2217, or PTY.
+    #
+    # @param port [String] connection target URI or serial device path
     def initialize(port)
       uri = URI.parse(port)
       @io = if uri.scheme == "tcp"
               require "socket"
               TCPSocket.new(uri.host, uri.port)
-            elsif uri.scheme == "telnet" || uri.scheme == "rfc2217"
+            elsif %w[telnet rfc2217].include?(uri.scheme)
               require "net/telnet/rfc2217"
               Net::Telnet::RFC2217.new(host: uri.host,
                                        port: uri.port || 23,
@@ -24,6 +31,10 @@ module SDN
               io, slave = PTY.open
               puts "Slave PTY available at #{slave.path}"
               io
+            elsif uri.scheme == "esphome"
+              gem "esphome", "~> 1.1"
+              require "esphome/serial_proxy"
+              ESPHome::SerialProxy.open(uri, baud: 4800, data_bits: 8, parity: :odd, stop_bits: 1)
             else
               require "ccutrer-serialport"
               CCutrer::SerialPort.new(port, baud: 4800, data_bits: 8, parity: :odd, stop_bits: 1)
@@ -31,21 +42,41 @@ module SDN
       @buffer = +""
     end
 
+    # Indicates whether raw byte tracing is enabled.
+    #
+    # @return [true, false]
     def trace?
       @trace
     end
 
+    # Serializes and writes a message to the underlying transport.
+    #
+    # @param message [SDN::Message]
+    #
+    # @return [void]
     def send(message)
       SDN.logger.debug("Sending #{message.inspect}")
       @io.write(message.serialize)
     end
 
+    # Sends a message with acknowledgement requested and waits for an initial response batch.
+    #
+    # @param message [SDN::Message]
+    #
+    # @return [<SDN::Message>] received response messages
     def transact(message)
       message.ack_requested = true
       send(message)
       receive(1)
     end
 
+    # Re-sends a request until an expected response is received.
+    #
+    # The expected response message is dependent on the message sent.
+    #
+    # @param message [SDN::Message]
+    #
+    # @return [SDN::Message] the message that is of the expected response type
     def ensure(message)
       loop do
         messages = transact(message)
@@ -56,15 +87,24 @@ module SDN
       end
     end
 
+    # Default inter-read wait time, in seconds, while assembling a partial frame.
     WAIT_TIME = 0.25
 
+    # Reads and parses messages from the transport until parsing is exhausted or a timeout occurs.
+    #
+    # @param timeout [Numeric, nil] optional read timeout in seconds
+    #
+    # @yield [message] yields each parsed message when a block is given
+    # @yieldparam message [SDN::Message] parsed message
+    #
+    # @return [<SDN::Message>] parsed messages when no block is given
     def receive(timeout = nil)
       messages = []
 
       loop do
         message, bytes_read = Message.parse(@buffer.bytes)
         # discard how much we read
-        @buffer = @buffer[bytes_read..-1] if bytes_read
+        @buffer = @buffer[bytes_read..] if bytes_read
         unless message
           break unless messages.empty?
 

data/lib/sdn/message/control.rb

@@ -2,13 +2,37 @@
 
 module SDN
   class Message
+    # Command that applies or clears a positional motor lock.
     class Lock < Message
+      # (see Ack::MSG)
       MSG = 0x06
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 5
+      # Mapping from symbolic lock targets to SDN parameter values.
       TARGET_TYPE = { current: 0, up_limit: 1, down_limit: 2, ip: 4, unlock: 5, position_percent: 7 }.freeze
 
-      attr_reader :target_type, :target, :priority
-
+      # @!attribute [rw] target_type
+      #
+      # @return [:current, :up_limit, :down_limit, :ip, :unlock, :position_percent]
+      attr_reader :target_type
+
+      # @!attribute [rw] target
+      #
+      # @return [Integer, nil]
+      attr_reader :target
+
+      # Requested lock priority.
+      #
+      # @return [Integer]
+      attr_reader :priority
+
+      # Creates a lock or unlock control message.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param target_type [:current, :up_limit, :down_limit, :ip, :unlock, :position_percent] lock target selector
+      # @param target [Integer, nil] lock target value
+      # @param priority [Integer] lock priority
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, target_type = :unlock, target = nil, priority = 1, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -34,6 +58,7 @@ module SDN
         @priority = value & 0xff
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.target_type = TARGET_TYPE.invert[to_number(params[0])]
@@ -42,21 +67,50 @@ module SDN
         self.priority = to_number(params[3])
       end
 
+      # (see Message#params)
       def params
         transform_param(TARGET_TYPE[target_type]) + from_number(target,
                                                                 2) + transform_param(priority) + transform_param(0)
       end
     end
 
-    # Move in momentary mode
+    # Command that moves a motor in momentary mode.
     class Move < Message
+      # (see Ack::MSG)
       MSG = 0x01
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 3
+      # Mapping from symbolic directions to SDN parameter values.
       DIRECTION = { down: 0x00, up: 0x01, cancel: 0x02 }.freeze
+      # Mapping from symbolic speed modes to SDN parameter values.
       SPEED = { up: 0x00, down: 0x01, slow: 0x02 }.freeze
 
-      attr_reader :direction, :duration, :speed
-
+      # @!attribute [rw] direction
+      #
+      # @return [:down, :up, :cancel]
+      attr_reader :direction
+
+      # @!attribute [rw] duration
+      #
+      # Requested movement duration in protocol units.
+      #
+      # @return [Integer, nil]
+      attr_reader :duration
+
+      # @!attribute [rw] speed
+      #
+      # Requested movement speed mode.
+      #
+      # @return [:up, :down, :slow]
+      attr_reader :speed
+
+      # Creates a momentary movement command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param direction [:down, :up, :cancel] movement direction
+      # @param duration [Integer, nil] duration in protocol units
+      # @param speed [:up, :down, :slow] speed selector
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, direction = :cancel, duration: nil, speed: :up, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -65,6 +119,7 @@ module SDN
         self.speed = speed
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.direction = DIRECTION.invert[to_number(params[0])]
@@ -98,6 +153,7 @@ module SDN
         @speed = speed
       end
 
+      # (see Message#params)
       def params
         transform_param(DIRECTION[direction]) +
           transform_param(duration || 0) +
@@ -105,10 +161,13 @@ module SDN
       end
     end
 
-    # Move relative to current position
+    # Command that moves a motor relative to its current position.
     class MoveOf < Message
+      # (see Ack::MSG)
       MSG = 0x04
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
+      # Mapping from symbolic relative targets to SDN parameter values.
       TARGET_TYPE = { next_ip: 0x00,
                       previous_ip: 0x01,
                       jog_down_pulses: 0x02,
@@ -116,8 +175,32 @@ module SDN
                       jog_down_ms: 0x04,
                       jog_up_ms: 0x05 }.freeze
 
-      attr_reader :target_type, :target
-
+      # @!attribute [rw] target_type
+      #
+      # Requested relative target selector.
+      #
+      # @return [:next_ip, :previous_ip, :jog_down_pulses, :jog_up_pulses, :jog_down_ms, :jog_up_ms, nil]
+      attr_reader :target_type
+
+      # @!attribute [rw] target
+      #
+      # Requested relative target amount in pulses or milliseconds.
+      #
+      # @return [Integer, nil]
+      attr_reader :target
+
+      # Creates a relative movement command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param target_type [:next_ip,
+      #   :previous_ip,
+      #   :jog_down_pulses,
+      #   :jog_up_pulses,
+      #   :jog_down_ms,
+      #   :jog_up_ms,
+      #   nil] relative target selector
+      # @param target [Integer, nil] pulses or milliseconds
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, target_type = nil, target = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -125,6 +208,7 @@ module SDN
         self.target = target
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.target_type = TARGET_TYPE.invert[to_number(params[0])]
@@ -147,6 +231,7 @@ module SDN
         @target = value
       end
 
+      # (see Message#params)
       def params
         param = target || 0xffff
         param /= 10 if %I[jog_down_ms jog_up_ms].include?(target_type)
@@ -154,15 +239,43 @@ module SDN
       end
     end
 
-    # Move to absolute position
+    # Command that moves a motor to an absolute target.
     class MoveTo < Message
+      # (see Ack::MSG)
       MSG = 0x03
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
+      # Mapping from symbolic absolute targets to SDN parameter values.
       TARGET_TYPE = { down_limit: 0x00, up_limit: 0x01, ip: 0x02, position_pulses: 0x03, position_percent: 0x04 }.freeze
+      # Mapping from symbolic speed modes to SDN parameter values.
       SPEED = { up: 0x00, down: 0x01, slow: 0x02 }.freeze
 
-      attr_reader :target_type, :target, :speed
-
+      # @!attribute [rw] target_type
+      #
+      # Requested absolute target selector.
+      #
+      # @return [:down_limit, :up_limit, :ip, :position_pulses, :position_percent]
+      attr_reader :target_type
+
+      # @!attribute [rw] target
+      #
+      # @return [Integer, nil]
+      attr_reader :target
+
+      # @!attribute [rw] speed
+      #
+      # Requested movement speed mode.
+      #
+      # @return [:up, :down, :slow]
+      attr_reader :speed
+
+      # Creates an absolute movement command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param target_type [:down_limit, :up_limit, :ip, :position_pulses, :position_percent] absolute target selector
+      # @param target [Integer, nil] target value
+      # @param speed [:up, :down, :slow] speed selector
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, target_type = :down_limit, target = nil, speed = :up, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -171,6 +284,7 @@ module SDN
         self.speed = speed
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.target_type = TARGET_TYPE.invert[to_number(params[0])]
@@ -198,27 +312,37 @@ module SDN
         @speed = value
       end
 
+      # (see Message#params)
       def params
         transform_param(TARGET_TYPE[target_type]) + from_number(target || 0xffff, 2) + transform_param(SPEED[speed])
       end
     end
 
-    # Stop movement
+    # Command that stops motor movement.
     class Stop < Message
+      # (see Ack::MSG)
       MSG = 0x02
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
 
+      # Creates a stop command for the specified destination.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
       end
 
+      # (see Message#params)
       def params
         transform_param(0)
       end
     end
 
+    # Command that triggers the motor's wink or identify behavior.
     class Wink < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x05
     end
   end