Will "Getting Started" tutorial be updated?

https://contextualelectronics.com/learning/getting-to-blinky-4-0-part-1-2-3/

Chris, allow me to be the first to say (on behalf of everybody here) a mighty “THANK YOU”.

Legend! :thumbsup:

Have you checked recently?

Looks the same to me… again, please be specific.

If you follow the instructions, it worked for me…

I don’t think that is ambiguous, in all guides I have ever seen “a” means press the “a” key, and not Shift-A or Ctrl-A or Alt-A. A couple of seconds would verify which is meant. But if you think there is a problem, please suggest some wording to make it less ambiguous…

The current text recommends 50 mils, but anyway that is a question about the program design.

Seesm to work with my 4.0.0 install, again, please be specific. Which files?

These seem like minor issues, rather than anything needing a rewrite. Is the problem that nowadays people prefer video guides rather than reading through text?

Anyway, if you want to help improve kicad, raise specific issues on https://github.com/KiCad/kicad-doc/issues. Generalised complaints here are unlikely to get acted on.

Yes seems to have fixed some things in the Getting started manual, that’s great!

With the “A” and “Shift+A”… If you type “?” to get up the list of shortcuts, it says “Add Component = A”. But if you go menu/Place/Component, it lists the shortcut as “Shift+A”. They both work, sort of similarly.

Grid-size, yes I mixed it up. Default is 25mils, but manual says “it is recommendable to use a grid of 50mils for schematic”. Why then is the default 25mils?

But these are tiny issues. Seems like someone’s addressed some of the other ones, which is good. Obviously not so minor as to not needing addressing? Reading text guides is great if it flows logically. You shouldn’t have to second-guess things or puzzle needlessly over ambiguities.

Yes, I’ve noticed there is some inconsistent behaviour here. In fact if you do Shift-A as the menu says, it doesn’t work! However, if I have Caps Lock on, the A key still works, and Shift-A still doesn’t. I will raise a bug on Kicad about that. But this is a bug in Kicad, the tutorial is correct. Even so, I am trying to get the text replaced with icons, unfortunately getting improvements is an uphill struggle :frowning: https://github.com/KiCad/kicad-doc/issues/226

Form what I can see and remember, the default size is 50 mil. Either way, the tutorial is correct.

[quote]Reading text guides is great if it flows logically. You shouldn’t have to second-guess things or puzzle needlessly over ambiguities.
[/quote]

I absolutely agree with that. But I think it is inevitable that any single guide will have ambiguities, condensing complex concepts into a few easy to digest sentences always suffers from information loss. It’s always a good idea to consult a few different sources.

It’s also why forums like this are useful, people can ask “I’m doing step 14 and it says do xx. Can anyone explain?”. If a lot of people ask the same question, then improvements can be identified.

I will withdraw my previous suggestion to raise issues on github; don’t bother. The team there don’t seem to want to change anything, even where they admit things are wrong!

I will create a fork anyway to submit pull requests.

Apparently “not a bug”, it’s the way Kicad is designed. Shift+A enters “Place component mode”, but does not start the place component dialog - it is equivalent to clicking the tool bar button. To actually place a component, you have to click in the drawing area or press the A hot key.

Oh well, we’ll have to forget about trying to improve the Kicad user interface. Project lead Wayne Stambaugh is firmly opposed to improving the interface:

I will not change the behavior of hot keys because some users are confused by their behavior.

Wayne didn’t bother to read what I had written, and got the wrong idea, so I think it would be pointless to argue with him!

I’m a new user trying to get through the tutorial. Here are the issues I see so far

Document I’m using (for section numbers referenced below)
http://docs.kicad.org/en/getting_started_in_kicad.pdf

Kicad version and OS in use

kicad-product-4.0.1-x86_64.exe on Win7 Pro:

Section 3.1

  1. When I hover on the component and press r instead of rotation I get a dialog box
clarify selection
       field value
       component R R?

easy enough, it wants component R R? selected then r rotates. however a warning
this will occur would be good, a way to avoid it would be even better!

10 right clicking on R also gets the Clarify selection box, same solution as above

11 History in the PDF is wrong. Since we haven’t yet selected a Barrel Jack, it is not
in history (minor nit, but potentially confusing to a newby and easily fixed!)

