exsys 1.0 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b64ad35673afb17f7d07e21cd404043cf832637c9247a6697a08148ca781977e
-  data.tar.gz: fd871f3815d45d51731a686cda177a28d1fb8315c72dd9a299da91bfeee1a091
+  metadata.gz: a4be13bb30c8ab3697d13b8b3c9f92fd398ffbd2d1f3cbd817470b3da313e521
+  data.tar.gz: 2b0059f98f7d2efe29789fdeb362faf6e4c63a5218cbc57d22593d978d42153f
 SHA512:
-  metadata.gz: 0ba2590f1165d88b24642f02a27b14ce5855f42c793e46ad1d2a697ebe6c795eeddb34ffb8e0d411988e920740de7bc189839545446107bdc850332c906d19a7
-  data.tar.gz: 6c9f2cdf259a245308884fba34601a3c7040c656659472b99d0c8fed03435bc8233bb5aad21eaf87970eb2503aabdce611a62d37448a2f74e177be15d65b43be
+  metadata.gz: 2438a668ebc64b1236ea4d3001f4c78c4682ca3754d7214c6e50d48aa55163ca78cec57496e1ab51af010079dc2e89cf8f5127bdd8be5240d85268cf1a2946df
+  data.tar.gz: 4e0005f569dff091a466f44161836ba256304450b5c7499461e7e3758fa00425e167a5a988e13cca4c8967c943483d8916983adfbf0682472ee02d73580fecd0

data/README.md

@@ -33,6 +33,9 @@ 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`.
 
+`exsys-usb discover` lists the lines that could be a hub, so you do not
+have to guess which one it is.  See [Finding the hub](#finding-the-hub).
+
 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.
@@ -58,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
@@ -73,6 +76,7 @@ exsys-usb -d ${dev} -c on 1           # Turn on port 1, and save to flash
 | `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 |
+| `discover`          | List the lines that could be a hub              |
 | `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`          |
@@ -95,17 +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)             |
-| `-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
@@ -123,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
@@ -132,6 +137,82 @@ exsys-usb -d /dev/ttyU0 off 3 || echo "could not switch port 3 off"
 ~~~
 
 
+## Finding the hub
+
+The management side of the hub is an ordinary FTDI FT232, so the host
+can be asked which serial lines are attached and what their serial
+numbers are:
+
+~~~sh
+exsys-usb discover
+~~~
+
+~~~text
+/dev/ttyUSB0 A50285BI 1-1.2.4.4
+/dev/ttyUSB1 - 1-1.3
+~~~
+
+One line per adapter: the device to pass to `-d`, the FT232's own
+serial number, and where it sits in the USB tree.  A `-` is a name this
+host cannot give — an EEPROM carrying no serial, or a topology that
+could not be established.  The same list from Ruby:
+
+~~~ruby
+ExSYS::ManagedUSB.available
+# => [ { :device => "/dev/ttyUSB0", :serial => "A50285BI",
+#        :usb_path => "1-1.2.4.4" },
+#      { :device => "/dev/ttyUSB1", :serial => nil,
+#        :usb_path => "1-1.3" } ]
+~~~
+
+**A candidate is not a hub.**  That FT232 is not an ExSYS part and
+carries no ExSYS id, so this lists every FT232 on the host — a
+USB-serial cable, a debug probe, a second hub — and nothing short of
+opening the line and asking (`?Q`, the `query` action) tells them
+apart.  Opening an unknown line means writing to somebody else's
+device, which is why this reports rather than decides.  A program that
+switches ports should not pick one silently when there is more than
+one: the ports of an unrelated hub exist, accept the frames, and report
+success.
+
+**Write down a serial or a path, not the line.**  The number in
+`/dev/ttyUSB1` is neither the hub's nor the USB device number: it is
+the usbserial (Linux) or ucom (FreeBSD) layer's own index, and it is
+the lowest one free when that adapter is probed.  So it depends on what
+else attached first, and it is reused — unplug whatever holds
+`ttyUSB0` and the next thing to attach takes `ttyUSB0`.  Two hubs can
+swap lines across a reboot, or while the machine is up.
+
+The other two are stable, in different ways, and which one is wanted
+depends on the question:
+
+| Name       | Stays with          | Answers                          |
+| :--------- | :------------------ | :------------------------------- |
+| `:serial`  | the adapter         | "this particular hub"            |
+| `:usb_path`| the socket          | "whatever is plugged in there"   |
+
+Move a hub to another port and its serial goes with it while its path
+changes; swap in a replacement hub and the path is unchanged while the
+serial is not.  For naming one particular hub the serial is the answer.
+The path is for a hub whose EEPROM carries no serial to be named by,
+and for a bench where the socket is the fixed thing.
+
+Both platforms report a path, by different means.  Linux states it, in
+`/sys`.  FreeBSD states nothing of the kind, so it is walked out of the
+sysctl tree: each device's `%location` gives the port it occupies on
+its parent and `%parent` names that parent, so collecting the ports
+from the adapter up to the root hub builds the same shape.  The
+numbering is each host's own, though — FreeBSD counts buses from 0 and
+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` 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.
+
+
 ## Library
 
 ~~~ruby
