adam6050 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 693c25cc61968c917bd119cc16986779e955a29a
-  data.tar.gz: 72381c1a3a55fd9852bc6cfa4e9b1dec9ba05d6b
+  metadata.gz: 2c831e1aa753967132fff58891039d680b8affbc
+  data.tar.gz: 27d7aad6b04f7085c8b059e744434fea7939ddb0
 SHA512:
-  metadata.gz: 27d756b741f3dd98161fc75c135b906c6d30c451ece1d6c93238ac049a8ef7de24fb6fac0f67d9e23c03f6aa87060bd887a6698ccb6bd66b2233577f8b48a0b6
-  data.tar.gz: bcafa5b71fa111dd1925ce1a5cfac4ae211709ce09e8e0f33ec3ebf9f72535d8dac5a25050650c5366f15b12ec95b992ea4173d85b23e3731bd98269115fe648
+  metadata.gz: aeba0631241b8976c771d32c62e1c9d9ed2d299e6d57b335c01529241e16daf449ee1004294f399d9ad3b2617ba4300baeea29e861c3ae4cff8ebeb6e4758013
+  data.tar.gz: 28e971677d1e7befbdec55f875e86f288c62266218a0694506bb17f72b133fe85379ab5eb989ff2512d489df2f72f9365c2f8f932d48164754876f010494b765

data/.rubocop.yml

@@ -42,6 +42,7 @@ Metrics/BlockLength:
     - 'Rakefile'
     - '**/*.rake'
     - 'test/**/*.rb'
+    - '*.gemspec'
 
 Metrics/ModuleLength:
   Exclude:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    adam6050 (0.1.3)
