KiCad 9.0.0-RC1 Python API

One of the new features of KiCad 9 is its python API. Since the first release candidate was published a few days ago, I wanted to give it a try by updating our coil generator addon from the python SWIG bindings to the API calls. But I’m a bit lost on where to start.

I assumed that this API is bundled within KiCad itself and I can just use it in python. But when I try to follow a simple example like this:

from kipy import KiCad

It breaks because kipy is unknown. The documentation says that I have to install the kipy package. While this makes sense, this sounds counter intuitive as this would mean that every user that tries to use the plugin has to first install a package.

Additionally the documentation mentions that the user can enable the python API in the settings. But this comes with an additional step that most users probably won’t do. Moreover, this needs the user to manually select the python runtime, even though it is already shipped with KiCad.

This whole API project looks like a library useful for CI implementations and so on, but not really useful for plugins that are listed in KiCad’s plugin manager. I’m not sure if I’m missing something here or if I misunderstood the whole point of the API. My assumption was that it was intended to replace the SWIG bindings.

Presumably kipy will also be released via pip then any plugin requiring it would specify that and have it pulled in as a dependency, no different from other Python package dependencies.

It is already released via pip.

But wait - there is a way to define dependencies? I’ve always assumed that there is no way to do that since KiKit for example requires the user to manually install the dependency.

I took a look at the examples again and I’ve noticed that there is now a requirements file. I will give it a try!

I switched to the new plugin style with the plugin.json. Something doesn’t work and the error is not that helpful. Maybe this is a useful feedback for the devs:

image

I figured it out, but it seems like a bug to me. The identifier was set to "identifier": "com.github.DIaLOGIKa-GmbH.kicad-coil-creator", which didn’t match the folder name in my dev environment. I’d have expected this to not matter since the plugin.json is INSIDE the folder where the issue came from.

I’m unable to get it to work. I struggle to get the plugin to load at all. And since KiCad gives no feedback I don’t know where the issue is. I think I have done it the same way it was done it the examples, but I don’t see the icon in the toolbar.

KiCad detects my addon. I can see that because a wrong identifier triggers an error. With the correct identifier nothing happens. Nothing shows up in KiCad and I have no real way of debugging it. What I did:

Created a requirements.txt in the coilgen plugin root folder

kicad-python>=0.1.0
wxPython~=4.2

Created a plugin.json in the coilgen plugin root folder

{
    "identifier": "coilgen",
    "name": "PCB Coil Generator",
    "description": "Generates ...",
    "runtime": {
        "type": "python",
        "min_version": "3.11"
    },
    "actions": [
        {
            "identifier": "coilgen",
            "name": "PCB Coil Generator",
            "description": "Generates ...",
            "show-button": true,
            "scopes": [
                "pcb"
            ],
            "entrypoint": "coilgen.py",
            "icons-light": [
                "icon.png"
            ]
        }
    ]
}

Replaced the old plugin init with the new way

old __init__.py:

try:
	from .plugin import Plugin
	plugin = Plugin()
	plugin.register()
except Exception as e:
	import logging
	logger = logging.getLogger()
	logger.debug(repr(e))

old Plugin class in main file:

class Plugin(pcbnew.ActionPlugin):
	def __init__(self):
		self.name = "Coil Generator"
		self.category = "Manufacturing"
		self.description = "Toolkit to automatically generate coils for KiCad"
		self.pcbnew_icon_support = hasattr(self, "show_toolbar_button")
		self.show_toolbar_button = True
		self.icon_file_name = os.path.join(os.path.dirname(__file__), 'icon.png')
		self.dark_icon_file_name = os.path.join(os.path.dirname(__file__), 'icon.png')
			
	def Run(self):
		# Assuming the PCBNew window is focused when run function is executed
		# Alternative would be to keep track of last focussed window, which does not seem to work on all systems
		CoilGeneratorUI(wx.Window.FindFocus()).Show()

new initialization in main file:

if __name__ == "__main__":
    app = wx.App()
    coilgen = CoilGeneratorUI(wx.Window.FindFocus())
    coilgen.Show()
    app.MainLoop()
    coilgen.Destroy()

Here’s a current draft PR to see the changes I did: Update to KiCad 9 Python API by TimGoll · Pull Request #17 · DIaLOGIKa-GmbH/kicad-coil-creator · GitHub


I want to add that I also am unable to get the official examples working. I placed the round_tracks folder into the appropriate KiCad folder:
image

