Need help using replicate_layout plugin

If you do, I’d appreciate it if you look at the project which comes with the plugin.
Can you help me find it? The pcb file in the gif file seems to replicate_layout/referfence multiple_hierarchy/multiple_hierarch… Is that what I should use?

BTW did the animated gif pass any valuable information to you when you started with the plugin?

I must have watched that gif 100 times over the course of a couple of hours.

First, it was too fast I couldn’t figure out how to slow it down. Then, I fixated on not seeing my top level sheet–I should have realized the only reason the hierarchy showed up in your example was that there were 2 levels of hierarchy.

Personally, I think it would be better to keep the example as simple as possible. Using for deeper levels of hierarchy is nice, but that complicates things. I’d have it as a second example.

I guess ideally you’d have both.

If you include text for every mouse action, it gets long and virtually unreadable fast–(been there, done that!).

But, if you have a video where every mouse click is clearly indicated (automatically), it’s easy to watch the video for the big picture, then go back and pause it where needed.

This example isn’t that complicated, so I can probably find time this week to do both.

Thanks for the feedback. I appreciate it.

Perfect, this is the precise user experience that I wanted to hear. And looking back, it used to be the simple case at the start. But then I expanded the plugin functionality along with documentation (if you can call it that). So I forgot about basic users. This is really the slap on the face I needed to bring me down a bit.

And to toot on my own horn a bit, I’ve recently heard that Altium rooms feature does not support hierarchy, so we’re step ahead here.

As I’m starting to write a mini “tutorial”, I thought of something that might make it more intuitive for many users.

My expectation was to simply supply a delta X and delta Y along with the source sheet and target sheet(s).

What you’ve implemented is more flexible, since the replicates need not be equally spaced. But, I bet a large majority of users want the replicas equally spaced linearly or in a matrix.

Certainly once you’ve used the plugin with the anchor footprint, it’s super easy to use. Just different than my expectations. So, having an option for evenly spaced replicas with a dx, dy input might be easier for users to use the first time.

I’m happy with it as is, but it is a bit different than I’ve used before (albeit, with additional flexibility).

Well the plugin used to work exactly as you specified. But I’ve split the placement functionality into separate plugin (Place footprints) for flexibility obviously. And while I totally agree that the described behavior would be easier for beginner, but there is nothing I can do about it (besides making and supporting a simplified version of the plugin).

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.

  1. “What does it do”.
  2. “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:

image

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…
image
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.
image

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…