[feature] Connector-Connector & Connector-Ferrule mating

[stmaxted]

It would be nice to be able to specify a wire requires a ferrule before being put into a connector. I'm think of the case where someone wants to do something like:

[kvid]

Maybe PR #115 could be a solution for this request? A solution for #53 might also be useful here?

[formatc1702]

My initial reaction is to specify the ferrules as additional BOM items (as per #115) like @kvid suggests.

otherwise, you would need to define a connection between two connectors directly, with no wire inbetween, which (at least currently) is not possible by design.
I'm not saying it's impossible, though... the connection from ferrule to the actual connector could be graphically represented as a thin, dashed line, for example, or even an arrow, to make it clear that it's not a physical wire linking the two.

🤔

Mockup (Source)

[stmaxted]

Adding additional lines to the BOM would work nicely.
However the mockup looks very similar to what I was thinking of.

[kvid]

otherwise, you would need to define a connection between two connectors directly, with no wire inbetween, which (at least currently) is not possible by design.
I'm not saying it's impossible, though... the connection from ferrule to the actual connector could be graphically represented as a thin, dashed line, for example, or even an arrow, to make it clear that it's not a physical wire linking the two.

One way this could be specified, is to use <-, --, or -> instead of a cable/wire between two connectors in a connections entry to indicate a direct connection without wires between, and the arrow direction can be used to indicate male to female connection like in the mockup above with a possible input YAML like this:

connectors:
  X1:
    pincount: 4
    type: Screw terminal connector
    color: GN
  F1:
    style: simple
    autogenerate: true
    type: Ferrule
    color: GY

cables:
  W1:
    gauge: 0.25 mm2
    length: 1
    color: BK
    colors: [BK, WH, BU, BN]

connections:
  -
    - X1: [1-4]
    - <-
    - F1
    - W1: [1-4]

Such an implementation would also fix #148 to enable a harness that is split with mating connectors, and would help implementing #142 as well.

[formatc1702]

I was thinking of having a separate section in the YAML file.
connections could remain unchanged, for strict connector-cable-connector-[...] sequences.
A new section, mates or similar, could define mechanical matings such as the one suggested above, as well as #142 and #148. It could define pinwise mates (such as the four ferrules above going into different pins on the connector), or simple connector to connector mates, where all pins are linked 1-to-1, without having one explicit arrow for each (this would look insane on high-pincount connectors)...

[formatc1702]

Renamed issue title to consolidate with #148.

[MSBGit]

This is a common situation that I run into, where I want to specify that one connector must plug into another connector. I haven't been able to figure out a good way to do this other than using a naming convention for both connectors. Ideally wireviz would allow me to specify this type of connection and somehow render it so it's obvious to the person looking at the wiring diagram:

[formatc1702]

One way [a mate between two connectors] could be specified, is to use <-, --, or -> instead of a cable/wire between two connectors in a connections entry to indicate a direct connection without wires between, and the arrow direction can be used to indicate male to female connection like in the mockup above [...]

It could define pinwise mates (such as the four ferrules above going into different pins on the connector), or simple connector to connector mates, where all pins are linked 1-to-1, without having one explicit arrow for each (this would look insane on high-pincount connectors)...

One idea building upon @kvid's suggested syntax would be:

• use <-, --, ->, <-> to display a single dashed line/arrow between two components (e.g. when mating male and female connectors of one series)

  connections:
    -
      - X1
      - <-
      - X2

  The issue will be that currently, listing a designator without appending a pin list (- X1) is the syntax used for auto-generation of connectors, so we would need a way to differentiate the two use-cases, or come up with a new syntax for this case. The first idea that comes to mind is using an empty pinlist:

  connections:
    -  # mating two connectors
      - X1: []  # empty pinlist: join the connectors themselves, not individual pins!
      - <-
      - X2: []
    -  # defining the connection of X2's pins to other wires etc. in a separate connection set
      - X2: [1-4]
      - W99: [1-4]
      # etc. 

• use <=, ==, =>, <=> to display one dashed line/arrow for each pin in the connection set (e.g. for @stmaxted's ferrule example)

  connections:
    -
      - X1: [1-4]
      - <=
      - F1

  I don't see any issue with this use-case, except forbidding the use of <= et.al. as user-assigned designators, which shouldn't be too bad as a restriction.

---

A full example using two complementary connectors from @stmaxted's original photo could look like this:

connectors:
  X1: &X
    type: Screw connector
    subtype: female
    color: GN
    pincount: 4
  X2:
    <<: *X
    subtype: male
  F:
    style: simple
    autogenerate: true
    type: Ferrule
    color: GY

cables:
  W1: &W
    colors: [BK, WH, BU, BN]
  W2:
    <<: *W

connections:
  -  # ferrules + connector X1
    - W1: [1-4]
    - F
    - =>
    - X1
  -  # mate X1 and X2
    - X1: []
    - ->
    - X2: []
  -  # ferrules + connector X2
    - X2
    - <=
    - F
    - W2: [1-4]

[kvid]

• use <-, --, ->, <-> to display a single dashed line/arrow between two components (e.g. when mating male and female connectors of one series)
  [...]
• use <=, ==, =>, <=> to display one dashed line/arrow for each pin in the connection set (e.g. for @stmaxted's ferrule example)

If I understand you correctly, you suggest <- to mate a full connector (i.e. all pins) rendered as a single arrow, and <= to mate a individual pins rendered as one arrow for each pin.

Personally, I find it more intuitively to swap them, to associate the thinner <- with single pin mating and the and the double/thicker <= with a whole connector mating.

If you also plan a difference in visual appearance between these two mating arrows, then I also suggest the thinnest visual style for a single pin mating. Maybe a single dashed line for a single pin mating (as in the mock-up above) and a double dashed line for a whole connector mating?

The issue will be that currently, listing a designator without appending a pin list (- X1) is the syntax used for auto-generation of connectors, so we would need a way to differentiate the two use-cases, or come up with a new syntax for this case. The first idea that comes to mind is using an empty pinlist:

connections:
  -  # mating two connectors
    - X1: []  # empty pinlist: join the connectors themselves, not individual pins!
    - <-
    - X2: []
  -  # defining the connection of X2's pins to other wires etc. in a separate connection set
    - X2: [1-4]
    - W99: [1-4]
    # etc. 

Why not generalize this, and let an empty pin list mean all pins in any connection specifier? As far as I can see, that will remove the need for separate connection sets, but please correct me if I have misunderstood.

Alternatively (1), [-] could mean all pins as a generalization of [2-] (all pins from 2 and up), [-4] (all pins up to 4) and the current [2-4] (all pins from 2 up to 4), but that would also mean designators with a leading or trailing dash must be put in quotes to avoid ambiguity.

Alternatively (2), [*] could mean all pins as a generalization of [2-*] (all pins from 2 and up), [*-4] (all pins up to 4) and the current [2-4] (all pins from 2 up to 4).

Alternatively (3), a new syntax for a range of pins that support both numeric and alphabetical ranges, custom value distance within the range and more advanced combinations to generate e.g. [A-F], [2,4,6,8,...], [1a,1b,1c,2a,2b,2c,3a,...], [a-z,aa-zz], etc.; with input syntax e.g. something like this (range,distance,loop order):

• [(A-F)] => [A-F]
• [(1-20,2)] => [2,4,6,8,...,20]
• [(1-5)(a-c)] => [1a,1b,1c,2a,2b,2c,3a,...,5c]
• [(1-5,1,2)(a-c,1,1)] => [1a,2a,3a,4a,5a,1b,2b,3b,...,5c]
• [(a-z,1,1)(a-z,1,1)] => [aa-zz]

These alternatives are just ideas and need more work to become something useful...

See also my #184 (comment) where I suggest to release the current single designator syntax for other usage.

[formatc1702]

If I understand you correctly, you suggest <- to mate a full connector (i.e. all pins) rendered as a single arrow, and <= to mate a individual pins rendered as one arrow for each pin.

Personally, I find it more intuitively to swap them, to associate the thinner <- with single pin mating and the and the double/thicker <= with a whole connector mating.

I was thinking <-> resembled a single line, and <=> resembled two (=multiple) lines (one for each arrow that would be drawn), that's why I chose it. But I can totally see your point, and perhaps swapping them makes more sense.

If you also plan a difference in visual appearance between these two mating arrows, then I also suggest the thinnest visual style for a single pin mating. Maybe a single dashed line for a single pin mating (as in the mock-up above) and a double dashed line for a whole connector mating?

You mean the dashed lines in the GraphViz output? I'll need to see if we can make double dashed lines work... this sounds like a good idea.

The issue will be that currently, listing a designator without appending a pin list (- X1) is the syntax used for auto-generation of connectors, so we would need a way to differentiate the two use-cases, or come up with a new syntax for this case. The first idea that comes to mind is using an empty pinlist:

connections:
  -  # mating two connectors
    - X1: []  # empty pinlist: join the connectors themselves, not individual pins!
    - <-
    - X2: []
  -  # defining the connection of X2's pins to other wires etc. in a separate connection set
    - X2: [1-4]
    - W99: [1-4]
    # etc. 

Why not generalize this, and let an empty pin list mean all pins in any connection specifier? As far as I can see, that will remove the need for separate connection sets, but please correct me if I have misunderstood.

There is a slight misunderstanding. The idea is that an empty pinlist means "connect the connector as a whole" (using one, potentially double dashed, arrow) whereas no pinlist would auto-generate simple connectors (one per pin on the other connector) and link each of them with a singled dashed arrow.

Alternatively (1), [-] could mean all pins as a generalization of [2-] (all pins from 2 and up), [-4] (all pins up to 4) and the current [2-4] (all pins from 2 up to 4), but that would also mean designators with a leading or trailing dash must be put in quotes to avoid ambiguity.

Alternatively (2), [*] could mean all pins as a generalization of [2-*] (all pins from 2 and up), [*-4] (all pins up to 4) and the current [2-4] (all pins from 2 up to 4).

Alternatively (3), a new syntax for a range of pins that support both numeric and alphabetical ranges, custom value distance within the range and more advanced combinations to generate e.g. [A-F], [2,4,6,8,...], [1a,1b,1c,2a,2b,2c,3a,...], [a-z,aa-zz], etc.; with input syntax e.g. something like this (range,distance,loop order):

* `[(A-F)]` => `[A-F]`

* `[(1-20,2)]` => `[2,4,6,8,...,20]`

* `[(1-5)(a-c)]` => `[1a,1b,1c,2a,2b,2c,3a,...,5c]`

* `[(1-5,1,2)(a-c,1,1)]` => `[1a,2a,3a,4a,5a,1b,2b,3b,...,5c]`

* `[(a-z,1,1)(a-z,1,1)]` => `[aa-zz]`

These alternatives are just ideas and need more work to become something useful...

See also my #184 (comment) where I suggest to release the current single designator syntax for other usage.

All these ideas are very, good, but best discussed in a separate issue, since this only relates to the expand() function and has nothing to do with implementing new connection schemes. Thanks!