diff --git a/aligning_items.md b/aligning_items.md index 3fd8d95..990b958 100644 --- a/aligning_items.md +++ b/aligning_items.md @@ -59,12 +59,6 @@ what happened: ### Which items move, and to which grid -> **Status: pending.** The shape changes in this section describe -> [PR #1152](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1152), -> not yet merged. Until it lands, shapes are left out: a selection of -> shapes only greys the commands out, and a shape outside a group is not -> moved. This notice will come out once it merges. - | Item | Snaps to | |---|---| | Symbols | the folio grid, by the symbol's origin point: exactly where dragging it would have dropped it | @@ -97,13 +91,6 @@ Items already on the grid stay exactly where they are. ## Align -> **Status: pending.** The shape changes in this section, and "a single -> group counts as one item", describe -> [PR #1152](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1152), -> not yet merged. Until it lands, shapes are left out: a selection of -> shapes only greys the commands out, and a shape outside a group is not -> moved. This notice will come out once it merges. - ### Using it 1. Select **two or more** items: symbols, pictures, free texts, shapes or groups. diff --git a/api_reference.md b/api_reference.md index bd5db16..488e73b 100644 --- a/api_reference.md +++ b/api_reference.md @@ -213,6 +213,21 @@ It reports each file as OK, WARN (loads but suspicious — for instance zero terminals) or FAIL (unparseable, wrong root tag, missing bounding box), and exits non-zero on any failure. Put it in CI if you generate `.elmt` files. +> **Status: pending.** The terminal-name checks in this paragraph describe +> [PR #1159](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1159), +> not yet merged. This notice will come out once it merges. + +It also checks terminal names, with the same rule the element editor applies +on save (see **[Using the element editor](element_editor)** §5): two terminals +of one element sharing a name is a **FAIL**, and terminals without a name are +a **WARN** (folio reports, conductor definitions and thumbnails excepted). +The element editor's setting to turn the check off does not apply here. + +```text +FAIL my_elements/shelly_pro_2pm.elmt (repeated terminal names: N ×3) +WARN my_elements/90-10-0111.elmt (2 of 2 terminals have no name) +``` + ### Rules of thumb - **Close the project in QET before rewriting its file.** QET holds its own diff --git a/element_editor.md b/element_editor.md index a52cbcb..87d185d 100644 --- a/element_editor.md +++ b/element_editor.md @@ -62,6 +62,9 @@ Terminal *type* and *function* (generic, fuse, diode, ground…) are set afterward in the terminal's own properties, not while placing it — see **[Linking elements](element_linking)** §4. +Give every terminal a **name** in its properties too, and never the same name +twice in one symbol — see §5, *Terminal names*. + --- ## 3. Width, height and hotspot are computed, not typed @@ -118,6 +121,58 @@ An element with zero terminals still saves — you'll just get a dialog telling you it can't be wired to anything, which is sometimes exactly what you want (a thumbnail, a text block, a title-block decoration). +### Terminal names + +> **Status: pending.** Everything in this subsection describes +> [PR #1159](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1159), +> not yet merged. Nothing here works until that lands — check the PR before +> trying any of this against your own build. This notice will come out once +> it merges. + +Every terminal of a symbol should have a name, and no two terminals of the +same symbol may share one. The wiring list (what connects to what) names each +end of a wire as *symbol label : terminal name*, so two terminals both called +`N` on `-K1` give two different wires the same address, `-K1:N`, and nobody +wiring the panel can tell them apart. IEC 61666 §4.1 states the rule: *"Each +terminal shall be unambiguously identified with respect to the object +itself."* + +| Condition | Severity | +|---|---| +| Two or more terminals share a name | **error** — the save is blocked, and the terminals involved are selected so you can find them | +| One or more terminals have no name | **warning** — the save goes ahead. Folio reports, conductor definitions and thumbnails are not checked | + +![The error dialog when saving a Shelly Pro 2PM with three terminals named N: "Plusieurs bornes portent le même nom : N ×3", with the fix "Donner un nom unique à chaque borne, par exemple N.1 et N.2"](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/element-editor-duplicate-terminal-names.png) + +How names are compared: + +- Spaces at the start and end are ignored: `PE` and ` PE ` are the same name. +- Case counts: `n` and `N` are different names. +- Unnamed terminals are counted as unnamed, never as duplicates of each other. + +**Real devices sometimes print the same marking twice.** Some Shelly relays +have two terminals marked N or two marked L, bridged inside the device. The marking on the device is still not enough +for the drawing: IEC 61666 §4.2 says that when the manufacturer's marking is +insufficient to tell terminals apart, you assign your own designations and +explain them. Give each one a distinct name that keeps the printed marking, +for example `N.1` and `N.2`. + +![The warning dialog for a feed-through terminal whose two terminals have no name: "2 borne(s) sans nom"](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/element-editor-unnamed-terminals.png) + +#### Turning the check off + +*Configuration → Configurer QElectroTech → Général → Editor →* +**Vérifier les noms des bornes à l'enregistrement** (*Check terminal names +when saving*). It is on by default. Unticked, neither the error nor the +warning appears and every symbol saves as before. + +![The Editor tab of the configuration dialog, with the "Vérifier les noms des bornes à l'enregistrement" checkbox ticked](https://raw.githubusercontent.com/wiki/qelectrotech/qelectrotech-source-mirror/images/settings-check-terminal-names.png) + +The setting belongs to your QElectroTech installation, not to the symbol or +the project. The command-line check (`--check-elements`, see +**[Automating QElectroTech](api_reference)**) ignores it and always checks +names. + --- ## 6. The panels around the canvas diff --git a/images/element-editor-duplicate-terminal-names.png b/images/element-editor-duplicate-terminal-names.png new file mode 100644 index 0000000..cf9bc82 Binary files /dev/null and b/images/element-editor-duplicate-terminal-names.png differ diff --git a/images/element-editor-unnamed-terminals.png b/images/element-editor-unnamed-terminals.png new file mode 100644 index 0000000..d3af81e Binary files /dev/null and b/images/element-editor-unnamed-terminals.png differ diff --git a/images/settings-check-terminal-names.png b/images/settings-check-terminal-names.png new file mode 100644 index 0000000..9eca9ca Binary files /dev/null and b/images/settings-check-terminal-names.png differ