somfy_sdn 2.4.0 → 2.5.0

data/lib/sdn/message/set.rb

@@ -2,9 +2,13 @@
 
 module SDN
   class Message
+    # Command that resets a motor's persisted settings.
     class SetFactoryDefault < Message
+      # (see Ack::MSG)
       MSG = 0x1f
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
+      # Mapping from symbolic reset scopes to SDN parameter values.
       RESET = { all_settings: 0x00,
                 group_addresses: 0x01,
                 limits: 0x11,
@@ -13,14 +17,25 @@ module SDN
                 ips: 0x15,
                 locks: 0x17 }.freeze
 
+      # @!attribute [rw] reset
+      #
+      # Requested reset scope.
+      #
+      # @return [:all_settings, :group_addresses, :limits, :rotation, :rolling_speed, :ips, :locks]
       attr_reader :reset
 
+      # Creates a factory reset command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param reset [:all_settings, :group_addresses, :limits, :rotation, :rolling_speed, :ips, :locks] reset scope
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, reset = :all_settings, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.reset = reset
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.reset = RESET.invert[to_number(params)]
@@ -35,18 +50,37 @@ module SDN
         @reset = value
       end
 
+      # (see Message#params)
       def params
         transform_param(RESET[reset])
       end
     end
 
+    # Command that assigns a motor to a group slot.
     class SetGroupAddr < Message
+      # (see Ack::MSG)
       MSG = 0x51
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
 
+      # @!attribute [rw] group_address
+      #
+      # @return [(Integer, Integer, Integer), nil]
       attr_accessor :group_address
+
+      # @!attribute [rw] group_index
+      #
+      # Group slot to assign the address to in the range 1..16.
+      #
+      # @return [Integer]
       attr_reader :group_index
 
+      # Creates a group assignment command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param group_index [Integer] group slot
+      # @param group_address [(Integer, Integer, Integer), nil] group address
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, group_index = 1, group_address = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -54,6 +88,7 @@ module SDN
         self.group_address = group_address
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.group_index = to_number(params[0]) + 1
@@ -66,28 +101,43 @@ module SDN
         @group_index = value
       end
 
+      # (see Message#params)
       def params
         transform_param(group_index - 1) + transform_param(group_address || [0, 0, 0])
       end
 
+      # (see Message#class_inspect)
       def class_inspect
         ", group_index=#{group_index.inspect}, group_address=#{group_address ? print_address(group_address) : "nil"}"
       end
     end
 
+    # Command that sets a motor's rotation direction.
     class SetMotorDirection < Message
+      # (see Ack::MSG)
       MSG = 0x12
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
+      # Mapping from symbolic directions to SDN parameter values.
       DIRECTION = { standard: 0x00, reversed: 0x01 }.freeze
 
+      # @!attribute [rw] direction
+      #
+      # @return [:standard, :reversed]
       attr_reader :direction
 
+      # Creates a motor direction command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param direction [:standard, :reversed] rotation direction
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, direction = :standard, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.direction = direction
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.direction = DIRECTION.invert[to_number(params[0])]
@@ -99,23 +149,52 @@ module SDN
         @direction = value
       end
 
+      # (see Message#params)
       def params
         transform_param(DIRECTION[direction])
       end
     end
 
+    # Command that stores, deletes, or distributes intermediate positions.
     class SetMotorIP < Message
+      # (see Ack::MSG)
       MSG = 0x15
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
       # for distribute, value is how many IPs to distribute over
+      # Mapping from symbolic write modes to SDN parameter values.
       TYPE = { delete: 0x00,
                current_position: 0x01,
                position_pulses: 0x02,
                position_percent: 0x03,
                distribute: 0x04 }.freeze
 
-      attr_reader :type, :ip, :value
-
+      # @!attribute [rw] type
+      #
+      # Requested intermediate-position write mode.
+      #
+      # @return [:delete, :current_position, :position_pulses, :position_percent, :distribute]
+      attr_reader :type
+
+      # @!attribute [rw] ip
+      #
+      # Requested intermediate-position slot in the range 1..16.
+      #
+      # @return [Integer, nil]
+      attr_reader :ip
+
+      # @!attribute [rw] value
+      #
+      # @return [Integer, nil]
+      attr_reader :value
+
+      # Creates an intermediate position write command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param type [Symbol] IP write mode
+      # @param ip [Integer, nil] IP slot
+      # @param value [Integer, nil] IP value
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, type = :delete, ip = nil, value = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -124,6 +203,7 @@ module SDN
         self.value = value
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.type = TYPE.invert[to_number(params[0])]
@@ -143,7 +223,7 @@ module SDN
       end
 
       def ip=(value)
-        raise ArgumentError, "ip must be in range 1..16 or nil" unless ip.nil? || (1..16).cover?(ip)
+        raise ArgumentError, "ip must be in range 1..16 or nil" unless value.nil? || (1..16).cover?(value)
 
         @ip = value
       end
