BTW place footprint plugin supports also circular placement
Understand!!
I have an explanation in the tutorial about how the method you implemented provides additional flexibility.
On the installation part of the tutorial… I did it on Windows 10. Is it useful to include that process?
I see someone posted a video tutorial on the plugin just yesterday:
Video tutorial on replicate_layout
I haven’t watched it–for some reason it just hangs after a few seconds. I have a gigabit internet connection an other YouTube videos play fine, so I don’t know what’s up with that.
If it’s good, I’m not interested in doing another, unless the author MitahJ specifically requests it. (I have no incentive for people to visit my YouTube page, was just trying to “give back”)
I don’t mind finishing up the written version, if you still think it might be useful.
Got the video tutorial to play.
The video tutorial didn’t explain the concept of the anchor footprint and the flexibility it provides to automatically update PLACED layouts when changes are made.
Maybe the YouTube author will read this and update his tutorial in the next couple of days. If not, I’ll do one.
I uploaded a first draft (pdf) of a writeup. Feedback is welcome–maybe I should add a section crediting the author.
replicate_layout.pdf (240.5 KB)
At this point, I’d reference a video tutorial. First showing the example “multiple_hierarchy”, but with a simple resistor network in Leg.sch. Then, I would add the “sensor.sch” sheets in the Leg.sch to highlight the ability to handle multiple levels of hierarchy.
2 Likes
This is good. If you are willing I can give you a write access to my github repo and you can enter this in the wiki (which I’ve just started to setup).
As for the video I concur that the referenced one (while good first attempt) skips on the important concepts and is not really what I would confortable sharing (but my standards might be too high). So for time being I’d rather focus on writen documentation. Thanks for the effort.
1 Like
This evening I’ve experimented with this replicate layout script.
I have never used, nor even installed any script in KiCad before, and therefore I consider myself an excellent newbie for commenting on the usability of the draft of this PDF tutorial.
So I used the pdf as a guide to replicate some simple circuit and typed notes here as I went along, and afterwards read through these notes again for a bit of a cleanup.
I’m using Linux Mint 19.3, so if it also works there, you can add it to your mention of windows…
Introduction:
I would split this in 2 sections.
- “What does it do”.
- “How does it do it”. with an outline of the general flow, which is as far as I know now:
- Create hierarchical schematic.
- Flat base sheet? with (single layer?) sub hierarchy? (I do not know of more advanced methods to use the script (yet).
- Make a layout of one of the sub sheets.
- Place one “Reference” component for each sub sheet to be replicated.
- Select / highlight the "Reference* Footprint of the subsheet which has been layed out / routed.
- Invoke the script. It will replicate chosen parts (screenshot!) of the reference sheet to the corresponding parts of the other sheets, using the Footprint that is highlighted when the script is invoked as references for location and rotation of Footprints, Tracks and other items from the duplicated hierarchical sheets.
If this is added to the introduction, readers have an overview of how it works and further reading will then fill in gaps. Without it, you’re on a journey though mist and details are harder to put in their place.
How is the PDF generated? Does it use asciidoc or similar?
I’m missing chapter numbering, which can also be generated by asciidoc. I assume the sources will find a place on gitlab somewhere…
I can see this document growing into a collection of description for different scripts.
Myself I’m trying to update “Getting started in KiCad” for KiCad V5, but after I did something stupid and crashed my PC and had to re-install Linux I have some trouble in compiling the Asciidoc from the official documentation in 15 languages and at least 3 formats (ePUB, HTML, PDF, …). It seems quite nicely set up, just haven’t dived into it yet.
Before installing: KiCad scripting is not always supported. There is a setting in the version info “Kicad / Help / About Kicad / Show Version Info” . I currently seem to have support for scripting, but you may want to check this first before installing.
Build settings:
…
KICAD_SCRIPTING=ON
KICAD_SCRIPTING_MODULES=ON
KICAD_SCRIPTING_PYTHON3=ON
KICAD_SCRIPTING_WXPYTHON=ON
…
This just works, no need to browse to github (gosh, almost typed gitlab).
paul@dualcore:~/projects/kicad$ git clone https://github.com/MitjaNemec/Kicad_action_plugins
Cloning into ‘Kicad_action_plugins’…
remote: Enumerating objects: 383, done.
remote: Counting objects: 100% (383/383), done.
remote: Compressing objects: 100% (230/230), done.
remote: Total 2679 (delta 251), reused 242 (delta 129), pack-reused 2296
Receiving objects: 100% (2679/2679), 20.54 MiB | 1.28 MiB/s, done.
Resolving deltas: 100% (1857/1857), done.
Location for the plugins… On my first guess, it’s where the Footprint Wizards are already installed:
paul@dualcore:~$ ls -hl /usr/share/kicad/scripting/plugins/
total 172K
-rwxr-xr-x 1 root root 6,0K Mar 27 14:36 bga_wizard.py
-rwxr-xr-x 1 root root 4,8K Mar 27 14:36 circular_pad_array_wizard.py
-rwxr-xr-x 1 root root 28K Mar 27 14:36 FootprintWizardBase.py
-rwxr-xr-x 1 root root 6,6K Mar 27 14:36 FPC_wizard.py
-rwxr-xr-x 1 root root 1 Mar 27 14:36 init.py
-rwxr-xr-x 1 root root 25K Mar 27 14:36 kicad_qrcode.py
-rwxr-xr-x 1 root root 7,8K Mar 27 14:36 microMatch_connectors.py
-rwxr-xr-x 1 root root 14K Mar 27 14:36 PadArray.py
-rwxr-xr-x 1 root root 8,7K Mar 27 14:36 qfn_wizard.py
-rwxr-xr-x 1 root root 6,3K Mar 27 14:36 qfp_wizard.py
-rwxr-xr-x 1 root root 7,7K Mar 27 14:36 qrcode_footprint_wizard.py
-rwxr-xr-x 1 root root 8,8K Mar 27 14:36 sdip_wizard.py
-rwxr-xr-x 1 root root 7,6K Mar 27 14:36 touch_slider_wizard.py
-rwxr-xr-x 1 root root 6,1K Mar 27 14:36 uss39_barcode.py
-rwxr-xr-x 1 root root 6,7K Mar 27 14:36 zip_wizard.py
There is another location which has BOM and Netlist scripts:
paul@dualcore:~$ ls -hl /usr/share/kicad/plugins/
total 100K
-rw-r–r-- 1 root root 3,7K Mar 27 14:36 bom2csv.xsl
-rw-r–r-- 1 root root 4,0K Mar 27 14:36 bom2grouped_csv.xsl
-rw-r–r-- 1 root root 5,7K Mar 27 14:36 bom_csv_grouped_by_value.py
-rw-r–r-- 1 root root 2,2K Mar 27 14:36 bom_csv_grouped_by_value_with_fp.py
-rw-r–r-- 1 root root 2,0K Mar 27 14:36 bom_csv_sorted_by_ref.py
-rw-r–r-- 1 root root 3,0K Mar 27 14:36 bom_html_grouped_by_value.py
-rw-r–r-- 1 root root 4,3K Mar 27 14:36 bom_html_with_advanced_grouping.py
-rw-r–r-- 1 root root 2,0K Mar 27 14:36 bom_sorted_by_ref.py
-rw-r–r-- 1 root root 5,9K Mar 27 14:36 bom_with_title_block_2_csv.xsl
-rw-r–r-- 1 root root 26K Mar 27 14:36 kicad_netlist_reader.py
-rw-r–r-- 1 root root 4,0K Mar 27 14:36 netlist_form_cadstar-RINF.xsl
-rw-r–r-- 1 root root 3,8K Mar 27 14:36 netlist_form_cadstar.xsl
-rw-r–r-- 1 root root 6,7K Mar 27 14:36 netlist_form_OrcadPcb2.xsl
-rw-r–r-- 1 root root 2,0K Mar 27 14:36 netlist_form_pads-pcb.asc.xsl
-rw-r–r-- 1 root root 1,2K Mar 27 14:36 README-bom.txt
So my first task is to figure out what the right location for these scripts is on Linux. Scripting in KiCad, how does that work?
file:///usr/share/doc/kicad/help/en/pcbnew.html#_kicad_scripting_reference
Not really related, but chapter: “17.3 Footprint Wizards” an alternative location of “$HOME/.kicad_plugins.” is mentioned.
I think I would prefer: "$HOME/.config/kicad/plugins/ " The KiCad directory already exists, and dumping
more in “$HOME” used to be common I think, but I’d rather keep ~ less cluttered.
So https://github.com/MitjaNemec/Kicad_action_plugins suggests to use:
“~/.kicad/scripting/plugins/” as a location for Mint. I did this and it works for me.
Is this the same, or an older version of the same script?
https://kicad.mmccoo.com/2017/02/01/replicating-pcbnew-new-for-arrayed-sheets/
I may have seen that site before, not sure. Seems to have some nice info on scripting.
Always struggling with copy stuff, but now I have:
paul@dualcore:~$ ls -hl .kicad/scripting/plugins/replicate_layout/
total 188K
-rw-rw-r-- 1 paul paul 17K Apr 2 19:57 action_replicate_layout.py
-rw-rw-r-- 1 paul paul 4,6K Apr 2 19:57 compare_boards.py
-rw-rw-r-- 1 paul paul 2,6K Apr 2 19:57 duplicate-replicate_layout.svg
-rw-rw-r-- 1 paul paul 371 Apr 2 19:57 duplicate-replicate_layout.svg.png
-rw-rw-r-- 1 paul paul 526 Apr 2 19:57 init.py
drwxrwxr-x 2 paul paul 4,0K Apr 2 20:36 multiple_hierarchy
-rw-rw-r-- 1 paul paul 1,7K Apr 2 19:57 no_wxpython.py
-rw-rw-r-- 1 paul paul 8,3K Apr 2 19:57 remove_duplicates.py
-rw-rw-r-- 1 paul paul 64K Apr 2 19:57 replicate_layout_GUI.fbp
-rw-rw-r-- 1 paul paul 4,3K Apr 2 19:57 replicate_layout_GUI.py
-rw-rw-r-- 1 paul paul 51K Apr 2 19:57 replicatelayout.py
-rw-rw-r-- 1 paul paul 4 Apr 2 19:57 version.txt
Before going further with creating hierarchical sheets etc, first:
Pcbnew / Tools / External Plugins / Refresh Plugins
Pcbnew / Tools / External Plugins
Yes, works for me. Replicate is now there. Installation done, time for next chapter.
About the screenshot with the hierarchical sheets. This could be improved. Showing part of that other progam with “size” “color 1” “color 2” obfuscates the screenshot. There is a bit of an art to good screenshots. It generally helps to make the screenshots from a whole window, but first make that window small, or else it gets scaled too much and text gets very small. But still everything has to fit. In this case it would mean making the hierarchical sheets smaller. Also, the “power.sch” in the screenshot makes it bigger then it needs to be. Screenshots are not only for making the document more attractive and easier to read. They are also reference points for people glancing through the document to find certain subjects quick. Each significant part should have a screenshot: Working with Hierarchical overview, a hierarchical subsheet. Component placement in Pcbnew, and more. Some balance has to be found.
I made a KiCad project of an imaginary USB hub.
It’s an easy recognizable item, and having a project helps with explaining concepts. The project is attached to this post for a number of reasons:
- Making additional screenshots. (For example for translators of the pdf).
- It is explicitly designed to make compact screenshots.
- People who want to experiment with the script, but have no project at hand.
Entering hierarchical sheet Properties is a nice opportunity to throw in some graphics to make the tutorial look more attractive:
I have no experience (yet) with Replicate Layout. I assume it is important that the hierarchical sheet only has components that have to be replicated. This is not immediately clear from the pdf.
Tutorial is about the replicate layout, not about hierarchical sheets.
A pointer to the manual part for working with hierarchical sheets would be nice, and avoid duplicating explaining how hierarchical sheets work.
Eeschema / Help / Eeschema Manual …
file:///usr/share/doc/kicad/help/en/eeschema.html#hierarchical-schematics
My fictional circuit to be replicated. I do not know whether 22 Ohm is right for USB, I vaguely remember I saw it somewhere…
See: Screenshot of a small window gives big text for the documentation. The forum scales it to > 100% which is not optimal, but will do for now.
There is no mention of annotation in the pdf. Is there anything significant to it? Probably not, but even then it should be mentioned.
I did annotation with “First free after sheet number X 100” Probably not important, but it helps in keeping me sane by separating the sheets by RefDes. It’s also a feature not everybody is familiar with and remembering them helps them to learn.
After assigning Footprints, [F8] to Pcbnew with no errors. Gosh, I like the way Footprints are already grouped by sheet. That’s worth a Screenshot.
So now, finally, the preparation is done. It took me 3 hours to get here. Yet another reason to put this as a “testcase” on github, for a quick start for someone just wanting to experiment with the Replicate Layout script. Maybe Mitja already has something similar on github / gitlab (I don’t like github anymore, they sold out to M$. Also, if this Tutorial has aspirations to become part of official documentation, gitlab is also a better place.
Just to avoid confusion, I renamed 2 of the hierarchical sheets to “Output_200” and “Output_300”, to be in line with the current RefDes assignments. Did not bother to rename the rest. Let’s see what happens.
The order in which to do things was a bit fuzzy here to me. Terms like “anchor footprint” and “source instance sheet” confuse me. It is easier to understand if written like:
Replicating a Layout consists of a few simple steps.
- First we place one of the USB connectors of each sub sheet on the PCB. These will later be used as anchor points for relative positions for the other components.
- Next step is to place all the parts of one of the Hierarchical sub-sheets on the PCB, and this layout will be used as a template for corresponding components of the other sheets.
- 3rd step. Select the Footprint that is to be used as an anchorpoint and then invoke the script.
Using the USB connector as a physical component to relate to helps in generating understanding. It’s a lot easier then talking in abstract wordings. Fully annotated schematic with screenshots also makes writing documentation more concrete. You can talk about “Use Output_200” sheet as the template, Place Connector J201, etc.
This is also the core of the whole tutorial. Each step deserves a screenshot.
Ah, so now I’ve run the script a few times.
I must say, I’m very impressed with the script. It especially starts to be a time saver if stuff gets edited after the inital layout. This happens all the time. EMI filtering is added, component sizes change, Connectors become obsolete and have to be replaced etc. (Hmmm, also put this in the introduction?)
It was fun experimenting with this script and helping to get some documentation going.
Without the PDF I would not have found the motivation to experiment with KiCad scripting, and in overview it was enough to get it done. The only trouble I had was with finding the right location to put the script. Now I know it works I am sort of curious to the other scripts…
Finally, here is the project I created to try this plugin. Use or abuse it in any way fit / unfit or possible including, but not limited to becoming a Billionaire.
Replicate_Layout_2020-04-03T01:11.zip (42.6 KB)
1 Like
Is that because of the detailed notes and thinking about how the write-up should be. Or, are you saying it actually took you 3 hours to figure out how to do it?
If the latter, what was the confusion?
I used Microsoft Word and then just saved as a pdf. I can easily add page numbers. Or, if you just want the raw text to add to some other tool, I can send that instead.
Flat base sheet? with (single layer?) sub hierarchy? (I do not know of more advanced methods to use the script (yet).
I’m a newbie. I don’t even know what layers are in a schematic. Yes, you can have sub-hierarchy, buy my suggestion is to keep the first example as absolutely simple as possible. Once you get through the simplest usage, THEN go through something more complicated.
I disagree that we should do a layout as part of the tutorial–maybe that’s not what you were suggesting. Just have the sheets already created. As you indicated, this is NOT a tutorial on how to do hierarchical sheets–they are just the means for identify what to repicate.
Not sure if I need to have anything in the document for “Build Settings”. Is that something a user should worry about, or is KiCad now always built that way? (I didn’t have to set anything on WIndows 10 with the recent version of Kicad.
Same story about your notes about where the location should be. Is that just a note, or a comment of where the plugin should be located.
Are you saying $HOME is an environment variable guaranteed to be set in Kicad environment. If this is really that hard, then how about a simple, platform independent install script?
I had the wide screenshot just so the pop-up help for the create hierarchical sheet was up. I could easily edit the screen shot to eliminate the obfuscation.
My experience is that too many screen shots discourages many to complete a tutorial. I’d suggest doin a run through with minimal screen shots, then follow with a something showing some additional feature (like multi-hierarchy). Then, include all the screenshots. They are there for reference if someone gets stuck due to lack of the detail (like I did) on the “quick start” version.
I was asked to use the project that’s already part of the github repository for replicate_layout. You guys decide what you want to use, and I can do that.
No, there is nothing significant about annotation. Same as anything else.
It took me 3 hours because of a little quirck in my head. I have difficulty swithing context. Any Context, so switching between reading the pdf document, making a test project, writing response, and doing that multiple times including time for formulating and switching makes it difficult for me. It also took me some time to figure out where to put the scripts on my Linux Box. Your PDF writeup was good and the plugin script worked flawlessly.
Ah, word…
Quite a substantial amount of KiCad’s documentation is old. Some parts were made for KiCad V4. PDF files are hard to edit.
Documentation is not only about making a good writeup, but also about having the tools to change the documentation, when updates need to be made. Same for translators. Most of KiCad’s documentation has been translated into some 10+ languages. The translators need access to the project from which the screenshots were made, to make similar screenshots, but with menu texts etc in their language. I also did not do my own homework well. Later I saw on Mitja’s page on github that you used the same project for your screenshots.
About the $HOME stuff… Just add to your pdf that Linux users can put these scripts in: “~/.kicad/scripting/plugins/” (including the tilde and the dot before kicad (It’s a linux thing). “~” is just a sort of shortcut / alternative name for $HOME.
I probably diverged too much on some places, result of my fuzzy mind, and why it took me 3 hours to get that far.
About the Hierarchical stuff. I fully agree to keep the first example simple. More complicated examples later, maybe even added by other people, (and they will need access to the documents the pdf was created with!)
This seems to be a misunderstanding. I just had to do some layout of tracks to have something for the script to work with.
The “Build Settings” are in KiCad’s about box. It is just a place where you can see if scripting is enabled for your version of KiCad. (This is not true for everybody).
About the screenshots… Some balance has to be made.
I saw that too late, or I probably would have used Mitja’s project to try the script.
I know that now, but it’s good to put that in your pdf. I did not know it at the moment I needed to do the annotation, because I had not used the script yet! (And using the 100x numbering helps with separating the parts, you instinctly know that R401 and R501 are equivalent parts from different sheets.)
I’m a very long time Linux developer (and Windows, and about anything else that’s been around).
Is that really the right place? Many Linux applications look first in a place that all users will have read access, and only use the user specfic configuration file (like ~/.myspecial hidden directory).
What you suggested makes sense for single user platform (“~/.kicad/scripting/plugins/” ), but maybe not for a “global” install.
It’s not unusual to have servers to have multiple users with dedicated administrative staff. Tool users never want to worry about installation details–just have the admin handle it. And, they wouldn’t want to touch user’s home directories for something like this.
I don’t want to debate where things should be installed on various systems. I’m not “signing up” for that. It can get complicated, to cover all platforms, single user, multiple users, etc. That’s why I made the example for Windows and just indicated “this is what worked for me on Windows”.
Sorry, I don’t know the KiCad players Maybe you are a Kicad developer (maybe even a lead developer) and understand where everything should be installed versus just finding a place that works (like me). Hopefully, something has been well thought out and I just don’t know it.
I suggest all the “where it goes” on this platform versus another platform versus single user, all users needs to kept out of this tutorial. That should be in something like a configure script, or one of the several great open source tools for this purpose.
I’ll get a second draft out this weekend.
Thanks!
And, for now, I have no problem add "Linux users can put these scripts in: “~/.kicad/scripting/plugins/”
PDF is just an output format. Probably the most portable around, but it’s not a good choice for the source of the documenation.
Pretty much any decent tool has an option for writing a pdf. Flat text is fine for command line help, readme, etc, but I was thinking the target viewer would be a web browser. But, it really doesn’t matter to me. I could probably get into about anything you want without much trouble, if you don’t just want the text.
So, what tool do you want to be used for documentation?
And, to be clear. I don’t know of ANY developer who would rather write code than document it. Not that I like it, I was just doing what was asked…
I don’t know if it’s a good idea to include very detailed plugin installations directions for one plugin. Then it should be replicated (not sorry for the pun) for every plugin which has instructions. I’d rather have one good common document for installation and refer to it.
KiCad looks in several places when it tries to find all plugins. They can be installed for the global installation or for one user, and the exact instructions depend on the platform. That’s one reason to not include detailed installations instructions - are you going to write longer section for installation than for using the plugin?
For me the first step: downloading the plugins was a breeze. Just a “git clone …”.
Just finding a place where to put the plugin was half an hour or maybe more work. I found at least 4 different places where KiCad does something with plugins or scripting. For me it was the first time ever I tried to use a script in KiCad.
I have at least:
/usr/share/kicad/plugins # This has BOM and netlist scripts.
/usr/share/kicad/scripting/plugins # This has the Footprint Wizards.
In the PCB User manual: file:///usr/share/doc/kicad/help/en/pcbnew.html#_kicad_scripting_reference I found:
On linux you can also keep your user plugins in $HOME/.kicad_plugins.
I also found some configuration files (but no scripts) in:
~/.config/kicad/
Certainly, but I do not know the place for a global install for these scripts in Linux. At the time I just wanted to focus on just getting the thing to work, and comment on the pdf draft.
I still don’t know what would be the “best” place. I was just happy I found a place that worked.
Agree, such detailed descriptions should be in the Pcbnew user manual, inclusive an overview of which scripts go where. That document is vague in this regard. A single line as a suggestion to where this script can be placed (even for a single user) seems a good Idea to me, so he can move on and focus on getting the script to work.
Also: Why are there 3 locations for KiCad stuff in the user directory?
~/.config/kicad
~/.kicad/scripting/plugins
~/.kicadplugins
This was one aspect of why I wrote the plugin and documentation. Before me there were three solutions to this problem. But none of them were actively supported, they didn’t have a GUI (you had to run a script within pcbnew python console) and their documentation was even worse than mine.
This is a really nice example how difficult is to write the documentation properly. Either you write it for experts, so you skip on basic issues (installation details, basic concepts). Or you write it for beginners so you might be to verbose for more knowledgeable user. It is hard to write balanced documentation, even more so as a developer because you are (or should be) an expert and it is hard to put yourself in the shoes of a beginner. So the more I think the more I see the validity of @Dave_Thomas’s remark. I’ll need to bite the bullet and write the documentation for two (or even more) cases. Simple and expert (and maybe intermediate).
As for installation instruction the ones published by Qu1ck in his InterractiveHtmlBom wiki are the best ones I’ve seen. I should put a link to them.
I do appreciate the discussion and experiences shared, but I currently lack the time to participate as much as I’d like to and I can not really process everything.
Just had a quick look at the Qu1ck’s InteractiveHTMLBom Wiki and then opened: Pcbnew / Tools / Scripting Console and pasted his 2 lines of code in it. The result is:
import pcbnew print(pcbnew.PLUGIN_DIRECTORIES_SEARCH)/usr/share/kicad/scripting
/usr/share/kicad/scripting/plugins
/usr/share/kicad/scripting
/usr/share/kicad/scripting/plugins
/home/paul/.config/kicad/scripting
/home/paul/.config/kicad/scripting/plugins
/home/paul/.kicad_plugins
/home/paul/.kicad/scripting
/home/paul/.kicad/scripting/plugins
(Yes, some directories are listed twice, I don’t know why).
It also does not explain which sort of plugins should go where.
Edit: I did a bit of reading in:
and in the source code of the Replicate Layout plugin itself.
If I understand it correct, then KiCad just executes all plugins found in all plugin directories, and the plugins register themselves into the right location in KiCad. So any compatible location should work.
Usually the way it would work is that the /usr/shar/kicad directories would be sufficient for all users without then need in someplace like /home/paul.
The /home/paul/.config and /home/paul.kicad would only be used if the user wanted to override something in the /usr/share place.
Not saying that’s the way Kicad works–just the way most *nix applications work.
Anyway, I think for the purpose of this writeup should not be able how to install plugins. Documented at that location.