tribble-control 0.4.4

data/lib/tribble-control/cli/flash.rb

@@ -0,0 +1,102 @@
+require_relative '../cli'
+
+module TribbleControl
+
+class CLI
+class Flash < CLI::Command
+    DESCRIPTION = 'Flash devices'
+
+    # Every board goes through openocd: check for it up front.
+    OPENOCD     = true
+
+    # 'serial' first, so it is the default (Methods.first): boards stay
+    # powered and are flashed in parallel.  It needs serial= on every
+    # board, and it was measured on 2026-09-16 rather than assumed: with
+    # all four J-Links live, a flash addressed by serial landed on the
+    # board whose FICR.DEVICEID matched and left its neighbours' flash
+    # byte-for-byte unchanged, and power_cycle = after-flash still
+    # fired.  'power' -- every port cut, one board powered at a time,
+    # the bench left off -- is for a board whose serial is missing or
+    # wrong.
+    Methods  = [ 'serial', 'power' ]
+    Defaults = {}
+    Parser   = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROGNAME} flash [options] FIRMWARE [PORT|DEVNAME]..."
+
+        opts.separator ''
+        opts.separator "#{DESCRIPTION}."
+        opts.separator ''
+
+        opts.separator 'Options:'
+        opts.on '--power-cycle', 'Power the port off and on again after a',
+                                 'successful flash, whatever the configuration',
+                                 'says (power_cycle = after-flash)'
+    end
+
+    def flash(firmware, **hopts)
+        openocd('init', 'targets', 'reset init',
+                "flash write_image erase #{firmware}",
+                'reset run', **hopts)
+    end
+
+    def run(argv, **opts)
+        firmware = argv.shift
+        # Checked before any port is switched, not left to openocd once
+        # per board -- under --method power, after the whole bench has
+        # been cut.  openocd resolves the path against the current
+        # directory, as File.file? does.
+        raise Error, 'flash: FIRMWARE missing' if firmware.nil?
+        unless File.file?(firmware) && File.readable?(firmware)
+            raise Error, "flash: no readable firmware file '#{firmware}'"
+        end
+        tty&.info "Firmware: #{firmware}"
+
+        each_device(argv).map do |name, hopts={}|
+            flash(firmware, **hopts).tap do |ok|
+                if ok
+                then tty&.success "Device #{name}: Flashed"
+                else tty&.error   "Device #{name}: Flashed failed"
+                end
+                # A DWM1001-DEV comes out of the openocd flash sequence
+                # (reset init, write, reset run) in a state where its DW1000
+                # never reports a transmission again until the module is
+                # power-cycled: it receives, resolves nothing, and logs
+                # "our TX timestamps are missing".  An SWD reset alone does
+                # not do it, so only the flash needs the cycle.  The configuration
+                # says which boards need it (power_cycle = after-flash), so
+                # a flash by hand on the hub gets it right; --power-cycle
+                # forces it for any board.
+                if ok && (opts[:'power-cycle'] ||
+                          @cli.power_cycle?(name, 'after-flash'))
+                    _, port = @cli.name_port(name)
+                    if !hub.vbus?
+                        # Cutting the link would only re-enumerate the
+                        # probe; the board would keep the very state
+                        # the cycle exists to clear.  Skip it and say
+                        # so, in the same words as the protected case.
+                        tty&.warn "Device #{name}: NOT power-cycling," \
+                                  " #{hub} cuts the link, not the power" \
+                                  " (#{CLI::SWITCH_KEY} = link).  The board" \
+                                  ' may be in the state power_cycle' \
+                                  ' exists to avoid'
+                    elsif offable?(port)
+                        tty&.info "Device #{name}: power-cycling after flash"
+                        hub.off(port); sleep(2); hub.on(port)
+                    else
+                        # Saying it plainly matters: a DWM1001 that misses
+                        # its cycle comes out of the flash with a DW1000
+                        # that reports no transmission, which looks like a
+                        # radio fault rather than a skipped step.
+                        tty&.warn "Device #{name}: NOT power-cycling," \
+                                  " the configuration protects port #{port}." \
+                                  ' The board may be in the state' \
+                                  ' power_cycle exists to avoid'
+                    end
+                end
+            end
+        end.all?(&:itself)
+    end
+end
+end
+
+end

data/lib/tribble-control/cli/reset.rb

@@ -0,0 +1,39 @@
+require_relative '../cli'
+
+module TribbleControl
+
+class CLI
+class Reset < CLI::Command
+    DESCRIPTION = 'Reset devices over SWD'
+
+    # Every board goes through openocd: check for it up front.
+    OPENOCD     = true
+
+    Methods  = [ 'serial' ]
+    Defaults = {}
+    Parser   = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROGNAME} reset [options] [PORT|DEVNAME]..."
+
+        opts.separator ''
+        opts.separator "#{DESCRIPTION}."
+        opts.separator ''
+    end
+
+    def reset(**hopts)
+        openocd('init', 'targets', 'reset run', **hopts)
+    end
+
+    def run(argv, **_opts)
+        each_device(argv).map do |name, hopts={}|
+            reset(**hopts).tap do |ok|
+                if ok
+                then tty&.success "Device #{name}: Reseted"
+                else tty&.error   "Device #{name}: Reset failed"
+                end
+            end
+        end.all?(&:itself)
+    end
+end
+end
+
+end

data/lib/tribble-control/cli/serial.rb