19 PIC12C508A-I/SN isn’t in the list of microchip processors loaded by default.
Someone noted this above, along with the suggestion that it is in the repository.
This is correct, and I’ve downloaded the zip from


But I can’t figure out even from reading the manual how to get the symbol from
the zip file into the symbol library. If someone would enlighten me that would be
great, and it should be documented in the PDF as well since it is impossible
to complete the tutorial til you figure out how to do this and it isn’t obvious (at
least to me) how to do it. Since I’m stopped here that is as many issues as I
have for now (perhaps to all of your relief).

Well, I suppose everyone would be satisfied if a user could reassign all shortcuts (which doesn’t seem to be the case at the moment).

Hi vanepp.

You probably already have the library on your library directory, it just has not been loaded into the project by default.

The latest version of the tutorial includes details of how to load the required library.

Before add-component, add microchip_pic12mcu to your Component library files
by Preferences → Component Libraries and press Add button.

It is always worth checking the latest documentation via the link on eeschema’s Help menu (these links appear to be one of the things fixed in 4.01 as they did not work for me in 4.0 ;-)) .
.

More generally, can I just take a moment to thank the person(s) who updated the tutorial :smile: . I know it seems like a small thing to experienced users, but I am certain that making the first baby-steps easier for noobs will pay dividends in encouraging wider adoption of KiCad.

Cheers, Bob.

1 Like
 By using ls -lR from cygwin I did indeed discover that I have the libraries in program 

files. I also saw and tried

Before add-component, add microchip_pic12mcu to your Component library
files by Preferences → Component Libraries and press Add button.

I read that in the tutorial but that didn’t work any better. However when I tried again just now I found my error: I was pressing add in the User defined search path, not component library files (which is above that on the screen), since there are two add buttons it may be worthwhile specifying in the tutorial that you want to press the top add button to add the library not the bottom one. I’d say it was just me being stupid, except that someone else further up in this thread said the same thing (although it is possible that he was referring to an older copy of the tutorial too).
I too would like to thank the folks that create and maintain the tutorial as it is important to have a clear way for a newcomer to figure out how the tool works and I must admit that I was beginning to think that if I couldn’t get the tutorial to work then Kicad may not be an answer for me. Thanks for the pointer as that is what got me to look at this yet again and finally figure out what I was doing wrong.

It may be worth noting in the tutorial that if you screw up (as I have multiple times) and try to restart by deleting the tutorial1 directory you created that you also (at least on Windows) need to delete \Users\Owner\AppData\Roaming\kicad (at least in my case, your path will be different) because it is storing things in there too and will remember them when you recreate your directory.
Now a bunch more issues as I have moved along in the tutorial listed by section number. If this isn’t an appropriate place for this I assume that someone will tell me :smile: . Again indexed by the reference numbers in the tutorial:

6-1
7 click on the first corner, do not hold button down while moving to the other corner as that does something different than create the rectangle.

43 Annotate schematic icon is in the tools menu on the top menu bar (I was trying to find it on the screen …)

45 change “Perform Electric Rules check” to tools -> Electrical Rules Checker.
change Click “Test ERC button” to “Run” in both places.
on Windows clicking “create ERC file report” run save file tutorial1.erc results in “No default editor found you must choose it” . I chose c:\windows\notepad.exe and that seems to work. I expect this will be different for Unix (if the $editor environment variable is set it may not come up on Unix) …

46 Change “Click on the Netlist generation icon” to “Click on tools -> Generate Netlist File”
“Click on Netlist then” to “Pcbnew (default) press Generate then save”

47 change " click on the Run Cvpcb icon " to “click on tools -> Assign component footprint”

49 Add "click til you get “filtered by library” only in the bottom right window then click on the specified library in the left window (i.e. Housings for the IC1 footprint). then double click on the appropriate foot print in the right side window.

52 “File -> save as” to “File -> Save edits”

53 change “File ? Save Whole Schematic Project” to “File ? Save Schematic Project”

54/55 While they do no harm, there doesn’t appear to be any point to them either. Netlist doesn’t appear any where in the project manager and we are going back to Eeschema for the next step so why close it and go to project manager. Perhaps move the comment in 55 about the netlist being an editable text file back to step 52 and eliminate 54 and 55?

