[feature] Option to change connector terminology "pin", to "way" or customise

[scottbouch]

Hi, the word "pin" implies a male contact connector.

"Pin" is used commonly for through-hole PCB parts, as these will always be male gender, but is less relevant to connectors for wiring harnesses which can be either gender, I shall elaborate:

In this example, the connectors all state "4-pin", but the two connectors on the right are female, and actually don't have round pin-shaped contacts, but sliding contacts similar to a 3.5mm headphone jack: https://scottbouch.com/tmp/UHF2.html

A de-gendered approach is to use the word "way" to describe the number of electrical paths through the connector, and then specify contact gender separately, ie;

6 way male contact, fixed connector = 6 way plug, panel mounted
6 way female contact, free connector = 6 way socket, cable mounted

In these two examples above, the terms "plug" and "socket" define the gender of the contacts within the connector, and the terms "fixed" and "free" define the mounting of the connector bodies.

• The term "Way" is commonly used to describe the number of electrical signals the connector can carry ("pin" implies the gender of a contact).
• The term "Contact" is commonly used to physically describe the presence of metallic parts used, where a gender can be applied.
• The terms "Male" and "Female" are commonly used to determine the gender of the contact, if relevant. "Male" = plug, "Female" = socket, either can be free of fixed.
• Sometimes contacts are replaced by a plastic plug too, this is where not all contacts are needed, but the IP ingress protection needs to be maintained.
• The term "Fixed" is commonly used to mean "panel mounted".
• The term "Free" is commonly used to mean "cable mounted".

Some people will be happy to stay with the term "Pin" as it is used a lot in language, I also see that the term pin is used a lot in the WireViz scrips, but it would be a real improvement to add an option to change the output displayed term to "Way" or a custom defined term perhaps.

Many thanks, Scott.

[scottbouch]

Here is an example where the term 'pin' is not relevant to the connector.

Plug Type 671
Socket Type 626

Also known as 'NATO' plugs and sockets, used for many British and French aircraft communication headsets. (for reference, the spigot is 7.5 mm in diameter, x 22 mm in length)

Note the ways are not numbered or lettered, instead are identified by colours relating to the DEF-STAN multicore cable color code, red, blue, green, yellow being the first 4, used in 4 core cables. See related feature: #337 (comment)

[kvid]

Hi Scott,

There are 4 usage areas of pin as far as I can see:

1. Text output in diagram and BOM mainly. Does it make sense to (optionally for each connector or the whole harness) replace pin with way at all places of the output?
2. Connector attributes in YAML input. Does it make sense to accept attribute aliases where pin is replaced with way? Is it OK to mix (some with pin and some with way) or should the code enforce consistency overall or within each connector?
   • pincount = waycount
   • pins = ways
   • pinlabels = waylabels
   • pincolors = waycolors
   • show_pincount = show_waycount
   • hide_disconnected_pins = hide_disconnected_ways
3. In code identifiers. I assume we can live with pin usage in the code. It doesn't affect the user directly, except when exposed in exceptions. Edit: Or do you also prefer (in the long run) replacing pin with way in the code because it's the more general term?
4. Exceptions can expose pin usage in the code. Some warnings/errors might also use pin. Should the latter always use both ("pin/way") or only "way"? It might complicate the code to require such messages use the same optional output term as in point 1, but I don't know yet. Error messages about aliased attributes in point 2 will not reflect which of the aliases has been used because a translation into the defined ones must happen early in the parsing process.

Are there maybe other alternatives than pin or way we should consider, or should the user be able to specify it literally - maybe enabling output in other languages, but then text like connector, wire, cable, etc. also need alternative output?

Have I forgotten or misunderstood some parts of this issue?

[scottbouch]

Thanks for considering this request, brilliant!

From my users point of view, even just an option to define "way" or another custom term (as other people may have other ideas too) in the yaml configuration, and have that presented in the diagram would do... but for conciseness and consistency, I suppose exchanging all user-facing terms used by the yaml (xcount, xlabels, xcolors, show_xcount, hide_disconnected_x) as you suggest, may be a good move, if everyone is happy with using "way" as the most agnostic (least specific) term. if the back-end code still uses "pin" this won't harm the user experience, and would save a lot of re-work.

