@andrian.yablonskyy/thub-coordinator 1.1.17 → 1.1.18

package/views/help/_usb-power.pug

@@ -0,0 +1,147 @@
++section('usb-power', 'USB port power (uhubctl)', 'power')
+  p.
+    An HW Client can switch the power of the USB ports its boards hang off, with
+    #[a(href="https://github.com/mvp/uhubctl" target="_blank" rel="noopener") uhubctl]. Use it to power-cycle a
+    hung board, start every job from a cold boot, or keep boards off between jobs. It needs a USB hub with
+    #[strong per-port power switching] (uhubctl's README lists hubs known to work) and #[code sudo apt install uhubctl]
+    on the Client host.
+
+  h3.h6 Setting it up
+  ol.small
+    li
+      | Find each board's hub and port. Run #[code uhubctl] with no arguments. The hub's #[strong location] is the
+      | word after #[code hub], and the #[strong port] is the number after #[code Port]. #[code ppps] means the hub
+      | switches each port on its own, and #[code ganged] means it switches all its ports together. A USB3 hub shows up twice
+      | (#[code 1-1.4] and #[code 2-1.4] below): use the half the board is on, and uhubctl switches the other with it.
+      +code('Client host').
+        $ sudo uhubctl
+        Current status for hub 1-1.4 [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps]
+          Port 1: 0100 power
+          Port 2: 0103 power enable connect [0483:3748 STMicroelectronics STM32 STLink 066DFF485457725187092834]
+          Port 3: 0103 power enable connect [0483:3748 STMicroelectronics STM32 STLink 0670FF505055877267183229]
+          Port 4: 0000 off
+        Current status for hub 2-1.4 [2109:0817 VIA Labs, Inc. USB3.0 Hub, USB 3.00, 4 ports, ppps]
+          Port 1: 02a0 power 5gbps Rx.Detect
+    li
+      | Try it by hand:
+      +code('Client host').
+        sudo uhubctl -l 1-1.4 -p 2 -a off    # the board on port 2 goes dark
+        sudo uhubctl -l 1-1.4 -p 2 -a on
+    li
+      | List the ports under #[code hw-devices.usbPower.ports] in the Client's config, up to 8. Each port's number is
+      | its #[strong position in this list] (from 1), and that's what #[code --port] takes. It isn't the hub's own
+      | port number: below, #[code --port 2] is hub #[code 1-1.4] port 3.
+      +code('~/.config/thub/dut1.json').
+        "hw-devices": {
+          "stlinks": [{ "index": 1, "devpath": "1.4.2" }, { "index": 2, "devpath": "1.4.3" }],
+          "usbPower": {
+            "ports": [
+              { "hub": "1-1.4", "port": 2 },
+              { "hub": "1-1.4", "port": 3 }
+            ]
+          }
+        }
+    li
+      | Restart the Client. It installs a udev rule that lets the #[code plugdev] group (which its service has)
+      | switch hub ports without root, and reports the ports to the Coordinator, along with whether uhubctl is
+      | installed. Then check:
+      +code('Client host').
+        sudo systemctl restart thub-client@dut1
+        thub-client --config ~/.config/thub/dut1.json power status
+        #   1. hub 1-1.4 port 2: on  (Port 2: 0103 power enable connect [...])
+        #   2. hub 1-1.4 port 3: on  (Port 3: 0103 power enable connect [...])
+  +note.
+    Saving a runner's devices on its #[strong Config] tab keeps #[code usbPower] as it is. The ports are only edited in the
+    config file.
+
+  h3.h6 What the actions do
+  p.small.
+    Every action switches all the listed ports, unless #[code --port] picks one. The Client runs one power request at a
+    time, so a job's own reset, its owner's and one from the bench never overlap.
+  .table-responsive
+    table.table.table-sm.small.align-middle
+      thead
+        tr
+          th(style="width: 12%") Action
+          th What the Client runs
+      tbody
+        tr
+          td: code on
+          td: code uhubctl -l 1-1.4 -p 2,3 -a on
+        tr
+          td: code off
+          td: code uhubctl -l 1-1.4 -p 2,3 -a off
+        tr
+          td: code reset
+          td
+            | #[code uhubctl … -a off], then a wait of the #[strong reset delay] (1 s unless given, 0–60 s, fractions
+            | allowed), then #[code uhubctl … -a on]. Give boards that are slow to discharge a longer delay.
+        tr
+          td: code status
+          td #[code uhubctl -l 1-1.4 -p 2,3], each port's state from it (Client host only)
+
+  h3.h6 Three ways to switch the power
+  .row.g-3.mb-3
+    .col-md-4
+      .card.h-100
+        .card-header.small
+          i.bi.bi-pc.me-1
+          strong On the Client host
+        .card-body.small
+          p.
+            #[code thub-client power on|off|reset|status [--port N] [--delay SEC]]. It goes through the running Client.
+            If a job is running, its log records the action.
+    .col-md-4
+      .card.h-100
+        .card-header.small
+          i.bi.bi-play-circle.me-1
+          strong At a job's start and end
+        .card-body.small
+          p.mb-2.
+            #[code thub run --power-on-start … --power-on-end … [--power-reset-delay SEC]] (HW jobs). The start action runs
+            after the downloads, before the command; if it fails, the job ends #[code ERROR].
+          p.mb-0.
+            The end action runs however the job ends (failed and canceled jobs too), before the result is reported.
+            If it fails, the failure is logged and the verdict stays as it was.
+    .col-md-4
+      .card.h-100
+        .card-header.small
+          i.bi.bi-lightning.me-1
+          strong While your job runs
+        .card-body.small
+          p.mb-2.
+            #[code thub power on|off|reset <jobId> [--delay SEC] [--port N]]. Power-cycle a hung board straight away,
+            without canceling the job.
+          p.mb-0.
+            Only the job's owner can do this, not even an admin, and only while the job is #[code PREPARING] or
+            #[code RUNNING]. It reaches the Client within about a second.
+
+  +code('Cold-boot the board before the job, leave it off afterwards').
+    thub run --type hw --label board:nucleo-f401re \
+      --download-file "$IMAGE_URL" \
+      --command 'st-flash --reset write "$THUB_DOWNLOAD_1" 0x08000000 && ./ci/test.sh' \
+      --power-on-start reset --power-reset-delay 2 \
+      --power-on-end off \
+      --wait
+  +code('The board hung: power-cycle it from another terminal').
+    $ thub power reset M-00131
+    USB power reset, 1 s off sent to lab-hw-01 for job M-00131 — the job's log shows when it's done.
+    $ thub power reset M-00131 --port 2 --delay 3     # just the Client's second port, 3 s off
+    $ thub power off M-00131 && thub power on M-00131
+  +code('What the job log shows').
+    [runner] job start: USB power reset
+    [runner] USB power reset: 1-1.4:2, 1-1.4:3 (off 2 s)
+    [runner] preparing DUT
+    [runner] USB power reset (port 2) requested by alice (thub power)
+    [runner] USB power reset: 1-1.4:3 (off 3 s)
+    [runner] job end: USB power off
+    [runner] USB power off: 1-1.4:2, 1-1.4:3
+  +code('From the test script itself, between test cases (the Agent must be installed on the Client host)').
+    thub run --type hw --env AGENT_URL --env AGENT_KEY --command './ci/test.sh' --wait
+    # in ci/test.sh — the key must be the one that submitted the job:
+    thub --url "$AGENT_URL" --key "$AGENT_KEY" power reset "$THUB_JOB_ID" --delay 2
+  p.small.mb-0.
+    A dry run (#[code --dry-run]) lists the uhubctl calls instead of making them. The command sees what was asked for
+    as #[code JOB_POWER_ON_START], #[code JOB_POWER_ON_END] and #[code JOB_POWER_RESET_DELAY]. Problems are covered
+    under #[a(href="#troubleshooting") Troubleshooting]. Boards on a smart socket or a PDU outlet are switched by the job
+    itself: see #[a(href="#lab-devices") Smart sockets, PDUs and other lab devices].

package/views/help/index.pug

@@ -12,11 +12,14 @@ block content
       { id: 'agent-setup', label: 'Agent setup' },
       { id: 'client-setup', label: 'Client setup' },
       { id: 'client-machines', label: 'Client machines (HW / SW)' },
+      { id: 'usb-power', label: 'USB port power (uhubctl)' },
+      { id: 'lab-devices', label: 'Smart sockets, PDUs, devices' },
       { id: 'docker', label: 'Using Docker' },
       { id: 'git', label: 'Using git' },
       { id: 'agent-cli', label: 'Agent CLI reference' },
       { id: 'env', label: 'Environment variables' },
-      { id: 'ci', label: 'CI/CD (GitHub Actions)' },
+      { id: 'storage', label: 'Artifact storage & certificates' },
+      { id: 'ci', label: 'CI/CD (GitHub, GitLab, Bitbucket, Jenkins)' },
       { id: 'troubleshooting', label: 'Troubleshooting' }
     ]
 
@@ -58,10 +61,13 @@ block content
       include _agent-setup
       include _client-setup
       include _client-machines
+      include _usb-power
+      include _lab-devices
       include _docker
       include _git
       include _agent-cli
       include _env
+      include _storage
       include _ci
       include _troubleshooting
 

package/views/mixins/client-config.pug

@@ -234,10 +234,13 @@ mixin configPanes(r, returnTo, groupsById)
       +configPane(p, t[0])
         p.small.text-body-secondary.mb-0 Devices can't be edited here: #{noConfigReport}
   else
+    //- What the tabs don't edit (usbPower, README §8.7) goes back as it was.
+    - const keep = Object.fromEntries(Object.entries(current).filter(([k]) => !['stlinks', 'uarts', 'usbs'].includes(k)))
     form(
       method="post"
       action=`/runners/${r.id}/config`
       data-client-config="hw"
+      data-keep=JSON.stringify(keep)
       data-confirm=`Apply these devices to ${r.name}? The Client writes them to its config file on its next heartbeat and restarts once it has no job running.`
       data-confirm-title="Save Client devices?"
       data-confirm-ok="Save"