56 BOM is now in tools -> Generate Bill of Materials not on the tool bar as stated
The add plugins window opens in Kicad\bin to get to the .xls files you need to click on “scripting”
then “plugins” (neither of which is likely obvious to a newbie). As noted the plugins are in KiCad\bin\scripting\plugins\ not /usr/lib/kicad/plugins/ as stated and the file is thus:

xsltproc -o “%O” “C:\Program Files\KiCad\bin\scripting\plugins\bom2csv.xsl” “%I”

not xsltproc -o “%O.csv” “/home//kicad/eeschema/plugins/bom2csv.xsl” “%I”

3.2 Bus connections.

  We currently have the tutorial1 schematic open from the BOM step in 56 above. There is no 4 pin connector  present. I suspect this example was taken from somewhere else and it needs a schematic (probably other than tutorial1!) created to provide the necessary connectors to connect to the bus or to be only a example for information only (which should then be stated so as to not have changes made to the tutorial one schematic that will trip the user up later).

4.1
5
C:\Users\Owner\Documents\kicad\tutorial1\tutorial1.net shows in the file window, clicking the Browse button opens C:\Program Files\KiCad\bin\scripting\plugins rather than C:\Users\Owner\Documents\kicad\tutorial1\ which in turn has no .net files in it (presumably because the plugins directory was my last reference).
I don’t see how to fix this, but it is likely confusing to a newbie. Obviously they would need to navigate to the correct directory (or just use the one offered in the window, which perhaps is new functionality).

“Click on Read Current netlist then click close” is misleading. It needs to indicate to check the messages window for errors first, because In my case I had screwed up (because going back and verifying the footprints were added fixed it, even though I made no changes) and the message window looked like this (note as it is a unix \n only delimited file, notepad won’t read it properly and I had to use vi in cygwin, it may be an idea to suggest this for windows users in the tutorial as well):

Info: Reading netlist file “C:\Users\Owner\Documents\kicad\tutorial1\tutorial1.net”.
Info: Using references to match components and footprints.
Error: No footprint defined for component ‘R2’.
Error: No footprint defined for component ‘R1’.
Error: No footprint defined for component ‘IC1’.
Error: No footprint defined for component ‘D1’.
Error: No footprint defined for component ‘J1’

which would not have worked at the next step.

6 looks like all components are moved to the center of the screen by default now so this isn’t needed

8 Looks like “hide board ratsnest” button has become “display local ratsnest”

9 Initially I got my friend “clarify selection” when trying to move with “g” but moving out of the window (to notepad where I am documenting this) and then clicking on the tool bar to select the window again, I can now use “g” to move components without the clarify selection window coming up. Confusing to say the least! Documenting how to turn “clarify selection” on and off would be useful (probably early in the tutorial) since I don’t know what I’m doing to invoce it.

11 “Select edge cuts” needs to add “(beteen perform design rules check and show active layer selections)” (preferably with their respective icons) on the tool bar. It was not obvious to me for quite some time what drop down menu you were referring to until I looked at the next screen shot, as a blank rectangle doesn’t appear to be a drop down menu, although in this case it is. As well a screen shot of the finished outline would be useful to know if I had done it correctly. Reminding the user that a double click will terminate the line wouldn’t be a bad bet either.

16 This doesn’t work as stated. An error box saying “Extra Track1 size 0.0100 < min track size” comes up, I assume because the sizes are in mm. I note there is a (inches) at the end of the line. I assume this means the table is intended to be in inches not mm. However there is nothing to tell the newbie how to change from mm to inches here so either that needs to be added (clicking on “in” in the left tool bar did it for me for instance) or the table changed to mm.

19 when the first track is added the rats nest disappears and clicking “display local ratsnest” doesn’t bring it back. In this case with a drawing to refer to that isn’t a problem, and starting a wire on a pin brings up the rats nest for that pin, but it makes it difficult to see when you have connected all the pins.

22 Doesn’t appear to work. With B Cu layer selected, click on Add zones and click on one corner of the board edge rectangle. No dialog box occurs and nothing appears to happen. Moving to the next edge and clicking also causes no change.
This one has me currently stopped until some good person here tells me what I’m doing wrong, because I don’t know how to get the ground plane to place.

