@aryacode/dsh-engineering 0.9.0 → 0.9.2

package/vendor/resources/corpus/rockwell/rockwell-hmi-handshake.md

@@ -0,0 +1,33 @@
+---
+id: rockwell-hmi-handshake
+title: The PLC–HMI handshake
+domain: rockwell
+level: practitioner
+basis: [Rockwell]
+tags: [hmi, handshake, comms]
+applies_to: [l5x, ftview]
+rules: [ROCK-HMI-01, ROCK-HMI-02, ROCK-HMI-03]
+---
+## Principle
+
+The HMI is a remote peer with a cable that can fail. Treat every command as a request with a status and a
+timeout.
+
+## Rules
+
+- **ROCK-HMI-01** Commands are pulse or edge requests with a matching acknowledgement bit; the HMI clears
+  the request when it sees the acknowledgement, not on a timer.
+- **ROCK-HMI-02** Detect comms loss: a heartbeat the HMI toggles must be watched by the PLC, and its loss
+  must put outputs in a defined state.
+- **ROCK-HMI-03** Data the PLC owns stays in the PLC. The HMI displays copies; it does not write setpoints
+  that the PLC never validates.
+
+## Apply
+
+Write the handshake as a small state pair (`Cmd` / `Sts`) and test it by unplugging the network, not by
+clicking twice.
+
+## Anti-patterns
+
+A command bit left on across HMI screens; setpoints accepted with no range check; heartbeat watched by the
+HMI but not the PLC.

package/vendor/resources/corpus/rockwell/rockwell-program-structure.md

@@ -0,0 +1,32 @@
+---
+id: rockwell-program-structure
+title: Logix program structure that scales
+domain: rockwell
+level: practitioner
+basis: [Rockwell]
+tags: [program, routine, aoi]
+applies_to: [l5x]
+rules: [ROCK-STRUCT-01, ROCK-STRUCT-02, ROCK-STRUCT-03]
+---
+## Principle
+
+The controller organiser is a map of the machine. A reader should find the logic for a device by following
+names, not by opening every routine.
+
+## Rules
+
+- **ROCK-STRUCT-01** One program per machine area, one main routine that reads as a table of contents, and
+  one routine per device or function. The main routine calls; it does not implement.
+- **ROCK-STRUCT-02** Keep the main routine thin enough to read in one screen: JSRs or AOI calls with a
+  comment per call.
+- **ROCK-STRUCT-03** Put reusable device logic in an AOI with a UDT for its state; one-off logic stays in
+  the routine that owns it.
+
+## Apply
+
+For inherited projects, map program → routines → devices before editing. Name new routines after the
+function they perform (`Conveyor_Control`), not after the week they were added.
+
+## Anti-patterns
+
+A 900-rung main routine; JSR chains nobody can follow; the same motor logic pasted four times.

package/vendor/resources/corpus/rockwell/rockwell-safety-boundaries.md

@@ -0,0 +1,31 @@
+---
+id: rockwell-safety-boundaries
+title: Where safety does not belong
+domain: rockwell
+level: specialist
+basis: [Rockwell]
+tags: [safety, boundaries]
+applies_to: [l5x]
+rules: [ROCK-SAFE-01, ROCK-SAFE-02]
+---
+## Principle
+
+A standard task cannot be trusted to remove power from a hazard. Safety functions belong in a certified
+safety controller or hardwired circuit, not in the logic this bundle edits.
+
+## Rules
+
+- **ROCK-SAFE-01** Never move an E-stop, guard interlock or light curtain function into standard logic, and
+  never bypass one to make a sequence run.
+- **ROCK-SAFE-02** Treat safety tags as read-only evidence: they may be read for indication, never forced
+  or overwritten.
+
+## Apply
+
+When a request asks for a change that would weaken a safety function, stop, explain the boundary and ask
+for a safety review. The bundle's tools refuse protected targets; do not work around them.
+
+## Anti-patterns
+
+Using a standard output as a safety output; disabling a guard to test a cam; "temporarily" forcing an
+interlock.

