exsys 0.5 → 0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f8a542193c2ef67c427b47ee5ee95c448ecb9f3aced7d1a763f4e3159340eb2
-  data.tar.gz: 04da256b271c0c43d07e258c808eff8659c2b95ecc03d7424ec8101d46f5c126
+  metadata.gz: ebdc824ab993ec59f3e5ba32fbef04a461e3f0354b8ea8723a17fa6125ba19a1
+  data.tar.gz: 783826b2949fc55f1f8b98c34aca2f39d79f9fe445acbe3863b33e1435f123e1
 SHA512:
-  metadata.gz: 6e2555919ac712c8b4d4064b4d4d9cd8e69d8aa74c3ce71dbb86be23deb6e20cf0be89907d7d41bf087010f139dec32dcdd6fd6b989ea21aad53a46e83721bf1
-  data.tar.gz: da9630c153d83bbedc4f840707aa32ac90f2320d038e43ae01d8bfea62db52c090d2da9a39694545518e7b4829cf197a3487e64c4c052a9233cc4a8254154a07
+  metadata.gz: '059792265ac5e663899a421176034d49bf555c61c5a3ca160f62cb5e53054fbb05e1b1fd5d13016f1003d0da9b9a033f1c20af17615e0852d506a0ce7031b52d'
+  data.tar.gz: 825f0ba1eab46d7fc3517954050d68a0b43bab0ce34d0cc05cfdf1696d87a2d2679a0b878d2691719dd04e393e0750dbee6dabab97fd55a34639df9ac502a264

data/README.md

@@ -1,44 +1,168 @@
+# exsys
 
-Controlling a [ExSYS Managed USB hub][1] without being 
-constrained by the official binary-only support.
+Switch the ports of an [ExSYS managed USB hub][1] on and off, from the
+shell or from Ruby, without being constrained by the vendor's
+binary-only tool.
 
+[![ExSYS EX-1526HMVS: managed 16-port USB 3.2 Gen 1 metal hub][hub]][1]
+
+
+## How it works
+
+The hub is driven over a serial line, not over USB: switching a port is
+a serial command, and the data path is not involved.  Every command is
+answered, and that reply is how the port state is read back and how a
+refused command is reported.
+
+~~~text
+  ┌───────────────┐                            ┌─────────────────────┐
+  │               │                            │                     │
+  │     host      │                            │     EX-1526HMVS     │
+  │               │  USB 3.2 (data)            │                     │
+  │               │◂──────────────────────────▸│     UP-A / UP-B     │
+  │               │                            │                     │
+  │   exsys-usb   │  serial, 9600 8N1          │                     │
+  │  (this gem)   │◂──────────────────────────▸│  management (FTDI)  │
+  │               │                            │                     │
+  │               │                            │  16 ports, 1 .. 16  │
+  └───────────────┘                            └─────────────────────┘
+~~~
+
+The serial line is `/dev/ttyU0` on FreeBSD, `/dev/ttyUSB0` on Linux.
+You need read and write access to it: the device is usually owned by a
+group such as `dialout` or `plugdev`, so check `ls -l` on it and add
+yourself to that group rather than reaching for `sudo`.
+
+The hub answers only to its password, `pass` unless it has been
+changed.  Port numbering runs from 1 to 16, and that range is fixed:
+this gem targets the 16-port model, so on a smaller hub the commands
+that take no port list would address ports that are not there.
+
+
+## Install
+
+~~~sh
+gem install exsys
+~~~
+
+The only runtime dependency is [uart][2], which pulls in `ruby-termios`
+-- a C extension, so a compiler and the Ruby headers must be available
+when it builds.
+
+Tested on Ruby 3.1, 3.3 and 3.4, on FreeBSD and on Linux.
+
+
+## Command line
+
+~~~sh
+dev=/dev/ttyU0
+exsys-usb -d ${dev} on                # All on
+exsys-usb -d ${dev} off               # All off
+exsys-usb -d ${dev} on 1 2            # Only turn on port 1 and 2
+exsys-usb -d ${dev} toggle 3, 5       # Toggle port 3 and 5
+exsys-usb -d ${dev} set 3:on 5:off    # Turn on port 3, turn off port 5
+exsys-usb -d ${dev} -D false set 3:on # Turn on port 3, all others off
+exsys-usb -d ${dev} -c on 1           # Turn on port 1, and save to flash
+~~~
+
+### Actions
+
+| Action              | Effect                                          |
+| :------------------ | :---------------------------------------------- |
+| `on [PORT...]`      | Power the listed ports, or every port           |
+| `off [PORT...]`     | Unpower the listed ports, or every port         |
+| `toggle [PORT...]`  | Invert the listed ports, or every port          |
+| `set PORT:STATE...` | Set the listed ports; `-D` decides the rest     |
+| `commit`            | Save the current port state to flash            |
+| `restore`           | Load the port state back from flash             |
+| `reset`             | Reset the hub; port power is *not* maintained   |
+
+A port state in `set` is written `PORT:STATE`, where `STATE` is one of
+`1`, `on`, `ON`, `true`, `TRUE`, `t`, `T` or their false counterparts
+`0`, `off`, `OFF`, `false`, `FALSE`, `f`, `F`.
+
+### Options
+
+| Option                | Meaning                                       |
+| :-------------------- | :-------------------------------------------- |
+| `-d`, `--device=DEV`  | Serial line to the hub (required)             |
+| `-p`, `--password=STR`| Hub password; defaults to `pass`              |
+| `-c`, `--commit`      | Also write the new state to flash             |
+| `-D`, `--default=BOOL`| State for the ports `set` does not name       |
+| `--debug[=FILE]`      | Trace the serial exchange to stderr, or FILE  |
+| `-V`, `--version`     | Print the library version                     |
+| `-h`, `--help`        | Print the usage                               |
+
+The debug trace shows every frame sent and received, with the password
+blanked out; when it is written to a file, that file is created
+readable only by you.
+
+### Exit status
+
+`0` when the command was carried out, `1` otherwise -- a malformed
+argument, a port outside 1..16, an unreachable serial line, or a
+command the hub refused.  The error goes to stderr, so a script can
+rely on the status:
 
