CLI Getting Started Guide

[jacobhylen]

Added a short getting started guide for users not familiar with the CLI or the Command prompt in general to get started with uploading sketches, self-made or examples to an Arduino board.

[per1234]

We already have a general guide to using Arduino CLI:

https://arduino.github.io/arduino-cli/latest/getting-started/

The documentation hosted in this repository must be restricted to information specific to the library. For everything else, just link to the existing documentation. Duplicating content means either an unnecessary increase in the maintenance burden or (much more likely) outdated zombie docs that confuse and frustrate the user.

[aentinger]

Thank you very much @jacobhylen for this first draft. I'd like to second @per1234 comments re duplicating of content available over for the arduino-cli. Maybe the most important difference to note is that you download the special multi-threading-cli differently than the default CLI and you need to ensure that you invoke the correct cli (that is the multi-threaded one, not maybe the default one which has been added to the system path and is therefore unintentionally invoked).

One thing I wanted to add: for images (screenshots) please make sure that only the relevant part is visible (and the non-relevant part has been cut away). You can include images also via

<p align="center">
  <img src="assets/boardlist.png" width="40%"></a>
</p>

which allows you to scale the image to the desired width.

[sebromero]

@per1234 @aentinger I don't agree in this specific case. Let me explain. It's a bit of a special case because this repo is not just a library, it's for now a place for people to test a draft of this new feature. Now that I tested it with my team and the majority struggled to get it working with the CLI, we've figured it would be a good idea to provide a very basic document that gets them started just for the purpose of testing this library. This is because at this point the only way to test it is to use the CLI. We actually lost a few people because first learning how to use the command line and all the commands of the Arduino CLI was too big of a hurdle. @per1234 You can check the feedback from the survey, I'll invite you.

So the idea is to have this document temporarily here to give the people just the things they need to do the testing. Once we move this library out of beta (alpha?) we can delete it. I'm a purist too and certainly we don't want to accumulate documentation maintenance debt (I mean my team would probably suffer the most), but practically speaking this currently solves a problem.

[aentinger]

Reading @sebromero ripose I'm inclined to side with him. Apparently there is a large percentage of people who really don't know how to use the arduino-cli and are consequently excluded from testing this library (although, since today there is also #80).

@alranel please make a timely decision on whether to keep the getting started guide in its current form, modify it, or scrap it.

[aentinger]

I've merged this now in order to move on. However, upon reading it once more its really "only" a arduino-cli getting started guide with v e r y little relevance to Arduino_Threads. Furthermore it's got a bit of a heavy focus on Windows but I suppose that's okay, given that there are many Windows users out there and Linux users are traditionally more in touch with command line tool usage. Let me say this though: The moment I get the feeling that having this getting started guide here causes confusion overall concerning arduino-cli I'll remove it.

[sebromero]

@aentinger Alright. So, if we want to make it more relevant for Arduino_Threads, what would you change / add?

[aentinger]

Drop the whole hocus-pocus how to install/start/use it. That's what the original getting started guide is for. In truth you only need to

Install custom arduino-cli

Download by left-clicking on link or curl:

cd Arduino_Threads
curl https://downloads.arduino.cc/tools/arduino-cli/inot_support/arduino-cli_git-snapshot_macOS_64bit.tar.gz

Ensure the right version of arduino-cli is used

by downloading it directly into the library (see above) and then calling it via ./

Arduino_Threads$ ./arduino-cli compile ...

If we are feeling generous we can supply the whole command for one example, i.e.

# Compile
./arduino-cli compile -v --fqbn arduino:mbed_portenta:envie_m7 examples/Threading_Basics/Thermostat
# Upload
./arduino-cli upload -v --fqbn arduino:mbed_portenta:envie_m7 examples/Threading_Basics/Thermostat/ -p /dev/ttyACM0

Everything else is the cli getting started guide for.

[alranel]

I agree with @aentinger, I'd re-frame this to "How to test Arduino_Threads from command line" (or CLI). This guide is only relevant as long as these changes are not merged in the official codebase of the CLI so it's important to clarify that the guide applies to an experimental build related to an experimental feature. Also, we should avoid that a random visitor not interested in testing threads takes this guide as a generic guide on how to use the CLI, since we have better and more maintained documentation for that purpose. So I would do the things recommended by @aentinger