somfy_sdn 2.4.0 → 2.5.0

data/lib/sdn/message/ilt2/set.rb

@@ -3,18 +3,29 @@
 module SDN
   class Message
     module ILT2
+      # Command that writes the ILT2 IR channel bitmask.
       class SetIRConfig < PostIRConfig
+        # (see Ack::MSG)
         MSG = 0x59
 
+        # Creates an ILT2 IR configuration write command.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param channels [Integer, nil] IR channel bitmask
+        # @param kwargs [Hash] additional message options
         def initialize(dest = nil, channels = nil, **kwargs)
           kwargs[:dest] ||= dest
           super(channels, **kwargs)
         end
       end
 
+      # Command that applies or clears an ILT2 lock target.
       class SetLockStatus < Message
+        # (see Ack::MSG)
         MSG = 0x5B
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
+        # Mapping from symbolic lock targets to SDN parameter values.
         TARGET_TYPE = {
           current: 0,
           up_limit: 1,
@@ -23,9 +34,27 @@ module SDN
           unlock: 5
         }.freeze
 
+        # @!attribute [rw] target_type
+        #
         # when target_type is down_limit, target is number of 10ms intervals it's still allowed to roll up
-        attr_reader :target_type, :target, :priority
-
+        # Requested ILT2 lock target selector.
+        #
+        # @return [:current, :up_limit, :down_limit, :ip, :unlock]
+        attr_reader :target_type
+
+        # @return [Integer, nil]
+        attr_reader :target
+
+        # @return [Integer]
+        attr_reader :priority
+
+        # Creates an ILT2 lock status write command.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param target_type [Symbol] lock target selector
+        # @param target [Integer, nil] 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 +63,7 @@ module SDN
           self.priority = priority
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.target_type = TARGET_TYPE.invert[to_number(params[0])]
@@ -60,17 +90,35 @@ module SDN
           @priority = value
         end
 
+        # (see Message#params)
         def params
           transform_param(TARGET_TYPE[target_type]) + transform_param(target) + transform_param(priority)
         end
       end
 
+      # Command that writes an ILT2 intermediate position slot.
       class SetMotorIP < Message
+        # (see Ack::MSG)
         MSG = 0x53
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
 
-        attr_reader :ip, :value
-
+        # @!attribute [rw] ip
+        #
+        # Requested ILT2 intermediate position slot in the range 1..16.
+        #
+        # @return [Integer, nil]
+        attr_reader :ip
+
+        # @return [Integer, nil]
+        attr_reader :value
+
+        # Creates an ILT2 intermediate position write command.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param ip [Integer] intermediate position slot
+        # @param value [Integer, nil] stored value
+        # @param kwargs [Hash] additional message options
         def initialize(dest = nil, ip = 1, value = nil, **kwargs)
           kwargs[:dest] ||= dest
           super(**kwargs)
@@ -78,6 +126,7 @@ module SDN
           self.value = value
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.ip = to_number(params[0]) + 1
@@ -94,18 +143,25 @@ module SDN
           @value = value&.& 0xffff
         end
 
+        # (see Message#params)
         def params
           transform_param(ip - 1) + from_number(value, 2)
         end
       end
 
+      # ILT2 motor-limit command whose payload is not yet decoded.
       class SetMotorLimits < UnknownMessage
+        # (see Ack::MSG)
         MSG = 0x5C
       end
 
+      # Command that moves an ILT2 motor to a specific target.
       class SetMotorPosition < Message
+        # (see Ack::MSG)
         MSG = 0x54
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
+        # Mapping from symbolic ILT2 move targets to SDN parameter values.
         TARGET_TYPE = {
           up_limit: 1,
           down_limit: 2,
@@ -121,8 +177,35 @@ module SDN
           position_percent: 16
         }.freeze
 
-        attr_reader :target_type, :target
-
+        # @!attribute [rw] target_type
+        #
+        # Requested ILT2 movement target selector.
+        #
+        # @return [:up_limit,
+        #   :down_limit,
+        #   :stop,
+        #   :ip,
+        #   :next_ip_up,
+        #   :next_ip_down,
+        #   :position_pulses,
+        #   :jog_up_ms,
+        #   :jog_down_ms,
+        #   :jog_up_pulses,
+        #   :jog_down_pulses,
+        #   :position_percent]
+        attr_reader :target_type
+
+        # @!attribute [rw] target
+        #
+        # @return [Integer, Numeric, nil]
+        attr_reader :target
+
+        # Creates an ILT2 motor positioning command.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param target_type [Symbol] target selector
+        # @param target [Integer, Numeric] target value
+        # @param kwargs [Hash] additional message options
         def initialize(dest = nil, target_type = :up_limit, target = 0, **kwargs)
           kwargs[:dest] ||= dest
           super(**kwargs)