package/vendor/resources/corpus/rockwell/rockwell-tag-naming.md

@@ -0,0 +1,33 @@
+---
+id: rockwell-tag-naming
+title: Tag names that carry meaning
+domain: rockwell
+level: practitioner
+basis: [Rockwell]
+tags: [naming, tags]
+applies_to: [l5x, ftview]
+rules: [ROCK-NAME-01, ROCK-NAME-02, ROCK-NAME-03]
+---
+## Principle
+
+A tag name is the only documentation that survives every export. Make it say direction, owner and
+meaning.
+
+## Rules
+
+- **ROCK-NAME-01** Prefix by direction and role: `In_` field input, `Out_` field output, `Cmd_` command to
+  equipment, `Sts_` status back, `Hmi_` operator interface, `Cfg_` configuration.
+- **ROCK-NAME-02** One spelling per concept across PLC and HMI. If the HMI says `AutoMode`, the PLC does not
+  say `Auto_Mode_Cmd`.
+- **ROCK-NAME-03** No abbreviations that are not in the plant's vocabulary; spell `Conveyor`, not `Cnvyr`.
+  Units belong in the name or the description, not both inconsistently.
+
+## Apply
+
+When a project has an established prefix scheme, follow it even if a better one exists: consistency beats
+elegance in maintenance.
+
+## Anti-patterns
+
+`Tag1`, `Spare`, `Test`; names that change with the project version; HMI tags shadowing PLC tags with
+different meaning.

package/vendor/resources/corpus/view/view-alarm-presentation.md

@@ -0,0 +1,32 @@
+---
+id: view-alarm-presentation
+title: Alarm presentation the operator can use
+domain: view
+level: practitioner
+basis: [ISA-18.2]
+tags: [alarms, banner, priority]
+applies_to: [ftview, optix]
+rules: [VIEW-ALM-01, VIEW-ALM-02, VIEW-ALM-03]
+---
+## Principle
+
+An alarm is an abnormal condition requiring a timely response. Everything else is a message or a log
+entry and must not compete for attention.
+
+## Rules
+
+- **VIEW-ALM-01** Each alarm has a cause, a consequence and an action in its text. "Fault" is not an alarm
+  message.
+- **VIEW-ALM-02** Present by priority, newest first, with a persistent banner for unacknowledged alarms.
+  Do not let the list scroll the operator past a trip.
+- **VIEW-ALM-03** Acknowledge does not clear. The condition clears; the acknowledgement is recorded with
+  who and when.
+
+## Apply
+
+Review the alarm list with the operator: for each entry, can they say what to do? If not, rewrite or
+delete it.
+
+## Anti-patterns
+
+Alarm flood from one root cause; alarms that re-announce every scan; a silent alarm with no banner.

package/vendor/resources/corpus/view/view-colour-and-contrast.md

@@ -0,0 +1,31 @@
+---
+id: view-colour-and-contrast
+title: Colour, contrast and meaning
+domain: view
+level: practitioner
+basis: [ISA-101]
+tags: [colour, contrast, accessibility]
+applies_to: [ftview, optix]
+rules: [VIEW-COLOR-01, VIEW-COLOR-02, VIEW-COLOR-03]
+---
+## Principle
+
+Colour is a signal, and about one in twelve men cannot separate red from green. Meaning must survive a
+greyscale screenshot.
+
+## Rules
+
+- **VIEW-COLOR-01** Reserve red, amber and green for abnormal, warning and normal, and use them nowhere
+  else. If a brand colour is red, do not put it on a status object.
+- **VIEW-COLOR-02** Never encode meaning in colour alone: pair it with text, an icon or a shape.
+- **VIEW-COLOR-03** Keep text contrast high (dark text on light surfaces) and size readable at the panel's
+  viewing distance; the export's palette is the reference.
+
+## Apply
+
+Read the project's palette from the profile and reuse it. A new screen with a different grey is a
+maintenance defect even if it is prettier.
+
+## Anti-patterns
+
+Rainbow trend pens; green buttons that are not "go"; white text on yellow.

