exsys 0.5

checksums.yaml

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

data/README.md

@@ -0,0 +1,44 @@
+
+Controlling a [ExSYS Managed USB hub][1] without being 
+constrained by the official binary-only support.
+
+
+Executable
+~~~sh
+dev=/dev/ttyU0 
+exsys-hub -d ${dev} on                # All on
+exsys-hub -d ${dev} off               # All off
+exsys-hub -d ${dev} on 1 2            # Only turn on port 1 and 2
+exsys-hub -d ${dev} toggle 3, 5       # Toggle port 3 and 5
+exsys-hub -d ${dev} set 3:on 5:off    # Turn on port 3, turn off port 5
+exsys-hub -d ${dev} -D false set 3:on # Turn on port 3, turn off all other ports
+~~~
+
+Library:
+
+~~~ruby
+# Instanciate hub (Linux: ttyUSB?, FreeBSD: ttyU?)
+# and enable debug output to stderr
+hub = ExSYS::ManagedUSB.new('/dev/ttyU0', debug: STDERR)
+
+# Chaining turning on all port, and swithing off ports 4,5,6
+hub.on.off(4,5,6)
+
+# Perform sequential toggle of all individual ports
+ExSYS::ManagedUSB::PORTS.each do |p|
+    hub.toggle(p)
+end
+
+# Set ports states for 1 and 2
+hub.set({ 1 => true, 2 => false })
+
+# Set ports states for 1 and 2, forcing other ports to off
+hub.set({ 1 => true, 2 => true }, false)
+~~~
+
+
+
+
+
+
+[1]: https://www.exsys-shop.de/shopware/en/categories/hubsdocks/usb-hubs-managed/1263/managed-16-port-usb-3.2-gen-1-metal-hub-with-15kv-esd-surge-protection-din-rail?c=35