@@ -130,6 +213,7 @@ module SDN
           self.target = target
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.target_type = TARGET_TYPE.invert[to_number(params[0])]
@@ -157,6 +241,7 @@ module SDN
                     end
         end
 
+        # (see Message#params)
         def params
           param = target
           param = (param * 255 / 100).to_i if target_type == :position_percent
@@ -168,11 +253,27 @@ module SDN
       # the motor does not move, and just stores the new values
       # flags of 1 is reverse direction, but you have to set it every time
       class SetMotorSettings < UnknownMessage
+        # (see Ack::MSG)
         MSG = 0x52
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 5
 
-        attr_accessor :flags, :down_limit, :position_pulses
+        # @return [Integer]
+        attr_accessor :flags
+
+        # @return [Integer]
+        attr_accessor :down_limit
+
+        # @return [Integer]
+        attr_accessor :position_pulses
 
+        # Creates an ILT2 motor settings write command.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param flags [Integer] settings flags
+        # @param down_limit [Integer] configured lower limit
+        # @param position_pulses [Integer] stored current position
+        # @param kwargs [Hash] additional message options
         def initialize(dest = nil, flags = 0, down_limit = 0, position_pulses = 0, **kwargs)
           kwargs[:dest] ||= dest
           super(**kwargs)
@@ -181,6 +282,7 @@ module SDN
           self.position_pulses = position_pulses
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.flags = to_number(params[0])
@@ -188,12 +290,15 @@ module SDN
           self.position_pulses = to_number(params[3..4])
         end
 
+        # (see Message#params)
         def params
           transform_param(flags) + from_number(down_limit, 2) + from_number(position_pulses, 2)
         end
       end
 
+      # ILT2 node-label write variant with a larger maximum payload.
       class SetNodeLabel < ::SDN::Message::SetNodeLabel
+        # Maximum label length, in bytes
         MAX_LENGTH = 32
       end
     end

data/lib/sdn/message/post.rb

@@ -2,60 +2,104 @@
 
 module SDN
   class Message
+    # Response carrying a motor's group address for a specific slot.
     class PostGroupAddr < Message
+      # (see Ack::MSG)
       MSG = 0x61
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
 
-      def initialize(group_index = nil, group_address = nil, **kwargs)
-        super(**kwargs)
+      # Creates a group address response message.
+      #
+      # @param group_index [Integer, nil] group slot number
+      # @param group_address [(Integer, Integer, Integer), nil] group address bytes
+      def initialize(group_index = nil, group_address = nil, **)
+        super(**)
         self.group_index = group_index
         self.group_address = group_address
       end
 
-      attr_accessor :group_index, :group_address
+      # Reported group slot number.
+      #
+      # @return [Integer, nil]
+      attr_accessor :group_index
 
+      # Reported group address for the slot.
+      #
+      # @return [(Integer, Integer, Integer), nil]
+      attr_accessor :group_address
+
+      # (see Message#parse)
       def parse(params)
         super
         self.group_index = to_number(params[0]) + 1
         self.group_address = transform_param(params[1..3])
-        self.group_address = nil if group_address == [0, 0, 0] || group_address == [0x01, 0x01, 0xff]
+        self.group_address = nil if [[0, 0, 0], [0x01, 0x01, 0xff]].include?(group_address)
       end
 
