docs: Add a new variant (board) and "Generic System Clock configuration"

[thernstig]

I had a hard time understanding https://github.com/stm32duino/Arduino_Core_STM32/wiki/Add-a-new-variant-%28board%29#3---generic-system-clock-configuration.

I am quoting the parts I found hard and what I felt was missing/strange:

Go to Pinout tab, enable the desired peripherals which require specific clock configuration (not needed for peripherals clocked by HCLKx, or APBx clock): SDIO, USB, ... In this example only USB needs to be enabled as other peripherals default clock are correct by default.

What is "desired peripherals" here? How would I know what to enable?

Set PLL Source Mux to HSI.

There is no PLL Source Mux for the MCU I added in #2556. The sentence is written like it is something that should exist, but it does not seem true for all MCUs.

[thernstig]

In addition, this part:

6 - Restart
Restart Arduino IDE and try one of the new entry with the CheckVariant example.

It mentions nothing on how to do this on that above page. Should there have been a link to somewhere on how to load the new board into Arduino to test it?

[fpistm]

The board should appears in the menu you add it that's all. Select it and voilà.

[thernstig]

@fpistm I am talking about an unreleased version of Arduino_Core_STM32. Then the new board does not immediately show up in the JSON file does it?

[fpistm]

Yes. I need to perform a release.
But if you use the git repository in the Arduino package you will see it.

[thernstig]

@fpistm I think this part:

But if you use the git repository in the Arduino package you will see it.

Is not explained from https://github.com/stm32duino/Arduino_Core_STM32/wiki/Add-a-new-variant-%28board%29#6---restart.

How would one know how to do this? I just started with both Arduino and STM32, so consider it from a point from someone who never used these tools before (even though understanding the basics).

[fpistm]

It is explained here: https://github.com/stm32duino/Arduino_Core_STM32/wiki/Using-git-repository

Feel free to propose update, it is a community project.

[thernstig]

I would propose a lot more if I knew the answers 😆

[thernstig]

Wrote #2559 as a separate issue.

The two core issues of this topic are still valid. I do not know how to update those as I have no idea what those parts in reality mean.

[thernstig]

@fpistm Not sure why this was converted into a discussion. The Wiki is ambiguous and mentions things that do not exist for all MCUs in STM32CubeMx.

[thernstig]

@fpistm understood I am in the advanced section, but I still think things can improve 😄

It is more clear. But I do not understand why you list all dependencies and have this text:

To get started with development on main branch, correct versions of the required dependencies have to be installed

If the only thing one has to do to install the latest dependencies in the Arduino IDE is to use the https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/dev/package_stmicroelectronics_index.json file, then I see no meaning to list all those dependencies. The wiki's purpose must be to just show quickly how to use the latest boards on main?

I would also rephrase the title possibly. I think "Using git repository" could be interpreted in many ways. It would be clearer maybe to say "How to use the latest unreleased version of STM32duino". That it is done by cloning the git repo is an implementation detail.

The best thing would of course be if you could setup the Github workflows so the artifact https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/dev/package_stmicroelectronics_index.json was updated to point to the latest parts from this repo so the only thing users had to do would be to add the https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/dev/package_stmicroelectronics_index.json in the "Additional boards manager URLs" in the Arduino IDE, and not have to do anything else 🙂 And even build such a .json file per commit, so people can test their own commits.

[fpistm]

I will rephrase as suggested.
About Artifact and json generation (daily or weekly) is something I've already considered, but time is missing for that.
This could be fine for other users to test but the main goal of using the git repo is also to develop/test before to provide a PR and so you have to use the git repo.

[fpistm]

And thanks a lot for all your great suggestions and contributions. Very appreciated. 👏

[thernstig]

Got it. Well I think you can leave it as-is then now. Better focus in the future on seeing if each commit can build a JSON file. Would be much more testable. Maybe even testable via the Ardunio CLI directly in CI!

[fpistm]

Ci already use the dev json file else it will not build when dependencies are updated. 😉