-Executable
 ~~~sh
-dev=/dev/ttyU0 
-exsys-hub -d ${dev} on                # All on
-exsys-hub -d ${dev} off               # All off
-exsys-hub -d ${dev} on 1 2            # Only turn on port 1 and 2
-exsys-hub -d ${dev} toggle 3, 5       # Toggle port 3 and 5
-exsys-hub -d ${dev} set 3:on 5:off    # Turn on port 3, turn off port 5
-exsys-hub -d ${dev} -D false set 3:on # Turn on port 3, turn off all other ports
+exsys-usb -d /dev/ttyU0 off 3 || echo "could not switch port 3 off"
 ~~~
 
-Library:
+
+## Library
 
 ~~~ruby
-# Instanciate hub (Linux: ttyUSB?, FreeBSD: ttyU?)
+# Instantiate the hub (Linux: ttyUSB?, FreeBSD: ttyU?)
 # and enable debug output to stderr
 hub = ExSYS::ManagedUSB.new('/dev/ttyU0', debug: STDERR)
 
-# Chaining turning on all port, and swithing off ports 4,5,6
+# Chain turning on all ports, then switch off ports 4, 5 and 6
 hub.on.off(4,5,6)
 
-# Perform sequential toggle of all individual ports
+# Toggle each port in turn
 ExSYS::ManagedUSB::PORTS.each do |p|
     hub.toggle(p)
 end
 
-# Set ports states for 1 and 2
+# Set the state of ports 1 and 2
 hub.set({ 1 => true, 2 => false })
 
-# Set ports states for 1 and 2, forcing other ports to off
+# Set ports 1 and 2, forcing every other port off
 hub.set({ 1 => true, 2 => true }, false)
 ~~~
 