+      # (see Message#params)
       def params
         from_number(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
 
+    # Response carrying a motor's configured rotation direction.
     class PostMotorDirection < Message
+      # (see Ack::MSG)
       MSG = 0x32
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
+      # Mapping from symbolic direction names to SDN parameter values.
       DIRECTION = { standard: 0x00, reversed: 0x01 }.freeze
 
+      # Reported motor rotation direction.
+      #
+      # @return [:standard, :reversed, nil]
       attr_accessor :direction
 
+      # (see Message#parse)
       def parse(params)
         super
         self.direction = DIRECTION.invert[to_number(params[0])]
       end
     end
 
+    # Response carrying a stored intermediate position value.
     class PostMotorIP < Message
+      # (see Ack::MSG)
       MSG = 0x35
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
 
-      attr_accessor :ip, :position_pulses, :position_percent
+      # Reported intermediate position slot.
+      #
+      # @return [Integer, nil]
+      attr_accessor :ip
+
+      # @return [Integer, nil]
+      attr_accessor :position_pulses
+
+      # @return [Integer, nil]
+      attr_accessor :position_percent
 
-      def initialize(ip = nil, position_pulses = nil, position_percent = nil, **kwargs)
-        super(**kwargs)
+      # Creates a motor IP response message.
+      #
+      # @param ip [Integer, nil] intermediate position slot
+      # @param position_pulses [Integer, nil] stored pulse value
+      # @param position_percent [Integer, nil] stored percentage value
+      def initialize(ip = nil, position_pulses = nil, position_percent = nil, **)
+        super(**)
         self.ip = ip
         self.position_pulses = position_pulses
         self.position_percent = position_percent
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.ip = to_number(params[0])
@@ -63,47 +107,79 @@ module SDN
         self.position_percent = to_number(params[3], nillable: true)
       end
 
+      # (see Message#params)
       def params
         from_number(ip) + from_number(position_pulses, 2) + from_number(position_percent)
       end
     end
 
+    # Response carrying a motor's upper and lower travel limits.
     class PostMotorLimits < Message
+      # (see Ack::MSG)
       MSG = 0x31
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
 
-      attr_accessor :up_limit, :down_limit
+      # @return [Integer, nil]
+      attr_accessor :up_limit
 
-      def initialize(up_limit = nil, down_limit = nil, **kwargs)
-        super(**kwargs)
+      # @return [Integer, nil]
+      attr_accessor :down_limit
+
+      # Creates a motor limits response message.
+      #
+      # @param up_limit [Integer, nil] upper limit in pulses
+      # @param down_limit [Integer, nil] lower limit in pulses
+      def initialize(up_limit = nil, down_limit = nil, **)
+        super(**)
         self.up_limit = up_limit
         self.down_limit = down_limit
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.up_limit = to_number(params[0..1], nillable: true)
         self.down_limit = to_number(params[2..3], nillable: true)
       end
 
+      # (see Message#params)
       def params
         from_number(up_limit, 2) + from_number(down_limit, 2)
       end
     end
 
+    # Response carrying a motor's current position and active intermediate position.
     class PostMotorPosition < Message
+      # (see Ack::MSG)
       MSG = 0x0d
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 5
 
-      attr_accessor :position_pulses, :position_percent, :ip
+      # @return [Integer, nil]
+      attr_accessor :position_pulses
+
+      # @return [Integer, nil]
+      attr_accessor :position_percent
+
+      # Reported active intermediate position slot.
+      #
+      # @return [Integer, nil]
+      attr_accessor :ip
 
-      def initialize(position_pulses = nil, position_percent = nil, ip = nil, **kwargs)
-        super(**kwargs)
+      # Creates a motor position response message.
+      #
+      # @param position_pulses [Integer, nil] current position in pulses
+      # @param position_percent [Integer, nil] current position in percent
+      # @param ip [Integer, nil] active intermediate position slot
+      def initialize(position_pulses = nil, position_percent = nil, ip = nil, **)
+        super(**)
         self.position_pulses = position_pulses
         self.position_percent = position_percent
         self.ip = ip
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.position_pulses = to_number(params[0..1], nillable: true)
@@ -111,17 +187,29 @@ module SDN
         self.ip = to_number(params[4], nillable: true)
       end
 
+      # (see Message#params)
       def params
-        from_number(position_pulses, 2) + from_number(position_percent) + from_number(ip)
+        from_number(position_pulses, 2) + from_number(position_percent) + from_number(0) + from_number(ip)
       end
     end
 
+    # Response carrying a motor's rolling speed configuration.
     class PostMotorRollingSpeed < Message
+      # (see Ack::MSG)
       MSG = 0x33
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 6
 
-      attr_accessor :up_speed, :down_speed, :slow_speed
+      # @return [Integer, nil]
+      attr_accessor :up_speed
 
+      # @return [Integer, nil]
+      attr_accessor :down_speed
+
+      # @return [Integer, nil]
+      attr_accessor :slow_speed
+
+      # (see Message#parse)
       def parse(params)
         super
         self.up_speed = to_number(params[0])
@@ -131,12 +219,19 @@ module SDN
       end
     end
 
+    # Response carrying a motor's movement state and last-action metadata.
     class PostMotorStatus < Message
+      # (see Ack::MSG)
       MSG = 0x0f
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 4
+      # Mapping from symbolic motor states to SDN parameter values.
       STATE = { stopped: 0x00, running: 0x01, blocked: 0x02, locked: 0x03 }.freeze
+      # Mapping from symbolic directions to SDN parameter values.
       DIRECTION = { down: 0x00, up: 0x01 }.freeze
+      # Mapping from symbolic action sources to SDN parameter values.
       SOURCE = { internal: 0x00, network: 0x01, dct: 0x02 }.freeze
+      # Mapping from symbolic action causes to SDN parameter values.
       CAUSE = { target_reached: 0x00,
                 explicit_command: 0x01,
                 wink: 0x02,
@@ -148,8 +243,37 @@ module SDN
                 over_current_protection: 0x21,
                 thermal_protection: 0x22 }.freeze
 
-      attr_accessor :state, :last_direction, :last_action_source, :last_action_cause
-
+      # Reported current motor state.
+      #
+      # @return [:stopped, :running, :blocked, :locked, nil]
+      attr_accessor :state
+
+      # Reported direction of the last movement.
+      #
+      # @return [:down, :up, nil]
+      attr_accessor :last_direction
+
+      # Reported source of the last action.
+      #
+      # @return [:internal, :network, :dct, nil]
+      attr_accessor :last_action_source
+
+      # Reported cause of the last action.
+      #
+      # @return [:target_reached,
+      #    :explicit_command,
+      #    :wink,
+      #    :limits_not_set,
+      #    :ip_not_set,
+      #    :polarity_not_checked,
+      #    :in_configuration_mode,
+      #    :obstacle_detection,
+      #    :over_current_protection,
+      #    :thermal_protection,
+      #    nil]
+      attr_accessor :last_action_cause
+
+      # (see Message#parse)
       def parse(params)
         super
         self.state = STATE.invert[to_number(params[0])]
@@ -159,22 +283,42 @@ module SDN
       end
     end
 
+    # Response carrying the network lock payload in an undecoded form.
     class PostNetworkLock < UnknownMessage
+      # (see Ack::MSG)
       MSG = 0x36
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 5
     end
 
+    # Response used during node address discovery.
     class PostNodeAddr < Message
+      # (see Ack::MSG)
       MSG = 0x60
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 0
     end
 
+    # Response carrying a node's application version details.
     class PostNodeAppVersion < Message
+      # (see Ack::MSG)
       MSG = 0x75
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 6
 
-      attr_accessor :reference, :index_letter, :index_number, :profile
+      # @return [Integer, nil]
+      attr_accessor :reference
+
+      # @return [String, nil]
+      attr_accessor :index_letter
+
+      # @return [Integer, <Integer>, nil]
+      attr_accessor :index_number
+
+      # @return [Integer, <Integer>, nil]
+      attr_accessor :profile
 
+      # (see Message#parse)
       def parse(params)
         super
         self.reference = to_number(params[0..2])
@@ -184,27 +328,38 @@ module SDN
       end
     end
 
+    # Response carrying a node's configured label.
     class PostNodeLabel < Message
+      # (see Ack::MSG)
       MSG = 0x65
+      # Maximum label length, in bytes
       MAX_LENGTH = 16
 
+      # @return [String, nil]
       attr_accessor :label
 
-      def initialize(label = nil, **kwargs)
-        super(**kwargs)
+      # Creates a node label response message.
+      #
+      # @param label [String, nil] node label
+      def initialize(label = nil, **)
+        super(**)
         self.label = label
       end
 
+      # (see Message#parse)
       def parse(params)
         @label = to_string(params)
       end
 
+      # (see Message#params)
       def params
         from_string(label, self.class::MAX_LENGTH)
       end
     end
 
+    # Response carrying a node's serial number string.
     class PostNodeSerialNumber < Message
+      # (see Ack::MSG)
       MSG = 0x6c
 
       # format is NNNNNNMMYYWW
@@ -212,14 +367,20 @@ module SDN
       # M = Manufacturer ID
       # Y = Year (last two digits)
       # W = Week
+      # Reported node serial number string.
+      #
+      # @return [String, nil]
       attr_accessor :serial_number
 
+      # (see Message#parse)
       def parse(params)
         @serial_number = to_string(params)
       end
     end
 
+    # Response carrying a node's protocol stack version details.
     class PostNodeStackVersion < PostNodeAppVersion
+      # (see Ack::MSG)
       MSG = 0x71
     end
   end