From 826b097becc842f8fe0ab0d895c2052f929d8ba7 Mon Sep 17 00:00:00 2001
From: TK <61820360+TomKovac@users.noreply.github.com>
Date: Tue, 21 Apr 2026 11:28:07 +0200
Subject: [PATCH 1/3] Create draft PR for #1115
From ee984635c0647f1655ee271cf605bf167a653ff6 Mon Sep 17 00:00:00 2001
From: TK <61820360+TomKovac@users.noreply.github.com>
Date: Tue, 21 Apr 2026 12:06:39 +0200
Subject: [PATCH 2/3] done
---
.../GSDML-V2.4-KUKA-KR C5-20220704.xml | 2690 +++++++++++++++++
.../assets/kuka_krc5/kuka_krc5_dio512.hwl.yml | 77 +
2 files changed, 2767 insertions(+)
create mode 100644 src/components.kuka.robotics/ctrl/assets/kuka_krc5/GSDML-V2.4-KUKA-KR C5-20220704.xml
create mode 100644 src/components.kuka.robotics/ctrl/assets/kuka_krc5/kuka_krc5_dio512.hwl.yml
diff --git a/src/components.kuka.robotics/ctrl/assets/kuka_krc5/GSDML-V2.4-KUKA-KR C5-20220704.xml b/src/components.kuka.robotics/ctrl/assets/kuka_krc5/GSDML-V2.4-KUKA-KR C5-20220704.xml
new file mode 100644
index 000000000..4bf4ad665
--- /dev/null
+++ b/src/components.kuka.robotics/ctrl/assets/kuka_krc5/GSDML-V2.4-KUKA-KR C5-20220704.xml
@@ -0,0 +1,2690 @@
+
+
+
+ PROFINET Device Profile
+ 1.00
+ Device Profile for PROFINET Devices
+ PROFIBUS Nutzerorganisation e. V. (PNO)
+ Device
+
+ 4
+ 1
+ GSDML
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/components.kuka.robotics/ctrl/assets/kuka_krc5/kuka_krc5_dio512.hwl.yml b/src/components.kuka.robotics/ctrl/assets/kuka_krc5/kuka_krc5_dio512.hwl.yml
new file mode 100644
index 000000000..972b86adf
--- /dev/null
+++ b/src/components.kuka.robotics/ctrl/assets/kuka_krc5/kuka_krc5_dio512.hwl.yml
@@ -0,0 +1,77 @@
+Templates:
+ Devices:
+ - Name: 'kuka_krc5_dio512'
+ Placeholders:
+ - Name: 'NAME'
+ Value: 'kuka_krc5_robot'
+ - Name: 'IP_ADDRESS_X1'
+ Value: '192.168.100.1/24'
+ - Name: 'PROFINET_DEVICE_NAME_X1'
+ Value: 'kuka_krc5_robot'
+ Content:
+ Name: '${NAME}'
+ Modules:
+ - Name: '${NAME}'
+ TypeIdentifier:
+ FileName: 'GSDML-V2.4-KUKA-KR C5-20220704.XML'
+ GsdId: 'DIM 1'
+ Interfaces:
+ - Name: 'Interface1'
+ Label: 'X1'
+ Addresses:
+ - Type: 'IPv4'
+ Address: '${IP_ADDRESS_X1}'
+ # RouterAddress: '192.168.0.1'
+ - Type: 'Profinet'
+ ProfinetDeviceName: '${PROFINET_DEVICE_NAME_X1}'
+ Parameters:
+ IECV22LLDPMode: False
+ PrioritizedStartup: False
+ Ports:
+ - Name: 'Port_1'
+ Label: 'X1 P1'
+ Parameters:
+ # Possible values: 8 - Automatic | 16 - TP 100 Mbps full duplex
+ TransmissionRateAndDuplex: 'Automatic'
+ EndOfDetectionOfAccessibleDevices: False
+ EndOfTopologyDiscovery: False
+ PortMonitoring: False
+ # TransmissionRateAutoNegotiation: True
+ # MediumAttachmentType: 'Copper'
+ - Name: 'Port_2'
+ Label: 'X1 P2'
+ Parameters:
+ # Possible values: 8 - Automatic | 16 - TP 100 Mbps full duplex
+ TransmissionRateAndDuplex: 'Automatic'
+ EndOfDetectionOfAccessibleDevices: False
+ EndOfTopologyDiscovery: False
+ PortMonitoring: False
+ # TransmissionRateAutoNegotiation: True
+ # MediumAttachmentType: 'Copper'
+ - Name: 'Port_3'
+ Label: 'X1 P3'
+ Parameters:
+ # Possible values: 8 - Automatic | 16 - TP 100 Mbps full duplex
+ TransmissionRateAndDuplex: 'Automatic'
+ EndOfDetectionOfAccessibleDevices: False
+ EndOfTopologyDiscovery: False
+ PortMonitoring: False
+ # TransmissionRateAutoNegotiation: True
+ # MediumAttachmentType: 'Copper'
+ - Name: 'Port_4'
+ Label: 'X1 P4'
+ Parameters:
+ # Possible values: 8 - Automatic | 16 - TP 100 Mbps full duplex
+ TransmissionRateAndDuplex: 'Automatic'
+ EndOfDetectionOfAccessibleDevices: False
+ EndOfTopologyDiscovery: False
+ PortMonitoring: False
+ # TransmissionRateAutoNegotiation: True
+ # MediumAttachmentType: 'Copper'
+ - TypeIdentifier: NotAssigned
+ Slot: 1
+ - Name: DIO512
+ TypeIdentifier:
+ GsdId: '15'
+ FileName: GSDML-V2.4-KUKA-KR C5-20220704.XML
+ Slot: 2
\ No newline at end of file
From 50b6fc00d751344730e805e47b7d622cb59dff3d Mon Sep 17 00:00:00 2001
From: Peter Kurhajec <61538034+PTKu@users.noreply.github.com>
Date: Tue, 21 Apr 2026 14:14:56 +0200
Subject: [PATCH 3/3] docs: Update KUKA documentation with new sections,
capabilities, and troubleshooting details
---
CHANGELOG.md | 22 ++
.../AxoKukaRobotics_Config.st | 10 +-
.../AxoKukaRobotics_HWIDs.st | 10 +-
.../docs/AxoKrc4_v_5_x_x.md | 106 ++++++++-
.../docs/CHANGELOG.md | 23 ++
src/components.kuka.robotics/docs/README.md | 50 +++-
src/components.kuka.robotics/docs/TROUBLES.md | 220 +++++++++++++++++-
7 files changed, 425 insertions(+), 16 deletions(-)
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.
---