+Reading the state back has no command-line equivalent; it is a library
+call, and answers in whichever shape suits the caller:
+
+~~~ruby
+hub.get           # => { 1 => true, 2 => false, ... }
+hub.get(:on_off)  # => { :on => [1, 3], :off => [2, 4, ...] }
+hub.get(:on)      # => [ 1, 3 ]
+hub.get(:off)     # => [ 2, 4, ... ]
+~~~
+
+Switching is a read-modify-write, and the library holds the serial line
+-- locked -- across the whole exchange, so two processes driving the
+same hub cannot lose each other's changes.  The wire protocol is
+documented in the `ExSYS::ManagedUSB` class comment.
+
+
+## Tests
+
+~~~sh
+rake test          # or: ruby -Itest test/test_managed_usb.rb
+~~~
+
+The suite drives the library and the executable against a model of the
+hub's serial protocol (`test/support/`), so it needs neither a hub nor
+the `uart`/`termios` gems.
 
 
+## License
 
+MIT, see [LICENSE](LICENSE).
 
 
-[1]: https://www.exsys-shop.de/shopware/en/categories/hubsdocks/usb-hubs-managed/1263/managed-16-port-usb-3.2-gen-1-metal-hub-with-15kv-esd-surge-protection-din-rail?c=35
+[1]:   https://www.exsys.de/en/managed-16-port-usb-3.2-gen-1-metal-hub-with-15kv-esd-surge-protection-din-rail/EX-1526HMVS
+[2]:   https://rubygems.org/gems/uart
+[hub]: https://www.exsys.de/thumbnail/df/a9/63/1716816684/EX-1526HMVS_-_Managed_16-Port_USB_3.2_Gen_1_Metall_HUB_15KV_ESD-1_800x800.jpg

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+require 'rake/testtask'
+require 'yard'
+
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do |t|
+    t.test_files = FileList['test/test_*.rb']
+    t.verbose    = true
+    t.warning    = false
+end
+
+task :default => :test
+
+YARD::Rake::YardocTask.new do |t|
+    t.files         = [ 'lib/**/*.rb', 'ext/ucl.c' ]
+    t.options       = [ '-m', 'markdown' ]
+    t.stats_options = [ '--list-undoc' ]
+end

data/bin/exsys-usb

@@ -23,26 +23,32 @@ parser = OptionParser.new do |op|
         exit
     end    
 end
-parser.parse!(into: $opts)
 
-debug = if $opts.include?(:debug)
-              if $opts[:debug].nil?
-              then STDERR
-              else File.open($opts[:debug], File::RDWR|File::CREAT)
-              end
-          end
-$hub = ExSYS::ManagedUSB.new($opts[:device], $opts[:password],
-                             debug: debug)
+# Option parsing, debug file and hub creation all live inside the
+# rescue, so that their failures are reported the same way as a hub
+# failure instead of escaping as a backtrace.
+begin
+    parser.parse!(into: $opts)
 
+    # Appended and kept private: the trace carries the hub password,
+    # and opening RDWR without truncating used to leave the tail of a
+    # longer previous session behind, reading as if it were hub traffic.
+    debug = if $opts.include?(:debug)
+                if $opts[:debug].nil?
+                then STDERR
+                else File.open($opts[:debug],
+                               File::WRONLY|File::CREAT|File::APPEND, 0600)
+                end
+            end
+    $hub = ExSYS::ManagedUSB.new($opts[:device], $opts[:password],
+                                 debug: debug)
 
-begin
     case action = ARGV.shift
     when nil
         puts parser
         exit
 
     when 'on'
-        puts ARGV.map(&:to_i).join(',')
         $hub.on(*ARGV.map(&:to_i), commit: $opts[:commit])
 
     when 'off'
@@ -70,7 +76,11 @@ begin
 
     when 'restore'
         $hub.restore
+
+    else
+        raise "unknown action: #{action}"
     end
-#rescue => e
-#    $stderr.puts "#{parser.program_name}: #{e}"
+rescue => e
+    $stderr.puts "#{parser.program_name}: #{e}"
+    exit 1
 end

data/exsys.gemspec

@@ -18,13 +18,15 @@ Gem::Specification.new do |s|
     s.authors     = [ "Stéphane D'Alu" ]
     s.email       = [ 'stephane.dalu@insa-lyon.fr' ]
 
-    s.files       = %w[ README.md exsys.gemspec ] +
-                    Dir['lib/**/*.rb']
+    s.files       = %w[ README.md exsys.gemspec Rakefile ] +
+                    Dir['lib/**/*.rb'] +
+                    Dir['test/**/*.rb']
 
     s.bindir      = 'bin'
     s.executables << 'exsys-usb'
 
     s.add_dependency 'uart'