Many thanks, Scott

[scottbouch]

Another terminology sometimes used is "pole" for "way", so allowing a custom value may be good.

Cheers, Scott

[scottbouch]

Hi, just checking in to see if this has been progressed in the WireViz code? I'm about to start making some new diagrams, and the term 'way' would be very useful for them.

Many thanks, Scott

[kvid]

No progress from my side about this issue, I'm afraid, but if you or someone else have ideas on how to proceed, please try them out.

My first goal is to complete PR #365, and when that is released, PR #251 is the first to be merged into dev.

[kvid]

@scottbouch - I decided to try a quick implementation of the basic feature you ask for. Please try my feature branch in PR #398 to see if it meets your expectations, and please report any unexpected issues.

Be aware that the feature branch doesn't (yet) include any of the bug-fixes I'm collecting (work-in-progress) in PR #365, so if if you need any of them, you might need to merge those two branches in your local workspace.

I selected 3 terms to optionally override, but if someone wants to replace "wire" with "core", I'm not sure if the term "core" can be used instead of "wire" in any context, e.g. for wires in a bundle? The term "single-core cable" I've seen in use, but then I would assume the shorter term "wire" is better. What is your opinion?

This is currently only a simple literal replacement of 3 terms in the diagram and BOM output. The original term is assumed in grammatical variations, like "{pin}s" and "{shield}ed", and that might create weird results with some user defined terms.

The term "+ S" for wire count of shielded cables is currently not affected. Does it make sense to always replace the "S" with a capitalized first letter of any options.terminology.shield term?

[martinrieder]

@kvid I recommend you take a look at chapter 3 of "VDA-Recommendation 4964". It contains a Glossary of terms and their German translation. I cannot link to the document directly, but it is easy to find online.

[kvid]

I found a copy of 2nd edition (KBL 2.4), November 2014 of the document @martinrieder refers to, and it confirms my understanding of these terms:

• 3.9 Cable: Multiple physical conductors (-> Cores) can be combined in a cable. Cables are available in various technologies like twisted-pair, shielded, coax, etc.
• 3.19 Core: A core is part of a cable. A cable consists of 1-n cores
• 3.45 Wire: A solid or stranded group of solid cylindrical conductors, together with any associated insulation.

The problem with supporting alternative terms for wire in WireViz, is that the same term is used for both cores in a cable and single-core cables in a bundle. I know @scottbouch didn't request the wire term, so we can drop it for now, but I expect requests for more terms when we release such a feature, so I want to be prepared. Maybe we need to differ like this:

options:
  terminology:
    pin: way
    wire:
      in cables: core
      in bundles: single-core cable
    shield: screen

or is it better to define a context level for all terms, like this:

options:
  terminology:
    in connectors:
      pin: way
    in cables:
      shield: screen
      wire: core
    in bundles:
      wire: single-core cable

Some drawbacks with the latter alternative:

• WireViz doesn't stop a user from defining a shield for a bundle.
• Terms might be used in more contexts in the future, e.g. shield might also be supported for connectors. See [feature] shield: true for connectors #285
• I dislike the need to repeat the same entry for several contexts when they're all equal.

[martinrieder]

For wires, I differentiate between the following definitions by Merriam-Webster:

• core : the conducting wire with its insulation in an electric cable (==> implies that it has a sheath)
• lead : an insulated electrical conductor connected to an electrical device (==> implied for wire bundles)

Note that the first type is uncommon in automotive applications, so you would not find it in the VDA document. (German term is Mantelleitung for the entire cable.)

Additionally, the following definitions do not imply having an insulation:

• wire (German Draht)
  • : metal in the form of a usually very flexible thread or slender rod
  • : a line of wire for conducting electric current
• conductor : a material or object that permits an electric current to flow easily (German Leiter)
• litz wire : a wire composed of individually enameled copper strands braided together to reduce skin effect and consequent high-frequency resistance (German Litze)

Refer to #31 about further impact of this implementation.