diff --git a/CHANGELOG.md b/CHANGELOG.md index d7af799ae..21c07f9d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,25 @@ +### [KUKA] KRC4 documentation refresh and GSDML/hw template callouts ([#TBD](https://github.com/Inxton/AXOpen/pulls)) + +**Note:** Documentation-only change for `components.kuka.robotics`. No runtime behavior modified. + +- docs: Added `` and `` tagged regions in `AxoKukaRobotics_Config.st` / `AxoKukaRobotics_HWIDs.st` so docs can reference them via `[!code-smalltalk[]]`. +- docs: Rewrote `docs/AxoKrc4_v_5_x_x.md` with full CONTROLLER / .NET TWIN / BLAZOR / HARDWARE tabs wired to the showcase and library source; added Capabilities + Configuration parameter table and an "Alternative example" block referencing `AxoKrc4_v_5_x_x_Showcase2.st`. +- docs: Expanded `docs/TROUBLES.md` with an error-ID reference covering the bring-up (700, 702, 710, 720–726, 1130–1133), cyclic I/O (1201, 1231), runtime-safety (20001–20005), and 500-range task *potential* identifiers; added component-specific diagnostics and known-limitations sections. +- docs: Updated `docs/README.md` with a "Hardware assets" table pointing at the library-shipped KRC4 GSDML (`ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml`) and the PROFINET hw template (`kuka_krc4_dio512.hwl.yml`); mirrored the callout in the `AxoKrc4_v_5_x_x.md` HARDWARE tab with GitHub links. +- docs: Repointed stale GitHub source links from branch `3-unify-showcase` to `dev`; appended `0.50.0` / `0.50.1` entries to `src/components.kuka.robotics/docs/CHANGELOG.md`. + +**Impact:** +- Integrators see the shipped GSDML and hw template path directly from the library docs, without vendor round-trips. +- Troubleshooting KRC4 cells on-site is driven from a per-error-ID table instead of generic advice. +- `[!code-smalltalk[]]` refs in the component doc now render the live `Config` / `HWIDs` declarations from the library source. + +**Risks/Review:** +- The new tagged regions must be preserved in future edits of `AxoKukaRobotics_Config.st` / `AxoKukaRobotics_HWIDs.st` — removing them breaks the doc references. +- PR number in this entry is `#TBD`; update once the PR is opened. + +**Testing:** +- Build docs locally via `scripts/_build_documentation.ps1` and confirm the KRC4 pages render, the `[!code-*]` directives resolve, and the new GitHub links on the HARDWARE tab / README resolve to existing files. + ### [CORE] Controller logger updates ([#1054](https://github.com/Inxton/AXOpen/pull/1054)) **Note:** Enhanced logging and messaging capabilities with new message categories and requalification features. diff --git a/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_Config.st b/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_Config.st index b1d95824c..bbbc667e2 100644 --- a/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_Config.st +++ b/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_Config.st @@ -1,8 +1,9 @@ NAMESPACE AXOpen.Components.Kuka.Robotics.v_5_x_x + // {#ix-attr:[Container(Layout.Stack)]} {S7.extern=ReadWrite} CLASS PUBLIC AxoKukaRobotics_Config - VAR PUBLIC + VAR PUBLIC {#ix-set:AttributeName = "<#Info time#>"} InfoTime : LTIME := LT#2S; {#ix-set:AttributeName = "<#Error time#>"} @@ -10,7 +11,8 @@ NAMESPACE AXOpen.Components.Kuka.Robotics.v_5_x_x {#ix-set:AttributeName = "<#Task timeout#>"} TaskTimeout : LTIME := LT#50S; {#ix-set:AttributeName = "<#Hardware IDs#>"} - HWIDs : AxoKukaRobotics_HWIDs; - END_VAR - END_CLASS + HWIDs : AxoKukaRobotics_HWIDs; + END_VAR + END_CLASS + // END_NAMESPACE diff --git a/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_HWIDs.st b/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_HWIDs.st index 74fb741ec..3268ba21f 100644 --- a/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_HWIDs.st +++ b/src/components.kuka.robotics/ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_HWIDs.st @@ -1,7 +1,8 @@ -NAMESPACE AXOpen.Components.Kuka.Robotics.v_5_x_x +NAMESPACE AXOpen.Components.Kuka.Robotics.v_5_x_x + // {S7.extern=ReadWrite} {#ix-attr:[Container(Layout.Stack)]} - CLASS PUBLIC AxoKukaRobotics_HWIDs + CLASS PUBLIC AxoKukaRobotics_HWIDs VAR PUBLIC {#ix-set:AttributeName = "<#Hardware ID of the device#>"} HwID_Device : UINT; @@ -9,6 +10,7 @@ NAMESPACE AXOpen.Components.Kuka.Robotics.v_5_x_x HwID_None : UINT; {#ix-set:AttributeName = "<#Hardware ID of the '512_DI_DO' submodule#>"} HwID_512_DI_DO : UINT; - END_VAR - END_CLASS + END_VAR + END_CLASS + // END_NAMESPACE \ No newline at end of file diff --git a/src/components.kuka.robotics/docs/AxoKrc4_v_5_x_x.md b/src/components.kuka.robotics/docs/AxoKrc4_v_5_x_x.md index 03c4a17e6..a9b7b6663 100644 --- a/src/components.kuka.robotics/docs/AxoKrc4_v_5_x_x.md +++ b/src/components.kuka.robotics/docs/AxoKrc4_v_5_x_x.md @@ -2,7 +2,49 @@ _KUKA KRC4 industrial robot controller_ -Generated documentation for the `AxoKrc4_v_5_x_x` component. +`AxoKrc4` (namespace `AXOpen.Components.Kuka.Robotics.v_5_x_x`) is the +controller proxy for robots driven by a KUKA KRC4. It extends +`AXOpen.Core.AxoComponent` and implements +`AXOpen.Components.Abstractions.Robotics.IAxoRobotics`, exposing all programme +and motion commands as `AxoTask` instances that advance their state machine +inside the component's `Run()` call. + +## Capabilities + +- Programme control — `StartAtMain`, `StartProgram`, `StopProgram`, `StartMotorsAndProgram`, `StopMovementsAndProgram`. +- Motor control — `StartMotors`, `StopMotors`. +- Motion commands — `StartMovements(movementParams)`, `StopMovements`, + and a combined `StartMotorsProgramAndMovements(movementParams)`. +- Safety-interlocked task execution — every task checks `Inputs.Manual`, + `Inputs.Automatic`, `Inputs.AlarmStopActive`, `Inputs.UserSafetySwitchClosed`, + and `Inputs.Error` while busy (error IDs 20001–20005). +- Hardware wiring — consumes a PROFINET device identifier; the `Run()` + method auto-resolves the child slot layout (slot 1 safety-module = empty, + slot 2 = 512 DI / 512 DO) via `ReadSlotFromHardwareID` and + `ReadHardwareIOAddress` during first cycle. +- Cyclic I/O transfer — `Siemens.Simatic.DistributedIO.ReadData`/`WriteData` + on slot 2 each cycle (error IDs 1201 / 1231 on transport failure). +- Tool / area / position / coordinate outputs driven from `MovementParameters`. +- Hardware diagnostics task (`HardwareDiagnosticsTask`) and two on-delay + info/error timers (`Config.InfoTime`, `Config.ErrorTime`, + `Config.TaskTimeout`). + +## Configuration + +The component is configured via the nested `Config : AxoKukaRobotics_Config` +member. Adjust these before invoking `Run()`; they can also be set from the +commissioning UI. + +| Parameter | Type | Default | Purpose | +|-----------|------|---------|---------| +| `Config.InfoTime` | `LTIME` | `LT#2S` | Delay before a task publishes a *potential* (waiting-for-signal) message. Controls how long the component waits silently on an expected input before surfacing progress via `TaskMessenger`. | +| `Config.ErrorTime` | `LTIME` | `LT#5S` | Delay before `_errorTimer.output` throws the currently-executing task. Acts as a per-step watchdog on KRC4 responses. | +| `Config.TaskTimeout` | `LTIME` | `LT#50S` | Hard upper bound for a task's total duration. `0s` disables the timeout (used in the showcase so commissioning demos never self-abort). | +| `Config.HWIDs` | `AxoKukaRobotics_HWIDs` | — | Device hardware identifiers, auto-populated on first `Run()` from the `hwID` argument and the slot layout. | + +[!code-smalltalk[](../ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_Config.st?name=AxoKukaRoboticsConfigDeclaration)] + +[!code-smalltalk[](../ctrl/src/AxoKukaRobotics_Datatypes_v_5_x_x/AxoKukaRobotics_HWIDs.st?name=AxoKukaRoboticsHWIDsDeclaration)] # [CONTROLLER](#tab/controller) @@ -26,20 +68,31 @@ Generated documentation for the `AxoKrc4_v_5_x_x` component. [!code-pascal[](../../showcase/app/src/components.kuka.robotics/Documentation/AxoKrc4_v_5_x_x_Showcase.st?name=Usage)] +## Alternative example + +A second wired-up instance (`AxoKrc4_v_5_x_x_Showcase2`) is available and is +rendered side-by-side on the showcase Blazor page. It reuses the same +hardware identifier `kuka_rb1_HwID` and differs only in that it keeps +`Config.ErrorTime` at the library default (live error watchdog) instead of +zeroing it out for commissioning. + +[!code-pascal[](../../showcase/app/src/components.kuka.robotics/Documentation/AxoKrc4_v_5_x_x_Showcase2.st?name=ComponentDeclaration)] +[!code-pascal[](../../showcase/app/src/components.kuka.robotics/Documentation/AxoKrc4_v_5_x_x_Showcase2.st?name=Initialization)] + ## Source -View the library source at [`AxoKrc4_v_5_x_x.st`](https://github.com/Inxton/AXOpen/tree/3-unify-showcase/src/components.kuka.robotics/ctrl/src/AxoKrc4_v_5_x_x/AxoKrc4_v_5_x_x.st). +View the library source at [`AxoKrc4_v_5_x_x.st`](https://github.com/Inxton/AXOpen/tree/dev/src/components.kuka.robotics/ctrl/src/AxoKrc4_v_5_x_x.st). # [.NET TWIN](#tab/twin) ## Source -View the .NET twin source at [`AXOpen.Components.Kuka.Robotics`](https://github.com/Inxton/AXOpen/tree/3-unify-showcase/src/components.kuka.robotics/src/AXOpen.Components.Kuka.Robotics/). +View the .NET twin source at [`AXOpen.Components.Kuka.Robotics`](https://github.com/Inxton/AXOpen/tree/dev/src/components.kuka.robotics/src/AXOpen.Components.Kuka.Robotics/). # [BLAZOR](#tab/blazor) -`AxoKrc4_v_5_x_x` does not ship a dedicated Blazor view. It renders via the generic `AxoComponent` pattern using `RenderableContentControl`, which inspects the component type at runtime and selects the matching rendering based on the `Presentation` attribute. +`AxoKrc4` does not ship a dedicated Blazor view. It renders via the generic `AxoComponent` pattern using `RenderableContentControl`, which inspects the component type at runtime and selects the matching rendering based on the `Presentation` attribute. ## Status display @@ -61,13 +114,54 @@ Available `Presentation` values: `Status-Display`, `Command-Control`, `Service-C ## Source -View the Blazor package at [`AXOpen.Components.Kuka.Robotics.blazor`](https://github.com/Inxton/AXOpen/tree/3-unify-showcase/src/components.kuka.robotics/src/AXOpen.Components.Kuka.Robotics.blazor/). +View the Blazor package at [`AXOpen.Components.Kuka.Robotics.blazor`](https://github.com/Inxton/AXOpen/tree/dev/src/components.kuka.robotics/src/AXOpen.Components.Kuka.Robotics.blazor/). # [HARDWARE](#tab/hardware) +## Library-shipped assets + +The raw KRC4 GSDML and the matching PROFINET device template live inside +the library package so `AxoKrc4` can be wired up without fetching files +from the vendor: + +- GSDML — [`ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml`](https://github.com/Inxton/AXOpen/tree/dev/src/components.kuka.robotics/ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml) + — vendor GSDML for Siemens hardware-catalog import. +- HW template — [`ctrl/assets/kuka_krc4/kuka_krc4_dio512.hwl.yml`](https://github.com/Inxton/AXOpen/tree/dev/src/components.kuka.robotics/ctrl/assets/kuka_krc4/kuka_krc4_dio512.hwl.yml) + — PROFINET device template expected by `Run()` (slot 1 empty, slot 2 = `512_DI_DO`, 64-byte cyclic I/O). + +The showcase copies the template into `showcase/app/hwc/library_templates/kuka_krc4/` +so application builds do not need a catalog round-trip. + ## Device template -PROFINET hardware template at `showcase/app/hwc/library_templates/kuka_krc4/`. +PROFINET hardware template at `showcase/app/hwc/library_templates/kuka_krc4/kuka_krc4_dio512.hwl.yml`. + +The template provisions a KRC4 as a PROFINET device with two slots: + +| Slot | Module | Purpose | +|------|--------|---------| +| 1 | *(safety module, left empty by the template)* | Reserved — `AxoKrc4.Run()` verifies this slot resolves to `HwID_None = 0`. | +| 2 | `512_DI_DO` | 64-byte in / 64-byte out PROFINET I/O cyclically transferred by the component. | + +## I/O mapping + +`Run()` takes a single `hwID : UINT` that identifies the KRC4 device in the +configured hardware layout. The component then: + +1. Calls `ReadSlotFromHardwareID(hwID)` to obtain the device's geographic + address. +2. Reads the hardware ID of slot 1 and asserts it is `0` (no safety module + wired — error 710 otherwise). +3. Reads the hardware ID of slot 2 (the 512 DI / 512 DO module) and caches + it in `Config.HWIDs.HwID_512_DI_DO`. +4. Calls `ReadHardwareIOAddress` on slot 2 and asserts it exposes exactly + 64 input and 64 output bytes (error 726 otherwise). +5. Each cycle thereafter: `Siemens.Simatic.DistributedIO.ReadData` / + `WriteData` transfer the 64-byte blocks bound to `Inputs` / `Outputs`. + +Use the `AXOpen.Showcase.HwIdentifiers#{device}_HwID` constants to supply +`hwID` from application code (as the showcase does with +`kuka_rb1_HwID`). ## Device instantiation diff --git a/src/components.kuka.robotics/docs/CHANGELOG.md b/src/components.kuka.robotics/docs/CHANGELOG.md index 9d58311c8..b1dde834b 100644 --- a/src/components.kuka.robotics/docs/CHANGELOG.md +++ b/src/components.kuka.robotics/docs/CHANGELOG.md @@ -6,3 +6,26 @@ - Restructured documentation to class-name convention: added `AxoKrc4_v_5_x_x.md`; removed legacy `*_Showcase.md`, `*_Showcase2.md`, and `ComponentTemplate.md`. - Added CONTROLLER, .NET TWIN, BLAZOR, and HARDWARE tabs with DocFX source references wired to live showcase markers. - Initial CHANGELOG entry. + +### 0.50.0 + +**Other:** +- `README.md` — added Components, Configuration/state types, Packages, Dependencies tables and the KUKA vendor link. +- `AxoKrc4_v_5_x_x.md` — added Capabilities and Configuration sections with a `Config` parameter table; wired `[!code-smalltalk[]]` references to new `AxoKukaRoboticsConfigDeclaration` / `AxoKukaRoboticsHWIDsDeclaration` regions in the library source; added an "Alternative example" block referencing `AxoKrc4_v_5_x_x_Showcase2.st`; expanded the HARDWARE tab with slot layout and `hwID` resolution flow. +- `TROUBLES.md` — added component-specific common-issues, runtime-safety, and error-ID reference sections covering IDs 700, 701, 702, 710, 720–726, 1130–1133, 1201, 1231, 20001–20005, and the 500-range task *potential* identifiers; retained the existing Support pointer. +- Repointed stale GitHub source links from branch `3-unify-showcase` to `dev`. + +**New regions:** +- `AxoKukaRobotics_Config.st` — ``. +- `AxoKukaRobotics_HWIDs.st` — ``. + +### 0.50.1 + +**Other:** +- `README.md` — added a "Hardware assets" table pointing at the + library-shipped GSDML (`ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml`) + and the PROFINET hw template (`ctrl/assets/kuka_krc4/kuka_krc4_dio512.hwl.yml`), + plus a note that the showcase re-uses the same template. +- `AxoKrc4_v_5_x_x.md` — HARDWARE tab now opens with a "Library-shipped + assets" section linking the GSDML and hw template on GitHub, so + integrators see where the raw assets live inside this package. diff --git a/src/components.kuka.robotics/docs/README.md b/src/components.kuka.robotics/docs/README.md index 6ab1923b0..bee93dcee 100644 --- a/src/components.kuka.robotics/docs/README.md +++ b/src/components.kuka.robotics/docs/README.md @@ -4,7 +4,55 @@ The **components.kuka.robotics** is a set of libraries covering the product port The package consists of a PLC library providing control logic and its .NET twin counterpart aimed at the visualization part. This package currently covers the robots driven by KRC4 controller. +### Components + +| Component | Description | +|-----------|-------------| +| [`AxoKrc4`](AxoKrc4_v_5_x_x.md) | KUKA KRC4 controller proxy (namespace `AXOpen.Components.Kuka.Robotics.v_5_x_x`) exposing programme/motion commands, safety state, tool/zone outputs, and hardware diagnostics. Derives from `AxoComponent` and implements `IAxoRobotics`. | + +### Configuration & state types + +| Type | Role | +|------|------| +| `AxoKukaRobotics_Config` | Configuration: `InfoTime`, `ErrorTime`, `TaskTimeout`, `HWIDs`. | +| `AxoKukaRobotics_HWIDs` | Hardware identifiers: `HwID_Device`, `HwID_None`, `HwID_512_DI_DO`. | +| `AxoKukaRobotics_State` | Input image (RC_RDY1, ALARM_STOP, USER_SAF, PERI_RDY, ROB_CAL, I_O_ACTCONF, STOPMESS, ROB_STOPPED, mode, position/zone, tool feedback, coordinates). | +| `AxoKukaRobotics_Control` | Output image (EXT_START, MOVE_ENABLE, CONF_MESS, DRIVES_OFF, DRIVES_ON, I_O_ACT, START_AT_MAIN, master mode, tool commands, action/speed/tool/point numbers, coordinates). | +| `AxoKukaRobotics_Component_Status` | Runtime status (extends `AxoRobot_Status`). | + +### Packages + +| Package | Purpose | +|---------|---------| +| `@inxton/axopen.components.kuka.robotics` | PLC library (apax) | +| `AXOpen.Components.Kuka.Robotics` | .NET twin | +| `AXOpen.Components.Kuka.Robotics.blazor` | Blazor rendering assets | + +### Hardware assets + +The library ships the KRC4 GSDML and a ready-to-apply PROFINET device +template so the robot can be dropped into a `plc_line.hwl.yml` without +vendor-side configuration: + +| Asset | Path | Purpose | +|-------|------|---------| +| GSDML | [`ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml`](../ctrl/assets/kuka_krc4/GSDML-V2.33-KUKA-KRC4-ProfiNet_5.0-20181102.xml) | Vendor GSDML (KUKA KRC4 ProfiNet 5.0, 2018-11-02) for Siemens hardware catalog import. | +| HW template | [`ctrl/assets/kuka_krc4/kuka_krc4_dio512.hwl.yml`](../ctrl/assets/kuka_krc4/kuka_krc4_dio512.hwl.yml) | PROFINET device template with slot 1 empty (safety) and slot 2 = `512_DI_DO` (64-byte in / 64-byte out). Expected by `AxoKrc4.Run()`. | + +The showcase application uses the same template via +`showcase/app/hwc/library_templates/kuka_krc4/kuka_krc4_dio512.hwl.yml` +and wires it into `plc_line.hwl.yml` under the `` region. + +### Dependencies + +| Package | Purpose | +|---------|---------| +| `@inxton/axopen.components.robotics` | Shared robotics abstractions (`AxoRobot_Status`, task/messenger base types). | + ### Links to documentation -[Siemens AX-documentation](https://developer.siemens.com/simatic-ax/developer.html) + +[Siemens AX-documentation](https://developer.siemens.com/simatic-ax/developer.html) [AxOpen-documentation](https://inxton.github.io/AXOpen/) + +[KUKA documentation](https://www.kuka.com/en-gb) diff --git a/src/components.kuka.robotics/docs/TROUBLES.md b/src/components.kuka.robotics/docs/TROUBLES.md index 5cdc2ba7d..a3f9b545c 100644 --- a/src/components.kuka.robotics/docs/TROUBLES.md +++ b/src/components.kuka.robotics/docs/TROUBLES.md @@ -1,5 +1,223 @@ # Troubleshooting -Unfortunately, we don't have a direct solution to your problem at the moment. If you encounter any issues, please [file a report on our GitHub](https://github.com/inxton/AXOpen/issues/new/choose). We appreciate your feedback and patience. +This page catalogues the error states surfaced by `AxoKrc4_v_5_x_x.AxoKrc4`, +each tied back to its raising site in the PLC source. Error identifiers are +published through `Status.Error.Id` and the component's `Messenger` / +`TaskMessenger`, so the ID seen in a log or on the HMI always maps to one +of the entries below. + +## Common issues + +### The component never completes its first-cycle hardware check + +**Symptom.** `_initHwCheckDone` never goes `TRUE`; `Status.Error.Id` sits at +one of 700, 701, 702, 710, 720–726, or 1130–1133; no `Inputs` are populated +from the field. + +**Why.** `Run()` stays inside its one-shot bring-up block until every slot +probe succeeds. If any probe fails, it activates the matching message and +`RETURN`s, so the cyclic I/O read at the bottom of `Run()` never executes. + +**What to check.** + +- `inParent` was passed to `Run()` (missing parent → error 700 / 1130). +- A non-zero hardware identifier was passed (`hwID = 0` → error 701 / 1131). + Prefer `AXOpen.Showcase.HwIdentifiers#{device}_HwID` constants. +- Slot 1 in the PROFINET template is empty (no safety module added by the + application). A non-zero ID here raises error 710 / 1132. +- Slot 2 is the `512_DI_DO` submodule from the shipped template and is + reachable on the PROFINET subnet (errors 720–725, 1133). +- The KRC4 template at + `showcase/app/hwc/library_templates/kuka_krc4/kuka_krc4_dio512.hwl.yml` + is the one applied in `plc_line.hwl.yml` (`- Apply: kuka_krc4_dio512`). + A different template likely breaks the 64-in / 64-out I/O size assertion + (error 726). + +### `Run()` runs but tasks never start + +**Symptom.** Calls like `ExampleRobot.StartMotorsAndProgram()` stay in a +`IsBusy()` state; `Status.Error.Id` reports 500-range *potential* IDs. + +**Why.** Every task advances its state machine inside +`AxoKrc4.Run()`. The 500-range IDs are informational — they report which +KRC4 input the task is waiting on (e.g. `UserSafetySwitchClosed`, +`DrivesReady`, `Automatic`, `AlarmStopActive`). They are not errors. + +**What to check.** + +- The KRC4 is in external-automatic mode (`Inputs.ExternalAutomatic = TRUE`) + and not in `Inputs.Manual`. Any active task immediately raises error + 20001 in manual mode. +- `Inputs.UserSafetySwitchClosed`, `Inputs.AlarmStopActive`, and + `Inputs.DrivesReady` track the KRC4 safety circuit. Tasks block on + these; if they never assert, inspect the E-stop chain on the robot cell. +- `Inputs.Error = TRUE` raises error 20005 while a task is busy; clear + the KRC4-side fault, then call `ExampleRobot.ErrorConfirmation` via + `Outputs.ErrorConfirmation` or run the `Restore` sequencer step. +- `Config.TaskTimeout` has not elapsed (default `LT#50S`). Set to `0s` + during commissioning to disable the watchdog. + +### Movement parameters never take effect + +**Symptom.** `StartMovements(params)` stays busy; `Status.Error.Id` +cycles through 554–559 (or 528–533 for the combined task). + +**Why.** The task writes movement parameters to `Outputs` and then waits +for the KRC4 to mirror each parameter back on `Inputs` before advancing. +If the mirror never happens the task is stuck at `_movement_progress = 354`. + +**What to check.** + +- The KRC4 programme on the controller side is running and processing the + AXOpen interface (the `I_O_ACT` output must be accepted; `I_O_ACTCONF` + should come back on `Inputs.InterfaceActivated`). +- The `ActionNo` written by the PLC (`Outputs.ActionNo`) matches the value + echoed back on `Inputs.ActionNo`. The component handshakes action numbers + `253`, `254`, `255` during the movement step machine; a mismatch means + the KRC4 programme is not advancing. +- `AXOpen.Components.Robotics.CoordinatesAreNearlyEqual` returns `TRUE` for + the commanded vs. echoed coordinates within `0.01` tolerance. Values + outside that tolerance keep the task in the acknowledge state. + +### PROFINET read / write transport failures + +**Symptom.** `Status.Error.Id` reports 1201 or 1231 and the component +`RETURN`s early each cycle, freezing all tasks. + +**Why.** + +- 1201 — `Siemens.Simatic.DistributedIO.ReadData` returned a non-zero + status. The 64-byte input block could not be fetched from slot 2. +- 1231 — `Siemens.Simatic.DistributedIO.WriteData` returned a non-zero + status. The 64-byte output block could not be pushed to slot 2. + +**What to check.** + +- The PROFINET device is online (link up, device name applied, IP reachable). + These are transport failures, not configuration faults. +- No other controller owns the same PROFINET device name + (`PROFINET_DEVICE_NAME_X1: kuka_rb1` in the shipped template). +- Slot 2 still contains the `512_DI_DO` submodule — replacing or removing + it after commissioning invalidates `HwID_512_DI_DO`. + +### Safety-interlock errors while a task is busy + +`AxoKrc4` arms a safety gate around every programme/motion task. While +`StartAtMainTask`, `StartMotorsAndProgramTask`, `StartMovementsTask`, +`StopMovementsTask`, `StopMovementsAndProgramTask`, or `StopProgramTask` +is busy, the component raises one of 20001–20005 as soon as the +corresponding input asserts/deasserts: + +| Id | Condition | Meaning | +|----|-----------|---------| +| 20001 | `Inputs.Manual = TRUE` | KRC4 went to T1 while a task is executing — automation path invalid. | +| 20002 | `Inputs.Automatic = FALSE` | KRC4 dropped out of auto — task is now illegal. | +| 20003 | `Inputs.AlarmStopActive = FALSE` | Alarm-stop dropped, likely external E-stop. | +| 20004 | `Inputs.UserSafetySwitchClosed = FALSE` | User safety gate opened during motion. | +| 20005 | `Inputs.Error = TRUE` | KRC4 itself raised an error while the task was running. | + +Resolution: bring the cell back into the safe automatic state, call the +task's `Restore()` method so its state machine rewinds, then re-invoke the +task. + +## Error ID reference + +### Hardware bring-up errors (first cycle) + +| Id | Category | Raised when | +|----|----------|-------------| +| 700 | ProgrammingError | `Run()` called with `inParent = NULL`. | +| 701 | ProgrammingError | `Run()` called with `hwID = 0`. | +| 702 | Error | `ReadSlotFromHardwareID` returned `WORD#8090` — unknown hardware ID. | +| 710 | Error | Slot 1 (reserved for a safety module) reports a non-zero hardware ID — unexpected module occupies slot 1. | +| 720 | Error | Slot 2 hardware ID is `0` — `512_DI_DO` submodule missing. | +| 721 | Error | Slot 2 probe returned `WORD#8091`. | +| 722 | Error | Slot 2 probe returned `WORD#8094`. | +| 723 | Error | Slot 2 probe returned `WORD#8095`. | +| 724 | Error | Slot 2 probe returned `WORD#8096`. | +| 725 | Error | Slot 2 probe returned `WORD#8097`. | +| 726 | Error | Slot 2 I/O address range is not 64 in / 64 out. Wrong module template applied. | +| 1130 | Error | Post-probe re-check — `inParent = NULL`. | +| 1131 | Error | Post-probe re-check — `HwID_Device = 0`. | +| 1132 | Error | Post-probe re-check — `HwID_None <> 0`. | +| 1133 | Error | Post-probe re-check — `HwID_512_DI_DO = 0`. | + +### Cyclic I/O errors + +| Id | Category | Raised when | +|----|----------|-------------| +| 1201 | Error | `DistributedIO.ReadData` returned non-zero status — PROFINET read failed. | +| 1231 | Error | `DistributedIO.WriteData` returned non-zero status — PROFINET write failed. | + +### Runtime safety errors (during a busy task) + +| Id | Category | Raised when | +|----|----------|-------------| +| 20001 | Error | `Inputs.Manual = TRUE`. | +| 20002 | Error | `Inputs.Automatic = FALSE`. | +| 20003 | Error | `Inputs.AlarmStopActive = FALSE`. | +| 20004 | Error | `Inputs.UserSafetySwitchClosed = FALSE`. | +| 20005 | Error | `Inputs.Error = TRUE`. | + +### Task "potential" (waiting-on-input) identifiers + +The 500-range identifiers are informational — the component uses them to +show which KRC4 input the currently-executing task is waiting on. They +are surfaced via `TaskMessenger` (category `Potential`) only after +`Config.InfoTime` has elapsed, so a brief wait never raises them. Typical +ranges: + +| Range | Task | What the task is waiting for | +|-------|------|------------------------------| +| 500 | `StartAtMain` | `StartAtMain` input acknowledgement. | +| 510–516 | `StartAtMain` handshake progression | Interface activate, drives ready, programme start confirmation. | +| 520–536 | `StartMotorsProgramAndMovements` | Combined motor/programme/movement bring-up. | +| 540–542 | `StartMotors` | `UserSafetySwitchClosed`, `AlarmStopActive`, `DrivesReady`. | +| 550–562 | `StartMovements` | `ProActive`, `DrivesReady`, `StopMess` clear, parameter acknowledge. | +| 570–576 | `StopMovements` / `StartMotorsAndProgram` | Drive-off handshake, mirrored parameters. | +| 580 | `StartProgram` | Programme start acknowledgement. | +| 590, 591 | `StopProgram`, `StopMovementsAndProgram` | Programme stop acknowledgement. | +| 600, 610, 620 | `StopMovements`, `StopMotors`, `ResetAllOutputs` | Final shutdown handshakes. | + +A *potential* entry is not a fault — inspect the KRC4 inputs named in the +task's current step comment. A task only converts to an error (`10020`, +`10040`, `10041`, …) after `Config.ErrorTime` elapses without the +expected input. + +## Diagnostics + +Read these properties when triaging: + +- `Status.Error.Id` — last raised error (most recent `Messenger.Activate` + call wins). +- `Status.Action.Id` — current macro state of the task layer + (120s / 140s / 150s / 160s ranges mirror `_power_progress` and + `_movement_progress`). +- `_power_progress`, `_movement_progress` — internal step indices. Exposed + read-only on the component so the HMI shows where a task is paused. +- `HardwareDiagnosticsTask` — the embedded `AxoHardwareDiagnostics` task + returns detailed PROFINET slot health; run it whenever transport errors + (1201 / 1231) appear. +- `Messenger` and `TaskMessenger` — the component's two messenger + channels. The first carries errors/programming faults; the second + carries task-level *potential* / info messages. + +## Known limitations + +- Only the KRC4 slot layout `kuka_krc4_dio512` (64-byte I/O) is recognised. + Swapping slot 2 for a different submodule invalidates `HwID_512_DI_DO` + and raises error 720/726. +- Slot 1 must be left empty. Adding a safety module there is currently + unsupported — error 710 is raised pre-emptively (the commented-out error + IDs 711–716 in the source show this branch was intentionally disabled). +- A single `hwID` device is supported per `AxoKrc4` instance; multi-arm + coordination happens at the application level, not inside the component. + +## Support + +Unfortunately, we don't have a direct solution to every problem. If you +encounter an issue not covered here, please +[file a report on our GitHub](https://github.com/inxton/AXOpen/issues/new/choose). +We appreciate your feedback and patience. ---