exsys 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97086399976474a8e6d5c41ca473a6b2bd385dfe65bc1a1655301510b93ce68d
-  data.tar.gz: f14819b8e580dcec1374b6ea1360628b3980c6dd7a8ea7aeb6f87ee406de312b
+  metadata.gz: a4be13bb30c8ab3697d13b8b3c9f92fd398ffbd2d1f3cbd817470b3da313e521
+  data.tar.gz: 2b0059f98f7d2efe29789fdeb362faf6e4c63a5218cbc57d22593d978d42153f
 SHA512:
-  metadata.gz: 3f70740de8575d2e1982b890fd33f65bc200181e73f7854435233dc325642cefd9b10103e7edacf936f0fbae6b8de8329ab97a979072713a83f49bc17ea623f6
-  data.tar.gz: 57c4f9a96bb7cf8de062101b72720bc76350ef0098081bb036632a7f3672975630a8d8eb14aee2a1837f9e283dc0e13a1ec31fbc43a71882521ef6daa1851911
+  metadata.gz: 2438a668ebc64b1236ea4d3001f4c78c4682ca3754d7214c6e50d48aa55163ca78cec57496e1ab51af010079dc2e89cf8f5127bdd8be5240d85268cf1a2946df
+  data.tar.gz: 4e0005f569dff091a466f44161836ba256304450b5c7499461e7e3758fa00425e167a5a988e13cca4c8967c943483d8916983adfbf0682472ee02d73580fecd0

data/README.md

@@ -61,7 +61,7 @@ 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} 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
@@ -99,18 +99,18 @@ A port state in `set` is written `PORT:STATE`, where `STATE` is one of
 
 ### Options
 