package/vendor/resources/corpus/view/view-faceplates.md

@@ -0,0 +1,32 @@
+---
+id: view-faceplates
+title: Faceplates and reusable screen objects
+domain: view
+level: specialist
+basis: [ISA-101, Rockwell]
+tags: [faceplate, reuse, objects]
+applies_to: [ftview, optix]
+rules: [VIEW-FACE-01, VIEW-FACE-02, VIEW-FACE-03]
+---
+## Principle
+
+A faceplate is a contract between the screen and the equipment: same layout, same readings, same
+controls, whatever the device.
+
+## Rules
+
+- **VIEW-FACE-01** One faceplate per equipment class (motor, valve, drive, loop), parameterised by tag.
+  Do not copy a faceplate and edit it for one device.
+- **VIEW-FACE-02** Show the same state indications in the same place on every faceplate: running, faulted,
+  interlocked, mode.
+- **VIEW-FACE-03** Keep operator controls on the faceplate only when the decision belongs there; manual
+  jogging often does not.
+
+## Apply
+
+Inventory the faceplates before adding a screen; extending the class is cheaper than a new one-off.
+
+## Anti-patterns
+
+Faceplates that differ only in colour; device-specific logic inside a generic faceplate; two faceplates
+for the same class.

package/vendor/resources/corpus/view/view-hpm-01.md

@@ -0,0 +1,33 @@
+---
+id: view-hpm-01
+title: High-performance HMI: what changes on a plant floor
+domain: view
+level: practitioner
+basis: [ISA-101]
+tags: [hmi, hierarchy, overview]
+applies_to: [ftview, optix]
+rules: [VIEW-HPM-01, VIEW-HPM-02, VIEW-HPM-03]
+---
+## Principle
+
+The operator's job is to detect an abnormal situation and act. A screen that shows every value equally
+makes that job harder, not easier.
+
+## Rules
+
+- **VIEW-HPM-01** Lead with an overview: the process in its normal state, then detail on demand. A screen
+  that needs a tour to understand is a wall of data.
+- **VIEW-HPM-02** Grey is the normal state. Use colour for deviation, never for decoration; a screen of
+  green boxes hides the one that turned red.
+- **VIEW-HPM-03** One screen, one purpose. If a screen serves two tasks, split it or make the second a
+  popup.
+
+## Apply
+
+For each screen ask: what decision does the operator make here, and what do they need to see to make it?
+Remove everything that does not serve that decision.
+
+## Anti-patterns
+
+3D bevels and gradients on process values; every tag on one screen; colour used to distinguish units
+instead of state.

package/vendor/resources/corpus/view/view-navigation.md

@@ -0,0 +1,31 @@
+---
+id: view-navigation
+title: Navigation that never traps the operator
+domain: view
+level: intro
+basis: [ISA-101]
+tags: [navigation, screens]
+applies_to: [ftview, optix]
+rules: [VIEW-NAV-01, VIEW-NAV-02, VIEW-NAV-03]
+---
+## Principle
+
+The operator must always know where they are and how to get back to the overview, including under stress.
+
+## Rules
+
+- **VIEW-NAV-01** Keep a persistent navigation area on every screen (header or footer), with the same
+  position and the same buttons.
+- **VIEW-NAV-02** Always provide a way back to the overview that does not depend on a popup being closed
+  first.
+- **VIEW-NAV-03** Name screens after the area they show, and number them consistently; the screen list is
+  part of the interface.
+
+## Apply
+
+Walk the navigation as the operator would during an alarm: from the overview to the faulted area and back
+in two clicks.
+
+## Anti-patterns
+
+Hidden hotspots; a popup that disables the nav bar; the only way home being a hardware function key.

package/vendor/resources/corpus/view/view-popup-patterns.md