@@ -152,19 +232,45 @@ module SDN
         @value = value&.& 0xffff
       end
 
+      # (see Message#params)
       def params
         transform_param(TYPE[type]) + transform_param(ip || 0) + from_number(value || 0, 2)
       end
     end
 
+    # Command that modifies a motor's travel limits.
     class SetMotorLimits < Message
+      # (see Ack::MSG)
       MSG = 0x11
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
+      # Mapping from symbolic limit write modes to SDN parameter values.
       TYPE = { delete: 0x00, current_position: 0x01, specified_position: 0x02, jog_ms: 0x04, jog_pulses: 0x05 }.freeze
+      # Mapping from symbolic limit targets to SDN parameter values.
       TARGET = { down: 0x00, up: 0x01 }.freeze
 
-      attr_reader :type, :target, :value
-
+      # @!attribute [rw] type
+      #
+      # @return [:delete, :current_position, :specified_position, :jog_ms, :jog_pulses]
+      attr_reader :type
+
+      # @!attribute [rw] target
+      #
+      # @return [:up, :down]
+      attr_reader :target
+
+      # @!attribute [rw] value
+      #
+      # @return [Integer, nil]
+      attr_reader :value
+
+      # Creates a limit write command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param type [:delete, :current_position, :specified_position, :jog_ms, :jog_pulses] limit write mode
+      # @param target [:up, :down] target limit
+      # @param value [Integer, nil]
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, type = :delete, target = :up, value = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -173,6 +279,7 @@ module SDN
         self.value = value
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.type = TYPE.invert[to_number(params[0])]
@@ -199,6 +306,7 @@ module SDN
         @value = value&.& 0xffff
       end
 
+      # (see Message#params)
       def params
         param = value || 0
         param /= 10 if target == :jog_ms
@@ -206,12 +314,35 @@ module SDN
       end
     end
 
+    # Command that updates a motor's rolling speeds.
     class SetMotorRollingSpeed < Message
+      # (see Ack::MSG)
       MSG = 0x13
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 3
 
-      attr_accessor :up_speed, :down_speed, :slow_speed
-
+      # @!attribute [rw] up_speed
+      #
+      # @return [Integer, nil]
+      attr_accessor :up_speed
+
+      # @!attribute [rw] down_speed
+      #
+      # @return [Integer, nil]
+      attr_accessor :down_speed
+
+      # @!attribute [rw] slow_speed
+      #
+      # @return [Integer, nil]
+      attr_accessor :slow_speed
+
+      # Creates a rolling-speed write command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param up_speed [Integer, nil] upward speed
+      # @param down_speed [Integer, nil] downward speed
+      # @param slow_speed [Integer, nil] slow speed
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, up_speed: nil, down_speed: nil, slow_speed: nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
@@ -220,6 +351,7 @@ module SDN
         self.slow_speed = slow_speed
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.up_speed = to_number(params[0])
@@ -227,42 +359,68 @@ module SDN
         self.slow_speed = to_number(params[2])
       end
 
+      # (see Message#params)
       def params
         transform_param(up_speed || 0xff) + transform_param(down_speed || 0xff) + transform_param(slow_speed || 0xff)
       end
     end
 
+    # Command that applies or clears the network lock state.
     class SetNetworkLock < Message
+      # (see Ack::MSG)
       MSG = 0x16
 
-      attr_accessor :locked, :priority
+      # @!attribute [rw] locked
+      #
+      # @return [true, false, nil]
+      attr_accessor :locked
+
+      # @!attribute [rw] priority
+      #
+      # @return [Integer, nil]
+      attr_accessor :priority
 
+      # (see Message#parse)
       def parse(params)
         self.locked = to_number(params[0]) == 1
         self.priority = to_number(params[1])
       end
 
+      # (see Message#params)
       def params
         transform_param(locked ? 1 : 0) + transform_param(priority)
       end
     end
 
+    # Command that writes a node's user-visible label.
     class SetNodeLabel < Message
+      # (see Ack::MSG)
       MSG = 0x55
+      # Maximum label length, in bytes
       MAX_LENGTH = 16
 
+      # @!attribute [rw] label
+      #
+      # @return [String]
       attr_accessor :label
 
+      # Creates a node label write command.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param label [String]
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, label = "", **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.label = label
       end
 
+      # (see Message#parse)
       def parse(params)
         self.label = to_string(params)
       end
 
+      # (see Message#params)
       def params
         from_string(label, self.class::MAX_LENGTH)
       end

data/lib/sdn/message.rb

@@ -3,10 +3,13 @@
 require "sdn/message/helpers"
 
 module SDN
+  # Raised when a parsed frame is structurally valid but its payload does not match the target message type.
   class MalformedMessage < RuntimeError; end
 