@@ -168,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
@@ -207,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/bin/exsys-usb

@@ -94,6 +94,30 @@ begin
     when 'status'
         report.call(ARGV.map(&:to_i))
 
+    # Which line to give -d.  Needs no hub and no password: it asks the
+    # HOST what is attached, so it works before anything is known.
+    #
+    # Three columns, "line serial usb-path", '-' for one the host does
+    # not report -- the same one-record-per-line shape as status, for
+    # the same reason.  What is listed is every FT232 on the host,
+    # which is not the same as every hub: see the library documentation
+    # for ExSYS::ManagedUSB.available.
+    when 'discover'
+        found = ExSYS::ManagedUSB.available
+        found.each do |c|
+            puts [ c[:device], c[:serial] || '-',
+                   c[:usb_path] || '-' ].join(' ')
+        end
+        # On stderr, and not as a row: stdout here is a listing meant
+        # to be read by awk, and a sentence in it would be parsed as an
+        # adapter.  An operator still wants to know the command ran and
+        # found nothing, which is what stderr is for.
+        if found.empty?
+            warn "#{parser.program_name}: no FTDI" \
+                 " #{ExSYS::ManagedUSB::CTRL_VENDOR}:" \
+                 "#{ExSYS::ManagedUSB::CTRL_PRODUCT} on this host"
+        end
+
     when 'query'
         q = $hub.query
         puts "id:       #{q[:id]}"

data/lib/exsys/discovery.rb

