Useful? Path for Datasheets

By policy (reasons below), we keep the datasheets for all parts used in our designs on our internal network and refer to them by filename (file:). The location of the datasheet “library” changes from time to time. For our use, a Path (Environment Variable) expanded when “Open Documentation” is chosen would be very useful. I tried adding an Environment Variable and using it (e.q. $(KICAD_DOC_LIB) ) in the Datasheet field (F 3) in the schematic and it appeared no expansion was done on 5.1.0.

My question for the “Feature Request Chat” folks is: would this feature be useful for anyone else?

Thanks,
MMM

Justification for local storage (as opposed to external URLs) of Datasheets: Links to external documentation get broken over time. Companies merge or even cease to exist. Part lines are sometimes transferred from one company to another. Links are sometimes changed. We needed a stable target.

The half-workable solution was to put links in the Field 3 (e.g. “file:.\Datasheets\Littlefuse_Fuse_473.lnk”). [This is Windoz.] The .lnk file points to one PDF file in a fairly large library of .PDF files. This way maintenance on a relative small and specialized set of directories is needed if the local Network Gods decide to move the datasheet store.

To make this work, we have to have the current working directory set to the project directory before running KiCad.exe. It would be cleaner for us to have an environment variable.

Absolutely!

Same issue here. In general I copy relevant documents (pdf etc.) into a local folder structure off of a /home/something/… etc. folder.

It definitely would be useful to be able to redirect the document root folder by means of an environment variable which would allow to group documents by project.

Go for it.

Should already be fixed in nightly meaning it will definitely be part of version 6: https://bugs.launchpad.net/kicad/+bug/1818220

Rene:

Great, thanks.

We cannot currently run nightlies on ‘production’ boards, but should be able to try it out fairly soon. Just have to free up a machine.

Apologize for not being facile with searching bugs and features.

MMM

Oh this was not a “use nightly” answer. It was a “no need to file a report it is already done” answer.

For using nightlies: Is it a good idea to use a nightly build version?

Rene:

Understood.

We will still do some tests on the nightlies (after an unrelated, local deadline) to determine how it works and if it completely solves the issue in our particular use case.

MMM

Apparently, the bug you’re linking has been solved and committed before the 5.1.0 was released.

I’m confused by Efcis’s reply. And maybe now by Rene’s. Looking at the 6/8 lines in the fix, it looks like this is in the library editor, assuming “LIB_EDIT_FRAME::OnViewEntryDoc” is part of the library editor. I think the fix is fine, but the issue for me was in the schematic editor (Eeschema). I right-click on a component and select “Open Documentation”. If I have an Environment Variable (see first post), it does not get expanded.

In lieu of a new Environment Variable, I’ve just tried to use KIUSR_SYMBOL_DIR and the result is a similar failure: “Failed to open URL “$(KIUSR_SYMBOL_DIR)\Datasheets\ON DF10M-D.lnk” in default broswer. (error 2: the system cannot find the file specified.)”.

I was hoping to use a new Environment Variable, either an arbitrary one or a system-defined one specific to documentation. That would avoid overloading one of the existing ones. But unless I’m really being ham-handed, expansion is not taking place.

I’m running:
KiCad (5.1.0)-1, release build
wxWidgets 3.0.4 Unidoce and Boost 1.60.0
Platform: Windows 7 (build 7601, Service Pack 1), 64-bit edition, 64 bit (Ultimate version).

MMM

Some time ago I wanted this also, and I made:

Eeschema / Preferences / Configure Paths

and in there added
“KICAD_DATASHEET” and that points to: /home/paul/electronics/datasheets
image

As a test I opened the documentation for a transistor that uses that path and it also works for me in KiCad V5.1.
The properties of the transistor look like:

Note, I’m currently running stable V5.1 with Linux here:

Application: kicad
Version: 5.1.0+dfsg1-1, release build
Libraries:
wxWidgets 3.0.4
libcurl/7.64.0 OpenSSL/1.1.1b zlib/1.2.11 libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) libssh2/1.8.0 nghttp2/1.36.0 librtmp/2.3
Platform: Linux 4.19.0-4-amd64 x86_64, 64 bit, Little endian, wxGTK
Build Info:
wxWidgets: 3.0.4 (wchar_t,wx containers,compatible with 2.8) GTK+ 3.24
Boost: 1.67.0
OpenCASCADE Community Edition: 6.9.1
Curl: 7.64.0
Compiler: Clang 7.0.1 with C++ ABI 1002

Build settings:
USE_WX_GRAPHICS_CONTEXT=OFF
USE_WX_OVERLAY=ON
KICAD_SCRIPTING=ON
KICAD_SCRIPTING_MODULES=ON
KICAD_SCRIPTING_PYTHON3=ON
KICAD_SCRIPTING_WXPYTHON=ON
KICAD_SCRIPTING_WXPYTHON_PHOENIX=ON
KICAD_SCRIPTING_ACTION_MENU=ON
BUILD_GITHUB_PLUGIN=ON
KICAD_USE_OCE=ON
KICAD_USE_OCC=OFF
KICAD_SPICE=ON

