reviews (was Re: [Milkymist-devel] [KiCad M1R4] First KiCad version for Milkymist One Schematics.)

Werner Almesberger werner at
Tue Apr 24 12:31:46 EDT 2012

Adam Wang wrote:
> We just generated first KiCad Milkymist One whole schematics for R4 version:

Great work. Congratulations !

> here's great pdf generated from Werner, he may introduce more idea of
> categories of components structure in another thread. :-)

Yes, the whole hierarchy is very chaotic and full of inconsistencies.
We should also give many component more systematic names. And there
are too many reasonably generic components that carry the name of a
specific vendor part.

Furthermore, some of the .lib files contain quite a few fairly
distinct components. It would be better to have one per file, so
that the revision history clearly identifies the component that got

I'm also unhappy that we have so many design-specific power symbols.
Not sure what to do about them, though. KiCad doesn't allow editing
of the symbol's name, so you need a separate symbol for each such
net. Perhaps we should use project-local components in such cases.

So this is still a construction site. Fortunately, it will be
relatively easy to propagate changes of component names to the
schematics (you can simply edit the .sch files with a text editor),
and changes in the hierarchy won't affect the schematics at all.

> about this KiCad M1r4, things to be reviewed/suggested:
> 1. directions of global labels

Yes, I see that you already made labels follow the direction of
the signals. This is an important improvement over the original

> 2. stupid wrong text, etc.

Heh :-) Let's not forget component values. I suggest to follow the
conventions we established for the gta02-core project:

- the beginning of the discussion thread:

- the conclusion:

- the results:

For example, resistor values would change as follows:
4.7K -> 4k7, 49.9 -> 49R9, 220 -> 220R.

> 3. better look; like part's value and reference orientation, etc.

Yes ! The original M1 schematics look very crowded at some places,
which makes them confusing. Parts of the circuit should always
expose their function clearly. The human brain is good at seeing
patterns but it's very bad at keeping track of a million details.

When a sheet gets too crowded, it's usually better to move part
of the circuit to a new sheet than to squeeze things into the
last little corners. The next person who comes along to make a
change will be thankful for a bit of room.

There are also simpler details. For example, NORFlash.sch has
the following formal/visual issues:

- the ground symbol on pin 32 (A0) overlaps the text "FLASH_A0",
- FLASH_D15 is not aligned with FLASH_D0 through _D14,
- TP37 doesn't need a pin number,
- the wire coming from pin 14 (CE1) shouldn't have a junction
  marker (fat dot),
- the text "TP37" is only 30 mil tall, compared to 50-60 mil for
  most of the other text,
- the 3V3 on VPEN and BYTE# have much smaller text than the 3V3
  on R183,
- I'd also try to avoid having positive rails point downward or
  ground point upward. E.g., I'd consider connecting pin 31
  (BYTE#) to pin 15 (VPEN) and remove the 3V3 at BYTE#.

This is just an example of how a sheet that looks nice and clean
at a first glance can still be full of surprises.

Speaking of which, did you notice that all the power symbols
call their pin "3V3" ? (E.g., click on 1V8 in VideoIn.sch, select
Pin 1, then it appears in the "Name" field in the status area.)
This should be easy to fix by editing pwr.lib with a text editor.

> next step:
> to create modules(footprints)

Reviews and cleanup first, please :)

> looking forward to hearing feedback from this and more people can join and
> contribute. :)

Yes, please ! :-) What needs doing:

- review of the symbols:
  - is the symbol understandable ?
  - are all pins present ?
  - do they have the correct name ?
  - do they have the correct number ?
  - does the pin type correspond to what the data sheet says ?
  - is text large enough ? (0.050-0.060" for component reference
    and value(s), 0.050" for pins and other text)
  - more ?

    Regarding pin types, KiCad has "No connection" (NC) and
    "Unspecified" (Unspec). NC produces an ERC complaint if
    anything is connected to it at all. Unspec doesn't care what
    is connected.

    When a data sheet says "NC", this can mean "no internal
    connection" or it can mean "do not connect anything here".
    Sometimes, a data sheet clarifies that, many don't.

    So we should use "NC" for anything says "do not connect" or
    that lacks clarification while we should use "Unspec" only
    if the data sheet says it's okay to connect something.

    Why make the distinction ? Because it can sometimes be
    convenient for the layout to be able to route a signal
    through an NC pin. But that only works if the pin truly isn't
    connected to anything on the inside of the package.

    Regarding pin names, we should follow whatever the data sheets
    use, unless the data sheets are obviously wrong or misleading.
    (I've seen pins named "ON" that turn something off ...)

    One issue: what to do with pin names that aren't valid C
    identifiers ? (*) Particularly inverted signals often have a
    lot of presentations that are a pain to use in a program: e.g.,
    nRESET, RESET_N, RESET#, /RESET, or RESET with a line on top.
    Of these, only nRESET and RESET_N can be directly used in a

    (*) I pick C here as an example for an identifier syntax shared
        by most programming languages.

    Names that aren't identifiers could still be transcribed but
    this easily results in confusion. Possible remedies:

    - always use C-friendly names in components,
    - define transcription rules and hope for the best,
    - a mix of both, e.g., use a C-friendly convention for inverted
      signals, leave the rest (FOO+, etc.) to transcription.

    Note that this doesn't affect alternate pin names. E.g., if we
    have a pin calles, say, GPIO1/TX/MOSI, then one would normally
    pick the name corresponding to the respective function or the
    most generic one, depending on context. So the / aren't part
    of any identifier.

  The components/symbols are in

  "make sch" will bring up the schematics editor configured for
  editing all the components we have. To edit/examine a component,
  click on "Library editor" in the top icon bar, then select the
  library with "Select working library", and the component with
  "Load component".

  There is a "catalog" that exposes a bit more information here:

  Note that some of the symbols are not drawn correctly in the
  catalog, due to bugs in KiCad's printing subsystem. E.g., in
  74X1G00_5 the arc is reversed. When in doubt, what the component
  editor shows is what matters.

- review of the schematics:
  - do they show the same circuit as in the original M1r4
    schematics ?
  - are the values the same ?
  - are things free from overlaps ?
  - is text readable ? (When adding a symbol from the component
    library to schematics, a copy is made of the fields. So if
    the text size is/was later changed in the library, this isn't
    automatically reflected in the schematics and the two may
  - can text be unambiguously associated with components ?
  - are component references on top or the left of values and/or
    part numbers ?
  - are comments/explanations understandable ?
  - when wires join in a T, is there a junction mark ?
  - are there no junction marks anywhere else ? In particular,
    do we only have crossings of the types 2b, 3b, and the right
    side of 3a, but never 1a or 2a ?
  - are connections straight and clear ? Here are some style
  - do positive rails point up, ground (and negative rails, but we
    don't have that in M1) down wherever reasonable ?
  - do labels point in the direction of the signal ? (This is all
    wrong in the original M1 schematics.)
  - more ?

  The schematics live in

  "make sch" will fire up the schematics editor. Then double-click
  on the respective sub-sheet.

  Before too long, we should also have the graphical schematics
  history back up. That will include an automatically generated
  PDF of the complete design. That'll be at

I would suggest to start with the components/symbols first, and
only then proceed to the schematics. That way, we avoid hitting
the same problems twice.

If someone reviews a component, please let us know even if you
don't find any problems. That way, we can keep track of which
components have been reviewed and which still need attention.

Note that our components library contains items not only from
Milkymist but also from other projects. E.g.,
Unclassified/werner-17042012 has things from ben-wpan and so on.
So don't be surprised to find strange parts like antennas :-)

- Werner

More information about the discussion mailing list