@@ -0,0 +1,332 @@
+require 'open3'
+require 'rbconfig'
+require 'shellwords'
+
+require_relative 'managed-usb'
+
+module ExSYS
+
+class ManagedUSB
+
+    # USB vendor and product of the hub's management adapter.
+    #
+    # It is not an ExSYS id.  The management side of the hub is an
+    # ordinary FTDI FT232, so this pair matches the hub AND every other
+    # FT232 attached to the host: a USB-serial cable, a debug probe,
+    # a second hub.  Nothing short of opening the line and asking it
+    # (?Q, see {#query}) tells them apart, and opening an unknown line
+    # means writing to somebody else's device.
+    #
+    # So {available} reports candidates, and choosing between them is
+    # the caller's -- see the note there.
+    CTRL_VENDOR  = '0403'.freeze
+    CTRL_PRODUCT = '6001'.freeze
+
+    # What a USB path looks like: a bus, a dash, and the chain of hub
+    # ports leading to the device -- 1-1.2.4.4.  Published so that a
+    # caller taking a device name from a human or a configuration file
+    # can tell one from a serial number without inventing the pattern
+    # again; the two cannot be confused, a serial never being digits
+    # and dashes in this shape.
+    USB_PATH = /\A\d+-\d+(?:\.\d+)*\z/
+
+    # Every serial line on this host that could be a managed hub.
+    #
+    # Each entry carries the names the host knows the adapter by:
+    #
+    #     [ { :device   => '/dev/ttyUSB0',
+    #         :serial   => 'AL03GD7X',
+    #         :usb_path => '1-1.2.4.4' },
+    #       { :device   => '/dev/ttyUSB1',
+    #         :serial   => nil,
+    #         :usb_path => '1-1.3' } ]
+    #
+    # `:device` is the line, as {#initialize} wants it.
+    #
+    # `:serial` is the FT232's own serial number, from its EEPROM, or
+    # nil for a chip carrying none -- an FT232R ships with one, an
+    # unprogrammed EEPROM is possible.
+    #
+    # `:usb_path` is where the adapter sits in the USB tree ({USB_PATH}),
+    # or nil where one cannot be established.  Linux states it; FreeBSD
+    # does not, and it is walked out of the sysctl tree instead (see
+    # Discovery::FreeBSD.usb_path).
+    #
+    # The shape is the same on both and the NUMBERING is each host's
+    # own: FreeBSD counts buses from 0 and Linux from 1, and neither
+    # orders its controllers for the other's benefit.  A path names a
+    # socket on the host that reported it, and does not travel.
+    #
+    # The two are stable in DIFFERENT ways, and which is wanted depends
+    # on the question.  A serial follows the adapter: move the hub to
+    # another socket, another port, another machine, and its serial goes
+    # with it.  A USB path follows the socket: whatever is plugged in
+    # there answers to it, including a replacement hub.  For naming one
+    # particular hub the serial is the answer; the path is for a hub
+    # with no serial to be named by, and for a bench where the socket is
+    # the thing that is fixed.
+    #
+    # Prefer one of them over the line for anything written down.  The number in
+    # /dev/ttyUSB1 is neither the hub's nor the USB device number: it is
+    # the usbserial (Linux) or ucom (FreeBSD) layer's own index, and it
+    # is the lowest one free when that adapter is probed.  It therefore
+    # depends on what else attached first, and it is reused -- unplug
+    # whatever holds ttyUSB0 and the next thing to attach takes
+    # ttyUSB0.  Two hubs can swap lines across a reboot, or while the
+    # machine is up.  The serial cannot move.
+    #
+    # ONE candidate is not proof that it is a hub, and several are not
+    # a list of hubs: see {CTRL_VENDOR}.  A caller that switches ports
+    # should therefore not pick one silently when there is more than
+    # one -- the ports of an unrelated hub exist, accept the frames,
+    # and report success.
+    #
+    # @return [Array<Hash>] one { :device, :serial } per FT232 found,
+    #                       in whatever order the host lists them
+    # @raise  [Error] if this platform has no way to look, or the tool
+    #                 that does the looking is not installed
+    def self.available = Discovery.available
+
+    # Asking the host what is attached.
+    #
+    # Each platform answers by running the tool that already knows --
+    # udevadm on Linux, sysctl on FreeBSD -- and each keeps the running
+    # and the parsing apart, so that the parsing can be tested against
+    # captured output on a machine with nothing plugged in.
+    module Discovery                                # @!visibility private
+
+        def self.available
+            case RbConfig::CONFIG['host_os']
+            when /^linux/   then Linux.available
+            when /^freebsd/ then FreeBSD.available
+            else raise Error, 'no hub discovery for this platform' \
+                              " (#{RbConfig::CONFIG['host_os']}):" \
+                              ' name the serial line instead'
+            end
+        end
+
+        # An absent USB string descriptor arrives as an empty one, not
+        # as nothing: udevadm prints ID_SERIAL_SHORT='' and uftdi's
+        # pnpinfo sernum="".  Both mean the EEPROM carries no serial,
+        # and nothing may be identified by ''.
+        def self.nonempty(str)
+            s = str.to_s
+            s.empty? ? nil : s
+        end
+
+        # What a platform reader ran, when it is not there at all.
+        # Reported rather than swallowed: an empty list would read as
+        # "no hub attached", which is a different thing and a lie.
+        def self.missing(tool, error)
+            raise Error, "cannot look for a hub: #{tool} (#{error.message})"
+        end
+
+        # Run a reader, and hand back only what it printed.
+        #
+        # Open3 with the arguments given SEPARATELY, and never a
+        # backtick: a backtick takes a single string, and a single
+        # string with a redirection or a metacharacter in it is run by
+        # /bin/sh -- which reports a missing binary ITSELF, as exit
+        # 127 and no output, so Errno::ENOENT never reaches Ruby and
+        # the rescue above becomes dead code.  That is exactly how
+        # this once answered "no hub attached" on a host with no
+        # sysctl.  Passing the arguments apart from the command runs
+        # it directly: no shell, no quoting, and a missing binary
+        # raises.
+        #
+        # stderr is dropped rather than redirected, for one message:
+        # with no FTDI ever attached the uftdi driver is not loaded,
+        # the oid does not exist, and sysctl says so on stderr while
+        # printing nothing.  That is not an error -- it is the answer,
+        # an empty list -- and a library has no business writing it to
+        # the terminal.  The exit status cannot tell the two apart
+        # either: sysctl exits 1 for an unknown oid, and 1 just the
+        # same when only one of several is unknown.
+        def self.run(tool, *args)
+            out, _err, _status = Open3.capture3(tool, *args)
+            out
+        rescue Errno::ENOENT, Errno::EACCES => e
+            self.missing(tool, e)
+        end
+
+
+        module Linux
+            UDEVADM = '/usr/bin/udevadm'
+
+            def self.available
+                Dir['/sys/class/tty/ttyUSB*'].sort.filter_map {|path|
+                    self.candidate(self.properties(path))
+                }
+            end
+
+            # One candidate, or nil for an adapter that is not an FT232.
+            def self.candidate(props)
+                return nil unless props[:ID_VENDOR_ID] == CTRL_VENDOR &&
+                                  props[:ID_MODEL_ID]  == CTRL_PRODUCT
+                { :device   => props[:DEVNAME],
+                  :serial   => Discovery.nonempty(props[:ID_SERIAL_SHORT]),
+                  :usb_path => self.usb_path(props[:DEVPATH]) }
+            end
+
+            # The adapter's own place in the USB tree, out of the sysfs
+            # path the tty hangs off.
+            #
+            # DEVPATH carries the whole chain -- the bus, every hub
+            # between, the device, its interface, then the tty:
+            #
+            #     .../usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/1-1.2.4.4:1.0/
+            #         ttyUSB0/tty/ttyUSB0
+            #
+            # Every hub on the way matches {USB_PATH} as well, so it is
+            # the LAST match that is the device itself; the interface
+            # component after it carries a ':' and matches nothing.
+            def self.usb_path(devpath)
+                devpath.to_s.split('/').grep(USB_PATH).last
+            end
+
+            # udevadm's --export format: KEY='value' a line, the value
+            # quoted the way a shell would want it.
+            def self.parse(export)
+                export.lines.to_h {|l| l.split('=', 2) }
+                      .transform_keys(&:to_sym)
+                      .transform_values {|v| Shellwords.split(v).join(' ') }
+            end
+
+            def self.properties(path)
+                self.parse(Discovery.run(UDEVADM, 'info', '-q', 'property',
+                                         '--export', path))
+            end
+        end
+
+
+        module FreeBSD
+            SYSCTL = '/sbin/sysctl'
+
+            # The two branches read together, in one call: the adapters
+            # themselves, and every hub, which is what the walk from an
+            # adapter up to its bus passes through and nothing else.
+            OIDS = %w[dev.uftdi dev.uhub].freeze
+
+            def self.available
+                tree = self.parse(self.read(*OIDS))
+                tree.filter_map {|name, dev|
+                    next unless name.start_with?('uftdi')
+                    self.candidate(dev, tree)
+                }
+            end
+
+            def self.candidate(dev, tree = {})
+                pnp = dev[:'%pnpinfo']
+                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) }
+            end
+
+            # The adapter's place in the USB tree, built by walking it.
+            #
+            # There is no /sys/bus/usb here and nothing states a path,
+            # but every piece of one is in the sysctl tree.  A device's
+            # %location gives the bus and the port it occupies on its
+            # parent, and its %parent names that parent -- always a
+            # uhub, up to the root hub, whose own %location is empty
+            # and whose parent is the usbus.  Collecting the ports on
+            # the way up and reversing them is the path:
+            #
+            #     uftdi0  port=4  parent=uhub5 ┐
+            #     uhub5   port=4  parent=uhub4 │  1-1.1.4.4
+            #     uhub4   port=1  parent=uhub2 │
+            #     uhub2   port=1  parent=uhub0 ┘  (root: stop)
+            #
+            # The shape is Linux's, and the numbering is this host's.
+            # FreeBSD counts buses from 0 and Linux from 1, and neither
+            # orders its controllers for the other's benefit, so the
+            # same socket is not the same string on the two systems.  A
+            # path names a socket on THIS host; see {USB_PATH}.
+            # A walk that does not REACH the root hub answers nil.
+            # Running off the end of the tree -- a parent nothing read
+            # describes -- leaves the ports collected so far, which
+            # read as a whole path and are not one: stopping one hub
+            # short of the root turns 1-1.1.4.4 into 1-4, a path that
+            # exists, names a socket, and is the wrong one.
+            def self.usb_path(dev, tree)
+                bus    = nil
+                ports  = []
+                rooted = false
+                seen   = {}
+                while dev
+                    loc = dev[:'%location']
+                    unless loc.is_a?(Hash) && loc[:port]
+                        rooted = true    # a root hub occupies no port
+                        break
+                    end
+                    bus ||= loc[:bus]
+                    ports.unshift(loc[:port])
+                    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('.')}"
+            end
+
+            # sysctl -e output, as { "uftdi0" => { key => value } }.
+            #
+            # Keyed by the device's name and not by its unit number:
+            # two branches are read at once, %parent names a parent
+            # that way, and unit numbers repeat across drivers.
+            #
+            # The two keys holding a list of their own -- %pnpinfo and
+            # %location -- are split into a hash of their own, since
+            # what is wanted is inside them.
+            def self.parse(output)
+                output.lines.map(&:chomp).reduce({}) {|acc, l|
+                    k, v     = l.split('=', 2)
+                    next acc if k.nil?
+                    dev, i, sk = k.split('.')[1..]
+                    # No unit number in it -- dev.uhub.%parent -- so
+                    # it describes the driver and not a device.
+                    next acc if sk.nil? || i !~ /\A\d+\z/
+                    if [ '%pnpinfo', '%location' ].include?(sk)
+                        # Not every token in one of these is a pair:
+                        # dev.acpi_timer.0.%pnpinfo is the bare word
+                        # 'unknown'.  Nothing outside a USB branch is
+                        # read today, but a parser that dies on one
+                        # driver's wording would take the hub with it.
+                        v = Shellwords.shellsplit(v.to_s)
+                                      .filter_map {|e|
+                                          k2, v2 = e.split('=', 2)
+                                          [ k2.to_sym, v2 ] if v2
+                                      }.to_h
+                    end
+                    acc.merge("#{dev}#{i}" => { sk.to_sym => v }) {
+                        |_k, o, n| o.merge(n)
+                    }
+                }
+            end
+
+            def self.read(*keys)
+                Discovery.run(SYSCTL, '-e', *keys)
+            end
+        end
+    end
+end
+
+end

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.0'  # Version
+    VERSION = '1.2'  # Version
 end

