Hi,

This is for earlier Werner's reply about my schematic editing. :-)
Here's one wiki page:
http://en.qi-hardware.com/wiki/Rules_on_Editing_Schematics

On Wed, Apr 25, 2012 at 12:31 AM, Werner Almesberger <werner@almesberger.net> wrote:


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.

Regards to how generic components are, we can keep improvements on this topic.


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
changed.

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.

Good idea ! Yeah, I moved few applicative power symbols locally. :)


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
schematics.

> 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:
 http://lists.openmoko.org/pipermail/gta02-core/2009-June/000174.html

- the conclusion:
 http://lists.openmoko.org/pipermail/gta02-core/2009-July/000184.html

- the results:
 http://people.openmoko.org/werner/gta02-core.html

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.

Liked you pointed an A3 size for still be probably readable, the four banks for fpga chip are split. :)


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.

For Milkymist One schematic, only on Dram.sch I quite didn't realize how to make a better outlook way to arrange vertical crowed resistors which is a little against rules I edited in wiki. :)


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.

yes, just cleaned. :)
 

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.

fixed.
 

> next step:
> to create modules(footprints)

Reviews and cleanup first, please :)

yeah,do you have good idea to generate a good quality pdf  instead of using KiCad's print ? So this way seems good for reviews without installing KiCad.


> 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 ?

I still recorded them above in wiki, if more extra-valuable comments/replies, then add.


   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.

Good reminder. :)
 

   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
   program.

I picked nRESET style for KiCad m1r4 sch now. :)
 

   (*) 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.

With C-friendly names did really save me suffer from some troubles while I edited m1r4. Like I used it for url link.


   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
 http://projects.qi-hardware.com/index.php/p/kicad-libs/source/tree/master/components/

 "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:
 http://downloads.qi-hardware.com/people/werner/tmp/kicad-libs-components.pdf

 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
   diverge.)
 - 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
   suggestions:
   http://downloads.qi-hardware.com/people/werner/tmp/style-0.pdf
 - 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 ?

just overall embellished upon above ideas/rules. :-)
 

 The schematics live in
 https://github.com/milkymist/board-m1/tree/master/r4/

 "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
 http://projects.qi-hardware.com/schhist/

Not sure if schhist can apply for m1r4 now.


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.

Although I overall reviewed symbols and modified most for the same size text and pins style, but still welcome to review them. :)
 

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 :-)


yes, if one discovers new problems or comments given.
thanks.

- adam