Equipment Commands (Command Registry)
PlantPulse adds a layer above the simple act of writing a value to a tag (control writes): "what can this equipment do?" This is the command registry.
Instead of writing to TAG_CNC01_SPEED_SP with 1200, an operator selects "Set Speed (SET_SPEED)" and
simply enters the speed. Which tags to write to, in what order, and what must be true for the
command to be allowed — these are defined in advance by administrators.
Pressing [Execute] here actually writes values to the PLC. Always test on a simulator connection or on stopped equipment. There is no automatic rollback — even if the sequence fails midway, values already written are not reverted (this is by design, to preserve the audit trail).
Where to find it
Select the EQUIPMENT node in the Asset screen (/asset/tree/index) to open the tabs at the bottom.
| Tab | Purpose |
|---|---|
| Commands | Select and execute a defined command · recent command history |
| Registry | Define commands (register, edit, delete) · asset statements |
Definitions are in the Command Registry panel within the Registry tab. The tab is called "Registry", not "Commands", so it's easy to look in the wrong tab first.
Who can view · Who can execute
Access is controlled at three levels.
| Level | Where | Gate |
|---|---|---|
| ① URL Filter | /asset/*/command* in security-rule.xml | The URL itself is blocked for everyone except ADMIN · MANAGER |
| ② Screen · Controller | Command Execution Panel in the Commands tab | Visible only to ADMIN / MANAGER. Other roles only see the history below. The server returns 401 for unauthenticated, and 403 for non-ADMIN/MANAGER |
| ③ Per-command | Allowed roles in the definition | Each command specifies "who can execute it". If not allowed, REJECTED_FORBIDDEN |
You can pass ② but still be blocked at ③ — meaning it can be narrowed down per command.
Though access control is described as "ADMIN or MANAGER", MANAGER is a role that cannot be assigned
in the user registration screen (the only options are ADMIN · API · USER). If you force it via
API, that account cannot log in —
see User Management.
So the only person who can actually use this screen is effectively ADMIN. The "Allowed Roles"
in the definition are only effective for ADMIN and API.
Define a command — the Registry tab
Press [Register Command] to open the definition dialog. As the screen prompt says, "Define the semantic commands for this asset. Configure parameters, preconditions, and a sequence of tag write steps."
Basic Information
| Field | Required | Description |
|---|---|---|
| Command Type | ✅ | Semantic identifier — values like START · STOP · SET_SPEED |
| Command Name | ✅ | Name shown in the execution select box |
| Allowed Roles | ADMIN · MANAGER · API checkboxes. "The roles that can execute this command" | |
| Order | List sort order (smaller comes first) | |
| Active | If off, the command won't appear in the execution select box. The definition remains |
The permission gate is fail-closed — if the requester's role is not in the 허용 역할 list, it is rejected.
If the list is empty (so no roles are in it), even ADMIN will get an REJECTED_FORBIDDEN.
Parameters
Define the values an operator will enter during execution in a table. Each row has Name · Type · Min · Max · Options · Required.
| Type | Validation |
|---|---|
| Number | Parsed as a number and must be a finite value (NaN · Infinity are rejected regardless of range). If 최소/최대 are set, must be within that range (inclusive) |
| Boolean | true / false (case-insensitive) |
| Enum | One of the values listed in 옵션 |
| String | No validation |
- If a required field is empty, it's rejected (
REJECTED_PARAM). - For optional parameters, leaving it empty skips type validation; if a value is provided, it's validated.
- A command with no parameters at all is also possible.
Command Flow — Step Sequence
The Command Flow area in the definition dialog is a visual editor. Drag nodes from the left palette (— "Click = append at end · Drag = insert in between" —) and fill in their values in the inspector on the right.
[시작] → [쓰기] → [지연] → [읽기 확인] → [종료]
| Node | Inspector Fields | Purpose |
|---|---|---|
Write (write) | Tag · Value Expression · Precondition (Interlock) | Writes a value to that tag |
Readback (read_back) | Tag · Operator · Expected Value · Stabilization Time · Polling Interval · Tolerance | Reads back to confirm the written value actually took effect |
Delay (delay) | Delay (ms) | Waits before the next step |
Value Expression can be a literal or a parameter reference — as the screen help states,
"Literal value or expression. {param} are replaced with command parameters of the same name."
It can be {speed} · 1 · SET {speed} RPM.
The blank fields in Readback use defaults: stabilization 2000 ms · polling 200 ms · tolerance 0.0. Since PLC values take time to settle, this settling window absorbs discrepancies from reading back immediately after a write.
In a Write node's tag list, only tags belonging to that equipment where rw is W or RW and
tag_type is SETPOINT or COMMAND appear. Readback and precondition tag lists have no restrictions (since they're reads).
If the tag you want to change isn't in the list, first fix the read/write and tag type in the Tag Properties tab.
Preconditions and Interlocks
Each condition is a set of three fields: Tag · Operator · Value, plus an Interlock checkbox.
The operators are eq · ne · gt · gte · lt · lte.
| Not Interlock | Interlock | |
|---|---|---|
| Before execution starts | Checked ✅ | Checked ✅ |
| Before each write step | Not checked | Re-checked ✅ |
If your sequence has a delay or a readback, time passes between the start and the actual writes. If a safety gate opens during that time? Only Interlock conditions are re-checked right before each write; if they fail, the write is not issued and the sequence is halted.
Conditions like "Door Closed = TRUE" or "E-Stop = FALSE" must be set as Interlocks.
Malformed condition definitions are not allowed through. If a tag or operator is missing or can't be parsed,
it's not silently skipped — it's blocked with REJECTED_PRECONDITION. This is a fail-closed design to ensure the safety gate
cannot be bypassed.
Execute a command — the Commands tab
- Select the command in the Command tab's select box — only active definitions appear, in order. (If you see "No active commands", activate one in the registry.)
- [Execute] — if parameters are defined, the parameter input dialog appears first (controls are auto-generated by type — Number shows min/max, Enum shows a select, Boolean shows true/false).
- Confirmation Dialog — "Execute command '○○' on asset '○○'?" along with a parameter summary. This is to prevent accidental execution, so be sure to read the target asset name here.
- Results are shown in the panel — for each step: tag · operation · requested value · actual value · success · error.
Execution Order (Fixed)
정의 로드 → 에셋 확인 → 자산락 → 권한 → 파라미터 → 태그 스코프 → 사전조건
↓
종결 판정 ← 스텝 시퀀스(쓰기 직전 인터록 재검증) ←
The asset lock ensures commands on the same equipment execute strictly sequentially. Commands on different equipment can run concurrently.
Result Statuses and Actions
| Status | Meaning | Where to look |
|---|---|---|
SUCCESS | All steps succeeded | — |
FAILED | A step failed and the sequence stopped there | The "Error" column in the results table. Prior writes have already been applied |
REJECTED_NOT_FOUND | Definition missing · belongs to different equipment · inactive | Check active status in the registry |
REJECTED_FORBIDDEN | My role is not in the command's allowed roles | The definition's allowed roles |
REJECTED_PARAM | Parameters don't match the spec | Missing required · out of range · invalid Enum value |
REJECTED_TAG_SCOPE | A referenced tag is no longer part of that equipment or isn't writable | If tags were re-wired or rw was changed after the definition was created |
REJECTED_PRECONDITION | Precondition not met — or the precondition definition itself is malformed | Current value of the condition tag |
REJECTED_BUSY | Another command is running on the same equipment (HTTP 409) | Try again after a moment |
FAILED is not "nothing happened"REJECTED_* blocks before any write begins, so the equipment state hasn't changed.
FAILED, on the other hand, halts after the sequence has started, so writes before the failed step
have already been applied. Check how far it got in the results table and manually revert if necessary.
Only REJECTED_BUSY and REJECTED_NOT_FOUND are not published to the history (pre-transmission race / routing errors).
Sequence Limits
| Item | Limit |
|---|---|
| Total sequence | 30,000 ms — if exceeded, the step is not executed and FAILED (op deadline) is issued |
| Readback | Stabilization time (default 2,000 ms) |
| Write | Edge HTTP timeout |
Readback polls multiple times, but writes are sent only once. Deliberately disabled to prevent partial application — if it fails, a human should decide and re-execute.
Where does the history go?
Completed executions are published as the standard asset_command and stored in the history table (tm_asset_command),
UNS, timeline, and cache. Failures and rejections also go to the diagnostic log
(Diagnostics).
The "Recent Command List" at the bottom of the Commands tab also shows commands published by statements — timestamp · statement name · key · value (JSON).
FAQ
Q. The command execution panel is not visible.
A. Your role is not ADMIN(or the unassignable MANAGER). Roles USER·API only see the history below.
Q. The select box shows "No active commands". A. There are no definitions, or all are inactive. Activate one in the Registry tab.
Q. The tag list in the Write step is empty.
A. There are no tags on that equipment where rw is W/RW and tag_type is SETPOINT/COMMAND.
Fix it in the Tag Properties tab.
Q. I keep getting REJECTED_BUSY.
A. Another command on the same equipment hasn't finished yet. Check the recent command list to see if a
command with a long delay or readback is running.
Q. I ran it, but the value doesn't seem to have changed. A. Look at the actual value column in the results table. If there's a readback step, that column holds the actually read-back value. If there's no readback step, you only know whether the write was sent, not whether it took effect — add a readback step to important commands.
Related Screens
- Factory Management —
rw·tag_typesettings for tags - Equipment — Equipment list and data queries
- Diagnostics — Diagnostic logs for failures and rejections
- Security Policy — Roles and permissions