@@ -0,0 +1,60 @@
+require_relative '../cli'
+
+module TribbleControl
+
+class CLI
+class Serial < CLI::Command
+    DESCRIPTION = "Report a debug probe's serial number"
+
+    # usb first, so it is the default: it reads the USB descriptor of
+    # one named board and disturbs nothing else.  Asking a board which
+    # serial it has should not black out the bench.
+    #
+    # power needs no USB topology.  It identifies a board by its being
+    # the only one powered -- the probe on it is then the only probe
+    # present, and reports its own serial -- at the cost of a power
+    # cycle of the whole bench, left off; see DEVICE SELECTION.
+    Methods  = [ 'usb', 'power' ]
+    Defaults = {}
+    Parser   = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROGNAME} serial [options] [PORT|DEVNAME]..."
+
+        opts.separator ''
+        opts.separator "#{DESCRIPTION}."
+        opts.separator ''
+    end
+
+    def get_serial(**hopts)
+        return Platform.usb_to_serial(hopts[:usb]) if hopts[:usb]
+
+        # --method power: this board is the only one powered, so the
+        # only probe enumerated is its own.  each_device has already
+        # refused more than one (CLI#only_probe!); the case below is
+        # the same rule kept where the answer is read.
+        probes = Platform.probe_consoles.keys
+        case probes.size
+        when 1 then probes.first
+        when 0 then nil
+        else
+            raise Error, "#{probes.size} probes are powered, so none of" \
+                         ' them can be attributed to this board:' \
+                         " #{probes.map {|p| p[0, 12] }.join(', ')}." \
+                         ' A probe on a port the configuration protects will' \
+                         ' do this; read it on Linux with --method usb'
+        end
+    end
+
+    def run(argv, **_opts)
+      each_device(argv).map do |name, hopts={}|
+            case serial = get_serial(**hopts)
+            when String then tty&.success "Serial for #{name}: #{serial}"
+            when nil    then tty&.warn    "No serial for #{name}"
+            else             tty&.error   "Accessing #{name} failed"
+            end
+            serial.is_a?(String)
+        end.all?(&:itself)
+    end
+end
+end
+
+end

data/lib/tribble-control/cli/usb.rb

@@ -0,0 +1,104 @@
+require_relative '../cli'
+
+module TribbleControl
+
+class CLI
+class USB < CLI::Command
+    DESCRIPTION = 'USB hub control'
+
+    # What 'set' accepts on the right of the colon.  The hub does not
+    # see these words: they are read here into true and false.
+    ON_WORDS  = %w[1 on ON true TRUE t T].freeze
+    OFF_WORDS = %w[0 off OFF false FALSE f F].freeze
+
+    Defaults = { :default => nil }
+    Parser   = OptionParser.new do |opts|
+        opts.banner = "Usage: #{PROGNAME} usb [options]" \
+                      " status|on|off|toggle|set [PORTS...]"
+
+        opts.separator ''
+        opts.separator "#{DESCRIPTION}."
+        opts.separator ''
+
+        opts.separator 'Options:'
+        opts.on '-D', '--default=BOOLEAN', TrueClass,
+                      'Default state if not specified'
+    end
+
+    def run(argv, **opts)
+        force = opts[:force]
+
+        case action = argv.shift
+        when 'status'
+            # Read-only: asks the hub for its port mask and prints it
+            # next to the configuration, so you can see what is on and what
+            # tribble-control is allowed to switch before you switch it.
+            state = hub.state
+            named = devices.to_h {|n| [ port_list([ n ]).first, n ] }
+            safe  = begin
+                        switchable
+                    rescue Error
+                        []
+            end
+            state.each do |port, on|
+                puts format('%2d  %-6s %-3s %s', port, named[port] || '-', on ? 'on' : 'off',
+safe.include?(port) ? '' : '(protected)')
+            end
+        when 'on'
+            # Powering up is always safe: no guard.
+            ports = port_list(argv)
+            # Every port, named outright: an empty list never reaches
+            # the hub meaning "all".
+            if ports.empty?
+            then tty&.info "Turning on all ports"
+                 hub.on(*hub.ports)
+            else tty&.info "Turning on ports: #{ports.join(' ')}"
+                 hub.on(*ports)
+            end
+        when 'off'
+            ports = offable(port_list(argv), force: force)
+            tty&.info "Turning off ports: #{ports.join(' ')}"
+            hub.off(*ports)
+            warn_link_only(ports)
+        when 'toggle'
+            # Toggle can power a port down, so it is guarded like 'off'.
+            ports = offable(port_list(argv), force: force)
+            tty&.info "Toggling ports: #{ports.join(' ')}"
+            hub.toggle(*ports)
+            warn_link_only(ports)
+        when 'set'
+            words = (ON_WORDS + OFF_WORDS).map {|w| Regexp.escape(w) }
+            a = argv.to_h {|e|
+                unless e =~ /^([^:]+):(#{words.join('|')})$/
+                    raise Error, "invalid argument (#{e})"
+                end
+                [ port_list([ $1 ]).first, ON_WORDS.include?($2) ]
+            }
+
+            # Vet the ports being powered down.
+            offable(a.reject {|_,on| on }.keys, force: force)
+
+            # A false default would sweep every unnamed port off, the
+            # protected ones included.  Expand it over the switchable
+            # ports instead, and leave the rest as they are.
+            default = opts[:default]
+            if (default == false) && !force
+                (switchable - a.keys).each {|p| a[p] = false }
+                default = nil
+            end
+
+            tty&.info "Applying port configuration:" \
+                      " #{a.map {|p, on| "#{p}:#{on ? 'on' : 'off'}" }.join(' ')}" \
+                      " (default=#{default&.to_s || 'current'})"
+            hub.set(a, default)
+            offs = a.reject {|_, on| on }.keys
+            offs = hub.ports - a.keys + offs if default == false
+            warn_link_only(offs.sort) unless offs.empty?
+        when nil   then raise Error, 'usb: action missing'
+        else            raise Error, "usb: unknown action (#{action})"
+        end
+    end
+end
+end
+
+end