22 (cont) found my problem. I was clicking on the left hand icon which is identical (except in function) to the right hand icon I should have been using. So back to noting issues.

“pad in zone” appears to be “pad connections” now
“zone edges” appears to be “outline slope”
and needs to change from “arbitrary” to “H, V, and 45 deg only”
OK brings up a “no layer selected” error box so more is obviously needed.
clicked on gnd in net (which highlighted probably incorrectly!) and then on B.Cu in Layer on the top left which is probably the correct thing to do.then the refill all zones worked.

4.2

2 browse brings up the default tutorial1 directory but OK raises a dialog box “Do you want to use a path relative to C:\Users\Owner\Documents\kicad\tutorial1” to which I replied no. An explaination of why or why not that was correct would be useful here for a newbie. I happen to like fully qualified path names but there may be a good reason to have a relative one in this or some case that I don’t know.
That said, the last layer loaded is the only one I can see. Clicking on the right hand menu doesn’t change layers for me (nor does anything else I’ve tried). Ah, right click on the on the
right hand Visibles menu and a dialog box comes up with default “show all layers”. Clicking on
“hide all layers but active” does what is desired (and should be documented here). Looks like
it is a two step procedure. I have to change the layer in the pull down menu on the tool bar then
right click in Visibles and select “hide all layers but active” to get it to change.

3 by default F.Cu, B.Cu, B.SilkS, F.ClikS, B.Mask, F.Mask were selected (foolishly I made changes before thinking and I’m pretty sure it has remembered at least some of my changes even though I canceled and restarted, for instance Edge.Cuts is selected, but I’m pretty sure it wasn’t initially).
The question is: is the suggested layer selection still valid? It looks so to me (for instance I don’t think bottom layer silk screens are common, but I could be wrong). Someone knowlegable should probably check the advise is still current.
With that I’m far enough to try a real (if simple) board before looking at autorouting, so I’ll cease bothering you for a while and someone in a private email has pointed me at the documentation folks URL as a more appropriate place for this…