@@ -0,0 +1,31 @@
+---
+id: view-popup-patterns
+title: Popups and dialogs
+domain: view
+level: practitioner
+basis: [ISA-101]
+tags: [popup, dialog, modal]
+applies_to: [ftview, optix]
+rules: [VIEW-POP-01, VIEW-POP-02, VIEW-POP-03]
+---
+## Principle
+
+A popup interrupts. Use it for a decision or a focused entry, not for information that could live on the
+screen.
+
+## Rules
+
+- **VIEW-POP-01** Decide modal or modeless deliberately: modal when the answer changes what happens next,
+  modeless when the operator may keep watching the process.
+- **VIEW-POP-02** Keep the action buttons in the same place and order as every other popup, and make cancel
+  the safe default.
+- **VIEW-POP-03** A popup has a title that names the decision, and a size that does not cover the values it
+  is asking about.
+
+## Apply
+
+Reuse the project's popup faceplate rather than building a one-off; the profile records the convention.
+
+## Anti-patterns
+
+Confirmation dialogs for reversible actions; popups that stack three deep; a popup with no visible close.

package/vendor/resources/corpus/view/view-screen-hierarchy.md

@@ -0,0 +1,31 @@
+---
+id: view-screen-hierarchy
+title: Screen hierarchy and count
+domain: view
+level: practitioner
+basis: [ISA-101]
+tags: [hierarchy, screens, structure]
+applies_to: [ftview, optix]
+rules: [VIEW-HIER-01, VIEW-HIER-02, VIEW-HIER-03]
+---
+## Principle
+
+Screens form a tree: overview, area, detail. The depth is a design decision, and every level must earn its
+place.
+
+## Rules
+
+- **VIEW-HIER-01** Three levels are usually enough: overview, area, equipment. A fourth level is a sign
+  the area screen is doing too much.
+- **VIEW-HIER-02** Number displays by level and area so the list reflects the tree, and never renumber a
+  published display.
+- **VIEW-HIER-03** Every screen reachable from the overview, and every screen has a way back; no orphan
+  screens.
+
+## Apply
+
+Draw the tree before adding screens; if a proposed screen has no parent, the hierarchy is wrong.
+
+## Anti-patterns
+
+A single screen with tabs; screens reachable only by a specific alarm; duplicate screens for shifts.

package/vendor/resources/corpus/yaskawa/yaskawa-cam-and-gear.md

@@ -0,0 +1,31 @@
+---
+id: yaskawa-cam-and-gear
+title: Cams, gears and registration
+domain: yaskawa
+level: specialist
+basis: [Yaskawa]
+tags: [cam, gear, registration]
+applies_to: [mwi]
+rules: [YAS-CAM-01, YAS-CAM-02]
+---
+## Principle
+
+A cam is a table and a phase. Changing the table changes the motion; changing the phase changes when it
+happens. Keep them separate and identifiable.
+
+## Rules
+
+- **YAS-CAM-01** Name and version each cam profile, and record which profile the machine is running. A
+  profile loaded from a recipe must be validated before it is engaged.
+- **YAS-CAM-02** Registration corrections are offsets applied to the phase, bounded and filtered; they do
+  not rewrite the cam table at runtime.
+
+## Apply
+
+Log profile id and offset at each engagement. When diagnosing a cut-quality complaint, read the active
+profile before reading the code.
+
+## Anti-patterns
+
+Editing the table to trim a registration error; two profiles with the same name; offsets that accumulate
+without a limit.

package/vendor/resources/corpus/yaskawa/yaskawa-error-handling.md

@@ -0,0 +1,31 @@
+---
+id: yaskawa-error-handling
+title: Errors, acknowledgements and retries
+domain: yaskawa
+level: practitioner
+basis: [Yaskawa]
+tags: [error, reset, retry]
+applies_to: [mwi]
+rules: [YAS-ERR-01, YAS-ERR-02, YAS-ERR-03]
+---
+## Principle
+
+An error has a cause, a reaction and a recovery. Without all three it is just a red light.
+
+## Rules
+
+- **YAS-ERR-01** Record the first error with its source and timestamp; later errors are consequences.
+- **YAS-ERR-02** Reset only what failed, and only when the cause is gone. A global reset that clears
+  everything hides the second fault.
+- **YAS-ERR-03** Retry only idempotent operations, with a bounded count and a delay. Motion commands are
+  not idempotent.
+
+## Apply
+
+Keep one error table: code, text, severity, reaction, reset condition. The HMI and the code read the same
+table.
+
+## Anti-patterns
+
+Resetting on a timer; retrying a move without checking `ErrorID`; error text that says "axis fault" with no
+axis number.