+  # Base type for all SDN protocol frames and message-specific serializers/parsers.
   class Message
     class << self
+      # @!visibility private
       def inherited(klass)
         super
         return Message.inherited(klass) unless self == Message
@@ -15,6 +18,11 @@ module SDN
         (@subclasses ||= []) << klass
       end
 
+      # Determines whether a received message satisfies the expected response for this request type.
+      #
+      # @param message [SDN::Message] received message candidate
+      #
+      # @return [true, false]
       def expected_response?(message)
         if /::Get([A-Za-z]+)/.match?(name)
           message.class.name == name.sub("::Get", "::Post") # rubocop:disable Style/ClassEqualityComparison
@@ -23,6 +31,11 @@ module SDN
         end
       end
 
+      # Attempts to parse the first valid SDN message from a byte stream.
+      #
+      # @param data [<Integer>] raw bytes buffered from the transport
+      #
+      # @return [(SDN::Message, Integer)] parsed message and consumed byte count
       def parse(data)
         offset = -1
         msg = length = ack_requested = message_class = nil
@@ -58,7 +71,7 @@ module SDN
         src = transform_param(data.slice(offset + 3, 3))
         dest = transform_param(data.slice(offset + 6, 3))
         begin
-          result = message_class.new(node_type: node_type, ack_requested: ack_requested, src: src, dest: dest)
+          result = message_class.new(node_type:, ack_requested:, src:, dest:)
           result.parse(data.slice(offset + 9, length - 11))
           result.msg = msg if message_class == UnknownMessage
         rescue ArgumentError => e
@@ -70,10 +83,13 @@ module SDN
 
       private
 
+      # Builds a lookup table from protocol opcode to message class.
+      #
+      # @return [{Integer => Class}]
       def message_map
         @message_map ||=
           @subclasses.each_with_object({}) do |klass, memo|
-            next memo unless klass.constants(false).include?(:MSG)
+            next memo unless klass.const_defined?(:MSG, false)
 
             memo[klass.const_get(:MSG, false)] = klass
           end
@@ -83,8 +99,32 @@ module SDN
     include Helpers
     singleton_class.include Helpers
 
-    attr_accessor :node_type, :ack_requested, :src, :dest
-
+    # Message sender node type.
+    #
+    # @return [Symbol, Integer]
+    attr_accessor :node_type
+
+    # Whether this message requests an acknowledgement.
+    #
+    # @return [true, false]
+    attr_accessor :ack_requested
+
+    # Source address for the message.
+    #
+    # @return [(Integer, Integer, Integer)]
+    attr_accessor :src
+
+    # Destination address for the message.
+    #
+    # @return [(Integer, Integer, Integer)]
+    attr_accessor :dest
+
+    # Builds a message envelope with optional addressing and acknowledgement behavior.
+    #
+    # @param node_type [Symbol, Integer, nil] originating node type
+    # @param ack_requested [true, false] whether the receiver should acknowledge the message
+    # @param src [(Integer, Integer, Integer), nil] source address bytes
+    # @param dest [(Integer, Integer, Integer), nil] destination address bytes
     def initialize(node_type: nil, ack_requested: false, src: nil, dest: nil)
       @node_type = node_type || 0
       @ack_requested = ack_requested
@@ -96,6 +136,13 @@ module SDN
       @dest = dest || [0, 0, 0]
     end
 
+    # Parses protocol-specific parameter bytes into this message instance.
+    #
+    # @param params [<Integer>] raw parameter bytes
+    #
+    # @return [void]
+    #
+    # @raise [SDN::MalformedMessage] when the parameter payload length is invalid
     def parse(params)
       return unless self.class.const_defined?(:PARAMS_LENGTH) && params.length != self.class.const_get(:PARAMS_LENGTH)
 
@@ -104,6 +151,9 @@ module SDN
                                                                              end}"
     end
 
+    # Serializes the message to a packed SDN frame.
+    #
+    # @return [String] binary protocol frame
     def serialize
       result = transform_param(node_type_to_number(node_type)) + transform_param(src) + transform_param(dest) + params
       length = result.length + 4
@@ -113,10 +163,12 @@ module SDN
       result.pack("C*")
     end
 
+    # @return [true, false]
     def ==(other)
       serialize == other.serialize
     end
 