data/lib/exsys.rb

@@ -3,3 +3,4 @@ end
 
 require_relative 'exsys/version'
 require_relative 'exsys/managed-usb'
+require_relative 'exsys/discovery'

data/test/test_discovery.rb

@@ -0,0 +1,270 @@
+require_relative 'helper'
+
+# Finding the hub's serial line, per platform.
+#
+# The reading and the parsing are kept apart in Discovery precisely so
+# that this runs on a machine with nothing attached: what is asserted
+# here is the parsing, against the output the two tools produce, and
+# not that this host has a hub on it.
+class TestDiscovery < Minitest::Test
+    D = ExSYS::ManagedUSB::Discovery
+
+    # sysctl -e dev.uftdi dev.uhub.
+    #
+    # The uhub half is captured verbatim from a real FreeBSD host --
+    # two controllers, a Genesys hub on one and a chain of two TI hubs
+    # on the other -- because the walk that builds a USB path out of it
+    # is the part worth testing against something nobody invented.
+    #
+    # The uftdi half is written: three adapters, one hanging off the
+    # deepest hub, one whose EEPROM carries no serial, and an FT230X,
+    # which uftdi drives too and which is not what is wanted.
+    UHUB = <<~'SYSCTL'
+        dev.uhub.%parent=
+        dev.uhub.0.%location=
+        dev.uhub.0.%parent=usbus1
+        dev.uhub.1.%location=
+        dev.uhub.1.%parent=usbus0
+        dev.uhub.2.%location=bus=1 hubaddr=1 port=1 devaddr=3 interface=0 ugen=ugen1.3
+        dev.uhub.2.%parent=uhub0
+        dev.uhub.3.%location=bus=0 hubaddr=1 port=2 devaddr=2 interface=0 ugen=ugen0.2
+        dev.uhub.3.%parent=uhub1
+        dev.uhub.4.%location=bus=1 hubaddr=3 port=1 devaddr=4 interface=0 ugen=ugen1.4
+        dev.uhub.4.%parent=uhub2
+        dev.uhub.5.%location=bus=1 hubaddr=4 port=4 devaddr=5 interface=0 ugen=ugen1.5
+        dev.uhub.5.%parent=uhub4
+    SYSCTL
+
+    UFTDI = <<~'SYSCTL'
+        dev.uftdi.0.%desc=FTDI FT232R USB UART
+        dev.uftdi.0.%driver=uftdi
+        dev.uftdi.0.%location=bus=1 hubaddr=5 port=4 devaddr=9 interface=0 ugen=ugen1.9
+        dev.uftdi.0.%pnpinfo=vendor=0x0403 product=0x6001 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="AL03GD7X" release=0x0600 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.0.%parent=uhub5
+        dev.uftdi.0.ttyname=U0
+        dev.uftdi.0.ttyports=1
+        dev.uftdi.1.%desc=FTDI FT232R USB UART
+        dev.uftdi.1.%driver=uftdi
+        dev.uftdi.1.%location=bus=0 hubaddr=2 port=3 devaddr=7 interface=0 ugen=ugen0.7
+        dev.uftdi.1.%pnpinfo=vendor=0x0403 product=0x6001 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="" release=0x0600 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.1.%parent=uhub3
+        dev.uftdi.1.ttyname=U1
+        dev.uftdi.1.ttyports=1
+        dev.uftdi.2.%desc=FTDI FT230X Basic UART
+        dev.uftdi.2.%driver=uftdi
+        dev.uftdi.2.%pnpinfo=vendor=0x0403 product=0x6015 devclass=0x00 devsubclass=0x00 devproto=0x00 sernum="DT04H6789" release=0x1000 mode=host intclass=0xff intsubclass=0xff intprotocol=0xff
+        dev.uftdi.2.%parent=uhub3
+        dev.uftdi.2.ttyname=U2
+        dev.uftdi.2.ttyports=1
+    SYSCTL
+
+    # udevadm info -q property --export, for one FT232R.
+    UDEVADM = <<~'UDEV'
+        DEVNAME='/dev/ttyUSB0'
+        DEVPATH='/devices/pci0000:00/0000:00:14.0/usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/1-1.2.4.4:1.0/ttyUSB0/tty/ttyUSB0'
+        ID_BUS='usb'
+        ID_MODEL='FT232R_USB_UART'
+        ID_MODEL_ID='6001'
+        ID_SERIAL_SHORT='A50285BI'
+        ID_VENDOR_ID='0403'
+        MAJOR='188'
+        SUBSYSTEM='tty'
+    UDEV
+
+    def freebsd(text = UFTDI + UHUB)
+        tree = D::FreeBSD.parse(text)
+        tree.filter_map {|name, dev|
+            next unless name.start_with?('uftdi')
+            D::FreeBSD.candidate(dev, tree)
+        }
+    end
+
+    def test_freebsd_reports_the_line_the_serial_and_the_path
+        assert_equal({ :device   => '/dev/ttyU0',
+                       :serial   => 'AL03GD7X',
+                       :usb_path => '1-1.1.4.4' }, freebsd.first)
+    end
+
+    # Nothing on FreeBSD states a path: it is walked, %parent by
+    # %parent, and the ports collected on the way up.  uftdi0 sits on
+    # port 4 of uhub5, which is on port 4 of uhub4, which is on port 1
+    # of uhub2, which is on port 1 of the root hub of bus 1.
+    def test_the_path_is_walked_up_to_the_root_hub
+        tree = D::FreeBSD.parse(UFTDI + UHUB)
+        assert_equal '1-1.1.4', D::FreeBSD.usb_path(tree['uhub5'], tree)
+        assert_equal '1-1.1',   D::FreeBSD.usb_path(tree['uhub4'], tree)
+        assert_equal '0-2',     D::FreeBSD.usb_path(tree['uhub3'], tree)
+    end
+
+    # A root hub occupies no port on anything: its %location is empty.
+    def test_a_root_hub_has_no_path_of_its_own
+        tree = D::FreeBSD.parse(UFTDI + UHUB)
+        assert_nil D::FreeBSD.usb_path(tree['uhub0'], tree)
+    end
+
+    # Without the hubs there is nothing to walk.  The half-built
+    # answer is the dangerous one: the adapter's own port alone reads
+    # as a whole path -- 1-4 rather than 1-1.1.4.4 -- and names a real
+    # socket that is not this one.
+    def test_a_walk_that_never_reaches_the_root_is_nil
+        assert_nil freebsd(UFTDI).first[:usb_path]
+    end
+
+    # An unprogrammed EEPROM answers sernum="", and nothing may be
+    # identified by an empty string.
+    # The case the path exists for: no serial to be named by, and the
+    # socket is then the only stable name it has.
+    def test_an_empty_serial_is_nil_and_the_path_is_still_there
+        assert_equal({ :device   => '/dev/ttyU1',
+                       :serial   => nil,
+                       :usb_path => '0-2.3' }, freebsd[1])
+    end
+
+    # uftdi drives every FTDI part, not only the one the hub uses.
+    def test_another_ftdi_part_is_not_a_candidate
+        refute_includes freebsd.map {|c| c[:device] }, '/dev/ttyU2'
+        assert_equal 2, freebsd.size
+    end
+
+    # dev.uhub.%parent has no unit number in it and must not become a
+    # device.  Two branches are read at once, so the key is the name.
+    def test_the_driver_wide_key_is_not_taken_for_a_device
+        keys = D::FreeBSD.parse(UFTDI + UHUB).keys
+        assert_includes keys, 'uftdi0'
+        assert_includes keys, 'uhub5'
+        refute_includes keys, 'uhub'
+        assert_equal 9, keys.size
+    end
+
+    # Not every token in a %pnpinfo is a key=value pair --
+    # dev.acpi_timer.0.%pnpinfo is the bare word 'unknown' -- and a
+    # parser that died on one driver's wording would take the hub
+    # with it.
+    def test_a_field_that_is_not_a_pair_does_not_stop_the_parse
+        tree = D::FreeBSD.parse(<<~'SYSCTL')
+            dev.uftdi.0.%pnpinfo=unknown vendor=0x0403 product=0x6001 sernum="AL03GD7X"
+            dev.uftdi.0.ttyname=U0
+        SYSCTL
+        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
+
+    def test_linux_reports_the_line_the_serial_and_the_path
+        assert_equal({ :device   => '/dev/ttyUSB0',
+                       :serial   => 'A50285BI',
+                       :usb_path => '1-1.2.4.4' },
+                     D::Linux.candidate(D::Linux.parse(UDEVADM)))
+    end
+
+    # Every hub on the way to the device matches the shape too, so it
+    # is the last match that is the adapter -- not 1-1, not 1-1.2.
+    def test_the_usb_path_is_the_device_not_a_hub_above_it
+        assert_equal '1-1.2.4.4', D::Linux.usb_path(
+            '/devices/pci0000:00/usb1/1-1/1-1.2/1-1.2.4/1-1.2.4.4/' \
+            '1-1.2.4.4:1.0/ttyUSB0/tty/ttyUSB0')
+    end
+
+    def test_a_devpath_with_no_usb_component_has_no_path
+        assert_nil D::Linux.usb_path('/devices/platform/serial8250/ttyS0')
+    end
+
+    # The published shape, so that a caller can tell a path typed by a
+    # human from a serial number.
+    def test_what_a_usb_path_looks_like
+        assert_match     ExSYS::ManagedUSB::USB_PATH, '1-1.2.4.4'
+        assert_match     ExSYS::ManagedUSB::USB_PATH, '2-3'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, 'AL03GD7X'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, '1-1.2.4.4:1.0'
+        refute_match     ExSYS::ManagedUSB::USB_PATH, '/dev/ttyUSB0'
+    end
+
+    def test_linux_skips_an_adapter_that_is_not_the_right_part
+        props = D::Linux.parse(UDEVADM.sub("'6001'", "'6015'"))
+        assert_nil D::Linux.candidate(props)
+    end
+
+    def test_linux_unquotes_the_export_format
+        assert_equal '/dev/ttyUSB0', D::Linux.parse(UDEVADM)[:DEVNAME]
+    end
+
+    # The public name delegates, so that a caller has one thing to call.
+    def test_available_is_what_the_platform_answered
+        found = [ { :device   => '/dev/ttyU0', :serial => 'AL03GD7X',
+                    :usb_path => nil } ]
+        D.stub(:available, found) do
+            assert_equal found, ExSYS::ManagedUSB.available
+        end
+    end
+
+    # A platform with no way to look says so.  An empty list would read
+    # as "no hub attached", which is a different thing and a lie.
+    def test_a_platform_we_cannot_look_on_is_an_error
+        RbConfig::CONFIG.stub(:[], 'solaris2.11') do
+            e = assert_raises(ExSYS::ManagedUSB::Error) { D.available }
+            assert_match(/no hub discovery for this platform/, e.message)
+            assert_match(/solaris2\.11/,                       e.message)
+        end
+    end
+
+    def test_a_missing_tool_is_an_error_too
+        e = assert_raises(ExSYS::ManagedUSB::Error) {
+            D.missing('/sbin/sysctl', Errno::ENOENT.new('/sbin/sysctl'))
+        }
+        assert_match(%r{cannot look for a hub: /sbin/sysctl}, e.message)
+    end
+
+    # Regression, and the reason Discovery.run exists.  This reader
+    # once ran `sysctl ... 2>/dev/null` in a backtick; the redirection
+    # made Ruby hand the string to /bin/sh, which reports a missing
+    # binary itself as exit 127 with no output, so Errno::ENOENT never
+    # reached the rescue and a host with no sysctl answered "no hub
+    # attached" -- the exact lie the comment there warns against.
+    #
+    # The status cannot stand in for it either: sysctl exits 1 for an
+    # unknown oid, which is the legitimate empty answer.
+    def test_a_reader_that_is_not_installed_raises_rather_than_answering_none
+        e = assert_raises(ExSYS::ManagedUSB::Error) {
+            D.run('/nonexistent/sysctl', '-e', 'dev.uftdi')
+        }
+        assert_match(%r{cannot look for a hub: /nonexistent/sysctl},
+                     e.message)
+    end
+
+    # ... and a reader that IS installed, asked for an oid this host
+    # has not got, answers nothing at all rather than raising.
+    def test_an_oid_that_does_not_exist_is_an_empty_answer
+        assert_empty D.run('/usr/bin/env', 'true')
+    end
+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.0'
+  version: '1.2'
 platform: ruby
 authors:
 - Stéphane D'Alu
@@ -81,11 +81,13 @@ files:
 - bin/exsys-usb
 - exsys.gemspec
 - lib/exsys.rb
+- lib/exsys/discovery.rb
 - lib/exsys/managed-usb.rb
 - lib/exsys/version.rb
 - test/helper.rb
 - test/support/fake_hub.rb
 - test/support/uart.rb
+- test/test_discovery.rb
 - test/test_exsys_usb.rb
 - test/test_managed_usb.rb
 - test/test_readme.rb