Paul:

OK, I don’t understand how my case is different - other that the name I picked for the datasheet location and maybe the fact that I have file: and use a Windoz link. Both of those work without the Environment Variable. I will investigate, but I followed your steps almost exactly. I’ll re-reply in a few hours.

MMM

I don’t think you need to add “file:” just have a folder path in your variable like “D:\datasheets”.

and

I’m noticing that you are using regular parentheses ( and ) to enclose the name of the environment variable. I thought the curly braces { and } should be used.

The dot between the colon and the backslash makes it a relative path.
Working with path names can be a bit finicky.
Linux uses slashes, while other os’es use backslashes.
When substituting with environment variables, you may get double backslashes if not carefull, etc.

Why are you using “.LNK” ? I just point to the “.pdf” and KiCad starts an pdf reader and opens them (Just as it uses a web browser for URL’s.

I also use parentheses for the environment variables. Did not think much of it, just copied it’s from from one of the other variables.

Gentle Readers:

OK, I’ve done quite a few tests and here are the results. Note F3 refers to Field 3 which seems to be the documentation pointer.

Environment Variable KICAD_DATASHEET_DIR Unused.
:white_check_mark: F3: file:C:\Users\Public\Downloads\Datasheets\era Transformer.lnk
:white_check_mark: F3: file:C:\Users\Public\Downloads\Datasheets\era Transformer.pdf
:x: F3: C:\Users\Public\Downloads\Datasheets\era Transformer.lnk - Unknown MIME Type for Doc File
:white_check_mark: F3: C:\Users\Public\Downloads\Datasheets\era Transformer.pdf

Environment Variable KICAD_DATASHEET_DIR: "C:\Users\Public\Downloads\Datasheets\"
:x: F3: $(KICAD_DATASHEET_DIR)era Transformer.lnk - Unknown MIME Type for Doc File
:white_check_mark: F3: $(KICAD_DATASHEET_DIR)era Transformer.pdf
:x: F3: file:$(KICAD_DATASHEET_DIR)era Transformer.lnk - Failed to open URL “$(KICAD_DATASHEET_DIR)era Transformer.lnk” in default browser. (error 2: the system cannot find the file specified.)
:x: F3: file:$(KICAD_DATASHEET_DIR)era Transformer.pdf - Failed to open URL “$(KICAD_DATASHEET_DIR)era Transformer.pdf” in default browser. (error 2: the system cannot find the file specified.)

Environment Variable KICAD_DATASHEET_DIR: "file:C:\Users\Public\Downloads\Datasheets\"
:white_check_mark: F3: $(KICAD_DATASHEET_DIR)era Transformer.lnk
:white_check_mark: F3: $(KICAD_DATASHEET_DIR)era Transformer.pdf

My conclusions:

  • Environment Variables are expanded only at the start of the F3 field.
  • Windoz Links (.lnk aka Symbolic Links aka Reparse Points) seem to need the leading “file:”
  • Normal files (not links) do NOT require the leading “file:”
  • Any Environment Variable name can be used.

Note to non-Windoz folks:
“.lnk” files in Windoz are actual files but are interpreted in a strange way. In particular, CreateFileA/W (which is used to Open files as well as create them) will open the target of the link unless the flag “FILE_FLAG_OPEN_REPARSE_POINT” is specified. I believe, but am not sure, that other calls’ default behavior is opposite. This might explain why using “file:” makes symbolic links “work” (the target file is found and opened). Note I am not a Windoz expert. And I’m certainly not an expert in KiCad code.

I have what I need in (5.1.0)-1 on Windoz.

Thanks to all,
MMM

Difference between:
$(KICAD_DATASHEET_DIR)
$(KICAD_DATSHEET_DIR)

Oops :slight_smile:

Paul:

I think “file:” does something else. My experiments shown in my previous reply indicate it enables the desired handling of links.

The reason to use links is to save space. They are usually less than 2KB whereas PDF files can be very large. I keep per-project Datasheets folders and if I put PDFs in multiple places it would take a lot of space. There are other ways to save space, I just happened to use symbolic links.

MMM

Oops is right. As I recall, I could not copy the text from the popup and typed it in (incorrectly). I’ll fix it. MMM

lnk files are not symbolic links. Windows does have actual symbolic links support both hard and soft, see mklink command.

1 Like

OK, together we have proven my statement “I am not a Windoz expert.” is true.

But the experiments show the .lnk files need the “file:” to work correctly (open the target). That’s the overall issue for me.

I believe those “.LNK” are text files with a string of text with a pathname, and at the same time Windoze tries to make it difficult to use those files as files.

About the same stupidity as a lot of those other “user friendly” options such as hiding file name extensions, and at the same time relying on them for executables etc. Yuch!

Just had an Idea though, which may already be implemented…
The pathname substitution works for me and I’m content with it.
I think it would be nice to have a default “Datasheet” field for symbols which consists of $(KICAD_DATASHEET_DIR) and the value field of the schematic symbol.

Is there some way to have a symbolic name for the value of another field name?