+    # @return [String]
     def inspect
       format("#<%s @node_type=%s, @ack_requested=%s, @src=%s, @dest=%s%s>",
              self.class.name,
@@ -128,6 +180,11 @@ module SDN
     end
     alias_method :to_s, :inspect
 
+    private
+
+    # Returns the protocol-specific portion of the inspection string.
+    #
+    # @return [String, nil]
     def class_inspect
       ivars = instance_variables - %i[@node_type @ack_requested @src @dest @params]
       return if ivars.empty?
@@ -137,22 +194,43 @@ module SDN
 
     protected
 
+    # Returns the protocol-specific payload bytes for this message.
+    #
+    # @return [<Integer>]
     def params
       []
     end
 
+    # Base class for request messages with no protocol-specific parameters.
     class SimpleRequest < Message
+      # Number of protocol parameter bytes expected
       PARAMS_LENGTH = 0
 
+      # Creates a simple request whose only payload is the destination address.
+      #
+      # @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
     end
 
+    # Positive acknowledgement response for commands that requested one.
+    class Ack < SimpleRequest
+      # Protocol message number
+      MSG = 0x7f
+      # (see SimpleRequest::PARAMS_LENGTH)
+      PARAMS_LENGTH = 0
+    end
+
+    # Negative acknowledgement response emitted when a request cannot be fulfilled.
     class Nack < Message
+      # (see Ack::MSG)
       MSG = 0x6f
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
+      # Mapping from symbolic error names to SDN error codes.
       VALUES = { data_error: 0x01,
                  unknown_message: 0x10,
                  node_is_locked: 0x20,
@@ -165,38 +243,66 @@ module SDN
       # 37 not implemented? (get motor rolling speed)
       # 39 at limit? blocked?
 
-      # presumed
+      # Parsed NACK error code as a symbolic name or raw integer.
+      #
+      # @return [Symbol, Integer, nil]
       attr_accessor :error_code
 
+      # Creates a negative acknowledgement message.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param error_code [Symbol, Integer, nil] protocol error code
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, error_code = nil, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.error_code = error_code
       end
 
+      # Parses the negative acknowledgement error code.
+      #
+      # @param params [<Integer>] raw parameter bytes
       def parse(params)
         super
         error_code = to_number(params[0])
         self.error_code = VALUES.invert[error_code] || error_code
       end
-    end
 
-    class Ack < SimpleRequest
-      MSG = 0x7f
-      PARAMS_LENGTH = 0
+      # (see Message#params)
+      def params
+        transform_param(VALUES[error_code] || error_code)
+      end
     end
 
-    # messages after this point were decoded from UAI+ communication and may be named wrong
+    # Fallback wrapper for frames whose opcode is unknown to the library.
+    #
+    # Messages after this point were decoded from UAI+ communication and may be named wrong.
     class UnknownMessage < Message
-      attr_accessor :msg, :params
-
-      def initialize(params = [], **kwargs)
-        super(**kwargs)
+      # Unknown protocol opcode captured for this message.
+      #
+      # @return [Integer, nil]
+      attr_accessor :msg
+
+      # Raw undecoded parameter bytes for this message.
+      #
+      # @return [<Integer>, nil]
+      attr_accessor :params
+
+      # Creates a message wrapper for an unrecognized protocol opcode.
+      #
+      # @param params [<Integer>] raw unparsed parameter bytes
+      def initialize(params = [], **)
+        super(**)
         self.params = params
       end
 
       alias_method :parse, :params=
 
+      # Serializes an unknown message only when raw parameters are present.
+      #
+      # @return [String] binary protocol frame
+      #
+      # @raise [NotImplementedError] when parameters are unavailable
       def serialize
         # prevent serializing something we don't know
         raise NotImplementedError unless params
@@ -204,6 +310,7 @@ module SDN
         super
       end
 
+      # (see Message#class_inspect)
       def class_inspect
         result = if instance_of?(UnknownMessage)
                    format(", @msg=%02xh", msg)

data/lib/sdn/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module SDN
-  VERSION = "2.4.0"
+  # Gem version string.
+  VERSION = "2.5.0"
 end

data/lib/sdn.rb

@@ -5,18 +5,26 @@ require "logger"
 require "sdn/client"
 require "sdn/message"
 
+# Top-level Somfy SDN module
 module SDN
+  # Broadcast destination address used for discovery and network-wide requests.
   BROADCAST_ADDRESS = [0xff, 0xff, 0xff].freeze
 
   class << self
-    def logger=(logger)
-      logger.datetime_format = "%Y-%m-%d %H:%M:%S.%L"
-      logger.formatter = proc do |severity, datetime, _progname, msg|
-        "#{datetime.strftime(logger.datetime_format)} " \
+    # @!attribute [rw] logger
+    #
+    # Sets a logger for use by this gem. If a logger is not set, a default logger that
+    # outputs to stdout with INFO level will be used.
+    #
+    # @return [Logger]
+    def logger=(value)
+      value.datetime_format = "%Y-%m-%d %H:%M:%S.%L"
+      value.formatter = proc do |severity, datetime, _progname, msg|
+        "#{datetime.strftime(value.datetime_format)} " \
           "[#{Process.pid}/#{Thread.current.object_id}] " \
           "#{severity}: #{msg}\n"
       end
-      @logger = logger
+      @logger = value
     end
 
     def logger