Explain better that "board listall" depends on installed cores

[alranel]

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

• Explain better that "board listall" depends on installed cores #550 (comment)
• Explain better that "board listall" depends on installed cores #550 (comment)

[masci]

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 #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]

@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]

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]

@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]

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]

@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]

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]

@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]

@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]

@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]

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 :)