+    s.add_development_dependency 'minitest', '~>5'
     s.add_development_dependency 'yard', '~>0'
     s.add_development_dependency 'rake', '~>13'
 end

data/lib/exsys/managed-usb.rb

@@ -3,13 +3,52 @@ require "uart"
 module ExSYS
 
 # Control a ExSYS Managed USB hub
+#
+# The hub is commanded over a serial line, not over USB.  Each command
+# is a short ASCII frame closed by CR, and the hub answers G on success
+# or Exx on error.  GP is the exception: it needs no password, and it
+# answers the port state directly.
+#
+#     GP   read the port state      SP   set it, in RAM
+#     WP   write RAM to flash       FP   set it, in RAM and flash
+#     RD   restore RAM from flash   CP   change the password
+#     RH   reset the hub (no reply)
+#
+# A frame carries the whole 16-port state, so changing one port is a
+# read-modify-write: GP to read it, then SP to put it back.
+#
+#     ┌────┬──────────┬──────┬──────┐
+#     │ SP │ pass···· │ 0300 │ FFFF │
+#     └─┬──┴────┬─────┴──┬───┴──┬───┘
+#       │       │        │      └─────  port mask, 4 hex, always FFFF
+#       │       │        └────────────  port state, 4 hex, low byte first
+#       │       └─────────────────────  password, 8 chars (· = pad space)
+#       └─────────────────────────────  command, 2 chars
+#
+# The fields go out concatenated, with no separator: the frame above
+# is written as "SPpass    0300FFFF\r".
+#
+# Port n is bit n-1 of the state word, and the word is sent low byte
+# first, so ports 1 and 2 on is 0x0003 and reaches the wire as "0300":
+#
+#       port  8  7  6  5  4  3  2  1    16 15 14 13 12 11 10  9
+#       bit   0  0  0  0  0  0  1  1     0  0  0  0  0  0  0  0
+#           └───── low byte  03 ───┘   └──── high byte  00 ───┘
+#
+# The mask selects which ports the state word applies to; the library
+# always sends FFFF, i.e. all sixteen.
 class ManagedUSB
     SPEED      = 9600                     # @!visibility private
     PASSWORD   = 'pass'.freeze            # @!visibility private
     PORTS      = 1.upto(16).to_a.freeze   # @!visibility private
     TRUE_LIST  = [ 1, :on,  :ON,  :true,  :TRUE,  :t, :T, true  ].freeze # @!visibility private
     FALSE_LIST = [ 0, :off, :OFF, :false, :FALSE, :f, :F, false ].freeze # @!visibility private
-    
+
+    # Raised by #flock when the platform won't lock a character device
+    LOCK_ERRORS = [ Errno::EOPNOTSUPP, Errno::ENOTSUP, Errno::ENOLCK,
+                    Errno::EINVAL,      Errno::EBADF,
+                    NotImplementedError ].freeze # @!visibility private
+
     # Error handling class
     class Error < StandardError
     end
@@ -34,21 +73,21 @@ class ManagedUSB
     #
     # @param commit   [Boolean] Commit to flash memory
     def toggle(*ports, commit: false)
-        _set(_get ^ mask(ports, :all), commit: commit)
+        session { _set(_get ^ mask(ports, :all), commit: commit) }
     end
 
     # Turn on all or specified ports
     # 
     # @param commit   [Boolean] Commit to flash memory
     def on(*ports, commit: false)
-        _set(_get | mask(ports, :all), commit: commit)
+        session { _set(_get | mask(ports, :all), commit: commit) }
     end
 
     # Turn off all or specified ports
     # 
     # @param commit   [Boolean] Commit to flash memory
     def off(*ports, commit: false)
-        _set(_get & ~mask(ports, :all), commit: commit)
+        session { _set(_get & ~mask(ports, :all), commit: commit) }
     end
 
     # Set state for the specified ports
@@ -71,8 +110,6 @@ class ManagedUSB
     # @param default  [Boolean,nil] Default value to use if unspecified
     # @param commit   [Boolean]     Commit to flash memory
     def set(dataset, default = nil, commit: false)