-| Option                | Meaning                                       |
-| :-------------------- | :-------------------------------------------- |
-| `-d`, `--device=DEV`  | Serial line to the hub (required, but see      |
-|                       | `discover`)                                   |
-| `-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                               |
+| Option                    | Meaning                                      |
+| :------------------------ | :------------------------------------------- |
+| `-d`, `--device=DEV`      | Serial line to the hub (required, but see    |
+|                           | `discover`)                                  |
+| `-p`, `--password=STRING` | Hub password; defaults to `pass`             |
+| `-c`, `--commit`          | Also write the new state to flash            |
+| `-y`, `--yes`             | Mean a destructive action                    |
+| `-v`, `--[no-]verbose`    | Report the port states after a change        |
+| `-D`, `--default=BOOLEAN` | 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
@@ -128,8 +128,8 @@ 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
+argument, a port the hub does not have, an unreachable serial line, or
+a command the hub refused.  The error goes to stderr, so a script can
 rely on the status:
 
 ~~~sh
@@ -149,7 +149,7 @@ exsys-usb discover
 
 ~~~text
 /dev/ttyUSB0 A50285BI 1-1.2.4.4
-/dev/ttyUSB1 -        1-1.3
+/dev/ttyUSB1 - 1-1.3
 ~~~
 
 One line per adapter: the device to pass to `-d`, the FT232's own
@@ -207,7 +207,8 @@ Linux from 1 — so a path names a socket on the machine that reported
 it and does not travel to another.
 
 Discovery reads `/sys/class/tty` through `udevadm` on Linux and
-`dev.uftdi` through `sysctl` on FreeBSD; any other platform raises
+`dev.uftdi` with `dev.uhub` -- the adapters and the tree above them --
+through `sysctl` on FreeBSD; any other platform raises
 rather than answering an empty list, an empty list being a claim that
 nothing is attached.
 
@@ -248,8 +249,8 @@ hub.get(:off)     # => [ 2, 4, ... ]
 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.
+switch every port on the hub.  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
@@ -287,7 +288,9 @@ new one; nothing in the library can notice the swap.
 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.
+run.  The hub's password goes back to `pass`, and the object follows it
+there, so it stays usable afterwards -- but a later run of the tool
+against that hub must drop its `-p`.
 
 Sessions nest, so the methods above stay correct when called inside
 one, and a session belongs to the thread that opened it: another thread

data/Rakefile

@@ -1,9 +1,24 @@
 require 'bundler'
+require 'rake/clean'
 require 'rake/testtask'
 require 'yard'
 
 Bundler::GemHelper.install_tasks
 
+# What a build leaves behind.
+#
+# CLEAN is the intermediate that is rebuilt from the sources every
+# time: yard's object database.  CLOBBER adds the products themselves
+# -- rendered documentation, packaged gems -- which `rake yard` and
+# `rake build` put back.
+#
+# Every entry is a path this repository's own tasks write, and every
+# one of them is in .gitignore.  Nothing is listed by a wildcard that
+# could reach further than that: clobber is a delete, and a list that
+# grows to match somebody's files is how a clean target eats work.
+CLEAN.include('.yardoc', '_yardoc')
+CLOBBER.include('doc', 'rdoc', 'pkg', 'coverage', '*.gem')
+
 Rake::TestTask.new do |t|
     t.test_files = FileList['test/test_*.rb']
     t.verbose    = true
@@ -13,7 +28,7 @@ end
 task :default => :test
 
 YARD::Rake::YardocTask.new do |t|
-    t.files         = [ 'lib/**/*.rb', 'ext/ucl.c' ]
+    t.files         = [ 'lib/**/*.rb' ]
     t.options       = [ '-m', 'markdown' ]
     t.stats_options = [ '--list-undoc' ]
 end

data/lib/exsys/discovery.rb

@@ -220,6 +220,13 @@ class ManagedUSB
                 return nil unless pnp.is_a?(Hash)
                 return nil unless pnp[:vendor]  == "0x#{CTRL_VENDOR}" &&
                                   pnp[:product] == "0x#{CTRL_PRODUCT}"
+                # No ttyname, no candidate.  An adapter whose tty is
+                # not named yet has no line to hand anybody, and the
+                # answer this used to give was the WORST one available:
+                # '/dev/tty' + '' is /dev/tty, the caller's own
+                # controlling terminal, which a caller taking it for a
+                # hub would open and write command frames to.
+                return nil if Discovery.nonempty(dev[:ttyname]).nil?
                 { :device   => '/dev/tty' + dev[:ttyname].to_s,
                   :serial   => Discovery.nonempty(pnp[:sernum]),
                   :usb_path => self.usb_path(dev, tree) }
@@ -255,6 +262,7 @@ class ManagedUSB
                 bus    = nil
                 ports  = []
                 rooted = false
+                seen   = {}
                 while dev
                     loc = dev[:'%location']
                     unless loc.is_a?(Hash) && loc[:port]
@@ -263,7 +271,17 @@ class ManagedUSB
                     end
                     bus ||= loc[:bus]
                     ports.unshift(loc[:port])
-                    dev = tree[dev[:'%parent'].to_s]
+                    parent = dev[:'%parent'].to_s
+                    # A tree is what this walks, and a %parent chain
+                    # that returns to a device already on the way up is
+                    # not one.  No kernel prints that, but this parses
+                    # whatever it is handed, and the answer without the
+                    # guard is not a wrong path -- it is an unbounded
+                    # loop, which on a bench tool is a command that
+                    # never returns and never says why.
+                    break if seen[parent]
+                    seen[parent] = true
+                    dev = tree[parent]
                 end
                 return nil unless rooted && bus && !ports.empty?
                 "#{bus}-#{ports.join('.')}"

data/lib/exsys/managed-usb.rb

@@ -48,6 +48,8 @@ class ManagedUSB
     PASSWORD   = 'pass'.freeze            # @!visibility private
     PORTS      = 1.upto(16).to_a.freeze   # @!visibility private
     ALL        = :all                     # every port, said explicitly
+    # The shapes {#get} will answer in; see it for what each one is.
+    TYPES      = [ :ports, :on_off, :on, :off ].freeze
     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
 
@@ -135,15 +137,15 @@ class ManagedUSB
 
     # Set state for the specified ports
     #
-    # Port specification can have one of the folling format
+    # Port specification can have one of the following format
     #
     # 1. hash of port values: { 1 => :on, 2 => :off, ...}
     # 2. hash of port states: { :on => [1, 3], :off => 4 }
     #
     # In the case 1. the state values can be specified by
-    # 
-    # * True:  1, :on,  :ON,  :true,  :TRUE,  true 
-    # * False: 0, :off, :OFF, :false, :FALSE, false
+    #
+    # * True:  1, :on,  :ON,  :true,  :TRUE,  :t, :T, true
+    # * False: 0, :off, :OFF, :false, :FALSE, :f, :F, false
     #
     # The port states that are not specified will acquire the
     # value specified by the default parameter (nil being the
@@ -258,7 +260,16 @@ class ManagedUSB
     # * off   : [ 1, 2, 3, ... ]
     #
     # @param type [:ports, :on_off, :on, :off] Type of returned value
+    # @raise [ArgumentError] for a type outside {TYPES}
     def get(type = :ports)
+        # Checked before the line is opened.  An unknown type is a
+        # caller's typo and nothing the hub can answer, so spending a
+        # GP and a ?Q on it before saying so helps nobody.
+        unless TYPES.include?(type)
+            raise ArgumentError, "unknown type: #{type.inspect} " \
+                                 "(expected one of #{TYPES.inspect})"
+        end
+
         h = session do
             v = _get
             ports.reduce({}) {|acc, obj|
@@ -281,7 +292,10 @@ class ManagedUSB
         when :off
             h.reject {|_,v| v }.keys
         else
-            raise ArgumentError
+            # Unreachable: TYPES is checked on the way in.  Here so
+            # that a type added to that list and not to this case says
+            # so, rather than answering nil.
+            raise Error, "no reader for #{type.inspect}"
         end
     end
 
@@ -297,6 +311,8 @@ class ManagedUSB
     #   power-on by itself.  Confirmed against the vendor's own cusba
     #   tool, whose /D issues the same RD command and documents it as
     #   "restore to factory default settings".
+    # @note The password this object holds follows the hub's back to
+    #   {PASSWORD}, so it stays usable afterwards.
     # @param confirm [Boolean] must be true; the keyword is the point
     # @raise [ArgumentError] when not confirmed
     def factory_reset(confirm: false)
@@ -305,7 +321,15 @@ class ManagedUSB
                   'factory_reset drops every port and resets the ' \
                   'password, and nothing undoes it; pass confirm: true'
         end
-        action('RD', @password, secrets: [ @password ]).then { self }
+        action('RD', @password, secrets: [ @password ])
+        # RD puts the hub's password back to the default, so the one
+        # this object was holding is now the wrong one.  Forgetting it
+        # here is what keeps the NEXT command from being refused by a
+        # hub that did exactly what it was told: without this, every
+        # later call on a hub that had a password raises E01, and
+        # nothing on the wire says why.
+        @password = PASSWORD.ljust(8)
+        self
     end
 
     # @deprecated Renamed to {#factory_reset} in 1.0.
@@ -407,13 +431,18 @@ class ManagedUSB
     def normalize(dataset, default)
         keys = dataset.keys
         if (keys - ports).empty?
-            dataset = dataset.transform_values do |v|
-                case v
-                when * TRUE_LIST then true
-                when *FALSE_LIST then false
-                when nil
-                else raise ArgumentError
-                end
+            # to_h rather than transform_values, so that a value that
+            # is not a state can name the port it was given for: with
+            # sixteen of them, the offending value alone is not enough
+            # to find the typo by.
+            dataset = dataset.to_h do |k, v|
+                [ k, case v
+                     when * TRUE_LIST then true
+                     when *FALSE_LIST then false
+                     when nil
+                     else raise ArgumentError,
+                                "not a port state: #{k} => #{v.inspect}"
+                     end ]
             end
         elsif (keys - [:on, :off]).empty?
             on  = Array(dataset[:on ])
@@ -428,7 +457,9 @@ class ManagedUSB
             dataset = on .to_h {|k| [k, true  ] }
                         .merge(off.to_h {|k| [k, false ] })
         else
-            raise ArgumentError
+            raise ArgumentError,
+                  'dataset is neither { port => state } nor ' \
+                  "{ :on/:off => ports }: #{keys.inspect}"
         end
 
         unless default.nil?
@@ -537,7 +568,20 @@ class ManagedUSB
                 (serial.gets("\n") || '').chomp.tap do |data|
                     @debug&.puts "--> #{data}"
                     if check && data[0] != 'G'
-                        raise Error, data[1..-1]
+                        # Exx is the hub saying no, and xx is what it
+                        # said.  Anything else is NOT a code, and must
+                        # not be reported as one: data[1..-1] of ''
+                        # -- which is what a silent hub and a timed-out
+                        # read both look like -- is nil, and an Error
+                        # raised with nil carries the class name as its
+                        # message and nothing else.  Of a one-character
+                        # reply it is '', an error with no message at
+                        # all.  Either way the operator is told the
+                        # command failed and not one thing more, at
+                        # exactly the moment the line went quiet.
+                        code = data.match(/\AE(\S+)\z/)
+                        raise Error, code ? code[1]
+                                     : "unexpected reply: #{data.inspect}"
                     end
                 end
             end

data/lib/exsys/version.rb

@@ -1,3 +1,3 @@
 module ExSYS
-    VERSION = '1.1'  # Version
+    VERSION = '1.2'  # Version
 end

data/test/test_discovery.rb

@@ -148,6 +148,35 @@ class TestDiscovery < Minitest::Test
         assert_equal '0x0403', tree['uftdi0'][:'%pnpinfo'][:vendor]
     end
 
+    # '/dev/tty' + '' is /dev/tty -- the caller's own controlling
+    # terminal.  An adapter whose tty is not named yet has no line to
+    # offer, and offering that one would have a caller open the
+    # operator's screen and write hub command frames into it.
+    def test_an_adapter_with_no_tty_yet_is_not_a_candidate
+        t = D::FreeBSD.parse(<<~SYSCTL)
+            dev.uhub.0.%location=
+            dev.uhub.0.%parent=usbus1
+            dev.uftdi.0.%location=bus=1 hubaddr=1 port=2 devaddr=3
+            dev.uftdi.0.%parent=uhub0
+            dev.uftdi.0.%pnpinfo=vendor=0x0403 product=0x6001 sernum="AL03GD7X"
+        SYSCTL
+        assert_nil D::FreeBSD.candidate(t['uftdi0'], t)
+    end
+
+    # A %parent chain that comes back on itself is not a tree.  No
+    # kernel prints one; this parses whatever it is handed, and the
+    # answer without a guard is not a wrong path but a command that
+    # never returns.
+    def test_a_parent_chain_that_loops_terminates
+        t = D::FreeBSD.parse(<<~SYSCTL)
+            dev.uhub.1.%location=bus=1 hubaddr=1 port=1 devaddr=2
+            dev.uhub.1.%parent=uhub2
+            dev.uhub.2.%location=bus=1 hubaddr=2 port=2 devaddr=3
+            dev.uhub.2.%parent=uhub1
+        SYSCTL
+        assert_nil D::FreeBSD.usb_path(t['uhub1'], t)
+    end
+
     def test_nothing_attached_is_an_empty_list_not_an_error
         assert_empty freebsd('')
     end

data/test/test_managed_usb.rb

@@ -134,10 +134,25 @@ class TestManagedUSB < Minitest::Test
         assert_match(/overlap/, err.message)
     end
 
+    # Each refusal names what it refused.  These used to be bare
+    # ArgumentErrors, whose message was the class name and which left a
+    # caller with sixteen ports to find the typo among by hand.
     def test_set_refuses_a_mixed_or_unknown_notation
-        assert_raises(ArgumentError) { @usb.set({ :on => [ 1 ], 2 => :off }) }
-        assert_raises(ArgumentError) { @usb.set({ :bogus => [ 1 ] })        }
-        assert_raises(ArgumentError) { @usb.set({ 1 => :perhaps })          }
+        err = assert_raises(ArgumentError) {
+            @usb.set({ :on => [ 1 ], 2 => :off })
+        }
+        assert_match(/neither/, err.message)
+        assert_match(/:on/,     err.message)
+
+        err = assert_raises(ArgumentError) { @usb.set({ :bogus => [ 1 ] }) }
+        assert_match(/:bogus/, err.message)
+
+        err = assert_raises(ArgumentError) {
+            @usb.set({ 1 => true, 7 => :perhaps })
+        }
+        assert_match(/not a port state/, err.message)
+        assert_match(/7/,                err.message)
+        assert_match(/:perhaps/,         err.message)
     end
 
     ## get ###############################################################
@@ -178,8 +193,17 @@ class TestManagedUSB < Minitest::Test
         assert_equal [ 3, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 ], @usb.get(:on)
     end
 
+    # Refused by name, and before the line is opened: an unknown type
+    # is a typo and nothing the hub can answer, so it used to cost a GP
+    # and a ?Q and then raise a bare ArgumentError whose message was
+    # the class name.
     def test_get_refuses_an_unknown_type
-        assert_raises(ArgumentError) { @usb.get(:bogus) }
+        @usb.port_count                  # the one-off ?Q, out of the way
+        @hub.log.clear
+        err = assert_raises(ArgumentError) { @usb.get(:bogus) }
+        assert_match(/unknown type/, err.message)
+        assert_match(/:bogus/,       err.message)
+        assert_empty @hub.log, 'a typo must not reach the hub'
     end
 
     ## Flash and reset ###################################################
@@ -353,6 +377,24 @@ class TestManagedUSB < Minitest::Test
         assert_equal FakeHub::DEFAULT_PASSWORD, @hub.password
     end
 
+    # Regression: RD puts the hub's password back to the default, and
+    # this object went on holding the old one.  Every later command was
+    # then refused by the hub that had just done what it was told --
+    # E01, with nothing on the wire saying why.  Only reachable on a hub
+    # whose password is NOT the default, which is why the test above,
+    # running on a default-password hub, could not see it.
+    def test_factory_reset_forgets_the_password_the_hub_dropped
+        UART.hub = hub = FakeHub.new(password: 's3cret'.ljust(8))
+        usb      = ExSYS::ManagedUSB.new('/dev/null', 's3cret')
+
+        usb.factory_reset(confirm: true)
+        usb.on(2)
+
+        assert_equal [ 2 ], hub.ports_on
+        assert_equal 'SPpass    0200FFFF', hub.log.last,
+                     'the frame must carry the password the hub now has'
+    end
+
     def test_on_with_commit_writes_through_to_flash
         @usb.on(3, commit: true)
         @usb.on(4)
@@ -440,6 +482,38 @@ class TestManagedUSB < Minitest::Test
         assert_raises(ExSYS::ManagedUSB::Error) { @usb.get }
     end
 
+    # Regression, and the same defect as the one above on the other
+    # path: a command whose reply is CHECKED -- commit, reset,
+    # factory_reset, password, and the SP behind every switch -- read
+    # the reply as an Exx code without first establishing it was one.
+    # data[1..-1] of '' is nil, and an Error raised with nil carries the
+    # class name as its message: a silent hub, which is also what a
+    # timed-out read looks like, reported itself as
+    # 'exsys-usb: ExSYS::ManagedUSB::Error' and nothing more.
+    def test_a_silent_hub_says_so_on_a_checked_command
+        @hub.silent = true
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.commit }
+        assert_match(/unexpected reply/, err.message)
+    end
+
+    # ... and of a one-character reply it is '', an error with no
+    # message at all.  Anything that is not an Exx is reported as what
+    # arrived, not as a code the hub never sent.
+    def test_a_reply_too_short_to_be_a_code_is_not_read_as_one
+        @hub.garbage = 'X'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.commit }
+        assert_match(/unexpected reply/, err.message)
+        assert_match(/"X"/,              err.message)
+    end
+
+    # The Exx path itself still answers with the code alone, which is
+    # what the wrong-password test above reads.
+    def test_a_refusal_on_a_checked_command_is_still_just_its_code
+        @hub.garbage = 'E42'
+        err = assert_raises(ExSYS::ManagedUSB::Error) { @usb.commit }
+        assert_equal '42', err.message
+    end
+
     ## The serial line ###################################################
 
     # Regression: a read-modify-write used to close the line between the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exsys
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.2'
 platform: ruby
 authors:
 - Stéphane D'Alu