exsys 0.6 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebdc824ab993ec59f3e5ba32fbef04a461e3f0354b8ea8723a17fa6125ba19a1
-  data.tar.gz: 783826b2949fc55f1f8b98c34aca2f39d79f9fe445acbe3863b33e1435f123e1
+  metadata.gz: 97086399976474a8e6d5c41ca473a6b2bd385dfe65bc1a1655301510b93ce68d
+  data.tar.gz: f14819b8e580dcec1374b6ea1360628b3980c6dd7a8ea7aeb6f87ee406de312b
 SHA512:
-  metadata.gz: '059792265ac5e663899a421176034d49bf555c61c5a3ca160f62cb5e53054fbb05e1b1fd5d13016f1003d0da9b9a033f1c20af17615e0852d506a0ce7031b52d'
-  data.tar.gz: 825f0ba1eab46d7fc3517954050d68a0b43bab0ce34d0cc05cfdf1696d87a2d2679a0b878d2691719dd04e393e0750dbee6dabab97fd55a34639df9ac502a264
+  metadata.gz: 3f70740de8575d2e1982b890fd33f65bc200181e73f7854435233dc325642cefd9b10103e7edacf936f0fbae6b8de8329ab97a979072713a83f49bc17ea623f6
+  data.tar.gz: 57c4f9a96bb7cf8de062101b72720bc76350ef0098081bb036632a7f3672975630a8d8eb14aee2a1837f9e283dc0e13a1ec31fbc43a71882521ef6daa1851911

data/README.md

@@ -33,10 +33,12 @@ 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 runs from 1 to 16, and that range is fixed:
-this gem targets the 16-port model, so on a smaller hub the commands
-that take no port list would address ports that are not there.
+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
@@ -73,9 +75,23 @@ exsys-usb -d ${dev} -c on 1           # Turn on port 1, and save to flash
 | `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 |
+| `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            |
-| `restore`           | Load the port state back from flash             |
-| `reset`             | Reset the hub; port power is *not* maintained   |
+| `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
@@ -85,9 +101,12 @@ A port state in `set` is written `PORT:STATE`, where `STATE` is one of
 
 | Option                | Meaning                                       |
 | :-------------------- | :-------------------------------------------- |
-| `-d`, `--device=DEV`  | Serial line to the hub (required)             |
+| `-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                     |
@@ -97,6 +116,15 @@ 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
@@ -109,6 +137,81 @@ 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` 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
@@ -116,11 +219,11 @@ exsys-usb -d /dev/ttyU0 off 3 || echo "could not switch port 3 off"
 # and enable debug output to stderr
 hub = ExSYS::ManagedUSB.new('/dev/ttyU0', debug: STDERR)
 
-# Chain turning on all ports, then switch off ports 4, 5 and 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)
 
 # Toggle each port in turn
-ExSYS::ManagedUSB::PORTS.each do |p|
+hub.ports.each do |p|
     hub.toggle(p)
 end
 
@@ -141,10 +244,55 @@ hub.get(:on)      # => [ 1, 3 ]
 hub.get(:off)     # => [ 2, 4, ... ]
 ~~~
 
-Switching is a read-modify-write, and the library holds the serial line
--- locked -- across the whole exchange, so two processes driving the
-same hub cannot lose each other's changes.  The wire protocol is
-documented in the `ExSYS::ManagedUSB` class comment.
+`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

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
@@ -43,19 +44,40 @@ begin
     $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] }
+
     case action = ARGV.shift
     when nil
         puts parser
         exit
 
     when 'on'
-        $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 ]}
@@ -67,15 +89,64 @@ begin
             [$1.to_i, tf[$2]]
         }
         $hub.set(a, $opts[:default], commit: $opts[:commit])
+        verbose.call
         
+    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]}"
+        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}"

data/lib/exsys/discovery.rb

@@ -0,0 +1,314 @@
+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}"
+                { :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
+                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])
+                    dev = tree[dev[:'%parent'].to_s]
+                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