data/bin/exsys-usb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'exsys'
+require 'exsys/managed-usb'
+
+$opts  = { :commit => false, :default => nil }
+parser = OptionParser.new do |op|
+    op.banner = "Usage: #{op.program_name} ACTION"
+
+    op.on '-d', '--device=DEV',      'Serial line to hub'
+    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       '--debug[=FILE]',    'Debug output file'
+    op.on '-v', '--[no-]verbose',    'Run verbosely'
+    op.on '-V', '--version',         'Version' do
+        puts "ExSYS library : #{ExSYS::VERSION}"
+        exit
+    end
+    op.on '-h', '--help',          'Help' do
+        puts op
+        exit
+    end    
+end
+parser.parse!(into: $opts)
+
+debug = if $opts.include?(:debug)
+              if $opts[:debug].nil?
+              then STDERR
+              else File.open($opts[:debug], File::RDWR|File::CREAT)
+              end
+          end
+$hub = ExSYS::ManagedUSB.new($opts[:device], $opts[:password],
+                             debug: debug)
+
+
+begin
+    case action = ARGV.shift
+    when nil
+        puts parser
+        exit
+
+    when 'on'
+        puts ARGV.map(&:to_i).join(',')
+        $hub.on(*ARGV.map(&:to_i), commit: $opts[:commit])
+
+    when 'off'
+        $hub.off(*ARGV.map(&:to_i), commit: $opts[:commit])
+
+    when 'toggle'
+        $hub.toggle(*ARGV.map(&:to_i), commit: $opts[:commit])
+
+    when 'set'
+        t  = ExSYS::ManagedUSB::TRUE_LIST .to_h {|e| [ e.to_s, e ]}
+        f  = ExSYS::ManagedUSB::FALSE_LIST.to_h {|e| [ e.to_s, e ]}
+        tf = t.merge(f) { raise "true/false conflict (internal error)" }
+        r  = tf.keys.map {|e| Regexp.escape(e)}
+        a = ARGV.to_h {|e| 
+            raise "invalid argument" unless e =~ /^(\d+):(#{r.join('|')})$/
+            [$1.to_i, tf[$2]]
+        }
+        $hub.set(a, $opts[:default], commit: $opts[:commit])
+        
+    when 'commit'
+        $hub.commit
+
+    when 'reset'
+        $hub.reset
+
+    when 'restore'
+        $hub.restore
+    end
+#rescue => e
+#    $stderr.puts "#{parser.program_name}: #{e}"
+end

data/exsys.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+require_relative 'lib/exsys/version'
+
+Gem::Specification.new do |s|
+    s.name        = 'exsys'
+    s.version     = ExSYS::VERSION
+    s.summary     = "ExSYS managed USB hub support"
+    s.description =  <<~EOF
+      
+      Provide command support to control ExSYS Managed USB hub.
+
+      EOF
+
+    s.homepage    = 'https://github.com/sdalu/ruby-exsys'
+    s.license     = 'MIT'
+
+    s.authors     = [ "Stéphane D'Alu" ]
+    s.email       = [ 'stephane.dalu@insa-lyon.fr' ]
+
+    s.files       = %w[ README.md exsys.gemspec ] +
+                    Dir['lib/**/*.rb']
+
+    s.bindir      = 'bin'
+    s.executables << 'exsys-usb'
+
+    s.add_dependency 'uart'
+    s.add_development_dependency 'yard', '~>0'
+    s.add_development_dependency 'rake', '~>13'
+end

data/lib/exsys/managed-usb.rb

@@ -0,0 +1,228 @@
+require "uart"
+
+module ExSYS
+
+# Control a ExSYS Managed USB hub
+class ManagedUSB
+    SPEED      = 9600                     # @!visibility private
+    PASSWORD   = 'pass'.freeze            # @!visibility private
+    PORTS      = 1.upto(16).to_a.freeze   # @!visibility private
+    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
+    
+    # Error handling class
+    class Error < StandardError
+    end
+
+    # Initialize object.
+    #
+    # @param line     [String]  Serial line
+    #                            (usually /dev/ttyU? or /dev/ttyUSB?)
+    # @param password [String]  Hub password
+    # @param debug    [IO]      Write debug output
+    def initialize(line, password = nil, debug: nil)
+        password ||= PASSWORD
+        if password.size > 8
+            raise ArgumentError, "password too long"
+        end
+        @line     = line
+        @password = password.ljust(8)
+        @debug    = debug
+    end
+
+    # Toggle all or specified ports
+    #
+    # @param commit   [Boolean] Commit to flash memory
+    def toggle(*ports, commit: false)
+        _set(_get ^ mask(ports, :all), commit: commit)
+    end
+
+    # Turn on all or specified ports
+    # 
+    # @param commit   [Boolean] Commit to flash memory
+    def on(*ports, commit: false)
+        _set(_get | mask(ports, :all), commit: commit)
+    end
+
+    # Turn off all or specified ports
+    # 
+    # @param commit   [Boolean] Commit to flash memory
+    def off(*ports, commit: false)
+        _set(_get & ~mask(ports, :all), commit: commit)
+    end
+
+    # Set state for the specified ports
+    #
+    # Port specification can have one of the folling 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
+    #
+    # The port states that are not specified will acquire the
+    # value specified by the default parameter (nil being the
+    # hub port current value)
+    #
+    # @param dataset  [Hash]        Port state specification
+    # @param default  [Boolean,nil] Default value to use if unspecified
+    # @param commit   [Boolean]     Commit to flash memory
+    def set(dataset, default = nil, commit: false)
+        val = _get
+
+        # Normalize
+        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
+            end
+        elsif (keys - [:on, :off]).empty?
+            on  = Array(dataset[:on ])
+            off = Array(dataset[:off])
+            
+            unless (on & off).empty?
+                raise ArgumentError, "on/off overlap"
+            end
+            
+            dataset = {}
+            dataset.merge!(on .to_h {|k| [k, true  ] })
+            dataset.merge!(off.to_h {|k| [k, false ] })
+        else
+            raise ArgumentError
+        end
+
+        # Fill unspecified
+        unless default.nil?
+            (PORTS - dataset.keys).each do |k|
+                dataset.merge!(k => default)
+            end
+        end
+
+        # Compute value
+        dataset.compact.each do |k,v|
+            flg = 1 << (k-1)
+            if v
+            then val |=  flg
+            else val &= ~flg
+            end
+        end
+        
+        _set(val, commit: commit)
+    end
+
+    # Get hub current state for all ports
+    #
+    # Return value depend of the asked type (default: ports)
+    #
+    # * ports : { 1 => true, 2 => false, ...}
+    # * on_off: { :on => [1,2,3,...], :off => [6,7,...] }
+    # * on    : [ 1, 2, 3, ... ]
+    # * off   : [ 1, 2, 3, ... ]
+    #
+    # @param type [:ports, :on_off, :on, :off] Type of returned value
+    def get(type = :ports)
+        val = _get
+        h   = PORTS.reduce({}) {|acc, obj|
+             acc.merge(obj => (val & (1 << (obj-1))).positive?)
+        }
+
+        case type
+        when :ports
+            h
+        when :on_off
+            h.reduce({}) {|acc, (k,v)|
+                acc.merge(v ? :on : :off => [ k ]) {|k,o,n| o + n  }
+            }
+        when :on
+            h.select {|k,v| v }.keys
+        when :off
+            h.reject {|k,v| v }.keys
+        else
+            raise ArgumentError
+        end
+    end
+
+    # Restore port states from the flash memory
+    def restore
+        action('RD', @password).then { self }
+    end
+
+    # Save the port states to the flash memory
+    def commit
+        action('WP', @password).then { self }
+    end
+
+    # Perform a hub reset action
+    #
+    # @note power is not maintained accros a reset
+    def reset
+        action('RH', @password, reply: false).then { self }
+    end
+
+    # Change the hub protection password
+    def password(new)
+        new = PASSWORD                           if new.nil?
+        raise ArgumentError, 'password too long' if new.size > 8
+        new_password = new.ljust(8)
+        action('CP', @password, new_password)
+        @password = new_password
+        self
+    end
+    
+    private
+    
+    def mask(ports, empty = :none)
+        case empty
+        when :none
+        when :all
+            ports = PORTS if ports.empty?
+        else raise ArgumentError
+        end
+        
+        ports.reduce(0) {|acc, obj| acc |= 1 << (obj-1) }
+    end
+
+    def _get
+        data = action('GP', check: false)
+
+        if (data.size == 3) && (data[0] == 'E')
+            raise Error, data[1..-1]
+        elsif data.size != 8
+            raise Error
+        end
+
+        [ data ].pack('H4').unpack1('v')
+    end
+
+    def _set(v, commit: false)
+        dataset = ([v].pack('v').unpack1('H*') + 'ffff').upcase
+        action(commit ? 'FP' : 'SP', @password, dataset).then { self }
+    end
+    
+    
+    def action(*cmds, reply: true, check: true)
+        cmd = cmds.join
+        UART.open @line, SPEED do |serial|
+            @debug&.puts "<-- #{cmd}"
+            serial.write "#{cmd}\r"
+            if reply
+                serial.read.chomp.tap do |data|
+                    @debug&.puts "--> #{data}"
+                    if check && data[0] != 'G'
+                        raise Error, data[1..-1]
+                    end
+                end
+            end
+        end
+    end
+end
+end
+

data/lib/exsys/version.rb

@@ -0,0 +1,3 @@
+module ExSYS
+    VERSION = 0.5  # Version
+end

data/lib/exsys.rb

@@ -0,0 +1,5 @@
+module ExSYS
+end
+
+require_relative 'exsys/version'
+require_relative 'exsys/managed-usb'

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: exsys
+version: !ruby/object:Gem::Version
+  version: '0.5'
+platform: ruby
+authors:
+- Stéphane D'Alu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: uart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+description: |2+
+
+  Provide command support to control ExSYS Managed USB hub.
+
+email:
+- stephane.dalu@insa-lyon.fr
+executables:
+- exsys-usb
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/exsys-usb
+- exsys.gemspec
+- lib/exsys.rb
+- lib/exsys/managed-usb.rb
+- lib/exsys/version.rb
+homepage: https://github.com/sdalu/ruby-exsys
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.19
+signing_key:
+specification_version: 4
+summary: ExSYS managed USB hub support
+test_files: []
+...