An overview of .fzpz, .fpz parts files usage in Fritzing

Hi all,

I was having a hard time figuring out how parts files are used in Fritzing ( otherwise I think the tutorials listed under fritzing .org /learning/tutorials/creating-custom-parts are quite nice ), so I wanted to document my experience. Unfortunately, knowing the Discourse software, it will likely prohibit me from posting links as a first time user (one would wish they had the insight of using JavaScript to notify the user of that in advance), so this post will be harder to read than necessary - but hey, we all know technology exists to make our lives harder :slight_smile:

Oh, there was more from Discourse: “Sorry, new users can only put one embedded media item in a post.”; well thanks for that, really makes me feel good after spending all that time taking screenshots! Why not limit me also to one code snippet - or indeed, just posting a single word? That would be so encouraging for new users! I’ll leave the links, hopefully a mod will correct them

The most important points for me are:

  • The Fritzing executable requires a local clone of the fritzing-parts repository ( github .com /fritzing/fritzing-parts ) to be present as its subdirectory
  • Upon startup, the Fritzing executable creates the following two directories (using Windows environment variables below) if they do not exits (so even if you delete them, they will be reconstructed upon next run of Fritzing):
    • %USERPROFILE%\Documents\Fritzing (that is, C:\Users\USER\Documents\Fritzing)
    • %APPDATA%\Fritzing (that is, C:\Users\USER\AppData\Roaming\Fritzing)
  • The .fzpz file is a .zip file - the .fzp and .fzb files are XML (text) files
    • The .fzpz file is only used for exchange between users, not for local storage: there are no .fzpz files in fritzing-parts, for instance
  • There is a concept called “bins”, I see it as a way to organize parts in groups, and I think they are implemented as .fzb files
    • Note that Fritzing internally also uses SQLite database(s), but I cannot really tell if they are related specifically to one, more or all of the filetypes mentioned above

As for the first point: I built Fritzing from source, and it refused to start properly I cloned the fritzing-parts repo as a subdirectory at the location of the executable. And even if I just rename the fritzing-parts subdirectory to something else, it will complain with “Regenerating parts database: Unable to find parts git repository”:

image

… and then with “Cannot read file /bins/core.fzb:” “The system cannot find the path specified…”:

