exsys 0.5 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f8a542193c2ef67c427b47ee5ee95c448ecb9f3aced7d1a763f4e3159340eb2
-  data.tar.gz: 04da256b271c0c43d07e258c808eff8659c2b95ecc03d7424ec8101d46f5c126
+  metadata.gz: b64ad35673afb17f7d07e21cd404043cf832637c9247a6697a08148ca781977e
+  data.tar.gz: fd871f3815d45d51731a686cda177a28d1fb8315c72dd9a299da91bfeee1a091
 SHA512:
-  metadata.gz: 6e2555919ac712c8b4d4064b4d4d9cd8e69d8aa74c3ce71dbb86be23deb6e20cf0be89907d7d41bf087010f139dec32dcdd6fd6b989ea21aad53a46e83721bf1
-  data.tar.gz: da9630c153d83bbedc4f840707aa32ac90f2320d038e43ae01d8bfea62db52c090d2da9a39694545518e7b4829cf197a3487e64c4c052a9233cc4a8254154a07
+  metadata.gz: 0ba2590f1165d88b24642f02a27b14ce5855f42c793e46ad1d2a697ebe6c795eeddb34ffb8e0d411988e920740de7bc189839545446107bdc850332c906d19a7
+  data.tar.gz: 6c9f2cdf259a245308884fba34601a3c7040c656659472b99d0c8fed03435bc8233bb5aad21eaf87970eb2503aabdce611a62d37448a2f74e177be15d65b43be

data/README.md

@@ -1,44 +1,236 @@
+# 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 starts at 1 and runs to however many ports
+the hub reports having: the gem asks it, rather than assuming sixteen.
+
+
+## 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     |
+| `status [PORT...]`  | Report the ports, one `N on` / `N off` per line |
+| `query`             | What the hub says it is: id, ports, firmware    |
+| `commit`            | Save the current port state to flash            |
+| `factory-reset`     | Factory reset; refuses without `--yes`          |
+| `reset`             | Reboot the hub; refuses without `--yes`         |
+
+> [!WARNING]
+> `reset` and `factory-reset` both drop power to every port, so both
+> refuse without `--yes`.  `reset` reboots the whole hub; it is not the
+> way to power-cycle one device, which is `off` then `on`.
+>
+> `factory-reset` is not the inverse of `commit`.  It issues the hub's
+> `RD` command: every port drops and the password goes back to `pass`.
+> Nothing in the protocol reloads a saved state -- the hub applies it
+> at power-on by itself.
+
+
+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             |
+| `-y`, `--yes`         | Mean a destructive action                     |
+| `-v`, `--verbose`     | Report the port states after a change         |
+| `-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.
+
+`status` prints one port per line, which greps and awks without
+parsing:
+
+~~~sh
+exsys-usb -d ${dev} status            # every port
+exsys-usb -d ${dev} status 3 7        # just those two
+exsys-usb -d ${dev} -v on 3           # switch, then report
+~~~
+
+### 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
-hub.on.off(4,5,6)
+# Chain turning on every port, then switch off ports 4, 5 and 6
+hub.on(:all).off(4,5,6)
 
-# Perform sequential toggle of all individual ports
-ExSYS::ManagedUSB::PORTS.each do |p|
+# Toggle each port in turn
+hub.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, ... ]
+~~~
+
+`on`, `off` and `toggle` want an explicit port list, and `:all` is how
+you say every port.  An empty list is refused rather than read as
+"all": `hub.off(*ports)` with an empty `ports` is the very same call as
+`hub.off`, so a computed list that came back empty would otherwise
+switch all sixteen.  The command line is unaffected -- naming no port
+there still means every port.
+
+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.
+
+A read-decide-write spans two calls, so it needs the line held across
+both.  Wrap them in a session:
+
+~~~ruby
+hub.session do
+    hub.on(1) unless hub.get[1]
+end
+~~~
+
+The hub will also describe itself, over the same line and without a
+password:
+
+~~~ruby
+hub.query       # => { id: "CENTOS", ports: 16, firmware: "v02",
+                #      raw: "CENTOS000516v02" }
+hub.port_count  # => 16, asked once and remembered
+~~~
+
+`:all` covers exactly those ports, and a port the hub does not have is
+refused.  The count is read from the same field the vendor's own tool
+reads, checked against it for hubs reporting 4, 8, 16 and 32 ports.
+
+It is asked once and kept for the life of the object, which outlasts
+any one connection -- the serial line is opened per operation, not
+held.  So a hub object is bound to the hub it first asked.  If the
+device is unplugged and another appears under the same name, build a
+new one; nothing in the library can notice the swap.
+
+`hub.factory_reset(confirm: true)` issues `RD` and carries the warning
+above.  The keyword is required: it is the one operation here that
+nothing undoes, and the one most easily reached by misunderstanding.
+It was called `restore` up to 0.6; the old name now raises rather than
+run.
+
+Sessions nest, so the methods above stay correct when called inside
+one, and a session belongs to the thread that opened it: another thread
+opens, and locks, its own line.  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

@@ -4,7 +4,7 @@ require 'optparse'
 require 'exsys'
 require 'exsys/managed-usb'
 
-$opts  = { :commit => false, :default => nil }
+$opts  = { :commit => false, :default => nil, :yes => false }
 parser = OptionParser.new do |op|
     op.banner = "Usage: #{op.program_name} ACTION"
 
@@ -12,8 +12,9 @@ parser = OptionParser.new do |op|
     op.on '-D', '--default=BOOLEAN', TrueClass, 'Default state if not specified'
     op.on '-p', '--password=STRING', 'Hub password'
     op.on '-c', '--commit',          'Commit change to flash memory'
+    op.on '-y', '--yes',             'Confirm a destructive action'
     op.on       '--debug[=FILE]',    'Debug output file'
-    op.on '-v', '--[no-]verbose',    'Run verbosely'
+    op.on '-v', '--[no-]verbose',    'Report port states after a change'
     op.on '-V', '--version',         'Version' do
         puts "ExSYS library : #{ExSYS::VERSION}"
         exit
@@ -23,33 +24,60 @@ 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)
+
+    # Naming no port on the command line still means every port.  The
+    # library wants that said outright rather than inferred from an
+    # empty list, so it is spelled out here.
+    ports = -> { ARGV.empty? ? [ ExSYS::ManagedUSB::ALL ]
+                             : ARGV.map(&:to_i) }
+
+    # One line per port, "3 on", which greps and awks cleanly.  Used by
+    # the status action and by --verbose after a change.
+    report = ->(only = []) {
+        state = $hub.get
+        (only.empty? ? $hub.ports : only).each do |p|
+            raise "invalid port: #{p}" unless state.key?(p)
+            puts "#{p} #{state[p] ? 'on' : 'off'}"
+        end
+    }
+    # Only meaningful after something changed.
+    verbose = -> { report.call if $opts[:verbose] }
 
-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])
+        $hub.on(*ports.call, commit: $opts[:commit])
+        verbose.call
 
     when 'off'
-        $hub.off(*ARGV.map(&:to_i), commit: $opts[:commit])
+        $hub.off(*ports.call, commit: $opts[:commit])
+        verbose.call
 
     when 'toggle'
-        $hub.toggle(*ARGV.map(&:to_i), commit: $opts[:commit])
+        $hub.toggle(*ports.call, commit: $opts[:commit])
+        verbose.call
 
     when 'set'
         t  = ExSYS::ManagedUSB::TRUE_LIST .to_h {|e| [ e.to_s, e ]}
@@ -61,16 +89,45 @@ begin
             [$1.to_i, tf[$2]]
         }
         $hub.set(a, $opts[:default], commit: $opts[:commit])
+        verbose.call
         
+    when 'status'
+        report.call(ARGV.map(&:to_i))
+
+    when 'query'
+        q = $hub.query
+        puts "id:       #{q[:id]}"
+        puts "ports:    #{q[:ports]}"
+        puts "firmware: #{q[:firmware]}"
+
     when 'commit'
         $hub.commit
 
     when 'reset'
-        $hub.reset
+        unless $opts[:yes]
+            raise 'reset reboots the hub, and every port loses power ' \
+                  'while it does; pass --yes to mean it'
+        end
+        $hub.reset(confirm: true)
 
+    when 'factory-reset'
+        unless $opts[:yes]
+            raise 'factory-reset drops every port and resets the ' \
+                  'password, and nothing undoes it; pass --yes to mean it'
+        end
+        $hub.factory_reset(confirm: true)
+
+    # A tombstone rather than an alias: anyone typing the old name is
+    # expecting the inverse of commit, which this never was.
     when 'restore'
-        $hub.restore
+        raise 'restore was renamed factory-reset: it restores the hub ' \
+              'to factory defaults, dropping every port and resetting ' \
+              'the password, and is not the inverse of commit'
+
+    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