Explain better that "board listall" depends on installed cores

alranel commented 4 years ago

Current behavior

When no cores are installed, I would expect that listall returned all the existing boards (like the Boards menu in the IDE). For a new user it's not clear that it only lists the boards whose cores are installed, also because core install is documented in the README after board listall.

$ arduino-cli board listall
Board Name FQBN

$ arduino-cli board
[...]
  listall     List all known boards and their corresponding FQBN.
[...]

Suggested behavior

$ arduino-cli board listall
No known boards: install your first core with "arduino-cli core install <core>" to support its boards.
$ arduino-cli board
[...]
  listall     List all known boards (and their corresponding FQBN) according to the installed cores.
[...]

Also, would it be possible to add a board search command to list all the existing boards (even if not installed)? Do we have such data around? Most users think like this: I have a board -> I know its name but I don't know what core it requires -> Please install whatever core is needed for my board

Additional context

Additional requests

masci commented 4 years ago

I second your concerns about the listall command, short term I think adjusting the output messages is fine but I'd like to discuss more its original purpose and how we can make it less confusing and more effective.

Most users think like this: I have a board -> I know its name but I don't know what core it requires -> Please install whatever core is needed for my board

When you do board list, if your board is connected you should see all the information needed to complete the installation:

arduino-cli board list                                     massi@xps
Port         Type              Board Name          FQBN                     Core        
/dev/ttyACM0 Serial Port (USB) Unknown                                                  
/dev/ttyACM1 Serial Port (USB) Arduino NANO 33 IoT arduino:samd:nano_33_iot arduino:samd

This is possible because the CLI queries a remote service which can tell you something about your board given VID and PID as they come from the USB connection (see https://github.com/arduino/arduino-cli/pull/336).

We should have a conversation about how much of this (along with other similar cases like core update-index) should be automated and transparent to the user - I'd like to go in this direction as much as we can so as to improve the user experience.

ubidefeo commented 4 years ago

@masci @alranel I think the correct behaviour would be adding flags such as --installed and --available, where the former lists the installed ones and the latter every board which can be installed.

hpsaturn commented 4 years ago

Yes, it is confused, I'm trying to use arduino-cli on Debian, and I'm following the official documentation but I only have a empty output from:

arduino-cli board listall 
Board Name FQBN

ubidefeo commented 4 years ago

@hpsaturn as you can see this issue is pretty old. the listall command will of course only list the ones you have available to your system, which are indeed "known" to your current arduino-cli setup

  listall     List all known boards and their corresponding FQBN.

hpsaturn commented 4 years ago

I know it, but it is confused, if I did running arduino-cli core update-index I hope that it give me all information, but not.

Some examples:

Debian

apt-get update
apt-cache search xxx

PlatformIO

pio update
pio boards | grep -i olimex

pio update
pio platform list

ubidefeo commented 4 years ago

@hpsaturn let me see if I get it: you'd like to see some information such as "no platforms are installed"? We're still putting together this kind of more user-friendly messaging and feedback, so we appreciate the suggestion.

Definitely the visual output to a shell user should be nicer, but as we are in development some features are pushed for a later time in order to make the CLI more stable and powerful. Once we're there we'll get to rework the UX and UI :)

hpsaturn commented 4 years ago

But it isn't a UX or shell friendly issue, after the first clean installation, how I know what FQBN strings exists?

list         Shows the list of installed platforms.
search       Search for a core in Boards Manager.

these commands only works if you already did a core installation. But how to I know what core install?

The arduino-cli core update-index should be load this information.

For me the documentation is not clear. After first clean installation these are documentation steps:

arduino-cli core update-index

arduino-cli board list
No boards found.

arduino-cli board listall
Board Name FQBN

arduino-cli board listall mkr
Board Name FQBN

the next step is arduino-cli core install arduino:samd how to you know that it be "arduino:samd" ? Maybe the listall option is wrong, and it should show all possible boards?

ubidefeo commented 4 years ago

@hpsaturn This is extremely helpful feedback, thank you so much for taking the time to compile it. @per1234 can we chat about this and find a way to address it?

Maybe there should be a suggestion to the user, it could be a "first run" message or something that just shows up when no platforms are installed

hpsaturn commented 4 years ago

@ubidefeo or maybe more easy:

arduino-cli board listall should show all possible platforms or boards that the user can be install and
arduino-cli board list should show the current installed boards

or

adding maybe the option boards, something like:

arduino-cli boards show all possible platforms and boards

ubidefeo commented 4 years ago

@hpsaturn list shows currently connected hardware listall could have a flag to show installable. I think automatically telling users that no boards support is installed and inviting them to install something is better.

will put it in our backlog as enhancement :)

WesleyAC commented 2 years ago

Another initially-confused user here. I've used Arduino stuff starting in the early 2010s, but haven't used it since arduino-cli came out. I'm very happy that there's finally a CLI, but I was initially a little confused about how to use it. Here's what I tried:

arduino-cli compile

Returns: Error during build: no FQBN provided

I google "Arduino FQBN", and find this, which suggests arduino-cli board listall to find a list of FQBNs. I run it:

arduino-cli board listall

Nothing shows up. I google around, and figure out that I have to install some boards.

From this issue, I figure out that I have to install a "core" to have boards installed. I run:

arduino-cli core list

And it showing nothing shows me that I don't have any cores installed. (I don't know what a "core" is at this point) I run:

arduino-cli core update-index

Thinking that this might download a list of available cores, but arduino-cli core list still shows nothing. I google "arduino-cli core" and find this page, hoping it'll have a list of cores. It doesn't.

Finally, I try arduino-cli core search, which appears to give me a list! I happen to know that my Nano is a AVR board (but if I didn't, I'd probably be confused!), so I run:

arduino-cli core install arduino:avr

And finally, arduino-cli board listall shows "Arduino Nano"!

Some things I'd have liked to be different:

arduino-cli board listall should print a message to stderr explaining how to install a core if you don't have any cores installed.
arduino-cli core should tell you that arduino-cli core search shows you available cores
There should be a page on the internet with good SEO that gives a list of cores, FQBNs, and explains how to install a core.

Overall, I really appreciate that there's a CLI that seems like it'll be relatively smooth to use. Hopefully this feedback can help make it even better :)

ubidefeo commented 2 years ago

hi @WesleyAC This is immensely useful feedback on the usability aspects of CLI as used by someone in the terminal. This tool is mostly used for automation and is behind IDE 2.0 via a gRPC interface.

We have been lagging behind the UX aspects of CLI but it is not outside of our radar, we just had to concentrate on how it is used by the IDE and how well it can be integrated in automated workflows.

We're nonetheless very pleased with your feedback and invite you to look at the documentation to signal anything else you might be confused by.

Looking forward to hearing from you Thanks again

Arduino Tooling Team

ahojukka5 commented 2 years ago

I came to this thread because arduino-cli board listall didn't return anything. arduino-cli core search was what I was finding for.

jmnc2 commented 2 years ago

In the getting started guide: https://arduino.github.io/arduino-cli/0.21/getting-started/ (Maybe same file as: https://github.com/arduino/arduino-cli/blob/master/docs/getting-started.md ?)

Under the heading "Connect the board to your PC" and then 3rd code block down replacing $ arduino-cli board listall mkr (Lists boards installed)? with: arduino-cli board search (Lists all boards available to install with arduino-cli core install FQBN)? Would of made my life easier.

NormanDunbar commented 1 year ago

With regard to the getting Started instructions I see the following:

If you see an Unknown board listed, uploading should still work as long as you identify the platform core and use the correct FQBN string. When a board is not detected for whatever reason, you can list all the supported boards and their FQBN strings by running the following:

$ arduino-cli board listall mkr ...

Unfortunately, this is incorrect. I have a brand new laptop with no Arduino IDE installed, yet, and I was updating the Arduino-cli chapter in my book, Arduino Software Internals to take account of all the new stuff since 2018/2019 and version 0.6.0!

Running the arduino-cli board listall command, with or without a search term, results in nothing at all. The reason, as stated elsewhere, being that there must be a core installed already, but catch-22, which core to install to get a list of boards? I'm fine, I know it's "arduino:avr" but a complete beginner to this stuff will probably have problems.

I have a number of boards in my colection; a genuine Mega 2560 R3; a clone Uno R3; a genuine Duemilanove; a couple of clone Nanos and a few "Normduinos" that I built myself to run without a crystal. Only the Mega is identified correctly with arduino-cli board list when connected. All my other boards are flagged as "Unknown" due to the FTDI chip onboard I assume. Hence, attempting to follow the instructions to arduino-cli board listall command from the getting started pages.

I did, eventually, discover that the arduino-cli core search xxx, or arduino-cli board search xxx where xxx is a search term, does list the cores available for the boards.

The documentation needs to be updated to mention this latter command, arduino-cli board search xxx, is best for finding the required core for our board when it is listed as "Unknown" and the installation is new/clean as it will download any required indexes to assist in the search.

In addition, and mildly irritating, my Duemilanove is not found with either a core or a board search. Luckily I know that the Diecimila is the same. It would be nice to be able to look fopr my actual board though! :wink:

HTH

Cheers, Norm.

HeadBoffin commented 9 months ago

One year on and here I am trying to figure this out. Thanks to those who provided details above.

DownloadableFox commented 2 months ago

I had to read this entire thread only to figure out how to get my Arduino board to show up with an FQBN different than "unknown".

This thread is more or less 4 years old and I still consider this to be really intuitive- the whole listall sub-command is just intuitive. I appreciate the help and all, but please, we should be changing something.

arduino / arduino-cli