package/vendor/resources/corpus/yaskawa/yaskawa-motion-function-blocks.md

@@ -0,0 +1,32 @@
+---
+id: yaskawa-motion-function-blocks
+title: Motion function blocks: execute, done, error
+domain: yaskawa
+level: specialist
+basis: [Yaskawa]
+tags: [motion, fb, execute]
+applies_to: [mwi]
+rules: [YAS-MOT-01, YAS-MOT-02, YAS-MOT-03]
+---
+## Principle
+
+Motion FBs are asynchronous. `Execute` starts a job; `Done`, `Busy`, `Error` and `ErrorID` report it. The
+scan that sets `Execute` is not the scan that finishes.
+
+## Rules
+
+- **YAS-MOT-01** Drive one FB per axis command and keep `Execute` true until `Done` or `Error`; a one-scan
+  pulse is a race.
+- **YAS-MOT-02** Handle `Error` before issuing the next command, and map `ErrorID` to the operator message
+  in one place.
+- **YAS-MOT-03** Re-arm with a fresh edge after a fault reset. Do not leave `Execute` latched across a
+  reset.
+
+## Apply
+
+Model each axis as `Idle → Commanded → Busy → Done/Faulted` and let the FB signals drive the transitions.
+
+## Anti-patterns
+
+Ignoring `Busy` and sending a second move; clearing `Error` by writing `Execute` false; one FB shared by two
+axes.

package/vendor/resources/corpus/yaskawa/yaskawa-pou-organisation.md

@@ -0,0 +1,29 @@
+---
+id: yaskawa-pou-organisation
+title: Organising a MotionWorks IEC project
+domain: yaskawa
+level: practitioner
+basis: [Yaskawa]
+tags: [pou, organisation, program]
+applies_to: [mwi]
+rules: [YAS-POU-01, YAS-POU-02]
+---
+## Principle
+
+MotionWorks projects mix programs, function blocks and functions. The project tree should say what runs,
+what is reused, and what is a library.
+
+## Rules
+
+- **YAS-POU-01** One program per machine function, one function block per reusable device, and functions
+  for pure calculations. Do not put device logic in a function (no state).
+- **YAS-POU-02** Keep the library blocks (motion, cam, communication) separate from application blocks, and
+  never edit a library block in place; wrap it.
+
+## Apply
+
+Read the task assignment before the code: which program runs in which task explains most timing bugs.
+
+## Anti-patterns
+
+All logic in one program; application code inside a vendor library block; a function with `VAR` state.

package/vendor/resources/corpus/yaskawa/yaskawa-task-rates.md

@@ -0,0 +1,30 @@
+---
+id: yaskawa-task-rates
+title: Task rates and motion determinism
+domain: yaskawa
+level: specialist
+basis: [Yaskawa]
+tags: [task, rate, jitter]
+applies_to: [mwi]
+rules: [YAS-TASK-01, YAS-TASK-02]
+---
+## Principle
+
+Motion quality is a function of task jitter. A logic task that occasionally overruns is a motion problem
+even when the motion code is correct.
+
+## Rules
+
+- **YAS-TASK-01** Keep HMI, file and diagnostic work out of the motion task; communicate through a
+  double-buffered structure.
+- **YAS-TASK-02** Measure the worst-case scan of each task under load, and set the watchdog from that
+  measurement.
+
+## Apply
+
+When a cam shows a periodic defect, compare the defect period with the task period before touching the
+profile.
+
+## Anti-patterns
+
+A 1 ms motion task running string formatting; changing the task rate to "fix" jitter without measuring.