[feature] Add ability to define connections using pin names (from pinout list) instead of pin numbers *if* they are unique

[formatc1702]

There was the expectation in #38 that connections were defined using pin names instead of pin numbers.

The argument against this was that, while pin numbers are unique (or at least should be), pin names are not (typical example: multiple GND pins on one conector).

However, in many cases, pin names are unique or can be made to be (using GND1, GND2, ...), then it is more intuitive to link functions rather than physical pins. A check should be performed whether the pin names referenced in a connection set are unique, in which case using pin names instead of number should be allowed.
An error should be thrown if:

• An attempt is being made to connect to a pin with an ambiguous name within the connector being referenced.
• A label is used both as a pin name, and a pin number, which makes the definition ambiguous as well.

Pin names in other connectors should not matter, since the format of a connection is always - CON_NAME: [PIN_NUMBER_LIST].
Pins that remain unconnected should not be included in the check. In particular, a connector might contain multiple pins labeled as N/C or similar... there is no need to differentiate between those.

[formatc1702]

An additional benefit is that, if pin functions are switched around on a connector, the connection definitions can stay untouched.

[kvid]

@formatc1702 wrote:

• A label is used both as a pin name, and a pin number, which makes the definition ambiguous as well.

I guess it should be "A label is used both as a pin name, and a pin number for different pins". If label gnd is defined for a pin named gnd, then it is not ambiguous.

[formatc1702]

@formatc1702 wrote:

• A label is used both as a pin name, and a pin number, which makes the definition ambiguous as well.

I guess it should be "A label is used both as a pin name, and a pin number for different pins". If label gnd is defined for a pin named gnd, then it is not ambiguous.

This was implemented

I just rediscovered your older comment and really like the idea of using # and $ to refer to pin index and pin name, respectively. I will think about it some more!

[kvid]

I might have mixed the pinname and pinlabel terms.

1. Does pinout define pin labels or pin names?

2. Does pinnumbers define pin numbers even if they might be non-numeric?

3. Is pin label rather the reference to either pin number or name?

4. When I wrote pin index, I was thinking about the default pin numbers when not customized.

Maybe a definition of terminology should be part of the README?

Personally, I would excpect IDs, indices, numbers, and normally also names to be unique within the context, but that several pins could have identical labels.

[formatc1702]

I realize I keep mixing up pinout and pinnumbers myself, so this is due for a change.

My proposal:

• pincount (int) will retain its current function, as the easiest way to define the number of pins on a connector, without assigning any special IDs or labels.
• pins (previously known as pinnumbers) is the list of unique identifiers for each pin, and is autofilled with [1,2,...,<pincount>] when it not specified explicitly. It is useful for non-numerical pinout schemes like [tip,ring,sleeve], an alphanumerical matrix ([A1,A2,...B1,B2,...]) and others, and to manually reorder pin numbers if so desired ([4,1,3,2]).
• pinlabels (previously known as pinout) allows assigning labels to each pin, e.g. it's function (VCC, GND, ...). It is autofilled with ''and hidden if not specified.

This makes things more consistent by using plural words for lists (pins,pinlabels, a wire's colors, ...) and similar terminology for ints (pincount,wirecount).
I have chosen pins since pinids is weird to read and I want to avoid uppercase letters (pinIDs) and underscores (pin_ids).

Personally, I would excpect IDs, indices, numbers, and normally also names to be unique within the context, but that several pins could have identical labels.

• IDs in pins have to be unique.
• indices are just the internal pointer to a list's elements so they are unique. We could allow acces to indices using # like you proposed, but I doubt it's urgent.
• labels do not have to be unique, but can only be used for defining connections if the ones being used are unambiguous (the point of this issue)
• the terminology "names" and "numbers" won't be used.

How does that sound?

[kvid]

I think your proposal is really good!!! Thank you for considering this change. It certainly fits my personal expectations.

What term do you suggest using for a reference to a pin (where the value is either an ID from pins or an unambiguous label from pinlabels)?

If a change like this might create extra conflicts with large PRs in the process, then you should consider what is the best moment to introduce this in the dev branch.

[formatc1702]

What term do you suggest using for a reference to a pin (where the value is either an ID from pins or an unambiguous label from pinlabels)?

not sure...

If a change like this might create extra conflicts with large PRs in the process, then you should consider what is the best moment to introduce this in the dev branch.

The only big one is the multicolor wires, that's why I'm bugging him regarding the completion ;)
Even that shouldn't mess too much with this one, which is concerned with logically joining components, not graphically.

[kvid]

@formatc1702 wrote "not sure..." Then I suggest simply "pin reference" if you are going to need a separate term for that at all.