maxcube-client 0.4.1 → 0.5.0

data/lib/maxcube/messages/tcp/type/c.rb

@@ -3,11 +3,14 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Configuration message.
         module MessageC
           private
 
+          # Mandatory hash keys.
           KEYS = %i[length address rf_address device_type
                     test_result serial_number].freeze
+          # Optional hash keys.
           OPT_KEYS = %i[
             firmware_version _firmware_version room_id
 
@@ -25,7 +28,6 @@ module MaxCube
 
           LENGTHS = [6].freeze
 
-          # Configuration message
           def parse_tcp_c(body)
             addr, enc_data = parse_tcp_c_split(body)
 
@@ -233,11 +235,11 @@ module MaxCube
       end
 
       class Serializer
+        # Request for configuration message (C).
+        # Does not contain any data.
         module MessageC
           private
 
-          # Request for configuration message (C)
-          # Does not contain any data
           def serialize_tcp_c(_hash)
             ''
           end

data/lib/maxcube/messages/tcp/type/f.rb

@@ -3,12 +3,13 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # NTP server message.
         module MessageF
           private
 
+          # Mandatory hash keys.
           KEYS = %i[ntp_servers].freeze
 
-          # NTP server message
           def parse_tcp_f(body)
             { ntp_servers: body.split(',') }
           end
@@ -16,13 +17,14 @@ module MaxCube
       end
 
       class Serializer
+        # Request for NTP servers message (F).
+        # Optionally, updates can be done.
         module MessageF
           private
 
+          # Optional hash keys.
           OPT_KEYS = %i[ntp_servers].freeze
 
-          # Request for NTP servers message (F)
-          # Optionally, updates can be done
           def serialize_tcp_f(hash)
             hash.key?(:ntp_servers) ? hash[:ntp_servers].join(',') : ''
           end

data/lib/maxcube/messages/tcp/type/h.rb

@@ -3,11 +3,13 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Hello message
         module MessageH
           private
 
           LENGTHS = [10, 6, 4, 8, 8, 2, 2, 6, 4, 2, 4].freeze
 
+          # Mandatory hash keys.
           KEYS = %i[
             serial_number
             rf_address
@@ -21,7 +23,6 @@ module MaxCube
             ntp_counter
           ].freeze
 
-          # Hello message
           def parse_tcp_h(body)
             values = body.split(',')
             check_msg_part_lengths(LENGTHS, *values)
@@ -55,7 +56,7 @@ module MaxCube
             hours = time[0..1].to_i(16)
             minutes = time[2..3].to_i(16)
 
-            values[7] = DateTime.new(year, month, day, hours, minutes)
+            values[7] = Time.new(year, month, day, hours, minutes)
             values.delete_at(8)
           rescue ArgumentError
             raise InvalidMessageBody

data/lib/maxcube/messages/tcp/type/l.rb

@@ -3,14 +3,15 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Device list message.
         module MessageL
           private
 
           LENGTHS = [6, 11, 12].freeze
 
+          # Mandatory hash keys.
           KEYS = %i[devices].freeze
 
-          # Device list message
           def parse_tcp_l(body)
             @io = StringIO.new(decode(body), 'rb')
 
@@ -22,7 +23,7 @@ module MaxCube
               parse_tcp_l_submsg_3(subhash, temperature_msb) if @length > 11
 
               hash[:devices] << subhash
-            end # until
+            end
 
             hash
           end
@@ -82,11 +83,11 @@ module MaxCube
             # Sometimes when device is in 'auto' mode,
             # this field can contain 'actual_temperature' instead
             # (but never if it is already contained in next byte)
-            # !It seems that 'datetime' is used for 'vacation' mode,
+            # !It seems that 'date' is used for 'vacation' mode,
             # but it is not sure ...
             begin
-              subhash[:datetime_until] = DateTime.new(year, month, day,
-                                                      hours, minutes)
+              subhash[:datetime_until] = Time.new(year, month, day,
+                                                  hours, minutes)
             rescue ArgumentError
               if @mode != :auto || @length > 11
                 raise InvalidMessageBody
@@ -116,11 +117,11 @@ module MaxCube
       end
 
       class Serializer
+        # Command to resend device list (L).
+        # Does not contain any data.
         module MessageL
           private
 
-          # Command to resend device list (L)
-          # Does not contain any data
           def serialize_tcp_l(_hash)
             ''
           end

data/lib/maxcube/messages/tcp/type/m.rb

@@ -3,15 +3,16 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Metadata message.
         module MessageM
           private
 
           LENGTHS = [2, 2].freeze
 
+          # Mandatory hash keys.
           KEYS = %i[index count unknown1 unknown2
                     rooms_count rooms devices_count devices].freeze
 
-          # Metadata message
           def parse_tcp_m(body)
             index, count, enc_data = parse_tcp_m_split(body)
 
@@ -104,18 +105,21 @@ module MaxCube
       end
 
       class Serializer
+        # Serializes metadata for Cube.
+        # Message body has the same format as response (M)
+        # -> reverse operations.
+        # Cube does not check data format,
+        # so things could break if invalid data is sent.
+        #
+        # ! I couldn't verify the assumption that bodies should be the same.
         module MessageM
           private
 
+          # Mandatory hash keys.
           KEYS = %i[rooms_count rooms devices_count devices].freeze
+          # Optional hash keys.
           OPT_KEYS = %i[index unknown1 unknown2].freeze
 
-          # Serialize metadata for Cube
-          # Message body has the same format as response (M)
-          # -> reverse operations
-          # ! I couldn't verify the assumption that bodies should be the same
-          # ! Cube does not check data format,
-          #   so things could break if invalid data is sent
           def serialize_tcp_m(hash)
             index = hash.key?(:index) ? to_int(0, 'index', hash[:index]) : 0
             head = format('%02x,', index)

data/lib/maxcube/messages/tcp/type/n.rb

@@ -3,12 +3,13 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # New device (pairing) message.
         module MessageN
           private
 
+          # Mandatory hash keys.
           KEYS = %i[device_type rf_address serial_number unknown].freeze
 
-          # New device (pairing) message
           def parse_tcp_n(body)
             @io = StringIO.new(decode(body), 'rb')
 
@@ -26,13 +27,14 @@ module MaxCube
       end
 
       class Serializer
+        # Command to set the Cube into pairing mode
+        # with optional +timeout+ in seconds.
         module MessageN
           private
 
+          # Optional hash keys.
           OPT_KEYS = %i[timeout].freeze
 
-          # Command to set the Cube into pairing mode
-          # with optional +timeout+ in seconds
           def serialize_tcp_n(hash)
             return '' unless hash.key?(:timeout)
             format('%04x', to_int(0, 'timeout', hash[:timeout]))

data/lib/maxcube/messages/tcp/type/q.rb

@@ -3,11 +3,11 @@ module MaxCube
   module Messages
     module TCP
       class Serializer
+        # Quit message - terminates connection.
+        # Does not contain any data.
         module MessageQ
           private
 
-          # Quit message - terminates connection
-          # Does not contain any data
           def serialize_tcp_q(_hash)
             ''
           end

data/lib/maxcube/messages/tcp/type/s.rb

@@ -3,18 +3,19 @@ module MaxCube
   module Messages
     module TCP
       class Parser
+        # Response to send command message.
         module MessageS
           private
 
           LENGTHS = [2, 1, 2].freeze
 
+          # Mandatory hash keys.
           KEYS = %i[
             duty_cycle
             command_processed
             free_memory_slots
           ].freeze
 
-          # Send command message (response)
           def parse_tcp_s(body)
             values = body.split(',')
             check_msg_part_lengths(LENGTHS, *values)
@@ -27,10 +28,13 @@ module MaxCube
       end
 
       class Serializer
+        # Message to send command to Cube.
         module MessageS
           private
 
+          # Mandatory hash keys.
           KEYS = %i[command].freeze
+          # Optional hash keys.
           OPT_KEYS = %i[
             unknown
             rf_flags
@@ -76,7 +80,6 @@ module MaxCube
             display_temperature: 0x0,
           }.freeze
 
-          # Message to send command to Cube
           def serialize_tcp_s(hash)
             @io = StringIO.new('', 'wb')
 

data/lib/maxcube/messages/tcp/type/t.rb

@@ -3,15 +3,16 @@ module MaxCube
   module Messages
     module TCP
       class Serializer
+        # Command to delete one or more devices from the Cube.
+        # Acknowledgement (A) follows.
         module MessageT
           private
 
-          # +count+ argument would cause ambuigity if it was optional
-          #   due to +rf_addresses+ has variable size
+          # Mandatory hash keys.
+          # +count+ key would cause ambuigity if it was optional
+          # due to +rf_addresses+ has variable size.
           KEYS = %i[count force rf_addresses].freeze
 
-          # Command to delete one or more devices from the Cube
-          # Acknowledgement (A) follows
           def serialize_tcp_t(hash)
             force = to_bool('force mode', hash[:force]) ? '1' : '0'
             rf_addresses = to_ints(0, 'RF addresses', *hash[:rf_addresses])

data/lib/maxcube/messages/tcp/type/u.rb

@@ -3,12 +3,13 @@ module MaxCube
   module Messages
     module TCP
       class Serializer
+        # Command to configure Cube's portal URL
         module MessageU
           private
 
+          # Mandatory hash keys.
           KEYS = %i[url port].freeze
 
-          # Command to configure Cube's portal URL
           def serialize_tcp_u(hash)
             "#{hash[:url]}:#{to_int(0, 'port', hash[:port])}"
           end

data/lib/maxcube/messages/tcp/type/z.rb

@@ -3,14 +3,16 @@ module MaxCube
   module Messages
     module TCP
       class Serializer
+        # Wakeup command.
+        # Acknowledgement (A) follows.
         module MessageZ
           private
 
+          # Mandatory hash keys.
           KEYS = %i[time scope].freeze
+          # Optional hash keys.
           OPT_KEYS = %i[id].freeze
 
-          # Wakeup command
-          # Acknowledgement (A) follows
           def serialize_tcp_z(hash)
             time = format('%02x', to_int(0, 'time', hash[:time]))
             scope = hash[:scope].to_sym

data/lib/maxcube/messages/udp.rb

@@ -2,7 +2,14 @@ require 'maxcube/messages'
 
 module MaxCube
   module Messages
+    # This module contains classes aimed onto UDP messages of Cube protocol.
+    #
+    # Structure of every UDP Cube message:
+    # * Starts with {MSG_PREFIX}
+    # @example
+    #   eQ3MaxApKEQ0523864>I
     module UDP
+      # Prefix of any UDP Cube message
       MSG_PREFIX = 'eQ3Max'.freeze
     end
   end

data/lib/maxcube/messages/udp/handler.rb

@@ -4,32 +4,60 @@ require 'maxcube/messages/handler'
 module MaxCube
   module Messages
     module UDP
+      # Extends {Messages::Handler} of routines connected to UDP Cube messages.
       module Handler
         include Messages::Handler
 
+        # Validates whether message contains correct {MSG_PREFIX}
+        # (suffix of the prefix differs for parser and serializer).
+        # @param msg [String] input message.
+        # @return [Boolean] whether message prefix is valid.
         def valid_udp_msg_prefix(msg)
           msg.start_with?(self.class.const_get('MSG_PREFIX'))
         end
 
+        # As {#valid_udp_msg_prefix},
+        # but it raises exception if the prefix is not valid.
+        # @param msg [String] input message.
+        # @return [String] input message.
+        # @raise [InvalidMessageFormat] if the prefix is not valid.
         def check_udp_msg_prefix(msg)
           raise InvalidMessageFormat unless valid_udp_msg_prefix(msg)
+          msg
         end
 
+        # Validates whether given message is a valid UDP Cube message.
+        # It calls {#valid_udp_msg_prefix} and {#valid_msg}.
+        # @param msg [String] input message.
+        # @return [Boolean] whether message is valid.
         def valid_udp_msg(msg)
           valid_udp_msg_prefix(msg) &&
             valid_msg(msg)
         end
 
+        # As {#valid_udp_msg}, but raises exception if message is not valid.
+        # It calls {#check_udp_msg_prefix} and {#check_msg}.
+        # @param msg [String] input message.
+        # @return [String] input message.
         def check_udp_msg(msg)
           check_udp_msg_prefix(msg)
           check_msg(msg)
           msg
         end
 
+        # Validates whether given hash with message contents
+        # is valid for UDP Cube messaging purposes.
+        # It only calls {#valid_hash}.
+        # @param hash [Hash] input hash.
+        # @return [Boolean] whether hash is valid.
         def valid_udp_hash(hash)
           valid_hash(hash)
         end
 
+        # As {#valid_udp_hash}, but raises exception if hash is not valid.
+        # It only calls {#check_hash}.
+        # @param hash [Hash] input hash.
+        # @return [Hash] input hash.
         def check_udp_hash(hash)
           check_hash(hash)
           hash

data/lib/maxcube/messages/udp/parser.rb

@@ -4,22 +4,32 @@ require 'maxcube/messages/parser'
 module MaxCube
   module Messages
     module UDP
+      # Extends {Messages::Parser} and {UDP::Handler} of routines
+      # connected to UDP Cube messages parsing.
       class Parser
-        include Handler
+        include UDP::Handler
         include Messages::Parser
 
+        # Mandatory hash keys common for all UDP Cube messages.
         KEYS = %i[prefix serial_number id].freeze
 
-        %w[i n h].each { |f| require_relative 'type/' << f }
+        %w[i n h].each do |f|
+          require_relative 'type/' << f
+          include const_get('Message' << f.upcase)
+        end
 
+        # Known message types in the direction Cube -> client.
         MSG_TYPES = %w[I N h c].freeze
 
-        include MessageI
-        include MessageN
-        include MessageH
-
+        # {UDP::MSG_PREFIX} with a suffix.
         MSG_PREFIX = (UDP::MSG_PREFIX + 'Ap').freeze
 
+        # Parses single message.
+        # Subsequently calls {#check_udp_msg},
+        # {#parse_udp_msg_head}, {#parse_msg_body}
+        # and {#check_udp_hash}.
+        # @param msg [String] input message.
+        # @return [Hash] particular message contents separated into hash.
         def parse_udp_msg(msg)
           check_udp_msg(msg)
           hash = parse_udp_msg_head(msg)
@@ -29,10 +39,17 @@ module MaxCube
 
         private
 
+        # Tells how to get message type from a message.
+        # @param msg [String] input message.
+        # @return [String] message type.
         def msg_msg_type(msg)
           msg[19]
         end
 
+        # Parses head of UDP Cube message, that is common to all of these.
+        # Internal +IO+ variable contains message body string at the end.
+        # @param msg [String] input message.
+        # @return [Hash] particular message head contents separated into hash.
         def parse_udp_msg_head(msg)
           @io = StringIO.new(msg, 'rb')
           hash = {