Switch naming is inconsistent

[Ratfink]

Background

The naming of our standard switch symbols is presently quite inconsistent. Below are some examples:

The suffix x?? has two different meanings:

• SW_DIP_x02: two SPST switches in a single unit
• SW_DPST_x2: a single DPST switch split across two units

SPST is sometimes implicit, sometimes not:

• SW_SPST: number of poles and throws explicitly listed
• SW_Push: number of poles and throws is implicit

Format for listing number of poles and throws is inconsistent:

• SW_DPST: double pole, single throw switch
• SW_Push_Dual: double pole, single throw pushbutton switch
• SW_Rotary12: single pole, 12 throw rotary switch
• SW_Rotary3x4: 3 pole, 4 throw rotary switch

Naming of normally closed switches is inconsistent and unclear:

• SW_Reed_Opener
• SW_Push_Open

Reconciling these inconsistencies would make the library easier for users to search, and could make smarter footprint filtering possible if the footprints are renamed accordingly. This is related to KiCad/kicad-footprints#144.

Proposal

My proposal for a consistent naming convention for standard switches is as follows:

Fixed fields
Mandatory fields
Optional fields

SW_[type]_[poles]P[throws]Tx[quantity]_[NO/NC]_[control]_[light]_[options]

• type: e.g. Push, Reed, DIP
• poles: integer
• throws: integer
• quantity: two-digit integer
• NO/NC: if one switch of a given type uses this, all must to ensure proper filtering
• control: e.g. Temperature
• light: e.g. Lamp, LED
• options: anything else, e.g. Split

This would directly translate into footprint filters, as footprints could be named the same way with manufacturer name and part number as additional suffixes.

Effects

This proposal would reconcile all the inconsistencies above:

Before	After
SW_DIP_x02	SW_DIP_1P1Tx02
SW_DPST_x2	SW_2P1T_Split
SW_SPST	SW_1P1T
SW_Push	SW_Push_1P1T_NO
SW_DPST	SW_2P1T
SW_Push_Dual	SW_Push_2P1T_NO
SW_Rotary12	SW_Rotary_1P12T
SW_Rotary3x4	SW_Rotary_3P4T
SW_Reed_Opener	SW_Reed_1P1T_NC
SW_Push_Open	SW_Push_1P1T_NC

Limitations

This only covers standard mPnT switches. Manufacturer-specific switch symbols and coded switches are not considered by this proposal.

This could be perceived as overly verbose, requiring DIP switches to be explicitly labeled as 1P1T, and Push and Reed switches to be explicitly labeled as NO or NC. I think the benefits in clarity, both to users and footprint filters, outweigh this drawback.