Can I humbly suggest keep posting here in this thread? As well as notifying the documentation folks? I mean, you are doing wonderful work (christ what a mess of a “getting started” guide" lolz)… but who knows how long it will take for the “documentation folks” to implement your hard work into the guide? At least here us trainees have something we can lean on.

There may be some hope for updates as the person that sent me the private message indicated
he may add some of my updates. Apparantly you have to make (split off a fork?) a github repository,
then install and learn to use the document formater to change the document then push(?) your changes which will then be reviewed by the document maintainer. Looks to be more work than I want to get in to at the moment. The mismash above was as simple as open notepad and make notes as I hit issues then post them here in the hope that they would be useful to someone, i not the documentation folks then perhaps to the next new user that hits some of the same problems and looks to the forums. This was more or less a one time thing as the first time through everything is new and I noticed all the inconsistancies. It was not a lot of work (although not zero either) and hopefully will be useful to someone else (although the format is horrible because I expected it to be for a document maintainer familiar with both Kicad and the document, not as the documentation!), if not the document maintainers then perhaps to some other newbie that runs across the same problems I did. Being a Kicad user for all of three or four days, I doubt I’m qualified to update the documents. A number of the issues I hit need some one familiar with Kicad to tell us how it should be done (and that certainly isn’t me :slight_smile:

Peter Van Epp

[quote=“Andy_P, post:47, topic:1463”]
He can also work on the documentation himself, and submit patches, which I’m sure the documentation maintainers will appreciate.
[/quote]I’d like to reply to this frequently expressed advice / sentiment for newbs to “get involved”. Speaking as a newb myself, and running into similar difficulties with incomplete or (worse) erroneous documentation, it’s my opinion that this is well-intentioned perhaps, but nevertheless misplaced advice. If I am going through “Getting Started with KiCAD” it should be fairly obvious that I have no idea if my difficulties are actually with the program, the document, or my own faulty understanding of the concepts being communicated. It’s frustrating to spend a significant chunk of time attempting to understand a problem, and being casually told by some more experienced person, “Oh, yeah, the docs are incorrect… Why don’t you fix it!” Comes across as lazy or arrogant at best. I’m still trying to learn the program, and now I have to:
(1) Sign up for a developer account with GitHub.
(2) Learn to use GitHub, including learning abstruse terminology like forking, pull request, and the like, and (presumably) gain some understanding for their ramifications in the specific context of the KiCAD project
(3) Learn to use the “Document formatter”
(4) Make edits to documents to fix something that may only be an artifact of my own incomplete and uninformed understanding of a massive, complex program that I have all of 3 days experience with.
(5) After all this, I can submit my (quite possibly completely incorrect) changes, which will then:
(6) Be reviewed by the person who (presumably a volunteer) is responsible for maintenance of the document, who will then:
(7) approve (or deny) the changes.

This is quite a lot to ask of someone who:
(A) Is just trying to see if this program is actually as useful as it purports to be
(B) Is still (presumably) devoting his maximum effort and time to LEARN the program

Seems to me that Mr vanepp has done quite a bit more than a lot of folks would do in his circumstances, and in fact, I was following a similar path myself, after “Getting Started in KiCAD” blew up on me as well. I have similar objections to him at this attitude commonly echoed on “Open Source” program forums. It is in fact a totally reasonable request to make of someone who has:
(A) Learned to use KiCAD
(B) Loves KiCAD and wants to make sure it gets a wide a dissemination as possible
© Has overcome the difficulties in the documentation himself and has sufficient insight and understanding to suggest whether the document should be amended, and how.
(D) Has enough available time and resources to meet all the additional requirements to be a document maintainer (see above list)

In short, it is quite possible that the person making this suggestion to the complete newb, is in fact probably much better placed to do all these things, and the community (and the KiCAD project) would be better served for him to take his own advice, if he (presumably) knows so much about it.

I think that the best thing one can make to newb who is struggling with a mistake in the documentation is to facilitate the corrections to the document by either:
(A) Facilitate the newb’s communications with someone who is actively involved in maintaining the docs (presumably someone is doing this, or else who is reviewing the proposed edits?) with a link, or a PM with an email address, etc.
…OR…
(B) In the spirit of Open Source, with your greater insight and understanding of the project, help them with whatever their issue is, and pass an appropriate suggestion along to either the document team, or file a bug report, etc. for them.
…AND…
Save your “Just Fix It Yourself! It’s OPEN SOURCE!!” exhortations for someone who already knows the program well enough to know if he’s just making a newb mistake, and is hence more qualified to actually make the corrections.

This was a very dormant thread. Tutorials should be for the stable release and are best written by a user of that version. Therefore the developers are the worst people to do so.
General users with a few boards of experience on stable are best placed and can really help the project by contributing to all documentation. Some extra translations would be nice too

Since this thread the documentation has in fact been updated, so somebody “up there” is helping us out, and thank you! I’m not sure how much revision will be required for Kicad 5?

There’s actually quite a few learning resources for Kicad noobs now, we’re fortunate. I do agree it can help to follow a fellow noob’s learning journey via a blog or something.

1 Like

mollux, andy_p, vanepp:
Noob here - I spent >8hrs yesterday ATTEMPTING to get thru the Getting Started doc. What a mistake. Fortunately I stumbled onto this thread and was relieved to discover that I was neither “special” nor stupid.

I was however, EXTREMELY dismayed (I’d use some other term, but there might be some young impressionable eyes here) to find that these issues are OVER 3 YEARS old and not resolved. Even worse -probably not even seriously addressed.

It’s just my opinion, but, the Getting Started doc. should AT LEAST come with a dire warning regarding it current state.

To each of the issues that you (all) have raised, I can only offer an Amen Brother.

-JustAnutterNube-

Take a look at the FAQ section of this forum for additional help: (Start Here) Frequently Asked Questions

And remember that a lot of people who would help out with documentation are currently holding back as v5.1 is very near. v5.1 will bring a lot of updates to the user interface which means documenting v5 does not really make much sense at this point in time.
(Even some of my FAQ tutorials are already made for v5.1. These sections are however clearly marked so you should be good to go.)

I have been going through the Getting Started document, updating it for the upcoming 5.1. I’m just another volunteer and it requires inspiration. I have hoped to get it ready for 5.1 release but don’t promise anything. I waste my time with many things, KiCad is only one of them.

2 Likes