exsys 0.6 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebdc824ab993ec59f3e5ba32fbef04a461e3f0354b8ea8723a17fa6125ba19a1
-  data.tar.gz: 783826b2949fc55f1f8b98c34aca2f39d79f9fe445acbe3863b33e1435f123e1
+  metadata.gz: b64ad35673afb17f7d07e21cd404043cf832637c9247a6697a08148ca781977e
+  data.tar.gz: fd871f3815d45d51731a686cda177a28d1fb8315c72dd9a299da91bfeee1a091
 SHA512:
-  metadata.gz: '059792265ac5e663899a421176034d49bf555c61c5a3ca160f62cb5e53054fbb05e1b1fd5d13016f1003d0da9b9a033f1c20af17615e0852d506a0ce7031b52d'
-  data.tar.gz: 825f0ba1eab46d7fc3517954050d68a0b43bab0ce34d0cc05cfdf1696d87a2d2679a0b878d2691719dd04e393e0750dbee6dabab97fd55a34639df9ac502a264
+  metadata.gz: 0ba2590f1165d88b24642f02a27b14ce5855f42c793e46ad1d2a697ebe6c795eeddb34ffb8e0d411988e920740de7bc189839545446107bdc850332c906d19a7
+  data.tar.gz: 6c9f2cdf259a245308884fba34601a3c7040c656659472b99d0c8fed03435bc8233bb5aad21eaf87970eb2503aabdce611a62d37448a2f74e177be15d65b43be

data/README.md

@@ -34,9 +34,8 @@ group such as `dialout` or `plugdev`, so check `ls -l` on it and add
 yourself to that group rather than reaching for `sudo`.
 
 The hub answers only to its password, `pass` unless it has been
-changed.  Port numbering runs from 1 to 16, and that range is fixed:
-this gem targets the 16-port model, so on a smaller hub the commands
-that take no port list would address ports that are not there.
+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 +72,22 @@ 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 |
+| `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
@@ -88,6 +100,8 @@ A port state in `set` is written `PORT:STATE`, where `STATE` is one of
 | `-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                     |
@@ -97,6 +111,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
@@ -116,11 +139,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 +164,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,40 @@ begin
             [$1.to_i, tf[$2]]
         }
         $hub.set(a, $opts[:default], commit: $opts[:commit])
+        verbose.call
         
+    when 'status'
+        report.call(ARGV.map(&:to_i))
+
+    when 'query'
+        q = $hub.query
+        puts "id:       #{q[:id]}"
+        puts "ports:    #{q[:ports]}"
+        puts "firmware: #{q[:firmware]}"
+
     when 'commit'
         $hub.commit
 
     when 'reset'
-        $hub.reset
+        unless $opts[:yes]
+            raise 'reset reboots the hub, and every port loses power ' \
+                  'while it does; pass --yes to mean it'
+        end
+        $hub.reset(confirm: true)
+
+    when 'factory-reset'
+        unless $opts[:yes]
+            raise 'factory-reset drops every port and resets the ' \
+                  'password, and nothing undoes it; pass --yes to mean it'
+        end
+        $hub.factory_reset(confirm: true)
 
+    # A tombstone rather than an alias: anyone typing the old name is
+    # expecting the inverse of commit, which this never was.
     when 'restore'
-        $hub.restore
+        raise 'restore was renamed factory-reset: it restores the hub ' \
+              'to factory defaults, dropping every port and resetting ' \
+              'the password, and is not the inverse of commit'
 
     else
         raise "unknown action: #{action}"