-        val = _get
-
         # Normalize
         keys = dataset.keys        
         if (keys - PORTS).empty?
@@ -87,7 +124,9 @@ class ManagedUSB
         elsif (keys - [:on, :off]).empty?
             on  = Array(dataset[:on ])
             off = Array(dataset[:off])
-            
+
+            check_ports(on + off)
+
             unless (on & off).empty?
                 raise ArgumentError, "on/off overlap"
             end
@@ -106,16 +145,22 @@ class ManagedUSB
             end
         end
 
-        # Compute value
-        dataset.compact.each do |k,v|
-            flg = 1 << (k-1)
-            if v
-            then val |=  flg
-            else val &= ~flg
+        # Compute value and apply, holding the line for the whole
+        # read-modify-write so a concurrent process cannot interleave
+        # its own update between the read and the write.
+        session do
+            val = _get
+
+            dataset.compact.each do |k,v|
+                flg = 1 << (k-1)
+                if v
+                then val |=  flg
+                else val &= ~flg
+                end
             end
+
+            _set(val, commit: commit)
         end
-        
-        _set(val, commit: commit)
     end
 
     # Get hub current state for all ports
@@ -138,13 +183,16 @@ class ManagedUSB
         when :ports
             h
         when :on_off
-            h.reduce({}) {|acc, (k,v)|
-                acc.merge(v ? :on : :off => [ k ]) {|k,o,n| o + n  }
+            # Seeded with both keys, so that a hub with all its ports
+            # in the same state still answers the documented shape
+            # instead of omitting the empty one.
+            h.reduce({ :on => [], :off => [] }) {|acc, (k,v)|
+                acc.merge(v ? :on : :off => [ k ]) {|_,o,n| o + n  }
             }
         when :on
-            h.select {|k,v| v }.keys
+            h.select {|_,v| v }.keys
         when :off
-            h.reject {|k,v| v }.keys
+            h.reject {|_,v| v }.keys
         else
             raise ArgumentError
         end
@@ -152,19 +200,20 @@ class ManagedUSB
 
     # Restore port states from the flash memory
     def restore
-        action('RD', @password).then { self }
+        action('RD', @password, secrets: [ @password ]).then { self }
     end
 
     # Save the port states to the flash memory
     def commit
-        action('WP', @password).then { self }
+        action('WP', @password, secrets: [ @password ]).then { self }
     end
 
     # Perform a hub reset action
     #
     # @note power is not maintained accros a reset
     def reset
-        action('RH', @password, reply: false).then { self }
+        action('RH', @password,
+               reply: false, secrets: [ @password ]).then { self }
     end
 
     # Change the hub protection password
@@ -172,12 +221,21 @@ class ManagedUSB
         new = PASSWORD                           if new.nil?
         raise ArgumentError, 'password too long' if new.size > 8
         new_password = new.ljust(8)
-        action('CP', @password, new_password)
+        action('CP', @password, new_password,
+               secrets: [ @password, new_password ])
         @password = new_password
         self
     end
     
     private
+
+    def check_ports(ports)
+        ports.each do |p|
+            unless PORTS.include?(p)
+                raise ArgumentError, "invalid port: #{p.inspect}"
+            end
+        end
+    end
     
     def mask(ports, empty = :none)
         case empty
@@ -186,8 +244,9 @@ class ManagedUSB
             ports = PORTS if ports.empty?
         else raise ArgumentError
         end
-        
-        ports.reduce(0) {|acc, obj| acc |= 1 << (obj-1) }
+
+        check_ports(ports)
+        ports.reduce(0) {|acc, obj| acc | (1 << (obj-1)) }
     end
 
     def _get
@@ -196,7 +255,7 @@ class ManagedUSB
         if (data.size == 3) && (data[0] == 'E')
             raise Error, data[1..-1]
         elsif data.size != 8
-            raise Error
+            raise Error, "unexpected reply: #{data.inspect}"
         end
 
         [ data ].pack('H4').unpack1('v')
@@ -204,14 +263,51 @@ class ManagedUSB
 
     def _set(v, commit: false)
         dataset = ([v].pack('v').unpack1('H*') + 'ffff').upcase
-        action(commit ? 'FP' : 'SP', @password, dataset).then { self }
+        action(commit ? 'FP' : 'SP', @password, dataset,
+               secrets: [ @password ]).then { self }
     end
-    
-    
-    def action(*cmds, reply: true, check: true)
-        cmd = cmds.join
+
+    # Run a block with the serial line open and exclusively locked.
+    #
+    # Nested calls reuse the outer session, so that a read-modify-write
+    # wrapped in one holds the line across both the GP and the SP
+    # command rather than reopening in between.
+    def session
+        return yield @serial if @serial
+
         UART.open @line, SPEED do |serial|
-            @debug&.puts "<-- #{cmd}"
+            flock(serial)
+            begin
+                @serial = serial
+                yield serial
+            ensure
+                @serial = nil
+            end
+        end
+    end
+
+    # Take an exclusive lock on the serial line, keeping concurrent
+    # processes from interleaving their own read-modify-write.
+    #
+    # Not every platform locks a character device; where it is refused
+    # the operation carries on unlocked -- single-process use is
+    # unaffected, concurrent use stays racy -- and says so on the debug
+    # output rather than failing outright.
+    def flock(serial)
+        serial.flock(File::LOCK_EX)
+    rescue *LOCK_ERRORS => e
+        @debug&.puts "!!! serial line not lockable (#{e.class})"
+    end
+
+    # Blank out the passwords before a command reaches the debug output.
+    def redact(str, secrets)
+        secrets.reduce(str) {|acc, s| acc.gsub(s, '*' * s.size) }
+    end
+
+    def action(*cmds, reply: true, check: true, secrets: [])
+        cmd = cmds.join
+        session do |serial|
+            @debug&.puts "<-- #{redact(cmd, secrets)}"
             serial.write "#{cmd}\r"
             if reply
                 serial.read.chomp.tap do |data|

data/lib/exsys/version.rb

@@ -1,3 +1,3 @@
 module ExSYS
-    VERSION = 0.5  # Version
+    VERSION = '0.6'  # Version
 end

data/test/helper.rb

@@ -0,0 +1,60 @@
+require 'minitest/autorun'
+require 'fileutils'
+require 'stringio'
+require 'open3'
+require 'shellwords'
+require 'tmpdir'
+
+ROOT = File.expand_path('..', __dir__)
+
+# test/support carries the `uart` double, and must come before the real
+# gem so that nothing here ever touches a serial line.
+$LOAD_PATH.unshift File.join(ROOT, 'test', 'support')
+$LOAD_PATH.unshift File.join(ROOT, 'lib')
+
+require 'exsys'
+
+# Run the executable in a subprocess, against a file-backed FakeHub.
+#
+# Returns [stdout, stderr, status]; the hub's state is left in the file
+# so the caller can assert on what the ports actually did.
+module CLI
+    EXE = File.join(ROOT, 'bin', 'exsys-usb')
+
+    def exsys_usb(*args, env: {})
+        exsys_usb_raw([ '-d', '/dev/null', *args ], env: env)
+    end
+
+    # As above, but with nothing added to the arguments -- for running a
+    # command line exactly as some other artifact spells it.
+    def exsys_usb_raw(args, env: {})
+        Open3.capture3({ 'EXSYS_TEST_HUB' => hub_file }.merge(env),
+                       RbConfig.ruby,
+                       '-I', File.join(ROOT, 'test', 'support'),
+                       '-I', File.join(ROOT, 'lib'),
+                       EXE, *args)
+    end
+
+    # The hub the subprocesses share, as this test left it.
+    def hub = FakeHub.new(path: hub_file)
+
+    def hub_file = @hub_file ||= File.join(@tmp, 'hub')
+
+    # Put the shared hub into a known state -- a test needing the hub to
+    # hold a particular password calls this before running anything.
+    def seed_hub(password: FakeHub::DEFAULT_PASSWORD, state: 0x0000)
+        FileUtils.rm_f(hub_file)
+        FakeHub.new(path: hub_file, password: password.ljust(8), state: state)
+    end
+
+    def setup
+        super
+        @tmp = Dir.mktmpdir('exsys-test')
+        seed_hub
+    end
+
+    def teardown
+        FileUtils.remove_entry(@tmp) if @tmp
+        super
+    end
+end