tribble-control 0.4.4

data/man/man1/tribble-control.1

@@ -0,0 +1,1483 @@
+.Dd October 7, 2026
+.Dt TRIBBLE-CONTROL 1
+.Os
+.Sh NAME
+.Nm tribble-control
+.Nd power, flash and monitor the devices on a switchable USB hub
+.Sh SYNOPSIS
+.Nm
+.Op Fl d Ar DEV
+.Op Fl -hub Ar KIND
+.Op Fl C Ar FILE
+.Op Fl m Ar TYPE
+.Op Fl W Ar SECONDS
+.Op Fl p Ar STRING
+.Op Fl -openocd Ar PATH
+.Op Fl F
+.Op Fl v
+.Op Fl -debug Ns Oo = Ns Ar FILE Oc
+.Ar command
+.Op command options
+.Op Ar PORT | DEVNAME ...
+.Nm
+.Fl -man | -help | -version
+.Sh DESCRIPTION
+The hub switches its ports independently, and there are two kinds of
+it.
+The ExSYS managed hub, the default, switches VBUS on each of its
+sixteen sockets over an FT232 serial line wired inside it, and
+tribble\-control drives that line.
+Any standard USB hub with per\-port power switching is the other
+\(em 'hub = usb' in the configuration, or \-\-hub usb \(em and it is switched on
+the bus itself, with hub\-class requests through
+.Xr usbconfig 8 ,
+which makes it
+.Fx
+only for now.
+See THE HUB.
+For a board on either that
+carries a debug probe, tribble\-control additionally speaks SWD through
+openocd and reads the board's console over USB CDC.
+Which probe and
+which chip a board needs is the configuration's business (interface= and
+target=), so the family it belongs to is not built in; the bench is
+nRF52 today, and that is the default, not a requirement.
+Everything
+else on the hub is only an electrical load \(em see PROTECTED PORTS.
+.Bd -literal
+tribble\-control \-C tribble.conf flash zephyr.hex alpha beta
+stdbuf \-oL tribble\-control \-C tribble.conf connect \-\-off gamma epsilon \e
+    | tee twr.log
+.Ed
+.Pp
+It lives on the host owning the hub, alongside tribble.conf.
+It is a gem, so
+.Ic gem install tribble-control
+\(em from a built .gem, or
+.Ic rake install
+in a checkout \(em puts
+.Nm
+on PATH with its dependencies and needs nothing further.
+.Pp
+A checkout with a vendored bundle works too, and is what a host that
+should not have gems installed system\-wide wants:
+.Ic bundle install --path vendor
+followed by
+.Ic bundle binstubs tribble-control
+writes bin/tribble\-control, which sets that bundle up before loading
+anything.
+Run that one from the directory holding the bundle.
+.Sh THE HUB
+.Bd -literal
+the host running tribble\-control
+      │
+      │  FT232R ──▸ /dev/ttyUSB0        the hub's control line.  It is
+      │             9600 8N1            internal to the hub: it is NOT
+      ▾                                 one of the 16 switched sockets.
+┌───────────────────────────────────────────────────────────────────┐
+│                   ExSYS 16\-port managed USB hub                   │
+│                                                                   │
+│    bank 1          bank 2          bank 3          bank 4         │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
+│  │  1       │    │  5       │    │  9       │    │ 13       │     │
+│  │  2       │    │  6       │    │ 10       │    │ 14       │     │
+│  │  3       │    │  7       │    │ 11       │    │ 15       │     │
+│  │  4       │    │  8       │    │ 12       │    │ 16       │     │
+│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
+└───────────────────────────────────────────────────────────────────┘
+    Sixteen independently switched sockets.  What is on each is the
+    configuration's business, not this diagram's: a socket may carry a board
+    the tool drives over SWD, or something it only powers and never
+    talks to, or nothing at all.  Sockets in the second class are what
+    PROTECTED PORTS exists for.
+.Ed
+.Pp
+Ports are numbered 1 to 16 across four internal banks of four.
+These are
+the hub's own numbers, the ones the configuration and every command use; whether
+the sockets are silkscreened that way is another matter, so count banks
+left to right and sockets top to bottom if you are looking for one by hand.
+.Pp
+The FT232 control adapter enumerates at the last position of the hub's
+internal tree (USB path 1\-1.2.4.4), which makes it look as though it
+occupies port 16.
+It does not: it is wired inside the hub and is not
+switched.
+Port 16 is an ordinary socket like the other fifteen.
+The one
+consequence is that a board must never be put on port 16: \-\-method usb
+would compute the path 1\-1.2.4.4 for it and address the FT232 instead.
+.Pp
+A port that only supplies power tells the tool nothing about what is on
+it, so if you need to reboot one device in particular, establish which
+socket it is physically first.
+Nothing on such a port communicates with
+the host, and the configuration records a name and a port, not what is plugged
+in.
+.Pp
+The host running tribble\-control is not powered from the hub, so no hub
+port can cut power to the machine you are typing on, and \-\-force is safe
+in that one narrow respect.
+.Pp
+Requirements: Ruby 3.1, and openocd \(em everything that reaches a
+board over SWD shells out to it.
+The Ruby dependencies come with the gem; openocd does not, being no
+gem of anybody's.
+It is expected at /usr/bin/openocd and found elsewhere with
+\-\-openocd; flash and reset check for it before switching anything, and
+connect \-\-reset when it reaches for it.
+.Ss A standard hub with per-port power switching
+Everything above is the ExSYS hub.
+\&'hub = usb' at the top of a configuration, or \-\-hub usb on the command line,
+drives any hub that switches its own ports instead.
+Nothing about it is an agreement with one manufacturer: what is spoken
+is the USB hub class, which every hub answers \(em the hub descriptor
+says how many ports there are, GET_STATUS says whether one is powered,
+and SET_FEATURE/CLEAR_FEATURE of PORT_POWER switches it.
+The ports are that hub's own, 1 to the bNbrPorts its descriptor
+reports, read once when the hub is opened.
+The fixed sixteen, and the 4\-by\-4 geometry \-\-method usb rests on, are
+the ExSYS hub's alone.
+.Pp
+The kind has to be said because it cannot be read off the
+.Cm device
+value: a USB path such as 1\-1.1 names the FT232's socket for an ExSYS
+hub and the hub itself for a usb hub, so the same line would mean two
+different hubs.
+It names what the hub IS and not which tool drives it, so a configuration
+written today keeps working when another host learns to drive such a
+hub.
+.Pp
+Today that host is
+.Fx
+only:
+.Xr usbconfig 8
+is what issues the requests, and no other host here has a command that
+sends an arbitrary control request to a hub.
+Root is not among the requirements.
+The ugen nodes are root:operator 0660, and the kernel asks for the
+driver privilege only for SET_ADDRESS, SET_CONFIG and SET_INTERFACE,
+so a hub\-class port feature request passes: membership of group
+operator is the whole of it
+.Pq Ic pw groupmod operator -m yourname ,
+then log in again.
+Without it every request answers "Permission denied" and
+.Nm
+says so, naming the group.
+.Pp
+Which hub, when the host has more than one, works as it does for the
+other kind: one candidate is taken, two or more are refused and listed
+\(em each with its serial, its ugen name, its USB path and its port
+count, semicolons between them, the count being the only thing that
+tells two of the same part apart when neither carries a serial.
+Root hubs are never candidates.
+They are the controller a host's own sockets hang off, and a port of
+one has no PORT_POWER to clear, so offering one would offer a hub every
+command against it then failed on.
+See
+.Fl d
+under
+.Sx OPTIONS
+for the three shapes a name may take.
+.Pp
+What 'off' then does to the socket is the one thing software cannot
+find out, and
+.Cm switch
+in the configuration is how it is told.
+A hub with no power switch wired still reports the port unpowered and
+still drops the link, so the device vanishes from the host and comes
+back either way.
+.Bl -tag -width "switch = link" -compact
+.It Li "switch = link"
+The default.
+\&'off' takes the port off the bus and the board stays powered.
+.It Li "switch = vbus"
+\&'off' cuts the socket's power.
+.El
+.Pp
+Watch a board's LED to find out which this hub is: put a board that
+lights up on a port, run 'usb off' for that port, and look.
+An LED that goes out is vbus; an LED that stays lit while the board
+disappears from the host is link.
+Test the socket the bench will use \(em the USB 2 and USB 3 sides of one
+physical socket are different ports on different hubs, and a hub may
+switch neither.
+The ExSYS hub refuses the key rather than ignoring it: it always cuts
+power, and a line that changes nothing is a line somebody will trust.
+.Pp
+Under 'switch = link' everything that powers down still works.
+\&'usb off', 'toggle' and 'set' behave, the board vanishes from the host
+exactly as a power cut would, and \-\-method power still identifies a
+board by being the only one openocd can see.
+What does not happen is the board restarting, so every power\-down
+warns once, naming the ports that stay powered, and the after\-flash
+power cycle is skipped with a warning rather than pretended \(em see
+.Sx TRAPS .
+.Pp
+After every switch the port's status is read back, and the command
+fails if the power bit did not follow.
+That read\-back is the tool's only measurement of whether a hub
+switches at all: one that accepts CLEAR_FEATURE(PORT_POWER), answers OK
+and leaves the port up would otherwise have 'usb off' report success on
+a bench it never touched.
+Nothing is refused on what a hub DECLARES about its switching, for the
+same reason \(em the dock's Genesys hub declares ganged and switches per
+port anyway.
+.Sh OPTIONS
+Ordering matters, and it is the thing most likely to waste your afternoon.
+Global options come before the command; a command's own options come after
+the command but before its sub\-action.
+So:
+.Bd -literal
+tribble\-control \-C tribble.conf \-\-force usb off 14      global, then cmd
+tribble\-control \-C tribble.conf usb \-\-default=false set gamma:on
+.Ed
+.Pp
+and NOT 'usb set \-\-default=false ...', which parses the flag as an argument
+to 'set' and fails with "invalid argument".
+.Pp
+Global options, which go before the command:
+.Bl -tag -width "-W, --warm-up=SECONDS"
+.It Fl d , Fl -device Ns = Ns Ar DEV
+Which hub to drive, in one of three shapes, told apart by what they
+look like:
+.Bl -tag -width "1-1.2.4.4" -compact
+.It Pa /dev/ttyUSB1
+a
+.Sq /
+in it, so the serial line itself, used as given \(em the same rule
+.Fl -openocd
+uses to tell a path from a name
+.It Cm 1-1.2.4.4
+the USB path shape, so the adapter sitting in that socket on this host
+.It Cm AL03GD7X
+anything else, so the FT232's serial number
+.El
+.Pp
+With
+.Fl -hub Cm usb
+the three shapes name a hub of that kind instead:
+.Bl -tag -width "1-1.2.4.4" -compact
+.It Cm ugen1.4
+the ugen shape, so that device, used as given
+.It Cm 1-1.1
+the USB path shape, so the hub in that socket on this host
+.It Cm AC0528515619
+anything else, so the hub's own serial number
+.El
+.Pp
+ugen1.4 is that kind's /dev/ttyUSB1 and carries the same warning below:
+the number is enumeration order \(em ugen1.4 is the fourth device the
+second controller attached \(em so a replug renumbers it, and a configuration
+naming a hub that way points at whatever attached in its place.
+Write the serial, which follows the hub, or the USB path, which follows
+the socket.
+.Pp
+Three answers, in the order they are trusted: this option, then the
+configuration's own
+.Cm device
+line, then the host, which is searched for an FTDI 0403:6001 and
+normally turns up /dev/ttyUSB0.
+.Pp
+That last one is a guess, and it is made only when there is nothing to
+guess between.
+An FTDI 0403:6001 is the hub's control adapter and also every other
+FT232 on the host, so with two of them attached
+.Nm
+refuses and lists what it found, with serials, rather than switching the
+ports of whichever enumerated first.
+A host owning more than one bench says which in each configuration, so that
+.Fl C
+alone selects one; this option is for the one\-off.
+.Pp
+The serial line itself is the worst of the three to write down.
+The number in /dev/ttyUSB1 is not the hub's, and not the USB device
+number either: it is the usbserial layer's own index (ttyU on FreeBSD,
+allocated the same way), and it is the lowest one free when that
+adapter is probed.
+So it depends on what else attached first, and it is reused \(em unplug
+whatever holds ttyUSB0 and the next thing to attach takes ttyUSB0.
+Two hubs can swap names across a reboot, or while the machine is up,
+and every configuration naming them that way then points at the other bench,
+silently and in a way no command can detect.
+.Pp
+The other two are both stable, and they answer different questions.
+A serial stays with the ADAPTER \(em move the hub to another socket, or
+another machine, and its serial goes with it \(em and is the usual
+want, naming one particular hub.
+A USB path stays with the SOCKET: whatever is plugged in there answers
+to it, a replacement hub included.
+Use the path for a hub whose EEPROM carries no serial, that being the
+only stable name such a one has, and for a bench where the socket is
+the fixed thing.
+.Pp
+Both platforms report a path, by different means: Linux states it in
+/sys, and on FreeBSD it is walked out of the sysctl tree, each device's
+%location giving the port it occupies on its parent and %parent naming
+that parent.
+The numbering is each host's own, though \(em FreeBSD counts buses from
+0 and Linux from 1 \(em so a path names a socket on the machine that
+reported it and does not travel to another.
+Read the ones on this host with
+.Ic exsys-usb discover ,
+which the exsys gem installs and which lists one adapter per line, its
+line then its serial \(em or by asking
+.Nm
+for a serial that does not exist, since the refusal lists them.
+.It Fl -hub Ns = Ns Ar KIND
+Which kind of hub to drive:
+.Cm exsys
+(the default) or
+.Cm usb .
+Overrides the configuration's own
+.Cm hub
+line.
+The option takes those two words only; a configuration naming another kind is
+refused at load with both listed.
+See
+.Sx THE HUB .
+.It Fl C , Fl -config Ns = Ns Ar FILE
+The configuration.
+Required for any power\-down at all, and by any command taking device
+names.
+Without
+.Fl C ,
+a file named
+.Pa tribble-control.conf
+in the current directory is used if there is one; neither the home
+directory nor /etc is ever consulted, and given
+.Fl C
+the current directory is not either.
+.Ic usb on
+and
+.Ic usb status
+work without it.
+.It Fl m , Fl -method Ns = Ns Ar TYPE
+Device selection:
+.Cm power , usb
+or
+.Cm serial .
+See
+.Sx DEVICE SELECTION .
+Rejected if the command does not support it.
+.It Fl W , Fl -warm-up Ns = Ns Ar SECONDS
+Delay after powering a port on, before touching the board.
+Default 5.
+.It Fl F , Fl -force
+Switch ports the configuration does not allow.
+See
+.Sx PROTECTED PORTS .
+.It Fl p , Fl -password Ns = Ns Ar STRING
+Supplies the ExSYS hub's password; it does not change it.
+Default
+.Sq pass .
+A wrong one makes the hub answer E01 and the command abort loudly, not
+silently.
+A usb hub has no password, so the option is refused there rather than
+ignored.
+.It Fl r , Fl -require Ns = Ns Ar FILE Ns Op , Ns Ar FILE ...
+Ruby files to load before anything else runs, for the tallies they
+register.
+Repeatable: every
+.Fl r
+given is loaded, in order.
+An empty name, from \-\-require= or a doubled comma, is refused.
+See
+.Sx TALLIES .
+.It Fl -openocd Ns = Ns Ar PATH
+openocd binary.
+Default /usr/bin/openocd; a name with no
+.Sq /
+in it is looked up in PATH, which is how to reach it on a host that
+keeps it elsewhere (FreeBSD: /usr/local/bin).
+Checked before any port is switched, by the commands that always need
+it.
+.It Fl -debug Ns Oo = Ns Ar FILE Oc
+Show debug output \(em chiefly the openocd command line issued for each
+board, which is the thing worth having when a flash behaves oddly.
+With
+.Ar FILE ,
+the whole log is copied there as well as shown, appending, so a long
+run can be kept without being watched.
+An unwritable path is refused before any port is switched.
+.It Fl v , Fl -verbose , Fl -no-verbose
+Run verbosely.
+.It Fl V , Fl -version
+Print the tribble\-control and ExSYS library versions and exit.
+.It Fl h , Fl -help
+Usage, including the command list.
+.El
+.Pp
+Per\-command: 'usb' takes \-\-default=BOOL, 'connect' takes \-\-off.
+Both are
+described under COMMANDS.
+.Sh "HUB PROTOCOL, AND WHAT IT CANNOT TELL YOU"
+The ExSYS hub speaks a small ASCII protocol over the FT232 line.
+Recovered from
+the vendor's own cusba64 binary (which ships unstripped), the complete
+vocabulary is eight commands, each terminated by CR, answering 'G...' on
+success and 'E01' on error:
+.Bd -literal
+?Q   query: an id, the port count and the firmware   no password
+GP   get port states                                  no password
+SP   set port states                                  password
+FP   set port states, and save as the power\-on state  password
+WP   save the current states as the power\-on state    password
+CP   change password                                  password
+RD   restore factory defaults                         password
+RH   reset the whole hub                              password
+.Ed
+.Pp
+?Q answers a single string: an id, then the port count, then the
+firmware version \(em CENTOS000516v02 on a 16\-port hub running v02.
+It carries no port states; cusba64 fills its On= and Off= display from
+a separate GP.
+.Pp
+The exsys gem implements all eight as of 1.0, ?Q as #query, and the
+port count it answers decides what "every port" covers rather than
+being assumed.
+It holds an exclusive lock on the line for the whole of a
+read\-modify\-write, so two processes cannot lose each other's changes
+between the GP and the SP, and it refuses an empty port list rather
+than reading it as every port.
+The default password is
+\&'pass', right\-padded to 8 characters.
+.Pp
+tribble\-control only ever issues SP, never FP or WP: port states are set for
+the here and now and never written to the hub's flash, so nothing it does
+survives a hub power cycle.
+Note also that RD, the only recovery from a
+forgotten password, drops every port \(em so changing the password with CP
+is close to a one\-way door on a hub carrying anything that minds losing
+power without notice.
+.Pp
+There is no per\-port current or voltage telemetry, and no way to bolt it
+on: the protocol has no such command, cusba64 contains no such code, and
+USB 2.x/3.x hubs do not report per\-port draw to the host under any
+circumstances.
+A device's bMaxPower descriptor is what it asks for at
+enumeration, not what it consumes, and a pure power load never enumerates
+at all.
+Measuring consumption needs an inline USB power meter or an
+instrumented bench supply.
+.Pp
+Two of these commands are worth fearing.
+RH resets the hub and RD
+restores factory defaults; either drops every port, which power\-cycles
+everything on the hub, protected ports included.
+tribble\-control never
+issues them, and the exsys gem only does so via #reset and
+#factory_reset, both of which require an explicit confirm: true.
+.Ss What a usb hub is asked
+A hub of the other kind needs no gem and no serial line: the switching
+is on the bus itself, and the whole vocabulary is four control requests
+issued through
+.Xr usbconfig 8 ,
+by absolute path so that nothing depends on whoever's PATH the command
+was started with.
+.Bd -literal
+/usr/sbin/usbconfig \-d ugenB.D do_request ...
+
+  0xa0 0x06 0x2900 0 9     hub descriptor, USB 2
+  0xa0 0x06 0x2a00 0 12    hub descriptor, SuperSpeed
+  0xa3 0x00 0x0000 P 4     GET_PORT_STATUS of port P
+  0x23 0x03 0x0008 P 0     SET_FEATURE   PORT_POWER, port P
+  0x23 0x01 0x0008 P 0     CLEAR_FEATURE PORT_POWER, port P
+.Ed
+.Pp
+Both descriptors are asked for and whichever the hub answers decides
+how its port status word is read from then on; the other is refused,
+which is the only way to learn which kind of hub this is.
+The hubs themselves are found with '/sbin/sysctl \-e dev.uhub'.
+.Pp
+Nothing here outlives the hub either: PORT_POWER is set for the here
+and now, exactly as SP is above, and no descriptor is written.
+And there is no per\-port telemetry on this side either, for the reason
+already given \(em no USB hub reports per\-port draw to the host.
+.Sh CONFIGURATION
+A UCL file mapping a device name to a hub port, and optionally to the
+board's debug\-probe serial number.
+It is what \-C/\-\-config points at (or, failing that, a
+.Pa tribble-control.conf
+in the current directory), and it
+is the only thing that tells tribble\-control which ports it may touch.
+.Bd -literal
+device     = AL03GD7X           # which hub these ports are on
+hub        = exsys              # which KIND; 'usb' is the other
+protect {                       # what must not lose power;
+    undeclared = yes            #   see PROTECTED PORTS
+    ports      = [ 13, 14, 15, 16 ]
+    nodes      = [ rpi ]
+}
+
+alpha   { serial = '1026360216055e5b0000...97969902', port = 1    }
+beta    {                                             port = 2    }
+gamma   { serial = '1026360213072dde0000...97969902', port = 4    }
+retired { serial = '1026360202c4dc0f0000...97969902', port = none }
+rpi     {                                             port = 12   }
+.Ed
+.Pp
+Indentation is not significant, but separators are: two keys on one line
+need a comma between them, which is why the entries above carry one and
+one\-key\-per\-line entries do not.
+A CMSIS\-DAP serial is 48 hex
+characters and a J\-Link one 12, and both are pasted whole \(em the ones
+above are elided in the middle for width.
+.Pp
+Every device entry must carry a port, and 'port = none' is how one says it
+is a record rather than a board on the bench.
+\&'retired' above is the
+case: it stopped enumerating, its port was given to another board, and the
+entry stays so that its serial is not lost.
+Such an entry is left out of
+everything \(em never selected, never switched, never flashed \(em and naming
+it says so ("device 'retired' is not on the bench").
+A MISSING port is an
+error, not a synonym for none: deleting the port line is exactly what
+happens when a port is reassigned, and inferring "gone" from a line
+somebody forgot would drop a live board silently.
+Two entries claiming
+one port is refused at load, none excepted.
+.Pp
+Every key other than 'device', 'hub', 'switch', 'protect',
+\&'tally' and 'types' is a device.
+A command
+given no device names operates on all of them.
+Names may be used anywhere
+a port number can be, in every command.
+.Pp
+A board with no serial= cannot be reached by 'reset' or by \-\-method
+serial, both of which address a board by its serial number: the run
+aborts with "Device without serial".
+Fix it by running 'serial' (see
+RECIPES) and pasting the value in.
+.Pp
+Optional keys describe a board whose probe or console differs from
+the default:
+.Bd -literal
+epsilon { serial = '000760040233', interface = jlink, baud = 115200,
+          port = 7 }
+.Ed
+.Bl -tag -width power_cycle
+.It Cm interface
+The openocd interface script, without the .cfg:
+.Cm cmsis-dap
+(the default, a DAPLink probe such as the MDK's) or
+.Cm jlink
+(a J\-Link OB, as on the DWM1001\-DEV).
+Used by
+.Ic flash , reset
+and
+.Ic connect --reset .
+With
+.Cm jlink ,
+serial= is the J\-Link serial number as udev reports it; leading zeros
+are accepted.
+.It Cm target
+The openocd target script, without the .cfg:
+.Cm nrf52
+(the default, which is what the whole bench runs) or whatever openocd
+calls the chip on a board of another family.
+Used wherever interface= is.
+The two are independent: the probe says how to reach the chip, the
+target says which chip it is.
+.It Cm transport
+The transport openocd selects:
+.Cm swd
+(the default) or whatever the chip and the probe both speak, commonly
+.Cm jtag .
+.Cm none
+selects nothing and leaves the choice to the interface script; it is
+spelt as for
+.Cm work_area ,
+in any case, or null, or \-.
+Anything else that is not a name \(em a boolean such as no, a number, an
+empty string \(em is refused.
+Making
+.Cm target
+a key and leaving this one fixed would be half a fix: a chip reached
+over JTAG would take the right target script and then fail on a
+transport it has not got.
+.It Cm work_area
+How much target RAM openocd may borrow for its flash algorithms,
+default 0x4000, written as openocd wants it.
+.Cm none
+says nothing and leaves the target script to choose.
+16 KB is nothing to a large part and more than some have in total, so
+it belongs to the chip rather than to this tool.
+.It Cm baud
+The console speed
+.Ic connect
+opens, default 230400 (what the MDK overlay sets).
+The stock DWM1001\-DEV devicetree runs its console at 115200.
+.It Cm tally
+Which tally reads this board's console, overriding the file's own
+.Cm tally
+line.
+See
+.Sx TALLIES .
+.It Cm power_cycle
+The moments at which the board must have its port powered off and on
+again: one name, or a list of them.
+Known:
+.Bl -tag -width after-flash
+.It Cm after-flash
+After a successful flash.
+The DWM1001\-DEV needs it: after openocd's reset init / write / reset
+run its DW1000 no longer reports transmissions (the board resolves
+nothing and logs "our TX timestamps are missing") until the module is
+power\-cycled; a plain SWD reset is not enough.
+.El
+.Pp
+A name nothing acts on is not an error, so a new moment can be recorded
+here before the command that honours it exists.
+It lives here, and not only as the
+.Ic flash --power-cycle
+option, so that a flash by hand on the hub cannot forget it.
+.El
+.Pp
+\&'device' is the hub these ports are on: the serial number of its
+FT232 control adapter, a USB path such as 1-1.2.4.4, or the serial line
+itself if the value has a '/' in it.
+Quote a serial that is all digits: an unquoted one is read as a number,
+and a number has no leading zeros, so 00760040233 arrives as 760040233
+and matches nothing.
+The refusal lists what the host really has, which is the moment to
+notice.
+.Pp
+The key is newer than the rest, which matters when a configuration and a
+.Nm
+are deployed separately: every top-level key the tool does not know is
+taken for a board, and a board must declare a port, so this line meets
+an older
+.Nm
+as "devlist entry 'device' has no port".
+Nothing is switched and nothing is damaged \(em the command refuses at
+load \(em but upgrade the tool before adding the line.
+A configuration is one bench and a bench is one hub, so the file that says
+which board is on which port is where to say which hub those ports
+belong to; with it, \-C alone selects a bench on a host that owns two.
+Write the serial, or the USB path, rather than the serial line \(em a
+ttyUSB number is the lowest index free when the adapter was probed, so
+it depends on what else attached first and is reused when something
+detaches, and neither of the other two does.
+See
+.Fl d
+under
+.Sx OPTIONS
+for how to read one.
+\&'hub' is which KIND of hub that is: 'exsys', the default and
+everything described so far, or 'usb' for any hub that switches its own
+ports.
+\&'switch' is what such a hub's 'off' does to the socket: 'link', the
+default, takes the port off the bus and leaves the board powered, and
+\&'vbus' cuts the power.
+It applies to 'hub = usb' alone, and an ExSYS hub refuses it rather
+than ignoring it.
+Both are described under
+.Sx THE HUB ,
+and \-\-hub overrides the first for a one\-off.
+.Pp
+\&'protect' says what must never be powered down: ports by number,
+configuration entries by name, and every port the file does not mention
+unless it says otherwise.
+It is described under
+.Sx PROTECTED PORTS .
+\&'tally' sets the bench's default tally, described under
+.Sx TALLIES .
+\&'types' holds settings a device can inherit, described next.
+.Ss Types
+A bench is usually a handful of boards of two or three kinds, and what
+a kind is \(em which probe, which chip, which transport, how fast its
+console runs \(em is the same on every board of that kind.
+Written out per device that is the same four lines eleven times, and a
+reader has to compare them all to find the one that differs.
+.Pp
+\&'types' says it once:
+.Bd -literal
+types {
+  nrf52840-mdk {
+    interface = cmsis-dap
+    target    = nrf52
+    transport = swd
+    baud      = 230400
+  }
+  dwm1001-dev {
+    interface   = jlink
+    target      = nrf52
+    transport   = swd
+    baud        = 115200
+    power_cycle = after-flash
+  }
+}
+
+alpha { type = nrf52840-mdk, serial = '1026...9902', port = 1 }
+delta { type = dwm1001-dev,  serial = '000760040233', port = 7 }
+epsilon { type = nrf52840-mdk, baud = 9600, port = 2 }
+.Ed
+.Pp
+A device's own key wins over its type's: a type is what a kind of board
+has in common, and an entry saying otherwise is saying it about itself.
+\&'epsilon' above is an nRF52840\-MDK whose console has been moved.
+.Pp
+Three rules, each of them refusing something at load rather than
+letting it read as working:
+.Bl -bullet
+.It
+A type nothing defines is an error.
+A board that asked for the jlink type and silently got the cmsis\-dap
+default is a flash through the wrong probe, reported as a success.
+.It
+A type may not set
+.Cm port
+or
+.Cm serial .
+Both name one particular board \(em a port is where a single board is
+plugged in, a serial is one physical probe \(em so a type that set
+either would be saying that every board of that kind is the same board.
+.It
+Types do not nest.
+A type is a block of settings, not a thing that can have a type of its
+own.
+.El
+.Pp
+A misspelled 'protetc' becomes a device named protetc, which would
+silently unprotect every port the block named.
+That one is caught: every
+device entry must carry a port, so the misspelling is refused at load
+with "configuration entry 'protetc' has no port".
+A key misspelled INSIDE the block is caught by name, the block taking
+\&'undeclared', 'ports' and 'nodes' and nothing else \(em a 'port = [ 13 ]'
+quietly ignored would read as protection and be none.
+Validation stops there,
+though \(em a serial, an interface or a baud that is wrong is wrong
+silently \(em so after editing this file still run 'usb status' and read
+the names and the protected column before you trust it.
+.Sh PROTECTED PORTS
+Some things on the hub are there for power alone: a single\-board computer,
+a powered peripheral, anything the bench feeds but does not drive.
+Nothing
+communicates with them, so nothing notices if their VBUS disappears \(em they
+simply reboot, uncleanly, mid\-write.
+One configuration block keeps that from
+happening, with three keys.
+.Pp
+\&'undeclared' decides the fate of every port the configuration does not mention:
+.Bl -tag -width "undeclared = yes"
+.It Li "undeclared = yes"
+The default.
+Only ports declared in the configuration may be powered down.
+.It Li "undeclared = no"
+Any port the hub has may be powered down.
+.El
+.Pp
+\&'ports' and 'nodes' name what is never powered down whichever way that
+falls, so either protects a port even when that port is a declared
+device.
+\&'ports' takes port numbers, 'nodes' the names of configuration entries:
+.Bd -literal
+protect {
+    undeclared = yes
+    ports      = [ 13, 14, 15, 16 ]
+    nodes      = [ rpi ]
+}
+.Ed
+.Pp
+Prefer the name where there is an entry to name.
+The port number is then written once rather than twice, the protection
+follows the board if it moves socket, and 'usb status' prints the name
+next to the protected port instead of a dash.
+A name no entry declares is refused at load: a misspelling there would
+protect nothing while reading, in the file, exactly like protection.
+A name whose entry says 'port = none' is allowed and protects nothing,
+there being no port to keep powered.
+.Pp
+Together:
+.Bd -literal
+tribble\-control powers down a port only if the configuration allows it,
+and never one the configuration protects.
+.Ed
+.Pp
+This is enforced at every path that can cut power, not just the obvious
+one: 'usb off', 'usb toggle', 'usb set' with a port set to off, the
+all\-ports\-off that begins \-\-method power, and 'connect \-\-off'.
+You do not
+have to reason about which commands are dangerous; they all go through the
+same gate.
+.Pp
+So a bare 'usb off' means "every switchable port", not "every port the
+hub has".
+Naming a
+protected port is an error, not a silent skip:
+.Bd -literal
+$ tribble\-control \-C tribble.conf usb off 14
+tribble\-control: refusing to power down port(s) 14: protected by the
+configuration (use \-\-force)
+.Ed
+.Pp
+Without a configuration there is no safe set, so power\-down is
+refused outright.
+.Pp
+\-F/\-\-force lifts both rules and restores the old "every port" behaviour.
+It is the only way to deliberately reboot a power\-only device, and it is a
+hard VBUS cut, not a shutdown: the device loses power mid\-write, with
+whatever consequences that has for its filesystem.
+Shut it down over the
+network first if you care about what is on it.
+It cannot strand you,
+though \(em the host runs off its own supply, not off the hub.
+.Pp
+Powering *on* is never guarded: 'usb on' with no arguments still turns on
+every port the hub has, which is the state the bench should normally sit
+in.
+.Sh DEVICE SELECTION
+Flashing one of six identical boards means telling openocd which one.
+There are three ways, chosen with \-m/\-\-method:
+.Bd -literal
+┌─────────┬─────────────────┬──────────────┬────────────────────────┐
+│ method  │ addresses a     │ requires     │ power while the job    │
+│         │ board by        │              │ runs                   │
+├─────────┼─────────────────┼──────────────┼────────────────────────┤
+│ serial  │ its debug probe │ serial= for  │ every selected port    │
+│         │ serial number   │ every board  │ on; boards in parallel │
+├─────────┼─────────────────┼──────────────┼────────────────────────┤
+│ usb     │ its USB path,   │ a USB path   │ every selected port    │
+│         │ root.bank.slot  │ for the hub  │ on; boards in sequence │
+├─────────┼─────────────────┼──────────────┼────────────────────────┤
+│ power   │ being the only  │ nothing      │ exactly one board at   │
+│         │ board powered   │              │ a time, rest cut       │
+└─────────┴─────────────────┴──────────────┴────────────────────────┘
+.Ed
+.Pp
+Which to use:
+.Bl -tag -width serial
+.It Cm serial
+The default for
+.Ic flash
+and
+.Ic reset .
+Boards stay powered and are done in parallel, so it is much faster and
+far less disruptive.
+Aborts if any selected board lacks a serial=.
+.It Cm power
+Needs no configuration at all \(em it identifies a board by being the
+only one powered \(em and is the fallback for a board whose serial= is
+missing or wrong.
+Slowest by far: every board costs a power cycle plus the warm\-up, so
+the whole bench is sequential rounds.
+It also leaves every switchable declared board POWERED OFF when it
+finishes, because each port is switched off again after its turn.
+A board whose port the configuration protects stays powered, and says so.
+Run
+.Ic usb on
+afterwards to bring the bench back up.
+.Pp
+Because a protected or undeclared port stays powered, a probe on one
+would be a second adapter in front of openocd, which then picks between
+them by itself.
+So once a board is powered, the run is refused if more than one probe
+console is present: use serial, or \-\-force to power those ports down
+too.
+A probe that shows no CDC console cannot be counted.
+.It Cm usb
+What
+.Ic connect
+uses.
+Addresses by USB topology, so it needs no serials.
+On Linux the topology is read from /sys/bus/usb; on FreeBSD it is
+walked out of the sysctl tree, which cannot see a device no driver has
+claimed.
+.El
+.Pp
+Each command accepts only the methods that make sense for it, and uses the
+first as its default:
+.Bd -literal
+command    methods accepted          default
+\-\-\-\-\-\-\-    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-          \-\-\-\-\-\-\-
+usb        (none: acts on ports)     n/a
+serial     usb, power                usb
+flash      serial, power             serial
+reset      serial                    serial
+connect    usb, serial               usb
+.Ed
+.Pp
+\-\-method usb derives the board's USB location from the hub's own geometry,
+four banks of four:
+.Bd -literal
+port 5 ─┬─▸ bank 2      bank is (port minus 1) div 4, plus 1
+        └─▸ slot 1      slot is (port minus 1) mod 4, plus 1
+
+hub root path .............  1\-1.2
+openocd adapter usb location 1\-1.2.2.1
+                             └───┘ │ │
+                               │   │ └── slot
+                               │   └──── bank
+                               └──────── hub root
+.Ed
+.Pp
+That geometry is the ExSYS hub's own.
+A usb hub has none to account for, so a port there is one component
+below the hub's own path: a board on port 3 of the hub at 1\-1.1 is at
+1\-1.1.3.
+.Pp
+The location is documentation of intent rather than a selector: openocd
+0.12 ignores 'adapter usb location' for CMSIS\-DAP, reaching the same
+adapter whichever path it is given, including one that does not exist.
+What selects is 'adapter serial', which this method passes as well
+whenever the configuration has one.
+A board with no serial= is therefore
+addressed by nothing in particular, and with more than one adapter
+powered that is a board chosen at random.
+.Pp
+After any power\-on, \-W/\-\-warm\-up seconds (default 5) pass before the boards
+are touched, to let them enumerate.
+.Sh COMMANDS
+Every command takes device names or port numbers interchangeably, and
+operates on every board on the bench when given neither: each declared
+device but those with port = none.
+.Bl -tag -width Ds
+.It Ic usb Cm status | on | off | toggle | set Oo Ar PORT | DEVNAME Oc ...
+Drive hub port power directly.
+\&'set' takes PORT:STATE pairs, where
+STATE is any of on/off/1/0/true/false/t/f.
+With no arguments, 'on'
+means every port the hub has, while 'off' and 'toggle' mean every
+switchable port (see PROTECTED PORTS).
+On a hub whose
+.Cm switch
+is link, everything that powers down says so, naming the ports that
+stay powered.
+.Pp
+\-\-default=BOOL sets what happens to ports 'set' does not name; it goes
+before the word 'set'.
+Without \-\-force it is applied only to
+switchable ports, so it cannot sweep a protected port off.
+\&'status' is read\-only: it asks the hub for its port states and prints
+every port with its device name, its state, and whether the configuration
+lets tribble\-control switch it.
+Run it before anything involving
+\-\-force.
+Note that 'usb on' does not wait out \-\-warm\-up; it returns as soon as
+the hub acknowledges.
+.Pp
+Selection method: none.
+Exit status: 0, or 1 on error.
+.It Ic serial Oo Ar PORT | DEVNAME Oc ...
+Report each board's debug\-probe serial number, read from the USB
+descriptor the kernel already holds.
+Prints one line
+per board, "Serial for alpha: 1026...".
+Use it to populate the configuration.
+.Pp
+Selection methods: usb (default), power.
+Under
+.Cm usb
+it powers the boards' own
+ports up and leaves the rest of the bench alone \(em asking a board its
+serial is not a reason to black out the hub.
+.Cm power
+is the fallback that needs no topology at all, at the price of cutting
+the bench; see
+.Sx TRAPS .
+Exit status: 1 if any
+board could not be read.
+.Pp
+The serial comes from the operating system rather than from openocd,
+which does not report it: openocd 0.12 prints neither a CMSIS\-DAP
+"Serial# =" line nor a J\-Link "S/N" one, at any debug level.
+Asking
+the OS also means no board has to be the only one powered, which
+asking openocd would have required, since it cannot choose between
+adapters by itself.
+.It Ic flash Ar FIRMWARE Oo Ar PORT | DEVNAME Oc ...
+openocd 'flash write_image erase FIRMWARE' then 'reset run', against
+the board's target= script (nrf52 by default) over its interface=
+script (cmsis\-dap by default), on its transport= (swd by default).
+FIRMWARE is resolved by
+openocd relative to the current directory, and is checked to be a
+readable file before any port is switched.
+Every selected board is attempted even if an earlier one failed; the
+exit status reflects the whole run.
+A board whose configuration entry lists after\-flash under power_cycle (see
+CONFIGURATION: the DWM1001\-DEV) has its port powered off and on again after
+a successful flash; \-\-power\-cycle, before FIRMWARE, does the same for
+any board.
+.Pp
+Selection methods: serial (default), power.
+Exit status: 1 if any
+board failed.
+.It Ic reset Oo Ar PORT | DEVNAME Oc ...
+openocd 'reset run'.
+.Pp
+Selection method: serial only, so it cannot address a board that has
+no serial= in the configuration.
+Exit status: 1 if any board failed.
+.It Ic connect Oo Ar PORT | DEVNAME Oc ...
+Open each board's CDC console at its baud= (default 230400) and
+stream it, prefixing every line with <DEVNAME>.
+Every line is also handed to the board's tally, and on exit each board
+prints a SUMMARY line with whatever that tally has to say.
+What the lines MEAN is not decided here \(em see
+.Sx TALLIES .
+.Pp
+Boards are streamed concurrently, one thread each, which is what
+makes a two\-way\-ranging capture meaningful; the "in sequence" in the
+method table above describes the order boards are set up in, not the
+monitoring.
+.Pp
+\-\-off powers down every declared board first, for a clean start \-\-
+every declared board, not only the ones named on the command line \-\-
+and then powers the selected ones back up.
+.Pp
+\-\-reset resets each board over SWD once its console is open.
+Without
+it you see only what a board says from the moment the reader attaches,
+which on an already\-running board is nothing at all until the next
+ranging exchange: the banner and the driver's init lines \(em including
+any "Failed to initialize" \(em were printed seconds after power\-on and
+are gone.
+Use it whenever you care about why a board is quiet, and
+note that \-\-off alone does NOT substitute: the port is powered back up
+before the console is opened, so boot output still escapes.
+.Pp
+\-\-duration=SECONDS bounds the capture; the default is 600.
+.Pp
+\-\-command=CMD types CMD at each board's shell once it is up (two
+seconds after a \-\-reset, half a second otherwise) and is the way to
+reach anything the firmware gates behind a run\-time setting.
+The
+case it exists for: redskin compiles spank's log level to warning,
+but the ranging results are logged at info, so a capture counts zero
+exchanges on a bench that is in fact working perfectly \-\-
+.Bd -literal
+\-\-command='spank syslog info'      # the whole info stream
+\-\-command='spank report all'       # just the distances, cheaper
+.Ed
+.Pp
+turns them on without reflashing.
+Prefer the second: the report path
+is written straight out by the port instead of going through the
+syslog, so it is not silenced by the compiled\-in level and costs the
+firmware less in a loop that is timing sensitive.
+It is sent once,
+to every selected board, on a separate write handle; the command is
+not echoed by tribble\-control, but the board's own echo and reply
+appear in the capture like any other output.
+Give it once \-\-
+repeating the option keeps only the last.
+ALWAYS run it under 'stdbuf \-oL' if you are piping the output
+anywhere.
+Without that, the pipe buffers in 4 KB blocks and 'tee'
+shows nothing for minutes.
+.Pp
+\-\-interactive is \-\-command without the limit of one command decided
+in advance: standard input is forwarded to the board, a line at a
+time, and the console stays open until end of input instead of for
+a \-\-duration.
+One device only \(em there is one standard input, and
+two boards sharing it could not be told apart or addressed
+separately.
+What the board replies appears in the stream like
+anything else, prefixed with its name, so what was typed and what
+came back read in order.
+It is meant to be run through a terminal \(em 'bench connect' opens it
+over ssh \-t, which is what supplies the editing and the echo of the
+line being typed; a pipe works too, and sends what it is given.
+.Pp
+\-\-tally=NAME reads every selected board's console with tally NAME
+for this run, whatever the configuration says; \-\-tally=DEV=NAME does
+so for board DEV alone.
+See
+.Sx TALLIES .
+.Pp
+A console that cannot be opened or read, or whose tally raises, prints
+.Dl <DEVNAME> ERROR: message
+instead of its SUMMARY line.
+.Pp
+Selection methods: usb (default), serial.
+Exit status:
+1 on error, or if any selected board's console was not found or could
+not be read; otherwise 0, which says nothing about what the boards
+printed.
+.El
+.Sh TALLIES
+.Nm
+opens a board's console, prefixes each line with the board's name and
+prints it.
+What a line MEANS it does not know, and deliberately does not: the
+strings worth counting belong to whatever firmware is on the bench this
+month, they change when that firmware changes, and none of them are
+facts about a USB hub.
+.Pp
+A tally is where that knowledge goes.
+.Ic connect
+hands it every line and asks it, once the capture ends, for the text of
+the board's SUMMARY line.
+Two come built in:
+.Bl -tag -width lines
+.It Cm lines
+How many lines the board printed.
+The default, and all a tool that knows nothing about the firmware can
+honestly say.
+.It Cm none
+Nothing: the lines are printed, and no SUMMARY follows them.
+.El
+.Pp
+Any other is a block, registered by a Ruby file named with
+.Fl r :
+.Bd -literal
+# twr-tally.rb
+class TwrTally
+    def initialize(device) = @ok = 0
+    def <<(line)
+        @ok += 1 if line =~ /whatever this firmware calls success/
+        self
+    end
+    def summary = "ok=#{@ok}"
+end
+
+TribbleControl::Tally.register(:twr) {|device| TwrTally.new(device) }
+.Ed
+.Pp
+The object the block returns needs two methods:
+.Ic <<
+takes a line and returns anything, and
+.Ic summary
+returns the SUMMARY text, or nil for no SUMMARY line at all.
+The block is called once per board per run, so a tally may keep
+whatever state it likes without sharing it with another board's.
+.Pp
+Which tally a board uses is a configuration key.
+At the top of the file it sets the bench's default, and inside a device
+entry it overrides that for one board:
+.Bd -literal
+tally = twr                     # every board on this bench
+
+D4 { port = 7, tally = lines }  # except this one
+.Ed
+.Pp
+The configuration is about boards, not about what is flashed on them,
+so a run can override it.
+.Ic connect Fl \-tally Ns = Ns Ar NAME
+reads every selected board with NAME, and
+.Fl \-tally Ns = Ns Ar DEV Ns = Ns Ar NAME
+reads board DEV with NAME; DEV is a device name or a port number, as on
+the command line.
+The option may be repeated, or given a comma\-separated list, and every
+value counts:
+.Bd -literal
+connect \-\-tally twr \-\-tally D4=none     # D4 runs the probe firmware
+connect \-\-tally twr,D4=none             # the same
+.Ed
+.Pp
+For each board the first that applies wins: its DEV=NAME, the run's
+NAME, its own
+.Cm tally
+key (or its type's), the file's
+.Cm tally ,
+then
+.Cm lines .
+Two run\-wide names, two names for one board, a DEV the run does not
+capture, or an empty NAME (\-\-tally= or a doubled comma) are refused
+rather than resolved by order or left to the configuration.
+.Pp
+Every board's tally is built before a port is switched, so a name
+nothing has registered stops the run before \-\-off cuts the bench.
+A name nothing has registered is an error, not a silent fall back to
+counting lines: a configuration asking for twr on a run that forgot
+.Fl r
+would otherwise capture the whole bench and report line counts, which
+reads exactly like a firmware that has gone quiet.
+.Sh RECIPES
+Read the serials of every board, to fill in the configuration.
+This cycles the
+bench and leaves it powered off:
+.Bd -literal
+tribble\-control \-C tribble.conf serial
+tribble\-control \-C tribble.conf usb on
+.Ed
+.Pp
+Add a board on a new port.
+\&'serial 7' will not work: an undeclared port
+has no name, and the tool refuses to power ports the configuration never
+mentions.
+Declare a stub first, then read the serial and fill it in:
+.Bd -literal
+echo "X1 { port = 11 }" >> tribble.conf
+tribble\-control \-C tribble.conf serial X1
+.Ed
+.Pp
+Pick a port nothing else declares.
+Two entries on one port is refused at
+load time, for every command including 'usb status', so a collision here
+leaves the configuration unusable until it is edited back.
+.Pp
+Flash the whole bench, then just two boards:
+.Bd -literal
+tribble\-control \-C tribble.conf flash zephyr.hex
+tribble\-control \-C tribble.conf flash zephyr.hex alpha beta
+.Ed
+.Pp
+Flash in parallel, leaving the bench powered.
+Needs a serial for every
+board named, so fix the gaps first (see CONFIGURATION):
+.Bd -literal
+tribble\-control \-C tribble.conf \-\-method serial flash zephyr.hex
+.Ed
+.Pp
+Run a ranging capture to a log, for ten minutes:
+.Bd -literal
+stdbuf \-oL tribble\-control \-C tribble.conf connect \-\-off gamma epsilon \e
+    | tee twr.log
+.Ed
+.Pp
+Find out why a board is silent \(em capture its boot, including the driver
+init lines, for one minute:
+.Bd -literal
+stdbuf \-oL tribble\-control \-C tribble.conf connect \-\-off \-\-reset \e
+    \-\-duration=60 gamma beta | tee boot.log
+.Ed
+.Pp
+Capture ranging results from a stock redskin build.
+Without the command
+the log level hides them and the SUMMARY reads ok=0 / tx\-rate=NaN:
+.Bd -literal
+stdbuf \-oL tribble\-control \-C tribble.conf connect \-\-off \-\-reset \e
+    \-\-command='spank syslog info' \-\-duration=60 gamma beta | tee twr.log
+.Ed
+.Pp
+Power\-cycle one board without disturbing the others:
+.Bd -literal
+tribble\-control \-C tribble.conf usb off gamma && sleep 2 && \e
+tribble\-control \-C tribble.conf usb on  gamma
+.Ed
+.Pp
+Deliberately reboot a device on a protected port (the only case for
+\-\-force).
+This is a hard power cut; shut the device down over the
+network first:
+.Bd -literal
+tribble\-control \-C tribble.conf \-\-force usb off 14 && sleep 2 && \e
+tribble\-control \-C tribble.conf usb on 14
+.Ed
+.Pp
+Find out what a usb hub's 'off' really does, before writing
+\&'switch = vbus' in a configuration.
+Put a board whose LED lights up on a port, watch the LED, and cut that
+port:
+.Bd -literal
+tribble\-control \-\-hub usb \-C dock.conf usb status
+tribble\-control \-\-hub usb \-C dock.conf usb off gamma
+.Ed
+.Pp
+An LED that goes out is vbus; an LED that stays lit while the board
+disappears from the host is link.
+Do it on the socket the bench will actually use: the USB 2 and USB 3
+sides of one physical socket are different ports on different hubs, and
+a hub may switch neither.
+.Pp
+The script shipped as examples/vbus\-check runs that recipe: it takes
+the options you would give
+.Nm
+and the port, cuts the port for five seconds, restores it even on
+Ctrl\-C, and prints the 'switch =' line your answer implies.
+.Bd -literal
+examples/vbus\-check \-\-hub usb \-C dock.conf gamma
+examples/vbus\-check \-n \-\-hub usb \-d AC0528515619 \-F 2   # dry run
+.Ed
+.Pp
+List the switchable hubs this host has, to fill in 'device':
+.Bd -literal
+tribble\-control \-\-hub usb usb status
+.Ed
+.Pp
+With one candidate that command drives it.
+With two or more it refuses and lists them \(em serial, ugen name, USB
+path and port count \(em which is what to copy into the configuration.
+.Pp
+Flash from a script, failing the build if any board failed:
+.Bd -literal
+#!/bin/sh
+cd /root || exit 1
+exec tribble\-control \-C tribble.conf flash zephyr.hex
+.Ed
+.Sh TRAPS
+Exit status.
+Any command exits 1 if it aborts with an error \(em a refused
+power\-down, an unknown device name, a hub that answers E01.
+On top of
+that, flash, reset and serial exit 1 when they ran to completion but some
+board failed; usb and connect report nothing about the work itself, so a
+0 from 'connect' says only that it started.
+Beware that piping into
+\&'tee' hands you tee's status, not tribble\-control's \(em which is exactly
+what the capture recipe does, so do not use that shape in a script
+without a pipefail or a temporary file.
+.Pp
+\-\-method power leaves every switchable declared board powered off when
+it finishes.
+Nothing defaults to it any more: flash defaults to serial, reset is
+serial only, and serial and connect default to usb.
+You get it by asking
+for it with \-m power, and then you want 'usb on' afterwards to bring the
+bench back.
+.Pp
+connect stops after 600 seconds unless \-\-duration says otherwise; Ctrl\-C
+is the other way out of a shorter run.
+Under \-\-interactive there is no
+timer at all: it ends on end of input (Ctrl\-D) or on Ctrl\-C.
+.Pp
+A SUMMARY counting nothing is not proof that a board said nothing.
+A tally counts the strings one firmware prints, so the wrong tally on a
+board, or the right one on a firmware whose log level hides the lines,
+both report a healthy board as an idle one.
+Check which tally the board is using
+.Pq Sx TALLIES
+and that the firmware is logging at all before concluding the radio is
+dead; \-\-command is how a log level is raised at run time.
+.Pp
+\-\-debug is what makes a run verbose; the default is quiet.
+What it exists to reveal is the openocd command line issued for each
+board.
+\-\-debug=FILE also writes the log where it says.
+If you have a script that greps a run for its openocd invocations, it
+now has to ask for them.
+.Pp
+FreeBSD does everything Linux does, by different means, with one
+limit worth knowing.
+Nothing there states a USB path: it is walked out of the sysctl tree,
+each device's %location giving the port it occupies on its parent and
+%parent naming that parent, up to a root hub.
+Note also that openocd is not at
+/usr/bin/openocd there: pass \-\-openocd=/usr/local/bin/openocd, or just
+\-\-openocd=openocd and let PATH answer.
+.Pp
+The limit is that FreeBSD has no node for a device NO driver claimed
+\(em there is no dev.ugen \(em so such a device cannot be seen at all.
+A probe that enumerates and attaches nothing is invisible there rather
+than serial\-less, and
+.Fl m Cm usb
+will report no serial for it.
+Every probe the bench carries attaches something: a DAPLink is umodem,
+umass and usbhid at once, a J\-Link OB is umodem, and all of them
+report the device's serial.
+.Pp
+.Ic connect
+works anyway, with
+.Fl m Cm serial :
+the console is found by the serial of the probe in front of the board,
+which both a DAPLink and a J\-Link OB report, and which the configuration
+already carries in order to address that board for flashing.
+No USB tree is walked at all, on either host, which is what makes it
+the method to reach for when a topology is in doubt.
+.Pp
+.Ic serial
+works there too, with
+.Fl m Cm power .
+It has to identify a board it has no serial for yet, which is what
+.Cm power
+is for: it cuts every switchable port, brings up one board at a time,
+and the probe then enumerated is the only one there is.
+No topology, no descriptor path, nothing Linux has that FreeBSD has
+not.
+It costs a cycle of the whole bench and leaves it powered off \(em run
+.Ic usb on
+afterwards \(em which is why
+.Cm usb
+remains the default wherever the hub's USB path is known.
+.Pp
+A probe on a port the configuration protects stays powered through all of
+that, so it is enumerated alongside the board being asked.
+.Nm
+says so and stops rather than attributing one board's serial to
+another.
+.Pp
+\-\-method usb trusts the 4\-by\-4 geometry.
+A board on port 16 would resolve
+to 1\-1.2.4.4, which is where the FT232 control adapter already sits, so
+port 16 is not usable for a board addressed that way.
+.Pp
+Two hubs on one host are two benches, and only the configuration can tell
+them apart.
+Auto\-detection matches an FTDI 0403:6001, which every FT232 on the host
+is, so it is refused outright once there is more than one \(em name the
+hub with
+.Cm device
+in each configuration, by the serial of its FT232, and the command that
+already says which configuration says which hub as well.
+A command that reaches the wrong hub is not an error anywhere: the
+ports exist, the frames are accepted, and the boards that go dark are
+on the other bench.
+.Pp
+The hub password defaults to 'pass' (\-p/\-\-password to change it).
+It
+guards writes to the hub, not reads.
+.Pp
+\&'switch = link' means nothing restarts.
+A board on a port taken off the bus vanishes from the host exactly as a
+power cut would, so every command that powers down still works and
+\-\-method power still selects a board by being the only one visible \(em
+but the board keeps running and keeps its state.
+Every power\-down says so once, naming the ports that stay powered, and
+.Ic flash
+skips the after\-flash power cycle with a warning instead of pretending:
+a cycle that only re\-enumerates the probe would leave the board in the
+very state power_cycle exists to clear.
+.Pp
+The power bit is not the same bit on both kinds of hub.
+A USB 2 hub reports it in 0x0100 of wPortStatus; a SuperSpeed hub
+reports it in 0x0200 and puts the link state in bits 5\-8, so reading a
+SuperSpeed port with the USB 2 bit answers "unpowered" for a port that
+is fine.
+Which hub descriptor the hub ANSWERS \(em 0x29 or 0x2a \(em is what
+decides how its status word is read from then on.
+.Pp
+.Xr usbconfig 8
+exits 0 for a request the hub refused, printing REQUEST = <ERROR>, and
+exits 0 for a device it could not even find.
+The printed text is the truth; the status says nothing.
+.Pp
+A dock's hub chain may reset on its own.
+The pair of TUSB8041 hubs on the dock this was written against detached
+and re\-attached every few minutes under test, taking every board with
+them.
+A hub that flaps is a poor bench hub whatever its descriptor declares,
+and the tool cannot tell that apart from a bench somebody unplugged.
+.Pp
+The LED test is the only proof that a hub switches VBUS.
+The read\-back after a switch proves the hub did what it was told, not
+that the socket lost power: a hub with no power switch wired clears the
+bit and drops the link, reports itself unpowered, and leaves the board
+running.
+Watch a board's LED through 'usb off', on the socket the bench will
+use, and write the answer down as
+.Cm switch .
+.Sh FILES
+.Bl -tag -width /usr/bin/openocd
+.It Pa ./tribble-control.conf
+The configuration, used when
+.Fl C
+is not given and this file exists in the current directory.
+Named explicitly with
+.Fl C ,
+it may be at any path and under any name: it describes a bench rather
+than the tool, so it lives with whatever owns the bench.
+See
+.Sx CONFIGURATION .
+.It Pa /usr/bin/openocd
+The openocd binary, overridable with
+.Fl -openocd .
+.It Pa /usr/sbin/usbconfig
+How a usb hub is switched, and not overridable: this program switches
+benches, and what it runs must not depend on whoever's PATH it was
+started with.
+.It Pa /sbin/sysctl
+How the hubs of a
+.Fx
+host are found, read as 'sysctl \-e dev.uhub'.
+.El
+.Sh SEE ALSO
+.Xr openocd 1 ,
+.Xr usbconfig 8
+.Sh AUTHORS
+.An Stephane D'Alu Aq Mt sdalu@sdalu.com