+    adam6050 (0.1.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,11 +1,15 @@
-# 🎛 ADAM6050
+# ADAM6050
 
 [![Gem Version](https://badge.fury.io/rb/adam6050.svg)](https://badge.fury.io/rb/vissen-input)
 [![Build Status](https://travis-ci.org/seblindberg/ruby-adam6050.svg?branch=master)](https://travis-ci.org/seblindberg/ruby-adam6050)
 [![Inline docs](http://inch-ci.org/github/seblindberg/ruby-adam6050.svg?branch=master)](http://inch-ci.org/github/seblindberg/ruby-adam6050)
 [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/adam6050/)
 
-This library implements a server that emulates the functionality of the network connected Advantech ADAM-6050 IO module.
+![Advantech ADAM-6050 IO module](http://downloadt.advantech.com/download/downloadlit.aspx?LIT_ID=1-3150PW)
+
+This library implements a server that emulates the functionality of the network connected Advantech ADAM-6050 digital IO module. Specifically the UDP protocol that the unit speaks has been reverse engineered. Since I don't have an actual device to test with the response messages from the server may differ from what they should be. It all works well enough for interfacing with Synology Surveillance Station which is the original intent.
+
+More information about the module can be found on the Advantech [product page](http://www.advantech.com/products/a67f7853-013a-4b50-9b20-01798c56b090/adam-6050/mod_b009c4b4-4b7c-4736-b16f-241978245e6a) which among other things links to its manual.
 
 ## Installation
 
@@ -34,6 +38,10 @@ server.run do |state, prev_state|
 end
 ```
 
+## TODO
+
+-[ ] Improve the reliability of the server tests that involve socket connections. Hard coded delays are no good.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/adam6050.gemspec

@@ -12,7 +12,14 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'Server implementation of the ADAM-6050 IO module.'
   spec.description   = 'This library implements a server that emulates the ' \
-                       'Advantech ADAM-6050 IO module.'
+                       'functionality of the network connected Advantech ' \
+                       'ADAM-6050 digital IO module. Specifically the UDP ' \
+                       'protocol that the unit speaks has been reverse ' \
+                       "engineered. Since I don't have an actual device to " \
+                       'test with the response messages from the server may ' \
+                       'differ from what they should be. It all works well ' \
+                       'enough for interfacing with Synology Surveillance ' \
+                       'Station which is the original intent.'
   spec.homepage      = 'https://github.com/seblindberg/ruby-adam6050'
   spec.license       = 'MIT'
 

data/lib/adam6050/handler/login.rb

@@ -3,6 +3,10 @@
 module ADAM6050
   module Handler
     # Allows senders to login.
+    #
+    # I have so far not been able to find any documentation around this feature.
+    # It is therefore almost certain that the response in case of an incorrect
+    # password is wrong.
     class Login
       include Handler
 
@@ -18,8 +22,12 @@ module ADAM6050
 
       # @param  msg [String] the incomming message.
       # @param  state [Integer] the current state.
+      # @param  session [Session] the current session.
+      # @param  sender [Socket::UDPSource] the UDP client.
       #
-      # @return [Array<Integer, String>] the next state and an optional reply.
+      # @return [Integer] the next state (always unchanged).
+      # @return [String] a reply. The reply is either '>01' or '?' depending on
+      #   if the login attempt was successful or not.
       def handle(msg, state, session, sender)
         return state, '?' unless @password == msg[6..-1].chomp!
 

data/lib/adam6050/handler/read.rb

@@ -3,6 +3,20 @@
 module ADAM6050
   module Handler
     # Allows registed senders to read the state.
+    #
+    # From the manual:
+    #   Name        Read Channel Status
+    #   Description This command requests that the specified ADAM-6000 module
+    #               return the status of its digital input channels.
+    #   Syntax      #01C\r
+    #   Response    !0100(data)(data)(data)(data)\r
+    #               (data) a 2-character hexadecimal value representing the
+    #               values of the digital input module.
+    #
+    # TODO: The manual clearly states that onlyt the status of the input
+    #       channels should be included in the response. There are however
+    #       examples out there that also include the output.
+    #
     class Read
       include Handler
 
@@ -10,7 +24,8 @@ module ADAM6050
       MESSAGE_PREAMBLE = '$016'
 
       # @param  state [Integer] the current state.
-      # @return [Array<Integer, String>] the next state and an optional reply.
+      # @return [Integer] the next state (always unchanged).
+      # @return [String] the reply.
       def handle(_, state, *)
         # From the manual:
         #   The first 2-character portion of the response (exclude the "!"

data/lib/adam6050/handler/status.rb

@@ -3,6 +3,9 @@
 module ADAM6050
   module Handler
     # Allows registed senders to read the IO status.
+    #
+    # I have so far not been able to find any documentation around this feature.
+    # The meaning of the rely is therefore currently unknown.
     class Status
       include Handler
 
@@ -11,7 +14,8 @@ module ADAM6050
 
       # @param  msg [String] the incomming message.
       # @param  state [Integer] the current state.
-      # @return [Array<Integer, String>] the next state and an optional reply.
+      # @return [Integer] the next state (always unchanged).
+      # @return [String] the reply.
       def handle(msg, state, *)
         reply =
           if msg == MESSAGE_PREAMBLE + "\r"

data/lib/adam6050/handler/write.rb

@@ -23,7 +23,8 @@ module ADAM6050
 
       # @param  msg [String] the incomming message.
       # @param  state [Integer] the current state.
-      # @return [Array<Integer, String>] the next state and an optional reply.
+      # @return [Integer] the next state (always unchanged).
+      # @return [String] the reply.
       def handle(msg, state, *)
         channel, value = parse msg
         next_state = if msg[3] == '1'

data/lib/adam6050/password.rb

@@ -15,6 +15,7 @@ module ADAM6050
   #   password = Password.new
   #
   #   password == 'anything' # => true
+  #
   class Password
     # Format errors should be raised whenever a plain text password longer than
     # 8 characters is passed. Note that only ascii characters are supported.
@@ -41,6 +42,15 @@ module ADAM6050
 
     private
 
+    # Transforms a plain text password into an 8 character string recognised by
+    # the ADAM-6050. The algorithm, if you can even call it that, used to
+    # perform the transformation was found by trial and error.
+    #
+    # @raise [FormatError] if the plain text password is longer than 8
+    #   characters.
+    #
+    # @param  plain [String] the plain text version of the password.
+    # @return [String] the obfuscated, 8 character password.
     def obfuscate(plain)
       codepoints = plain.codepoints
 

data/lib/adam6050/server.rb

@@ -15,6 +15,7 @@ module ADAM6050
 
     # @param  password [String] the plain text password to use when validating
     #   new clients.
+    # @param  logger [Logger] the logger to use.
     def initialize(password: nil, logger: Logger.new(STDOUT))
       @session  = Session.new
       @handlers = [
@@ -28,8 +29,17 @@ module ADAM6050
       @logger = logger
     end
 
+    # Starts a new UDP server that listens on the given port. The state is
+    # updated atomically and yielded to an optional block everytime a change is
+    # made. By returning `false` the block can cancel the state update. This
+    # call is blocking.
+    #
+    # @yield [Integer] the updated state.
+    # @yield [Integer] the old state.
+    #
     # @param  host [String] the host to listen on.
     # @param  port [Integer] the UDP port to listen on.
+    # @return [nil]
     def run(host: nil, port: DEFAULT_PORT, &block)
       logger.info "Listening on port #{port}"
 
@@ -40,9 +50,13 @@ module ADAM6050
           handle(handler, msg, sender, &block)
         end
       end
+      nil
     end
 
-    # Updates the state atomicly.
+    # Updates the state atomicly. The current state will be yielded to the given
+    # block and the return value used as the next state.
+    #
+    # @yield [Integer] the current state.
     def update
       @state_lock.synchronize do
         @state = yield @state
@@ -51,6 +65,13 @@ module ADAM6050
 
     private
 
+    # @yield see #abort_state_change?
+    #
+    # @param  handler [Handler] the handler selected to handle the message.
+    # @param  msg [String] the received message.
+    # @param  sender [UDPSource] the UDP client.
+    # @param  block [Proc]
+    # @return [nil]
     def handle(handler, msg, sender, &block)
       @session.validate! sender if handler.validate?
 
@@ -59,12 +80,22 @@ module ADAM6050
       return if abort_state_change?(next_state, &block)
       @state = next_state
 
-      sender.reply reply + "\r" if reply
+      return unless reply
+
+      sender.reply reply + "\r"
+      logger.debug reply
     rescue Session::InvalidSender => e
       sender.reply "?\r"
       logger.warn e.message
     end
 
+    # @yield [Integer] the next state.
+    # @yield [Integer] the current state.
+    #
+    # @param  next_state [Integer] the next state.
+    # @return [true] if the next state differ from the current and the
+    #   (optional) given block returns `false`.
+    # @return [false] otherwise.
     def abort_state_change?(next_state)
       return false if next_state == @state
 

data/lib/adam6050/session.rb

@@ -32,8 +32,9 @@ module ADAM6050
     # authenticated within the session. This can either be beacuse the sender
     # has not yet logged in, or beacuse an old login has expired.
     class InvalidSender < Error
+      # @param  sender [Socket::UDPSource] the originating sender.
       def initialize(sender)
-        super "Invalid sender: #{sender}"
+        super "#{self.class.name}: #{sender.remote_address.inspect}"
       end
     end
 
@@ -111,27 +112,43 @@ module ADAM6050
     def cleanup!(time: monotonic_timestamp)
       return if time < @next_cleanup
 
-      remove_expired! time, @timeout
+      delete_expired! time, @timeout
 
       @next_cleanup = time + @cleanup_interval
     end
 
     private
 
+    # @param  sender [Socket::UDPSource] the UDP client.
+    # @return [#hash] a unique identifier for the sender.
     def session_key(sender)
       sender.remote_address.ip_address
     end
 
+    # This is slightly faster than calling Time.now since no new object needs to
+    # be allocated.
+    #
+    # @return [Numeric] the current monotonic process time.
     def monotonic_timestamp
       Process.clock_gettime Process::CLOCK_MONOTONIC
     end
 
-    def expired?(sess_time, time, timeout)
+    # @param  last_seen [Numeric] the time when the client was last seen.
+    # @param  time [Numeric] the current time.
+    # @param  timeout [Numeric] the time after which expired clients should be
+    #   deleted.
+    # @return [false] if the time last seen is within the timeout.
+    # @return [true] otherwise.
+    def expired?(last_seen, time, timeout)
       threshold = time - timeout
-      sess_time < threshold
+      last_seen < threshold
     end
 
-    def remove_expired!(time, timeout)
+    # @param  time [Numeric] the current time.
+    # @param  timeout [Numeric] the time after which expired clients should be
+    #   deleted.
+    # @return [Hash] the session hash with expired clients deleted.
+    def delete_expired!(time, timeout)
       @session.delete_if { |_, t| expired? t, time, timeout }
     end
   end

data/lib/adam6050/version.rb

@@ -2,5 +2,5 @@
 
 module ADAM6050
   # @return [String] the ADAM6050 library version number.
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: adam6050
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Sebastian Lindberg
@@ -108,8 +108,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: This library implements a server that emulates the Advantech ADAM-6050
-  IO module.
+description: This library implements a server that emulates the functionality of the
+  network connected Advantech ADAM-6050 digital IO module. Specifically the UDP protocol
+  that the unit speaks has been reverse engineered. Since I don't have an actual device
+  to test with the response messages from the server may differ from what they should
+  be. It all works well enough for interfacing with Synology Surveillance Station
+  which is the original intent.
 email:
 - seb.lindberg@gmail.com
 executables: []