Merge branch 'main' of ssh://892887cvmk08.aicp.io:24928/orisys-tech/orisys-app

apps/autocal/docs/workflow.md

@@ -61,17 +61,38 @@ slaves. A missing drive discovered at P7 wastes the whole run.
 **Inputs:** controller address, the matching `.bas` program
 (`ECAT.bas` / `RTEX.bas`).
 
-**Steps:** connect → download and run the BAS program → watch
-`Bus_InitStatus` to completion or timeout → read `BUS_TYPE`,
-`Bus_TotalAxisnum`, and the node count.
+**Steps:** connect → **adopt a program the controller is already running, or
+download one if `BUS_TYPE` is unreadable** → watch `Bus_InitStatus` to completion
+or timeout → read `BUS_TYPE`, `Bus_TotalAxisnum`, and the node count. Step 2 is
+conditional because a controller usually still has the program in ROM from the
+last session, and a download is a bus re-scan the operator did not ask for.
+
+**Re-initialising without a download:** `STOPTASK <task>` then
+`RUN "<file>",<task>`, on the task from `bas_task` in `preference.json`
+(default 4 — the task the vendor reference uses; stopping another task restarts
+nothing). Two things are easy to get wrong here, and both have been:
+
+- the file name must be the one the *controller* has. When the session adopted a
+  running program, the controller does not report the name, so the app carries
+  the remembered `bas_path` into the connect for exactly this purpose;
+- the controller answers a `RUN` naming a file it does not have with **code 0**
+  and the diagnosis in its reply text. The reply is checked, and its text is
+  shown instead of reporting an initialisation that is not happening.
 
 **Outputs:** bus type, node count, axis count, init status.
 
 **Gate:** init status is success, **and** the node/axis counts match what this
 bench is expected to have. A mismatch is a finding, not a warning.
 
-**Existing code:** `MotionService.download_bas` / `poll` already implement the
-state machine and the 25 s timeout.
+**Existing code:** `MotionService.download_bas` / `reinit_bus` / `poll` implement
+the state machine and the 25 s timeout.
+
+**Connection faults are a different family.** A `ZAux_*` code in 20000–29999 is a
+PC-library fault (handshake, socket, address), not a controller code: ZDevelop's
+table cannot contain it, so the app answers it with cable/IP/no-second-client
+advice and retries an Ethernet open up to three times, because a first open on a
+cold route can fail and succeed immediately after. `20008` at the bench was that
+case.
 
 ---