feat(gateway): generate executable device request seeds

Author: moqui-industrial

agent-skills/skills/moqui-device-gateway-startup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: moqui-device-gateway-startup
 description: Use when the user wants a guided first startup of moqui-device-gateway from reviewed Moqui seed data. This skill inspects the modeled gateway identity, device groups, and DeviceRequest rows, then emits a step-by-step startup checklist aligned with the gateway README and automated tests.
-compatibility: Requires Python 3.14+
 license: ../../LICENSE.md
 metadata:
   author: moqui-industrial
   version: "1.0"
+  compatibility: Requires Python 3.14+
 ---
 
 # Moqui Device Gateway Startup

agent-skills/skills/moqui-device-gateway-startup/scripts/render_gateway_startup_guide.py

@@ -16,6 +16,9 @@
 from pathlib import Path
 
 
+GATEWAY_RUN_SERVICE = "moqui.device.DeviceGatewayServices.run#GatewayDeviceRequest"
+
+
 def utc_now() -> str:
     return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
@@ -193,6 +196,16 @@ def analyze_model(model: dict) -> dict:
             if request.get("routerEnumId") == "DrrMoquiDeviceGateway"
             and request.get("deviceId")
             and request.get("deviceId") not in scoped_devices
+            and request.get("runServiceName") != GATEWAY_RUN_SERVICE
+        )
+        dispatch_wrappers = sorted(
+            (
+                request
+                for request in requests.values()
+                if request.get("deviceId") == gateway_id
+                and request.get("runServiceName") == GATEWAY_RUN_SERVICE
+            ),
+            key=request_name_of,
         )
 
         if not scoped_request_names:
@@ -206,6 +219,7 @@ def analyze_model(model: dict) -> dict:
                 "group_ids": group_ids,
                 "scoped_devices": [scoped_devices[key] for key in sorted(scoped_devices)],
                 "requests": [requests[name] for name in scoped_request_names],
+                "dispatch_wrappers": dispatch_wrappers,
                 "request_items_by_name": request_items_by_name,
                 "out_of_scope_request_names": out_of_scope_request_names,
             }
@@ -344,6 +358,15 @@ def render_guide(seed_path: Path, output_path: Path, analysis: dict) -> str:
             lines.append("- No in-scope gateway-routed requests were found.")
         lines.append("")
 
