Improve documentation of setting custom board options via FQBN

[noweare1]

Bug Report

I don't know if this is a bug or I just don't have the upload stuff set up correctly

Current behavior

arduino-cli upload -p /dev/ttyACM0  --fqbn STM32:stm32:Nucleo_64 myfirst.ino

I am confused about how the upload command is supposed to work with my board. I am using an stm32_core developed by ST. For sanity sake everything works fine in the arduino ide. Back to the CLI, I set up the tools as directed in the readme. Using the CLI and being IN the project directory I can compile if only if I include the ino extension. The compiler complains it can not find the file if I do not add the extension. The readme file shows the extension is omitted.

When i use the upload command the the uploader can not find the file because it adds the project directory and I am IN the project directory. The error is shown below.

Error: compiled sketch myfirst/myfirst.STM32.stm32.Nucleo_64.hex not found

The uploader looks for a file name which is different from what the compiler created. The compiler had added on ".ino" after the file name. The uploader looks
for a file without the extension:

myfirst.STM32.stm32.Nucleo_64.hex vs myfirst.ino.STM32.stm32.Nucleo_64.hex

It was a real task to find the correct --fqbn for my board also.

One question: Is the CLI use the .arduino15 settings for the core or am I supposed to use the arduino-cli.yaml file for setting things up for CLI?

Expected behavior

A successful upload

Environment

CLI Version: 0.4.0 Commit: =98b7be9

• OS and platform:
  Ubuntu, x86_64-linux

Additional context

I know this is still a work in progress and I am not being critical just trying to give you some feedback.

I really like the CLI. It will free me up to use my favorite text editor (Geany) which I use for everything.

[per1234]

The thing is that myfirst.ino is not a sketch. The folder myfirst is the sketch and it is the path to that folder that you should specify as the argument to arduino-cli. That might seem silly if all you have in the folder is myfirst.ino, but sketches may consist of multiple files. All source files in the sketch folder are compiled.

If you are running the command from inside the sketch folder, you can simply omit the path argument and arduino-cli will automatically assume the current folder is the sketch. Or you can specify the path to the sketch folder if you prefer.

I could understand a user of the Arduino IDE assuming that the .ino file should work as the sketch path argument because in the Arduino IDE File > Open does require you to select one of the files of the sketch to open it, rather than the more correct behavior of having you select the sketch folder.

To confuse matters more, arduino-cli compile does compile the full sketch if you specify the path to a sketch file, but it names the output file according to the path argument. So even though the root problem is from your arduino-cli compile command, you don't encounter the result of that until you run arduino-cli upload.

Even though I think that specifying the path to the sketch file instead of folder is technically wrong, maybe the developers could consider making it so that arduino-cli automagically names the default output filename correctly if the path argument of arduino-cli compile points to a file instead of a folder, just as it already automagically handles compilation under that condition.

[noweare1]

Thanks for the very helpful explanation. That clears that part up for me.

I do not know what the upload process is looking for.

Adding the debug option to the upload command shows that it is not finding the tool required for
uploading to my stm32 board. When using the ide, upload runs stm32CubeProg.sh script which uses stm32cubeprogrammer CLI tool to upload to my board.

Looking at the output from the upload command....
The upload process seems to be loading every tool from each package that exists in .arduino15 directory.

I have looked for a wiki but maybe this project is too new to have all documentation in place.
It seems that it is important to have the arduino-cli.yaml file populated with the correct information so the upload process is successful. I don't know, kind of lost with this tool set.

[noweare1]

I successfully uploaded to my board but it was not straightforward.
I compared the differences between the IDE and CLI build.options.json files in the /tmp/directory
The main difference was the 'fqbn" line, which in the IDE was:

STM32:stm32:Nucleo_64:pnum=NUCLEO_F030R8,upload_method=swdMethod,xserial=generic,usb=none,xusb=FS,opt=osstd,rtlib=nano

and on the CLI was:

STM32:stm32:Nucleo_64

I copied the fqbn text from the IDE build.options.json into the upload command line so it looked like this:

arduino-cli  upload  -p /dev/ttyACM0 --fqbn STM32:stm32:Nucleo_64:pnum=NUCLEO_F030R8,upload_method=swdMethod,xserial=generic,usb=none,xusb=FS,opt=osstd,rtlib=nano  myfirst

I could successfully upload using this command. One other issue I had was that the compile command does not copy the bin file from /temp/projdir to my project path, so I had to move the bin file to my project directory so I could upload it.

Is there any documentation available that lets me know how I can do this the correct way. As I said everything works from the IDE so things should be set up correctly. From what I can see there is only the readme file for documentation.

[masci]

@noweare1 unfortunately, you're correct: the README is the only source of documentation we have at the moment.

I'll put this issue to the attention of the team, in your detailed report I see few major points we absolutely need to discuss and fix because your user experience was terrible and we want it to be the opposite.