This would require renaming most of our switch symbols and footprints. This could prove difficult given the looming 5.0 freeze. The symbol changes could be done relatively quickly (as we don't have a ton of switch symbols), but the footprint changes would be more involved. None of the DIP switch footprints would need to be renamed, as they already match this proposal. I estimate a full day's worth of work to do the renaming, plus the time required to review the changes. I of course volunteer to do the renaming, as I'm the jerk who came up with this idea in the first place.

[evanshultz]

It would help me to see the symbols here so it's all together with the symbol names.

1. Having done this before professionally, it will be best to use only integers for poles and throws. That ways it's all consistent. You don't want to start with letters and then move to numbers, as users will need to search twice to find all desired symbols or else they will miss some.

2. I don't see the [quantity] field's value. With poles and throws given, what does it do? SW_DIP_SPSTx02 could be SW_DIP_2P1T. And also this symbol could be SW_4P3T_Rotary:
   

3. Similarly, what is the value in MultiUnit when the poles and switches can carry that info. Do you have an example that doesn't work?

4. I find poles and throws to be more important, so I'd put type after it as I've done above. That also makes all requires fields present before any optional ones. (Not saying you have to do this, just my preference.)

5. What about symbols that mix NO and NC types together? Not sure if there are, but what if...

That's all I can think of now, but this type of thing probably needs some time to sink in.

For footprints, I believe manufacturer info comes first.

[Ratfink]

1. I see the advantages of that (ensures lexicographic ordering), but the disadvantage is it means even more things will need to be renamed. I tried to avoid any renaming that wasn't strictly necessary in my proposal. We could add whichever format we don't use in the names to the keywords (e.g. name has SPST, add the keyword 1P1T, or vice versa) to make searching easier. If we accept that almost all our switches would be affected (e.g. even the DIP switch footprints), I would be (slightly begrudgingly) okay with this suggested name change.
2. I believe it's standard for "n poles" to mean that the poles are all controlled by a single mechanism (Wikipedia (2nd paragraph of that section) and Littelfuse agree with this), so a SW_DIP_1P1Tx02 really shouldn't be called SW_DIP_2P1T, as this would be inconsistent use of the word "pole". Also, DPST DIP switches do exist, and my proposal works fine for them. Also, don't we agree on naming of rotary switches (unless you're arguing that "Rotary" shouldn't be a type)?
3. MultiUnit is for improving the naming of e.g. our existing SW_DPST_x2 symbol, a DPST switch symbol split into separate units for each pole, to distinguish it from SW_DPST, where the poles are both in the same unit.
4. I was trying to minimize the disruption to our current naming while adding consistency, and we currently put the type immediately after SW.
5. If there are any, I would suggest we just string them together, e.g. SW_Push_SPSTx2_NO_NC.

Our switch footprints currently put manufacturer info last. See Button_Switch_SMD.pretty. Moving it would change the convention settled on in KiCad/kicad-footprints#218. Again, I'd rather not rename more things than absolutely necessary, and our current DIP switch naming seems okay overall.

---

EDIT: We should probably have at least one more option for the NO/NC field to cover pushbutton switches that toggle between open and closed on each press. Something like Toggle or Latching.

[Ratfink]

@poeschlr @jkriege2 @evanshultz Any more thoughts on this? While this isn't a major problem, I would like to improve our switch naming and filtering by 5.0 if there's time.

---

To clarify: "I don't think there's time" is also a perfectly acceptable answer. 🙂

[evanshultz]

Then "I don't think there's time".

1. I do think this is the best way to go. And with missing v5 on this, I assume, why not get it "right"?
2. Got it. Then I support x2 as that matches our resistor network naming.
3. I don't see this is relevant in light of the above. If the switch has x2, then it's multi-unit in this light. So this modifier goes away. Or am I missing something?
4. I see. Either way then. Just my preference.

Are switches commonly multi-sourced? If so, then putting the vendor after switch type is OK with me. If switches are generally sole-sourced, then I think it should come first. Since switches are so diverse, I'm not strongly leaning one way or the other. On the Package* libraries, though, we put the vendor first. Always, AFAIK. Is there a reason to make this consistent?

Buttons that only operate when depressed are Momentary or the shorter Tactile. That fits as another choice along with your suggestions of Toggle and Latching above (though for verb consistency we might use Latch). But since I believe most switches operate in fixed positions where the user puts the switch in a certain position and the switch operation does not change until the switch is touched again, meaning momentary behavior is the outlier, perhaps we only add momentary or tactile if needed?

[poeschlr]

Regarding the no time argument:
I agree we should not rush this just to have it in rc2. But if we find something that works well i would be prepared to include it in v5 (as long as it does not change the library names it should be ok)

[Ratfink]

@poeschlr Taking that into consideration, I'll take up the torch on this discussion again.

@evanshultz

1. Okay then, I don't even feel begrudged about this anymore. And as I mentioned before, we can still use keywords like SPST to aid in searching.

 

3. Those symbols are meant for the exact same switches as each other (they're both 2P1T), just for a different way of drawing the switch on a schematic. It's not the same as x2 for DIP switches because the two symbol units are controlled by the same mechanism, they're just drawn on separate units because that might make some schematics easier to draw. The current naming uses x2 to mean something different from what it does in DIP switches, which is one of the naming inconsistencies that made me start this whole discussion.

I don't really have a strong opinion on where manufacturer info should go in footprint names either, really. Putting it at the start would just mean we need a leading * in the footprint filters, which would be fine.

As I understand it, Tactile is a specific type of Momentary where the user can feel a change in force when the switch actuates. But as I see it, NO and NC implicitly mean Momentary, so we don't need to explicitly state that as well. My reason for wanting another value, e.g. Latch, to take their place when needed is so footprint filters for a latching switch don't also match NO and NC switches. Maybe that's not a problem though.

[poeschlr]

NO and NC do not necessarily mean momentary. there can also be switches that "keep" their state but still have NO and NC types. (Think about a emergency stop switch. It has a default state open or closed, pressing the button keeps it in the other state until some user action.)

[evanshultz]

1 Form C relays (like https://www.jameco.com/Jameco/Products/ProdDS/843155.pdf) have both a NO and NC contact both and they're either in one position or the other. There are relays that latch into a position and stay that way even if energy on the coil is removed (these are good to reduce continuous power consumption since the coil can be de-energized). However, I don't see that this matters for the schematic symbol, but it could be shown if desired.

3. So you're talking about a distinction between, say, two separate switch symbols in the same unit (x2) versus having two switch symbols on separate units (x2_MultiUnit)?

[Ratfink]

Okay, so we need another field for Momentary or Latch. I suggest putting it immediately before NO/NC.

A switch with one NO and one NC contact could just be called e.g. SW_Push_1P2T, right?

Yes, two separate switch symbols in the same unit is x2, two separate switch symbols in two separate units could be x2_MultiUnit (though we don't have any of those in the library currently), and one switch symbol split across multiple units is MultiUnit.

[evanshultz]

Only if the symbols are different, I suppose. Latching coils only apply to relays so it probably doesn't affect switches like shown above. Momentary will use a different symbol and I commonly see https://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/Push-to-make_switch_electronic_symbol.svg/500px-Push-to-make_switch_electronic_symbol.svg.png.

I think we should be explicit. I would want to know what switch configuration was present and I don't think having one of each cancels them out somehow.

Thanks for clarifying. I get it now. One question: because this nomenclature could be used elsewhere, is there a better name? Split, perhaps? I'm trying to think about applicability and brevity.

[Ratfink]

You're right, Split is more concise and works just as well. Now that GitHub lets us see old revisions of comments, I'll start revising the original post with changes we've agreed on.

[poeschlr]

We can think about a scheme that is used for new contributions. But existing symbols and footprints should not be changed in a manner that would break existing projects that use them. (Otherwise we are unable to supply users with bugfix updates of the library.)

[poeschlr]

Edit: Disclaimer: The naming convention should be followed by all new additions. Yes it is still kind of experimental and can evolve but we will never discover how to properly do it if we do not field test it.

---

I highly doubt we will ever find a system that will encompass everything i would go with the latest porbosal we had and codify that for now. Use that for new contributions and add further things to it if we see the need. The hope would be that by v6 there is a good naming convention that can then be used for all switch and button contributions.

The fact that we are hung up on such details already shows that the standard for the lib is already quite high.

---

My summary (with a bit of decision making added such that we can get this finalized)

Fixed fields
Mandatory fields
Optional fields

SW_[type]_[poles]P[throws]Tx[quantity]-[MP/SH]_[NO/NC]_[Latching/Toggle]_[control]_[light]_[options]_[Split]

I would keep split (=multi unit) explicit. This way we can offer symbols for the same part in both multi and single unit style (We do not paint us into a corner if we have this as an explicit option) I would also explicitly mark it as the last suffix to ensure correct ordering if there is a single and multi unit option of the same part.

MP/SH is to mark symbols (and footprints) that include mounting or shield pins.

---

type field (symbol) footprint:

• (Push) Push: actuation by pushing
• (?) Rocker: a rocker switch
• (Reed) Reed: reed contact
• (?) DIP The typical tip style switches (DIP specifies the pin arrangement not really the actuator type. Which will most likely be slide.)
• (?) Slide: a switch with a slider as the activator.
• (?) Lever: rocking lever type

It might be an option to have fewer options for the type field for symbols vs footprints and map different types to the same symbol.
Example the rocker, lever and possibly also slide option could be described by the same symbol. (I don't have a name right now. That is why i marked it with ? for now )

Toggle: The same action changes the switch between its states
Latching: One action activates the switch. A different action is required to reset it (typical example: emergency stop switch)

---

footprints

SW_[type]_[poles]P[throws]Tx[quantity]-[MP/SH]_[NO/NC]_[Latching/Toggle]_[control]_[light]_[options]_[Horizontal/Vertical]_[man]_[mpn]

The footprint side would use this naming convention as a prefix. After that would be the footprint specification. (so man+mpn for manufactuer specific footprints, size definition, and pitch for generic footprints)

This is done such that we can use simple footprint filters.

We might also want to add a specifier for horizontal vs vertical.

The alternative would be the use of atomic parts (specialized symbol and footprint for every manufacturer specific part)

[antoniovazquezblanco]

Is this ready to be documented in the KLC?

Should I move the latest relevant information to the corresponding repo (https://github.com/KiCad/kicad-website/issues)?

Thanks

[poeschlr]

There is already an issue on the website repo. I simply decided to point to this topic from there as i do not feel that it is a good idea to duplicate information in multiple issues.

[diegoherranz]

Regarding [poles]P[throws]T, I've seen that we use either 1P1T or SPST in the repo currently (see https://github.com/KiCad/kicad-footprints/tree/master/Button_Switch_SMD.pretty).

What would you guys think about enforcing S for single, D for Dual and using numbers for anything above 2? In my opinion, that's what seems to be the "norm" mostly everywhere.

I would be happy if we enforce the use of numbers too, I mainly want a unified convention since it makes it easier to search footprints.

Thanks!

[evanshultz]

I agree that words should not be used "above" dual. It gets too messy and looks ugly. My gut likes all numbers because then searches are a bit easier to me (thinking like a regular expression).

However, DigiKey (https://www.digikey.com/products/en/switches/toggle-switches/201), Mouser (https://www.mouser.com/Electromechanical/Switches/_/N-5g2h/), and Farnell (https://www.newark.com/c/switches-relays/switches) all classify switch poles and throws just as you said so I support that. Great suggestion!

[antoniovazquezblanco]

I personally prefer to use 1P1T instead of SPST but I agree that many users would prefer to look for the more traditional SPST term. That could be used as a keyword in order to allow users to use whatever term they prefer while keeping a cleaner naming using numbers?

[diegoherranz]

I think that may be a good compromise.
Numbers on the names which allows cleaner naming and nicer ordering, but mandating to include the traditional single/dual acronyms as keywords so that you can find them using both terms.

I will use this approach on related open pull requests unless someone disagrees. Please let me know.

Thanks!

[diegoherranz]

After approximately a week, I'll assume that there is no disagreement so I'll start using this approach.
I suggest the following wording to complete the convention by @poeschlr at #580 (comment) :

---

The number of poles and throws must be specified using a number even for 1 and 2 which are commonly or traditionally specified as single (S) or dual (D). In those cases, the "traditional" terms must be added to the keywords so that the footprints can be found using either acronym format. For example, for a 1P2T switch, 1P2T must be used in the name, and SPDT must be included in the keywords.

Thanks!

[poeschlr]

Sorry for the long silence. I must agree that i prefer numbers at least on the footprint side. This makes writing the rule a lot easier.

The idea is that we then have generic symbols that already have the correct footprint filters such that users do not really need to search for the footprints. (cvpcb should already point to the correct selection.)
I think at least the symbol keywords are also used by the search function. If not then we can always add aliases.

[diegoherranz]

No problem. I have just checked and yes, keywords work fine when searching for symbols, so it's probably a matter of simply adding keywords to existing generic symbols as well as footprint filters. I'll try to have a look.