Define Nomenclature for project names, symbols and footprints

[gbip]

We are currently missing a standardized way to name our boards, symbols and footprints.

For the board part I was thinking about <microcontroller name>_<functionnality all in snake case.

[gbip]

I think that we should also define the following worflow before manufacturing a board :

1. Increment the schematic number
2. Create a commit
3. Push the commit and tag the commit with <project_name>_<revision>

Pros

• We can easily find previous revision of a board
• Everything stays organized

Cons

• It involves knowing how to tag a specific commit in git
• There is no central place where all the revision are listed

[gbip]

One sided boards convention

We should also define a few conventions for one sided boards such as which side is for connectors, and which one for the copper.
Same for 3D models with solder through components : should they represent the fact that they are soldered through the board or not ?

Finally, we don't have any rules for linking masses together, and there is no documentation about this...
For example, should we link the mass between the servomotor connector and the µC or do we consider that since they are already linked at source it is okay ?

[gbip]

Here is the relevant section in the documentation : here.
You can see that Alex already started working on it.

Il va falloir bien suivre, la suite est très importante et te fera gagner beaucoup de temps. Un peu de contexte : plus une piste est large, plus elle peut conduire du courant sans chauffer. Une piste qui chauffe, ca veut dire des soudures qui fondent ou des composants qui grillent. Mais plus une piste est large, plus le routage sera difficile. Le nouveau jeu est donc de dimensionner chaque piste en fonction de son utilisation : pistes fines pour du signal, pistes larges pour la puissance. Pour cela, la solution idéale serait justement de pouvoir indiquer à KiCAD quelles connexions seront utilisées pour de la logique, et quelles connexions feront passer des gros courants. Ca tombe bien ! Setup -> Design rules... à été inventé pour ca. C'est un processus en deux étapes. D'abord on remplit le tableau 'Net classes'. On indique à KiCAD la liste des différents types de connexion. En reprenant l'exemple ci-dessus, on peut y ajouter une classe 'logique' et une classe 'puissance'. Pour le moment, deux classes ne se distingueront que par la caractéritique 'Track width', c'est à dire la largeur de la piste. Pour la logique (<300mA), rentrer 0.25mm. Pour la puissance, on prendra en général 1mm, mais c'est au cas par cas. Une piste qui alimente une STM32 (<1A) est plus fine qu'une qui alimente un moteur (plusieurs A).

[gbip]

@dotsumae @goowza @al342179
Can we validate the board naming ?

For the board part I was thinking about <microcontroller name>_<functionnality all in snake case.

For the symbols name, I we have two policy :

• one symbol per components
• one symbol per component usage (aka HE14-3 for PWM, HE14-3 for Serial, HE14-3 for Power, etc.)

[goowza]

I thought the board name convention was already declared in the documentation ?

For the symbols, i think one symbol per component usage is a good idea since it could make the schematics easier to read and understand.

[gbip]

Oh my bad I never saw it !
The problem with one symbol per component usage is that if you have something to fix in a component you have to fix all of them...
I think that we should look into other features of kicad to try to make the schematics easier to read and understand (hierarchic schematic ?)

[dotsumae]

As for symbol names, I suggest we use the same convention as KiCAD's included libraries : first word with a capital letter and the others in lowercase. Every word is separated with an underscore. I will add this to our documentation. I will also update our library to remove the confusion between a symbol and its usage : the "Carte Universelle" will be used as a reference/template for the layout/pinout/footprints of our connectors, thus removing the need to create one symbol per function (PWM, serial, power).
On, hierarchical sheets, I personally find graphical boxes and labels way easier to use and maintain. I feel like (after a few experiments) hierarchical sheets would be overkill (even for the bare STM32 project).

[gbip]

I totally agree with you 👍
Don't hesitate to link this issue to the related commit by adding #2 to the commit message 😉
Or directly link to it...

[dotsumae]

We should update the naming convention of our projects to to place the most important information first

[gbip]

What about <functionnality>_<µcname>_<year> ?

[dotsumae]

On the long run I think the year will be more important (when looking for a specific PCB without knowing how it is made) than the uc. Also the year is only 4 (or 2) characters long : it can't hide the uc name when displaying the file name. We could also remove the year from the filename and archive every year the old designs elsewhere

[gbip]

I agree with you, so do we agree for the following format : <functionnality>_<year>_<µc-name> ? You can format each field as you want it is not really important unless you are not consistent between project.

We have to choose between :

• snake_case
• CamelCase
• pascalCase

I have a personnal preference for snake_case but it is just a matter of personnal tastes, so pick whatever you prefer.

For archiving boards, I think we can discuss this issue later (after the competition) and focus ourselves on more important problems (see #14). 😉

[dotsumae]

snake_case and <functionnality>_<year>_<µc-name> is perfectly fine to me. Documentation has been updated

[gbip]

There is still a few things that we need to figure out :

I think that we should also define the following worflow before manufacturing a board :

• Increment the schematic number
• Archive the board and upload it to the release section in github
• Create a commit
• Push the commit and tag the commit with <project_name>_

An other point is writing a little bit about ground linking.

Finally we did not discuss the repository organization...
I think that we should make one repo per card is better because that's the way git is supposed to be use and many features makes more sense that way.
This repository would then become the "libkicad" repo.