I'll follow up on this issue as I manage to schedule some work to fix at least some of the problems you encountered, thanks again for your report.

[cmaglie]

@noweare1

Probably you don't need all of these parameters in the fqbn

pnum=NUCLEO_F030R8,upload_method=swdMethod,xserial=generic,usb=none,xusb=FS,opt=osstd,rtlib=nano

the CLI automatically selects the default value for all of them, maybe you just need one or two to be set specifically for you?
You can check the meaning for these params with the command:

arduino-cli board details STM32:stm32:Nucleo_64

[noweare1]

This is the minimum upload command I can get to work:

arduino-cli  upload  -p /dev/ttyACM0 --fqbn STM32:stm32:Nucleo_64:pnum=NUCLEO_F030R8,upload_method=swdMethod 

Thanks for hearing me out : )

[WalterHynson]

I connected the STM32F407 to the computer first ,then I turned on the arduino 1.8.10,I wrote a short blink program however It will not upload,I than installed st prg ,I tried the same thing and still no upload. The IDE sees the board but there is no port(its greyed out)but at the bottom of the ide it gives the port info PLEASE help or can someone explain what is wrong and how to correct it.

[amamory]

Related to the this same original issue, I decided to post here to share some partial progress. I am using Ubuntu 18.04.

I was trying to use stm32duino and CLI for a blue pill board.
I was able to compile and upload the blink application when I use the Arduino GUI (1.8.10).
Everything works fine with the GUI and the LED blinks as expected.

Then I tried to use arduino-cli (v0.9.0) with the same application. There were my steps once the sketch is created.

Compilation of stm32duino with arduino-cli

I managed to compile this app with arduino-cli, following these instructions in
with some adaptations and also this issue.

To compile the sketch, execute:

$ arduino-cli compile -v -b STM32:stm32:GenF1:pnum=BLUEPILL_F103C8

Uploading of stm32duino with arduino-cli

Once the sketch is compiled, the expected upload command was:

$ arduino-cli upload -p /dev/ttyACM0 -b STM32:stm32:GenF1:pnum=BLUEPILL_F103C8

However, it will cause a error because there is no Blink.STM32.stm32.GenF1.bin in the current folder.

Opening and parsing file: Blink.STM32.stm32.GenF1.bin
Error: The file Blink.STM32.stm32.GenF1.bin does not exist, please check the file's path

So, there are two alternatives. The first alternative is to find out the place in the /tmp where the project is being built and just copy the bin file
from there to the current dir, using the name Blink.STM32.stm32.GenF1.bin.
The second alternative is to create a bin file from the elf file using the following command:

$HOME/.arduino15/packages/STM32/tools/xpack-arm-none-eabi-gcc/9.2.1-1.1/bin/arm-none-eabi-objcopy Blink.STM32.stm32.GenF1.elf -O binary Blink.STM32.stm32.GenF1.bin

Now, repeat the upload, execute:

$ arduino-cli upload -p /dev/ttyACM0 -b STM32:stm32:GenF1:pnum=BLUEPILL_F103C8

and hopefully you will see the LED blinking and no up errors.

The issue

So, the issue is the the bin file is not created in the sketch folder for STM devices. Only the elf and hex were created. I believe that by generating the bin file the flow can be smother.

[nedseb]

I have exactly the same issue with the generation of the .bin file.

By removing of the file $HOME/.arduino15/packages/STM32/hardware/stm32/1.8.0/platform.txt the following line :

recipe.output.save_file={build.project_name}.{build.variant}.hex

The .bin file appear and the upload works without any other problem. I don't know if other upload methods need the hex file so I don't try to do a PR in STM32Duino

[fpistm]

Hi,
I've fixed the issue in the platform.txt of the STM32 core.
See stm32duino/Arduino_Core_STM32#1018

[per1234]

I think this issue ended up being about three separate topics:

• arduino-cli compile and arduino-cli upload have incompatible behavior when the path to a sketch file is provided as the argument.
  • This was fixed by Fix sketch metadata loader #690 (with a minor cosmetic issue reported in Unexpected output filenames when local sketch file is used as compile argument #691).
• Using FQBNs with custom configuration options is not well documented.
  • Some work has been done to improve this (e.g., Update FAQ.md #638, [skip changelog] Fix incorrect software specificity/non-specificity in documentation #652, improve find FQBN FAQ #274), but perhaps even more documentation is needed (e.g., Please specify instructions better #191 (comment), Board not supported message, even though it was detected #662 (comment)).
• Export file extension mismatch with upload pattern in the STM32:stm32 platform.
  • This was fixed in Arduino cli fix stm32duino/Arduino_Core_STM32#1018 and a universal fix is in the works in Compile extract all artifacts #687

So I think the issue has mostly been resolved, but I guess we can leave it open as a reminder to improve the documentation of using custom options in the FQBN, since I couldn't find another open issue dedicated to that topic.