+        if gateway["dispatch_wrappers"]:
+            lines.append("### Moqui REST dispatch wrappers")
+            lines.append("")
+            for request in gateway["dispatch_wrappers"]:
+                lines.append(
+                    f"- `{request_name_of(request)}` invokes `{request.get('query', '')}` through `{request.get('brokerUri', '')}`."
+                )
+            lines.append("")
+
         first_write = next(
             (request for request in gateway["requests"] if request.get("requestTypeEnumId") == "DrtWrite"),
             None,

agent-skills/skills/moqui-device-seed-designer/SKILL.md

@@ -64,6 +64,7 @@ Useful helper scripts:
 - `scripts/render_seed_from_surveys.py`
   - validates multi-FSM surveys and materializes StatusType/StatusItem/StatusFlow topology
   - assigns each FSM to its owning subsystem Device and preserves the physical device parent tree
+  - generates executable gateway-side MQTT/OPC UA requests plus their Moqui-side REST dispatch wrappers
 
 ## Validation Principle
 
@@ -75,6 +76,10 @@ The skill should verify:
 - parent/child references are resolvable
 - enumerations and purpose fields are coherent
 - request items point to existing parameters
+- each gateway sampling domain resolves to exactly one declared gateway transport
+- MQTT requests define a Camel `paho-mqtt5:` base URI and explicit topics
+- OPC UA requests reference a generated `DeviceConnection` and explicit node IDs
+- each Moqui-side dispatch wrapper targets a gateway Device and references its field-side request by `query`
 - status flows contain ordered states and valid transitions
 - every system/subsystem owns at most one directly visible FSM Device projection
 - flat FSMs remain independent; nested transitions use `toStatusFlowId` only when explicitly requested
@@ -106,6 +111,18 @@ The standard request families are normally only:
 2. recipe export request
 3. one live-parameter request for values acquired by `MqttParameterSub` in [moqui/moqui-plc](https://github.com/moqui/moqui-plc)
 
+For each gateway-executed family, keep the two model rows distinct:
+
+- the field-side request targets the PLC and contains MQTT/OPC UA transport data;
+- the Moqui-side wrapper targets the gateway, uses
+  `moqui.device.DeviceGatewayServices.run#GatewayDeviceRequest`, stores the
+  gateway REST base URL in `brokerUri`, and names the field-side request in
+  `query`.
+
+Do not put API keys, broker passwords, or OPC UA credentials in generated seed
+files. Supply credentials through deployment configuration or referenced user
+accounts.
+
 So the skill should avoid over-designing many different request families when
 the real variability belongs to the parameter model and to the request items.
 

agent-skills/skills/moqui-device-seed-designer/references/seed-survey-fields.md

@@ -71,6 +71,7 @@ For each elementary device:
   - `iecType`
   - optional `reverseLogic`
   - source classification rule
+  - explicit `gatewayQuery` (MQTT topic or OPC UA node ID) when the signal is projected through the gateway
   - notes
 
 ## Sampling domains
@@ -112,6 +113,8 @@ Optional but strongly recommended when the application also uses
 - `gatewayName`
 - optional `gatewayDeviceTypeEnumId`
 - optional `gatewayMemberPurposeEnumId`
+- `restBaseUri` used by Moqui to invoke the standalone gateway
+- positive `restTimeoutSeconds`
 - `scopedSubsystemIds`
 - optional `scopedDeviceIds`
 - optional notes
@@ -146,6 +149,25 @@ Required before declaring the seed complete:
 - default PLC4J `runServiceName`
 - connection strategy notes
 - rationale / constraints
+- one `gatewayTransports` row per runtime transport:
+  - stable `transportId`
+  - owning `gatewayDeviceId`
+  - protocol: `mqtt` or `opcua`
+  - explicitly scoped sampling-domain IDs
+  - MQTT Camel base `brokerUri`, or OPC UA connection/driver/transport fields
+  - optional ownership and topic of the single PLC-log and live-parameter MQTT channels
+
+The MQTT base URI must leave the topic portion empty so the gateway can append
+each `DeviceRequestItem.query`, for example
+`paho-mqtt5:?brokerUrl=tcp://artemis:1883&qos=1`. Credentials are deployment
+configuration, not generated seed data.
+
+`MqttParameterSub` subscribes to one configured live-parameter topic. Therefore
+all items in the generated live-parameter request use that same topic;
+`mqttKey` remains the application-level JSON mapping key recorded as
+`DeviceRequestItem.requestItemName`. The PLC-side JSON mapper must explicitly
+support the gateway payload contract; seed generation does not infer or validate
+that Structured Text mapping.
 
 This survey is where the workflow captures the non-optional fact that the
 model must project onto at least one runtime transport layer:

agent-skills/skills/moqui-device-seed-designer/scripts/README.txt

@@ -26,13 +26,14 @@ Current scripts:
   - materializes:
     - root PLC/controller `Device` + `PhysicalDevice`
     - optional survey-derived gateway `Device` + `PhysicalDevice`
-    - optional survey-derived `DeviceConnection` rows for `moqui-plc4j`
+    - optional survey-derived `DeviceConnection` rows for OPC UA gateway transports and `moqui-plc4j`
     - survey-derived elementary child `Device` + `PhysicalDevice` rows
     - subsystem and gateway `DeviceGroupMember` rows
     - signal-derived `ParameterDef` + `Parameter` rows
     - grouped physical I/O `DeviceRequest` + `DeviceRequestItem` rows for:
-      - `moqui-device-gateway` using signal names / MQTT semantics
+      - `moqui-device-gateway` using explicit MQTT topics or OPC UA node IDs
       - `moqui-plc4j` using explicit `plc4j_query` values from the surveys
+    - Moqui-side REST dispatch wrappers linked to gateway-side requests through `DeviceRequest.query`
   - runs the upstream survey validation first, so partial surveys block generation
   - keeps the output explicitly reviewable rather than pretending that all enums or grouping decisions are final