I was just helping someone out with running picotool uf2 convert because it was complaining that the family ID rp2350 was not valid. I've never used this tool before, so my first port of call was to run the help command. This did not provide any information on what the family ID should be for an RP2350. I looked at the README file on this repository, which did not appear to have a section listing the supported family names. I then tried searching the source code for family_id, --family, rp2350, and some of the constant values to try to discover what the flag should be. This did not help either - GitHub's search couldn't find where constants were defined, and I couldn't spot a location where all family names are enumerated. In the end I searched the closed issues for "rp2350" and found some examples that showed that the family ID should've been either rp2350-riscv or rp2350-arm-s. I think this user experience can be significantly improved.
The first thing I would like to request is a picotool list families command that lists the family IDs that are supported by the tool. This makes the families much more discoverable, directly within the tool. Implementing this as a list command (instead of, say, picotool list-families) provides a common basis for future functionality that lists other entities for easy discovery. Including this list in the readme would also be helpful, but this is secondary to having it directly in the tool.
The second thing I would like to request is a modification to the error message when an invalid family ID is provided. The error message should, of course, be updated to point the user to the new picotool list families command, instead of the more general help page. In addition, I think it would be helpful to perform a substring search on the erroneous family name that was provided by the user and return any matches as suggestions. For example, if a user enters rp2350, the error message should suggest "perhaps you meant one of these families: rp2350-arm-s, rp2350-riscv". Similarly, if a user enters RP2350-ARM, the error message should suggest "perhaps you meant rp2350-arm-s". This message would provide instant and helpful feedback without the user needing to execute a second command to discover the correct family name.
I was just helping someone out with running
picotool uf2 convertbecause it was complaining that the family IDrp2350was not valid. I've never used this tool before, so my first port of call was to run the help command. This did not provide any information on what the family ID should be for an RP2350. I looked at the README file on this repository, which did not appear to have a section listing the supported family names. I then tried searching the source code forfamily_id,--family,rp2350, and some of the constant values to try to discover what the flag should be. This did not help either - GitHub's search couldn't find where constants were defined, and I couldn't spot a location where all family names are enumerated. In the end I searched the closed issues for "rp2350" and found some examples that showed that the family ID should've been eitherrp2350-riscvorrp2350-arm-s. I think this user experience can be significantly improved.The first thing I would like to request is a
picotool list familiescommand that lists the family IDs that are supported by the tool. This makes the families much more discoverable, directly within the tool. Implementing this as alistcommand (instead of, say,picotool list-families) provides a common basis for future functionality that lists other entities for easy discovery. Including this list in the readme would also be helpful, but this is secondary to having it directly in the tool.The second thing I would like to request is a modification to the error message when an invalid family ID is provided. The error message should, of course, be updated to point the user to the new
picotool list familiescommand, instead of the more general help page. In addition, I think it would be helpful to perform a substring search on the erroneous family name that was provided by the user and return any matches as suggestions. For example, if a user entersrp2350, the error message should suggest "perhaps you meant one of these families: rp2350-arm-s, rp2350-riscv". Similarly, if a user entersRP2350-ARM, the error message should suggest "perhaps you meant rp2350-arm-s". This message would provide instant and helpful feedback without the user needing to execute a second command to discover the correct family name.