! [image|301x118 ]( upload:// 4gDEpDHS3NdUUjG0uAhMTiLeC9w.png )

… and then “Fritzing cannot load the parts bin”:

![image|249x114]( upload:// Ftxx4nfXO4327fdOWemqudO2zN.png )

… and then “Unable to find the following XX part(s)” - and then finally Fritzing will start, but without any parts, so you cannot do much with it.


So, let’s look at a concrete example - say we want to import a .fzpz part; say, Raspberry-Pi-Pico-tht.fzpz from forum.fritzing .org /t/looking-for-raspberry-pi-pico-part/11915/19

Seeing how important the fritzing-parts subdirectory is, my first thought was to place this .fzpz file somewhere in fritzing-parts - but no matter where I copied it, Fritzing would not pick it up. The crucial info for me here came from forum.fritzing .org /t/how-to-install-fritzing-component-fzpz/5762 :

In the top right corner of the parts area in Fritzing there is a little drop down menu with an import function. It is right next to where you type when doing a search for a part in Fritzing.

Alternately to the drop down menu you can also load a part in to the mine parts bin via file->open and then click on the .fzpz file for the part.

Ok, got it ; so let’s do a quick import experiment - note that I’ll be using MSYS2 bash below as a shell, which makes Windows environment variables available as $USERPROFILE and $APPDATA.

First of all, have Fritzing closed, and delete the automatically created directories - and the parts.db file, that gets autogenerated in fritzing-parts:

$ rm -rf $APPDATA/Fritzing $USERPROFILE/Documents/Fritzing fritzing-parts/parts.db

Then, let’s check in our fritzing-parts subdirectory at the Fritzing executable install location, whether we already have references to parts containing “pi” and “pico” in the name:

$ find fritzing-parts/ -iname '*pi*pico*'
$

Nothing there yet; now start Fritzing - and let’s inspect the autogenerated directories:

$ tree -F --dirsfirst $APPDATA/Fritzing
C:\Users\USER\AppData\Roaming/Fritzing/
├── backup/
│   └── 63a19d289a079edd70fe2a5d9c472b80/
│       └── ___lockfile___.txt
├── fzz/
│   └── 8499dfd5c7335e039b77023648aa1c03/
│       └── ___lockfile___.txt
└── partfactory/
    └── a2b86e0bbde52ab0a86d1ce6a2e3d679/
        ├── contrib/
        ├── core/
        │   ├── 4001_4_x_2_input_NOR_gate_multipart_subpart1.fzp
        │   ├── 4001_4_x_2_input_NOR_gate_multipart_subpart2.fzp
        │   ├── 4001_4_x_2_input_NOR_gate_multipart_subpart3.fzp
...
        │   └── SonySpresense_CXD5602PWBLM1_003_subpart4.fzp
        ├── svg/
        │   ├── contrib/
        │   │   ├── breadboard/
        │   │   ├── icon/
        │   │   ├── pcb/
        │   │   └── schematic/
        │   └── core/
        │       ├── breadboard/
        │       ├── icon/
        │       ├── pcb/
        │       └── schematic/
        │           ├── 4001_4_x_2_input_NOR_gate_multipart_schematic_subpart1.svg
        │           ├── 4001_4_x_2_input_NOR_gate_multipart_schematic_subpart2.svg
...
        │           └── 4081_4_x_2_input_AND_gate_multipart_schematic_subpart5.svg
        └── ___lockfile___.txt

19 directories, 84 files

$ tree -F --dirsfirst $USERPROFILE/Documents/Fritzing
C:\Users\USER/Documents/Fritzing/
├── bins/
│   ├── my_parts.fzb
│   └── search.fzb
└── parts/
    ├── contrib/
    ├── svg/
    │   ├── contrib/
    │   │   ├── breadboard/
    │   │   ├── icon/
    │   │   ├── pcb/
    │   │   └── schematic/
    │   └── user/
    │       ├── breadboard/
    │       ├── icon/
    │       ├── pcb/
    │       └── schematic/
    └── user/

15 directories, 2 files

So, at this point, $USERPROFILE/Documents/Fritzing is mostly empty, while $APPDATA/Fritzing seems to have cached some core files. Let’s just make sure whether these directories contain files with “pi” and “pico” in the name already:

$ find $USERPROFILE/Documents/Fritzing $APPDATA/Fritzing -iname '*pi*pico*'
$

… no, they don’t.


At this point, let’s first download Raspberry-Pi-Pico-tht.fzpz and inspect its contents:

$ wget https://forum.fritzing.org/uploads/short-url/hHiTYgzUUh6gwIxvtUzKyb9aSr5.fzpz -O Raspberry-Pi-Pico-tht.fzpz
...
2022-10-12 23:15:34 (84.4 MB/s) - ‘Raspberry-Pi-Pico-tht.fzpz’ saved [23783]

$ unzip -l Raspberry-Pi-Pico-tht.fzpz
Archive:  Raspberry-Pi-Pico-tht.fzpz
  Length      Date    Time    Name
---------  ---------- -----   ----
    27039  2021-08-25 07:24   part.rpi_pico-tht_1.fzp
   116324  2021-08-25 07:24   svg.breadboard.rpi_pico-tht_1_breadboard.svg
    24783  2021-08-25 07:24   svg.pcb.rpi_pico-tht_1_pcb.svg
    31690  2021-08-25 07:24   svg.schematic.rpi_pico-tht_1_schematic.svg
---------                     -------
   199836                     4 files

Neat - we can see one .fzp and three .svg files in there.

Then, lets import the downloaded Raspberry-Pi-Pico-tht.fzpz via the Fritzing GUI:

![image|459x304] (upload:// nkEmStOkbbmnCi5TKXv6QwiUyqQ.png )

After succesful import, the part appears in the GUI under “My Parts”/“MINE”:

![image|279x157]( upload:// sMzxjUU0UqRF6pTYv9JuygmKoHK.png )

So, are there any changes in our directories? Let’s again look up files with “pi” and “pico” in the name:

$ find fritzing-parts/ $USERPROFILE/Documents/Fritzing $APPDATA/Fritzing -iname '*pi*pico*'
C:\Users\USER/Documents/Fritzing/parts/svg/user/breadboard/rpi_pico-tht_1_breadboard.svg
C:\Users\USER/Documents/Fritzing/parts/svg/user/pcb/rpi_pico-tht_1_pcb.svg
C:\Users\USER/Documents/Fritzing/parts/svg/user/schematic/rpi_pico-tht_1_schematic.svg
C:\Users\USER/Documents/Fritzing/parts/user/rpi_pico-tht_1.fzp

Well, seemingly upon import of the .fzpz file - the .fzpz file got unpacked into constituent .fzp and .svg files, which ended up in $USERPROFILE/Documents/Fritzing/parts.

Now, let’s say we want this part inside our local fritzing-parts just for archival purposes. We can note that $USERPROFILE/Documents/Fritzing/parts has user and svg subdirectories - and so does fritzing-parts. So, let’s close Fritzing now - you will get asked “Do you want to keep the imported parts?”:

![image|296x113]( upload:// dIcekbO0dPtZYhGhedfjzj85nYt.png )

… say No here; then you will get asked ‘Do you want to save the changes you made in the bin “My Parts”?’ :

![image|430x134]( upload:// 4U0mVHAugbjyYOs3MkbDWsNsyFi.png )

… say “Don’t Save” here as well.

If you said “no” to both of these questions, note that the files that were found previously disappear:

$ find fritzing-parts/ $USERPROFILE/Documents/Fritzing $APPDATA/Fritzing -iname '*pi*pico*'
$

So now:

  • first unzip the .fzpz,
  • then try copy (unpacked) files into respective locations in fritzing-parts
    • (commented lines show where you would have copied from, if the unpacked files didn’t get deleted in $USERPROFILE)
    • (note that when you copy from unzipped contents, you have to manually rename as well)
  • again delete the autogenerated directories and the parts.db file, …
$ ls fritzing-parts/{svg,svg/user,user}
fritzing-parts/svg:
contrib/  core/  obsolete/  user/

fritzing-parts/svg/user:
breadboard/  icon/  pcb/  schematic/

fritzing-parts/user:
74xx08.fzp  placeholder.txt

# $ cp -av $USERPROFILE/Documents/Fritzing/parts/user/rpi_pico-tht_1.fzp fritzing-parts/user/
# $ cp -av $USERPROFILE/Documents/Fritzing/parts/svg/user/breadboard/rpi_pico-tht_1_breadboard.svg fritzing-parts/svg/user/breadboard/
# $ cp -av $USERPROFILE/Documents/Fritzing/parts/svg/user/pcb/rpi_pico-tht_1_pcb.svg fritzing-parts/svg/user/pcb/
# $ cp -av $USERPROFILE/Documents/Fritzing/parts/svg/user/schematic/rpi_pico-tht_1_schematic.svg fritzing-parts/svg/user/schematic/

$ unzip Raspberry-Pi-Pico-tht.fzpz
Archive:  Raspberry-Pi-Pico-tht.fzpz
  inflating: part.rpi_pico-tht_1.fzp
  inflating: svg.breadboard.rpi_pico-tht_1_breadboard.svg
  inflating: svg.pcb.rpi_pico-tht_1_pcb.svg
  inflating: svg.schematic.rpi_pico-tht_1_schematic.svg

$ cp -av part.rpi_pico-tht_1.fzp fritzing-parts/user/rpi_pico-tht_1.fzp
'part.rpi_pico-tht_1.fzp' -> 'fritzing-parts/user/rpi_pico-tht_1.fzp'

$ cp -av svg.breadboard.rpi_pico-tht_1_breadboard.svg fritzing-parts/svg/user/breadboard/rpi_pico-tht_1_breadboard.svg
'svg.breadboard.rpi_pico-tht_1_breadboard.svg' -> 'fritzing-parts/svg/user/breadboard/rpi_pico-tht_1_breadboard.svg'

$ cp -av svg.pcb.rpi_pico-tht_1_pcb.svg fritzing-parts/svg/user/pcb/rpi_pico-tht_1_pcb.svg
'svg.pcb.rpi_pico-tht_1_pcb.svg' -> 'fritzing-parts/svg/user/pcb/rpi_pico-tht_1_pcb.svg'

$ cp -av svg.schematic.rpi_pico-tht_1_schematic.svg fritzing-parts/svg/user/schematic/rpi_pico-tht_1_schematic.svg
'svg.schematic.rpi_pico-tht_1_schematic.svg' -> 'fritzing-parts/svg/user/schematic/rpi_pico-tht_1_schematic.svg'

$ rm -rf $APPDATA/Fritzing $USERPROFILE/Documents/Fritzing fritzing-parts/parts.db

… and start Fritzing again.

If started at this point, Fritzing will actually “see” the new part if you search it by name - but not necessarily as part of any bin, such as “Mine” or “Contrib”:

![image|269x213]( upload:// 3GQ9QYK8SIGM3rjNUMDOBfeGlCT.png )

![image|267x220]( upload:// v7jXLR9jZ9jnjR29vvMjV34s5FA.png )

![image|268x261]( upload:// At2UxTFVeFD0NU8NQJGX2O7Msmn.png )

So to make this part a part of the “contrib” bin: first close Fritzing, then what remains to be done, is that this needs to be added at end of fritzing-parts/bins/contribParts.fzb (overwriting the last </instances></module>):

...
		<instance moduleIdRef="rpi_pico-tht_1" path="">
			<views>
				<iconView layer="icon">
					<geometry z="-1" x="-1" y="-1"></geometry>
				</iconView>
			</views>
		</instance>
	</instances>
</module>

… and save these changes in the fritzing-parts/bins/contribParts.fzb.

Then just to make sure let’s delete the user directories and parts.db again:

$ rm -rf $APPDATA/Fritzing $USERPROFILE/Documents/Fritzing fritzing-parts/parts.db
$

… and start Fritzing again; now if you open up the “contrib” pin first, the part is immediately listed there:

![image|322x203]( upload:// n6B2NHfJ2Dj0r6pATWm7nXgDykU.png)

Well, that is approximately the scope of file usage that I need to remember when using Fritzing; glad that it’s documented now, so I don’t have to go through this all over again! :slight_smile:

You may want to have a look at

which documents most of the above. The easy (and correct) solution for loading .fzpz file is to either double click on them or us File->open then select the .fzpz file in the file system. That will load the part in to the mine parts bin and if you save it when exiting Fritzing it will be there in the mine parts bin when you next start Fritzing. To get a part in to core parts you need to make a pull request against the repository on github. Right clicking on a part in the mine parts bin then selecting export part will export the part as an .fzpz file for archiving (which is a wise idea as it is possible to corrupt the user directories and lose the contents of the mine parts bin.)

Peter

Not quite correct. The parts repository is needed, but a run time parameter can be used to specified where it is.

The (apparent) intent is for the .fzpz files to be the archive for the imported parts. Moving the fzp and svg files into the ‘core’ parts library can cause problems later. That is a git repository that can be updated independent of the application. It needs a bit more experience with git to merge remote updates when you also have made local changes to the repository.

I believe you can create your own custom bins, of core and/or imported parts, by adding new fzb files to $USERPROFILE/Documents/Fritzing/bins. Those should have png icon files to go with them.

When creating, or extending bins, not every part needs to be added. A single part from a ‘family’ of parts works fairly well. To use other parts from the same family, place the part that exists in the bin, then use Inspector to switch to other parts in the same family.

Extra side note: svg files are also xml text files.