somfy_sdn 2.4.0 → 2.5.0

data/lib/sdn/message/get.rb

@@ -2,18 +2,32 @@
 
 module SDN
   class Message
+    # Request for a motor's configured group address at a given slot.
     class GetGroupAddr < Message
+      # (see Ack::MSG)
       MSG = 0x41
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
 
+      # @!attribute [rw] group_index
+      #
+      # Group index in the range 1..16
+      #
+      # @return [Integer]
       attr_reader :group_index
 
+      # Creates a request for a specific group slot.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param group_index [Integer] group slot to query
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, group_index = 1, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.group_index = group_index
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.group_index = to_number(params[0]) + 1
@@ -25,27 +39,44 @@ module SDN
         @group_index = value
       end
 
+      # (see Message#params)
       def params
         transform_param(group_index - 1)
       end
     end
 
+    # Request for a motor's rotation direction setting.
     class GetMotorDirection < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x22
     end
 
+    # Request for a motor's stored intermediate position at a given slot.
     class GetMotorIP < Message
+      # (see Ack::MSG)
       MSG = 0x25
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 1
 
+      # @!attribute [rw] ip
+      #
+      # Intermediate position slot being queried.
+      #
+      # @return [Integer]
       attr_reader :ip
 
+      # Creates a request for a specific intermediate position slot.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param ip [Integer] intermediate position slot
+      # @param kwargs [Hash] additional message options
       def initialize(dest = nil, ip = 1, **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
         self.ip = ip
       end
 
+      # (see Message#parse)
       def parse(params)
         super
         self.ip = to_number(params[0])
@@ -57,54 +88,80 @@ module SDN
         @ip = value
       end
 
+      # (see Message#params)
       def params
         transform_param(ip)
       end
     end
 
+    # Request for a motor's configured travel limits.
     class GetMotorLimits < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x21
     end
 
+    # Request for a motor's current position.
     class GetMotorPosition < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x0c
     end
 
+    # Request for a motor's rolling speed configuration.
     class GetMotorRollingSpeed < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x23
     end
 
+    # Request for a motor's current run state and last action metadata.
     class GetMotorStatus < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x0e
     end
 
+    # Request for the current network lock state.
     class GetNetworkLock < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x26
     end
 
+    # Discovery request for a node address, usually sent as a broadcast.
     class GetNodeAddr < Message
+      # (see Ack::MSG)
       MSG = 0x40
+      # (see Ack::PARAMS_LENGTH)
       PARAMS_LENGTH = 0
 
+      # Creates a node discovery request, defaulting to broadcast.
+      #
+      # @param dest [(Integer, Integer, Integer), nil] destination address
+      # @param kwargs [Hash] additional message options
       def initialize(dest = [0xff, 0xff, 0xff], **kwargs)
         kwargs[:dest] ||= dest
         super(**kwargs)
       end
     end
 
+    # Request for a node's application version.
     class GetNodeAppVersion < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x74
     end
 
+    # Request for a node's configured label.
     class GetNodeLabel < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x45
     end
 
+    # Request for a node's serial number.
     class GetNodeSerialNumber < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x4c
     end
 
+    # Request for a node's protocol stack version.
     class GetNodeStackVersion < SimpleRequest
+      # (see Ack::MSG)
       MSG = 0x70
     end
   end

data/lib/sdn/message/helpers.rb

@@ -2,19 +2,40 @@
 
 module SDN
   class Message
+    # Shared conversions for SDN addresses, encoded parameters, strings, and checksums.
     module Helpers
+      # Converts a printable SDN address into its byte representation.
+      #
+      # @param addr_string [String] address such as `01.02.03`
+      #
+      # @return [(Integer, Integer, Integer)] three-byte address
       def parse_address(addr_string)
         addr_string.match(/^(\h{2})[:.]?(\h{2})[:.]?(\h{2})$/).captures.map { |byte| byte.to_i(16) }
       end
 
+      # Formats an address byte array using dotted hexadecimal notation.
+      #
+      # @param addr_bytes [(Integer, Integer, Integer)] address bytes
+      #
+      # @return [String]
       def print_address(addr_bytes)
         format("%02X.%02X.%02X", *addr_bytes)
       end
 
+      # Checks whether an address is a group address.
+      #
+      # @param addr_bytes [(Integer, Integer, Integer)] address bytes
+      #
+      # @return [true, false]
       def group_address?(addr_bytes)
         addr_bytes[0..1] == [1, 1]
       end
 
+      # Maps a numeric node type identifier to a symbolic name when known.
+      #
+      # @param number [Integer] protocol node type identifier
+      #
+      # @return [Symbol, Integer]
       def node_type_from_number(number)
         case number
         when 1 then :st50ilt2
@@ -27,6 +48,11 @@ module SDN
         end
       end
 
+      # Maps a symbolic node type name to its numeric protocol identifier.
+      #
+      # @param type [Symbol, Integer] node type
+      #
+      # @return [Integer]
       def node_type_to_number(type)
         case type
         when :st50ilt2 then 1
@@ -39,20 +65,42 @@ module SDN
         end
       end
 
+      # Formats a node type for inspection output.
+      #
+      # @param type [Symbol, Integer] node type
+      #
+      # @return [String]
       def node_type_to_string(type)
         type.is_a?(Integer) ? format("%02xh", type) : type.inspect
       end
 
+      # Applies the SDN byte inversion and endianness transformation to a parameter value.
+      #
+      # @param param [Integer, <Integer>] parameter value
+      #
+      # @return [<Integer>]
       def transform_param(param)
         Array(param).reverse.map { |byte| 0xff - byte }
       end
 
+      # Converts transformed SDN bytes into an integer.
+      #
+      # @param param [Integer, <Integer>] transformed bytes
+      # @param nillable [true, false] whether all-`0xff` values should become `nil`
+      #
+      # @return [Integer, nil]
       def to_number(param, nillable: false)
         result = Array(param).reverse.inject(0) { |sum, byte| (sum << 8) + 0xff - byte }
         result = nil if nillable && result == (1 << (8 * Array(param).length)) - 1
         result
       end
 
+      # Converts an integer into SDN-transformed bytes.
+      #
+      # @param number [Integer, nil] numeric value
+      # @param bytes [Integer] number of bytes to emit
+      #
+      # @return [<Integer>]
       def from_number(number, bytes = 1)
         number ||= (1**(bytes * 8)) - 1
         number = number.to_i
@@ -62,17 +110,33 @@ module SDN
         end
       end
 
+      # Decodes transformed SDN bytes into a trimmed string.
+      #
+      # @param param [<Integer>] transformed string bytes
+      #
+      # @return [String]
       def to_string(param)
         chars = param.map { |b| 0xff - b }
         chars.pack("C*").sub(/\0+$/, "").strip
       end
 
+      # Encodes a string into a fixed-width SDN byte array.
+      #
+      # @param string [String]
+      # @param bytes [Integer] output width
+      #
+      # @return [<Integer>]
       def from_string(string, bytes)
         chars = string.bytes
         chars = chars[0...bytes].fill(" ".ord, chars.length, bytes - chars.length)
         chars.map { |b| 0xff - b }
       end
 
+      # Computes the SDN checksum bytes for the provided payload.
+      #
+      # @param bytes [<Integer>]
+      #
+      # @return [(Integer, Integer)] two-byte checksum
       def checksum(bytes)
         result = bytes.sum
         [result >> 8, result & 0xff]

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

@@ -2,21 +2,39 @@
 
 module SDN
   class Message
+    # ILT2-specific message namespace.
     module ILT2
+      # Request for the configured IR channel bitmask.
       class GetIRConfig < SimpleRequest
+        # (see Ack::MSG)
         MSG = 0x49
       end
 
+      # Request for the current ILT2 lock status.
       class GetLockStatus < SimpleRequest
+        # (see Ack::MSG)
         MSG = 0x4b
       end
 
+      # Request for an ILT2 intermediate position at a given slot.
       class GetMotorIP < Message
+        # (see Ack::MSG)
         MSG = 0x43
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 1
 
+        # @!attribute [rw] ip
+        #
+        # Intermediate position slot being queried in the range 1..16.
+        #
+        # @return [Integer]
         attr_reader :ip
 
+        # Creates an ILT2 request for a specific intermediate position slot.
+        #
+        # @param dest [(Integer, Integer, Integer), nil] destination address
+        # @param ip [Integer] intermediate position slot
+        # @param kwargs [Hash] additional message options
         def initialize(dest = nil, ip = 1, **kwargs)
           kwargs[:dest] ||= dest
           super(**kwargs)
@@ -29,21 +47,27 @@ module SDN
           @ip = value
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.ip = to_number(params[0]) + 1
         end
 
+        # (see Message#params)
         def params
           transform_param(@ip - 1)
         end
       end
 
+      # Request for an ILT2 motor's current position.
       class GetMotorPosition < SimpleRequest
+        # (see Ack::MSG)
         MSG = 0x44
       end
 
+      # Request for ILT2 motor settings such as the configured limit.
       class GetMotorSettings < SimpleRequest
+        # (see Ack::MSG)
         MSG = 0x42
       end
     end

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

@@ -3,10 +3,17 @@
 module SDN
   class Message
     module ILT2
+      # Special five-byte ILT2 master-control frame parser.
       class MasterControl
         class << self
           include Helpers
 
+          # Parses a five-byte ILT2 master control frame when present.
+          #
+          # @param data [<Integer>] buffered input bytes
+          #
+          # @return [(SDN::Message::ILT2::MasterControl, Integer), nil]
+          # (see Message#parse)
           def parse(data)
             return unless data.length >= 5
             return unless checksum(data[0..2]) == data[3..4]
@@ -24,12 +31,15 @@ module SDN
           end
         end
 
+        # Master-control frame representing a down command.
         class Down < MasterControl
         end
 
+        # Master-control frame representing a stop command.
         class Stop < MasterControl
         end
 
+        # Master-control frame representing an up command.
         class Up < MasterControl
         end
       end

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

@@ -3,14 +3,25 @@
 module SDN
   class Message
     module ILT2
+      # Response carrying the configured ILT2 IR channel bitmask.
       class PostIRConfig < Message
+        # (see Ack::MSG)
         MSG = 0x69
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 1
 
+        # @!attribute [rw] channels
+        #
+        # IR channel bitmask.
+        #
+        # @return [Integer, nil]
         attr_reader :channels
 
-        def initialize(channels = nil, **kwargs)
-          super(**kwargs)
+        # Creates an ILT2 IR configuration response.
+        #
+        # @param channels [Integer, nil] bitmask of enabled IR channels
+        def initialize(channels = nil, **)
+          super(**)
           self.channels = channels
         end
 
@@ -18,110 +29,165 @@ module SDN
           @channels = value&.& 0xff
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.channels = to_number(params[0])
         end
 
+        # (see Message#params)
         def params
           transform_param(channels)
         end
 
+        # (see Message#class_inspect)
         def class_inspect
           ", @channels=#{channels.chr.unpack1("b8")}"
         end
       end
 
+      # Response carrying the current ILT2 lock priority.
       class PostLockStatus < Message
+        # (see Ack::MSG)
         MSG = 0x6B
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 1
 
-        attr_accessor :priority # 0 for not locked
+        # Reported lock priority, or `0` when unlocked.
+        #
+        # @return [Integer, nil]
+        attr_accessor :priority
 
-        def initialize(priority = nil, **kwargs)
-          super(**kwargs)
+        # Creates an ILT2 lock status response.
+        #
+        # @param priority [Integer, nil] current lock priority
+        def initialize(priority = nil, **)
+          super(**)
           self.priority = priority
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.current_lock_priority = to_number(params[0])
         end
 
+        # (see Message#params)
         def params
           transform_param(priority)
         end
       end
 
+      # Response carrying a stored ILT2 intermediate position.
       class PostMotorIP < Message
+        # (see Ack::MSG)
         MSG = 0x63
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
 
-        attr_accessor :ip, :position_pulses
+        # Reported intermediate position slot in the range 1..16.
+        #
+        # @return [Integer, nil]
+        attr_accessor :ip
 
-        def initialize(ip = nil, position_pulses = nil, **kwargs)
-          super(**kwargs)
+        # @return [Integer, nil]
+        attr_accessor :position_pulses
+
+        # Creates an ILT2 motor IP response.
+        #
+        # @param ip [Integer, nil] intermediate position slot
+        # @param position_pulses [Integer, nil] stored pulse value
+        def initialize(ip = nil, position_pulses = nil, **)
+          super(**)
           self.ip = ip
           self.position_pulses = position_pulses
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.ip = to_number(params[0]) + 1
           self.position_pulses = to_number(params[1..2], nillable: true)
         end
 
+        # (see Message#params)
         def params
           transform_param(ip - 1) + from_number(position_pulses, 2)
         end
       end
 
+      # Response carrying an ILT2 motor's current position.
       class PostMotorPosition < Message
+        # (see Ack::MSG)
         MSG = 0x64
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
 
-        attr_accessor :position_pulses, :position_percent
+        # @return [Integer, nil]
+        attr_accessor :position_pulses
+
+        # @return [Numeric, nil]
+        attr_accessor :position_percent
 
-        def initialize(position_pulses = nil, position_percent = nil, **kwargs)
-          super(**kwargs)
+        # Creates an ILT2 motor position response.
+        #
+        # @param position_pulses [Integer, nil] current position in pulses
+        # @param position_percent [Numeric, nil] current position in percent
+        def initialize(position_pulses = nil, position_percent = nil, **)
+          super(**)
           self.position_pulses = position_pulses
           self.position_percent = position_percent
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.position_pulses = to_number(params[0..1])
           self.position_percent = to_number(params[2]).to_f / 255 * 100
         end
 
+        # (see Message#params)
         def params
           from_number(position_pulses, 2) +
             from_number(position_percent && (position_percent * 255 / 100))
         end
       end
 
+      # Response carrying ILT2 motor settings in a partially decoded form.
       class PostMotorSettings < UnknownMessage
+        # (see Ack::MSG)
         MSG = 0x62
+        # (see Ack::PARAMS_LENGTH)
         PARAMS_LENGTH = 3
 
+        # Reported configured lower limit.
+        #
+        # @return [Integer, nil]
         attr_accessor :limit
 
-        def initialize(limit = nil, **kwargs)
-          super(**kwargs)
+        # Creates an ILT2 motor settings response.
+        #
+        # @param limit [Integer, nil] configured lower limit
+        def initialize(limit = nil, **)
+          super(**)
           self.limit = limit
         end
 
+        # (see Message#parse)
         def parse(params)
           super
           self.limit = to_number(params[1..2])
         end
 
+        # (see Message#params)
         def params
           transform_param(0) + from_number(limit, 2)
         end
       end
 
+      # ILT2 node-label response variant with a larger maximum payload.
       class PostNodeLabel < ::SDN::Message::PostNodeLabel
+        # Maximum label length, in bytes
         MAX_LENGTH = 32
       end
     end