Then the same error that I encountered happened, because the identifier was wrong for a manually installed addon. Once I changed the identifier from com.gitlab.kicad.kicad-python.round_tracks to round_tracks the issue was fixed. However, same as with my personal plugin, nothing showed up in KiCad.

This is not correct, you should not change this identifier.

The identifier doesn’t need to match the folder name. The error you are getting comes from some other source. Can you file a bug report about it?

First of all, if you are literally using rc1, rather than a nightly, it is missing a number of useful bugfixes since then – I’d kind of recommend updating, especially if you want to try out the api. For example, it should automatically find Python on Windows now (it used to only work on Linux and Mac)

In general I haven’t been doing much testing on Windows other than to verify that the underlying API things work, so it’s likely to have more rough edges at the moment than other platforms.

Eventually (not in 9.0.0) we will prompt people to turn it on if they try to install a plugin that requires it from PCM.

For now, if you want to experiment with the API, skip the whole plugin loading thing, and just directly run your plugin from your IDE of choice. One of the nice things about the new API is that you can do this, you don’t need to have KiCad launch your plugin for you like with the SWIG ones.

image

I’ve also tried Documents\KiCad\9.0\scripting\plugins as a base folder, but the issue is the same there.

Sure. In the KiCad repo? Or in the API repo?

This sounds like it is not recommended to use the new API for addons in KiCad 9? Bummer. I hoped that I can use that API to get the board stackup (and the parameter such as the layer thickness etc).

Moreover, I did not enable anything in the plugin settins. I assumed that the requirements.txt would suffice and that this setting is only needed if one wants to access KiCad from externally, such as from the IDE.


Just updated to the newest nightly and it behaves the same.

KiCad. I assume by “the API repo” you mean kicad-python, which is Python bindings to the API, not the API itself. Issues with the Python code itself would go in that repo.

Sure, it’s recommended. But like the readme says, it should be considered a “public beta” and will have lots of room to improve over time. Right now I have very little feedback from anyone doing anything with the new API, I expect as more people use it, more things will be uncovered. It is not intended to be an instant replacement to SWIG that will be transparent to non-developers. The initial release of the API is for Python developers more than regular users, and as the things get figured out for Python developers, it will become easier to use for regular users.

You assumed wrong. This needs to be enabled for anything to talk to the API, whether launched from KiCad or from your IDE.

Yes, that is correct. I will do that.

All right. Looking forward to the popup to request users to enable the API then. Because I already see the bug reports on why it stopped working because the users do not know that they have to enable the setting.

Well nothing can stop working until anything starts working? Existing SWIG-based plugins don’t need this checkbox, only new IPC plugins, and none of those exist yet.

I planned on updating the coil generator to be an IPC plugin. That’s what I meant earlier with “probably not recommended right now”

You should make a new iteration of your coil generator and see how it works, report issues, etc.

You should not intend to release a new version of your plugin on the PCM that switches from SWIG to the new API, at least not right now.

I would instead recommend doing things like only testing yourself, having people manually install who want to test, or maybe releasing the new-API plugin as a separate thing (not an update to the existing one)

The intention is that during V9, developers play with the API and see what needs to be added, changed, etc. They should also keep supporting their existing SWIG-based plugins in parallel.

V10 is the earliest version where I would recommend dropping support for your SWIG plugin and only supporting the new API.

1 Like

Understood, makes sense. I will probably publish a second coil generator addon then which uses the new features.

Updating to the new plugin file structure is recommended for version 9 though?


Issue created: Python Plugin Loading Broken (#19465) · Issues · KiCad / KiCad Source Code / kicad · GitLab

The plugin.json file is only used for new IPC plugins. It exists in parallel to, not as an update to, the PCM json file.

Yes, I didn’t want to replace the file. Sorry, that was probably a bit unclear.

That means: SWIG addons should stay unchanged? plugin.json and requirements.txt only affect the new IPC plugins?

Correct, the new API and new plugin loading mechanism are completely independent and do not require any changes to existing SWIG plugins.

1 Like

Good to know, thank you. That was not clear to me. I assumed the loading change would work for both addon types!

Well I guess that’s what you get for trying to play with it before I write any documentation :smiley:

(this thread is useful for figuring out what I should put in the FAQ that will come up with 9.0)

1 Like

As a dev of an open-source project with sub-par documentation myself, I feel that. All the great documentation is already in my head and it always surprising to see in which way addon devs break our APIs :smiley: