Usability concerns

[chemicstry]

I don't know if it's just me, but I find the yakut tool a bit inconvenient to use. It requires a lot of initial configuration compared to the old uavcan_gui tool. And this is especially hard for less tech-savvy field operators.

Initial confusion is that the first command given in the README is yakut --path=/the/path compile path/to/my_namespace --output=destination/directory. However, I could not understand why it needs 3 paths for compilation. As far as I understand only the arguments and the --output paths are used, while --path is ignored?

Then README explains to setup environment variables so that default compilation output goes to user data directory. Wouldn't it be better to have this as default instead of current working directory? AFAIK, this is the most common use case.

Would it be possible to ship public regulated data types together with yakut? Or maybe add a command that would download and compile them for you?

Another convienient option would be to load custom DSDLs from user directory and compile them automatically, as was the case with uavcan_gui tool.

I can contribute some of these changes, but firstly wanted to hear some opinions about this.

[thirtytwobits]

I agree it is not convenient but it is powerful. This, to me, suggests that something built on top of Yakut would be in order. Perhaps a VSCode plugin that uses Yakut and injects workspace defaults as Yakut defaults, does git pull of the public, regulated types, etc? I think opportunities to simplify the command-line would be accepted (I'm not the maintainer here though) but I don't think it's a good idea to provide any pre-compiled data types or otherwise tightly bind the tool with the types. While gui_tool worked well with little to no configuration the auto-magic defaults quickly became an impediment as our systems matured. I don't want to have that kind of inflexibility nor hidden behaviours in Yakut.

[chemicstry]

Just to be clear, I'm not advocating for removing configuration, but for providing convenient defaults instead.

Regarding bundled datatypes, what if YAKUT_PATH defaulted to ~/.yakut (or %APPDATA%/yakut) and it would be automatically populated with public types on first launch or with a yakut install? Opting out is just changing YAKUT_PATH, which you already have to do.

[pavel-kirienko]

Initial confusion is that the first command given in the README is yakut --path=/the/path compile path/to/my_namespace --output=destination/directory. However, I could not understand why it needs 3 paths for compilation.

It is a bad example that needs to be improved. The point of that snippet is not to illustrate how to invoke the yakut compile command, but to show the relationship between options and environment variables. Should it be replaced with another command here? Maybe something like yakut --format=json subscribe --count=1? A pull request improving this (and perhaps something else in the readme) would be appreciated.

Then README explains to setup environment variables so that default compilation output goes to user data directory. Wouldn't it be better to have this as default instead of current working directory? AFAIK, this is the most common use case.

I am generally okay with that change but I am not entirely sure if it is actually better than the current behavior because when it comes to generating anything, by default the user would expect the output to show up in the current working directory. Maybe we could provide a dedicated command that sets up the default system configuration when run, like yakut setup (which would edit .bashrc or whatever automatically)? But then we would be missing out on the opportunity to demonstrate to the user how to use environment variables to override the defaults. That said, see below on implicit DSDL generation support in PyCyphal.

Another option is to provide an automatic installation script that does all these things automatically per system, like:

bash -c "$(wget -O - https://raw.githubusercontent.com/OpenCyphal/yakut/main/setup.bash)"
# Also 'setup.pwsh' for Windows, etc.

Would it be possible to ship public regulated data types together with yakut?

No, this is not going to happen. In v0 it was a terrible decision that led to much confusion, causing many developers and vendors to fork the public regulated repository just to add some obscure application-specific types to the standard uavcan namespace. The current README actually has a paragraph with the rationale behind the lack of precompiled namespaces, also Scott basically already answered this in his post above.

Or maybe add a command that would download and compile them for you?

This is not as bad but then would it be much different from simply copy-pasting the public regulated data type URI to your shell? Compare:

# A helper command specifically for the public regulated data types:
yakut compile-public-regulated-dsdl

# What we have right now, where the URI is copy-pasted from the README:
yakut compile https://github.com/OpenCyphal/public_regulated_data_types/archive/refs/heads/master.zip

Actually, we already have a snippet in the README that merely needs to be copy-pasted to compile the standard namespace, so I would say that it is pretty much a non-issue? Maybe I am missing something though.

Another convienient option would be to load custom DSDLs from user directory and compile them automatically, as was the case with uavcan_gui tool.

Absolutely. This is tracked in PyCyphal with a slightly different bent: OpenCyphal/pycyphal#153. I want to get rid of the notion of DSDL pre-compilation completely (but it won't rid you of the need to download DSDL sources). Would you be inclined to help with that? I expect this to improve the UX of Yakut and PyCyphal scripting significantly.

There's also the outstanding problem of migrating the Python DSDL generator to Nunavut but it appears to be unaffected by this change (@coderkalyan was working on this for a while but right now the effort seems to be stagnating).

[chemicstry]

Then README explains to setup environment variables so that default compilation output goes to user data directory. Wouldn't it be better to have this as default instead of current working directory? AFAIK, this is the most common use case.

I am generally okay with that change but I am not entirely sure if it is actually better than the current behavior because when it comes to generating anything, by default the user would expect the output to show up in the current working directory. Maybe we could provide a dedicated command that sets up the default system configuration when run, like yakut setup (which would edit .bashrc or whatever automatically)? But then we would be missing out on the opportunity to demonstrate to the user how to use environment variables to override the defaults. That said, see below on implicit DSDL generation support in PyCyphal.

If yakut could implicitly compile DSDL's then this is no longer an issue and compile could work as is.

So if I understand the concerns correctly, my proposal would be:

• Make YAKUT_PATH default to ~/.yakut or %APPDATA%/yakut (when no env variable exists and --path is not given)
• Implement Implement implicit DSDL compilation via import hooks pycyphal#153
• Simplify DSDL installation. Here I can see a couple of options:
  • Tell user to manually download DSDL to ~/.yakut or %APPDATA%/yakut. If compilation is no longer required this is already a great improvement.
  • Add yakut dsdl install https://github.com/OpenCyphal/public_regulated_data_types/archive/refs/heads/master.zip and maybe a shorthand yakut dsdl install-regulated, which could be optionally invoked during yakut setup (if it is implemented).

Driver autodetection or configuration during yakut setup would also be nice, but I think this would be quite difficult with how python-can works. Maybe let's not go there now and leave it for the future.

[pavel-kirienko]

If we implemented OpenCyphal/pycyphal#153 then the need for YAKUT_PATH and yakut compile will be obviated completely, which is great. Instead of that we will have CYPHALPATH that points where DSDL sources are, which may default to ~/.cyphal or something similar depending on the platform.

Then we could have your yakut dsdl install that would by default download DSDL namespaces to, let's say, ~/.cyphal or maybe the first location specified in CYPHALPATH -- we should discuss the specifics later. (EDIT: if ~/.cyphal/uavcan is missing we could even fetch the namespace from GitHub automatically, does that seem reasonable?)

I suggest we discuss yakut setup later as well, for now it seems reasonable to focus on automatic DSDL compilation. Let's continue this over at OpenCyphal/pycyphal#153