[docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks #592

salkinium · 2021-03-24T01:07:17Z

Fixes some issues in #591.
Closes #280.

I recommend downloading the homepage HTML artifact from the GH action, extracting the docs folder and then running python3 -m http.server --bind 127.0.0.1 8000 in it to browse the resulting homepage. It's much easier to see that way.

cc @rleh and @WasabiFan.

rleh

Nice work 👍🏽

CONTRIBUTING.md

docs/src/guide/installation.md

rleh · 2021-03-26T14:38:04Z

docs/src/guide/installation.md


+Unfortunately Windows is not a great fit for the command line tools that modm is
+built on. Consider using the [Windows subsystem for Linux (WSL)][winwsl] and


@salkinium Have you tested WSL (and/or WSL2) with modm?

Nope, I should probably do that…

I know @daixtrose was going to use modm on Windows with WSL 2(?); maybe hecan tell us it worked great? 😉

docs/src/guide/installation.md

src/modm/board/mini_f401/module.lb

salkinium · 2021-03-26T23:20:59Z

.github/workflows/linux.yml

@@ -143,7 +143,7 @@ jobs:
      - name: Examples STM32F4 Without Discovery Board
        if: always()
        run: |
-          (cd examples && ../tools/scripts/examples_compile.py nucleo_f401re nucleo_f411re nucleo_f429zi nucleo_f446re stm32f411ccu_mini_f401 stm32f411ceu_mini_f411 stm32f407vet6_devebox stm32_f4ve)
+          (cd examples && ../tools/scripts/examples_compile.py nucleo_f401re nucleo_f411re nucleo_f429zi nucleo_f446re black_pill_f401 black_pill_f411 stm32f407vet6_devebox stm32_f4ve)


Fun: stm32f411ccu_mini_f401 was never compiled because it wasn't spelled correctly.

Pimped the tools/scripts/examples_check.py script and a whole host of issues appeared 😱

$ python3 tools/scripts/examples_check.py The build path '../build/stm32_f4ve/gui' is outside of the 'modm/build' folder! - 'examples/stm32_f4ve/gui/project.xml': '../../../../build/stm32_f4ve/gui' The build path '../build/arduino_nano/color' is outside of the 'modm/build' folder! - 'examples/arduino_nano/color/project.xml': '../../../../build/arduino_nano/color' Linux CI is missing examples: 'nucleo_f439zi', 'nucleo_f446ze' Please add these example folders to the appropriate CI job in '.github/workflows/linux.yml'!

docs/src/guide/installation.md

salkinium · 2021-03-27T21:19:52Z

There are now more detailed HAL driver tables in the README:

![](https://user-images.githubusercontent.com/163066/112735118-7a787a80-8f4a-11eb-91ed-98545ba4c2a8.png)

rleh · 2021-03-27T21:44:52Z

Nice!!

Two ideas:

Some controller families don't have peripherals like Ethernet at all. Would be nice to distinguish between "physically not available" and "not (yet) implemented in modm".
What about putting the microcontroller families to the columns and peripherals as rows? Then it could also become one big table with all MCU vendors.

salkinium · 2021-03-27T21:51:43Z

Some controller families don't have peripherals like Ethernet at all. Would be nice to distinguish between "physically not available" and "not (yet) implemented in modm".

Yes, that's planned. It's just not super trivial to compute generically…

What about putting the microcontroller families to the columns and peripherals as rows? Then it could also become one big table with all MCU vendors.

Meh, I had that on the first try, it was too much visual noise.
Plus the same peripherals are not named the same nor are they truly comparable in features.
Keeping the families separate was much better.

rleh · 2021-03-27T21:58:20Z

Keeping the families separate was much better.

I'm sure I looks a lot better, but for actual use-cases ("Which controller should I choose if I need peripherals X, Y & Z?") one large table is much better suited in my opinion.

salkinium · 2021-03-28T00:05:33Z

I've added the mapping of available, but not implemented drivers via a cross, which I hope is understandable. What do you think? A question mark maybe?

![](https://user-images.githubusercontent.com/163066/112738263-aa7f4800-8f61-11eb-905c-3b2cc334d6eb.png)

I'm sure I looks a lot better, but for actual use-cases ("Which controller should I choose if I need peripherals X, Y & Z?") one large table is much better suited in my opinion.

Sure, but wouldn't that be much better with a complete table plus a JS filter? And you would probably want to query some more things related to pinout as well. I think that would be really amazing…

These tables are "just" about setting the right expectations about what the state of the HAL actually is for STM32. I don't want to put too much info on the front page or it'll scare people off.

salkinium · 2021-03-28T01:31:17Z

I "fixed" running OpenOCD in the background on Windows only to discover that arm-none-eabi-gdb does not support TUI mode on Windows and gdbgui dropped Windows support recently due to lack of gevents support.

So… I'm going to keep the fix but I cannot test it. Meh.

rleh · 2021-03-28T14:28:57Z

Proposal for a legend:

Available	Not yet implemented	Hardware does not exist
✅	🔜	❌

salkinium · 2021-03-28T14:45:05Z

I specifically chose non-emoji, monocolor symbols since they get filled with the chosen text color.

I definitely prefer the empty cell over anything else. This is what it looks like with dark theme, the arrow-soon emoji is barely readable:

![](https://user-images.githubusercontent.com/163066/112756243-93356e80-8fe4-11eb-969e-99c6d68a16e3.png)

Here is a test with a • instead of a cross for less optical noise, I think it's better than the cross.

![](https://user-images.githubusercontent.com/163066/112756310-ddb6eb00-8fe4-11eb-84e3-707f531a8e67.png)

There's an even thinner dot…

![](https://user-images.githubusercontent.com/163066/112756537-f70c6700-8fe5-11eb-8099-9281187fd542.png)

rleh · 2021-03-28T14:47:42Z

I consider the first one much more expressive and clear.

salkinium · 2021-03-28T14:59:15Z

I consider the first one much more expressive and clear.

Eh… really? Maybe without the red cross:

![](https://user-images.githubusercontent.com/163066/112756684-a9dcc500-8fe6-11eb-87c4-61f82856b2fb.png)

I would prefer the one with the small dot. It think channels your view first to the implemented drivers, then to the drivers not implemented yet and then to the unavailable drivers.

rleh · 2021-03-28T15:01:56Z

With this table I don't get which peripherals are not supported by modm and which are not available in hardware without reading the text...

rleh · 2021-03-28T15:02:20Z

I don't want to put too much info on the front page or it'll scare people off.

People are more likely to get scared off by information that is hard to understand than by a table with many entries (that we could put inside a <details> ... </details> section).

I expect the most readers of this README to not know what exactly "RCC", "UID", "COMP", "ETH", "FSMC", "RNG", "EXTINT" and "GCLK" refer to. (Not even I know for sure what all the names are about.)

rleh · 2021-03-28T15:09:46Z

Maybe:

Available	Not implemented	Hardware does not exist
✓	(✓)	✗

(non-colored icons; I personally prefer colored icons (which use the full color range of modern screens), but that is a matter of taste...)

salkinium · 2021-03-28T15:16:18Z

Hmmm, visually attention wise it's like: "(✓)" > "✓" > "✗"

![](https://user-images.githubusercontent.com/163066/112757166-e14c7100-8fe8-11eb-858b-a1ee10eafe0c.png)

This is like: "✓" > "·" > ""

![](https://user-images.githubusercontent.com/163066/112757181-ead5d900-8fe8-11eb-800c-e7c2706841c5.png)

What about this?

![](https://user-images.githubusercontent.com/163066/112757260-4607cb80-8fe9-11eb-9f35-0c29814ccf5d.png)

salkinium · 2021-03-28T15:22:20Z

People are more likely to get scared off by information that is hard to understand than by a table with many entries (that we could put inside a <details> ... </details> section).

Ok, fair point, let me try to put a big combi table in details there.

salkinium · 2021-03-30T00:11:46Z

No pressure, but I would like to land this within this week for the 2021q1 release.

rleh

Really nice work! Thank you very much @salkinium!

rleh · 2021-03-30T11:37:27Z

README.md

-<td align="center">SAMD21-MINI</td>
-<td align="center">STM32-F4VE</td>
-<td align="center">STM32F030F4P6-DEMO</td>
+<td align="center"><a href="https://modm.io/reference/module/modm-board-al-avreb-can">AL-AVREB-CAN</a></td>


Maybe a link to https://docs.modm.io/develop/api/al-avreb-can/ would be more useful here? The module reference page has only very little information.

Or better: All board module reference pages should contain links to https://docs.modm.io/

The plan was to link all modules to the Doxygen docs, I just couldn't get my code to work yet (dealing with ambiguous destinations).

See also #598.

docs/src/guide/custom-project.md

docs/src/guide/installation.md

src/modm/board/module.lb

rleh · 2021-03-30T12:47:26Z

Maybe you should somehow rename this PR, because "Windows installation" is only a very small part.

chris-durand

Very nice, thanks!

README.md

docs/src/guide/custom-project.md

salkinium · 2021-03-30T17:16:58Z

I also checked the generated homepage with broken-link-checker and fixed all links. Unfortunately https://eurobot.org is down?

salkinium · 2021-03-30T19:31:28Z

I'll be merging this next.

salkinium · 2021-03-30T20:26:41Z

Got this close to perfection… BLC didn't complain, since it wasn't a link… 🤦‍♂️

salkinium added documentation 📑 fix 💎 labels Mar 24, 2021

salkinium force-pushed the feature/windows-install branch from 556aed8 to ce0a401 Compare March 26, 2021 01:04

rleh reviewed Mar 26, 2021

View reviewed changes

salkinium force-pushed the feature/windows-install branch 2 times, most recently from 12758ae to 774c06f Compare March 26, 2021 23:19

salkinium commented Mar 26, 2021

View reviewed changes

salkinium force-pushed the feature/windows-install branch 2 times, most recently from 4a14415 to fab1209 Compare March 27, 2021 00:59

rleh reviewed Mar 27, 2021

View reviewed changes

docs/src/guide/installation.md Outdated Show resolved Hide resolved

salkinium force-pushed the feature/windows-install branch 2 times, most recently from 556ca1f to 1646b0f Compare March 27, 2021 21:17

salkinium force-pushed the feature/windows-install branch from 1646b0f to 1a9a935 Compare March 28, 2021 00:00

salkinium force-pushed the feature/windows-install branch from 1a9a935 to 7108402 Compare March 28, 2021 01:29

salkinium force-pushed the feature/windows-install branch from 7108402 to 5d9e17f Compare March 28, 2021 01:34

salkinium mentioned this pull request Mar 29, 2021

Getting Started guide is confusing #280

Closed

salkinium requested review from rleh and chris-durand March 30, 2021 00:10

rleh approved these changes Mar 30, 2021

View reviewed changes

salkinium changed the title ~~[docs/tools] Improve Windows installation and support~~ [docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks Mar 30, 2021

salkinium force-pushed the feature/windows-install branch from 641eec2 to b127c01 Compare March 30, 2021 15:47

chris-durand reviewed Mar 30, 2021

View reviewed changes

README.md Show resolved Hide resolved

docs/src/guide/custom-project.md Outdated Show resolved Hide resolved

salkinium force-pushed the feature/windows-install branch from b127c01 to 5a6be43 Compare March 30, 2021 17:14

salkinium mentioned this pull request Mar 30, 2021

2021q1 release #597

Merged

12 tasks

salkinium added 13 commits March 30, 2021 21:16

[ci] Add homepage test build as artifact

910c5f3

[tools] Remove unused scripts from xpcc transition

82a3538

[tools] Fix AvrDude input confusion on Windows

cab5c97

[tools] Fix running OpenOCD in background on Windows

ad88d11

[board] Fix missing NUCLEO-F439ZI board.hpp

1e623cf

[boards] Consistent naming for all pill boards

b3d0459

[examples] Consistent naming for all pill boards

c8da390

[examples] Fix STM32F3 Discovery GDB example

eb2efbf

[tools] Improve example check script and fix issues

8cd153c

[docs] Add better Windows install instructions

01f0422

[docs] Rewrite getting started guide

2b4e075

[docs] Add URLs to board and driver list in README

396d38b

[docs] Add generated HAL driver support tables

c528dc2

salkinium force-pushed the feature/windows-install branch from 5a6be43 to c528dc2 Compare March 30, 2021 19:16

salkinium added the ci:hal Triggers the exhaustive HAL compile CI jobs label Mar 30, 2021

salkinium merged commit c528dc2 into modm-io:develop Mar 30, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks #592

[docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks #592

salkinium commented Mar 24, 2021 •

edited

Loading

rleh left a comment

rleh Mar 26, 2021

salkinium Mar 26, 2021

rleh Mar 26, 2021

salkinium Mar 26, 2021

salkinium Mar 27, 2021

salkinium commented Mar 27, 2021 •

edited

Loading

rleh commented Mar 27, 2021

salkinium commented Mar 27, 2021 •

edited

Loading

rleh commented Mar 27, 2021

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 •

edited

Loading

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 •

edited

Loading

rleh commented Mar 28, 2021

rleh commented Mar 28, 2021

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 30, 2021

rleh left a comment

rleh Mar 30, 2021

rleh Mar 30, 2021

salkinium Mar 30, 2021

salkinium Mar 30, 2021

rleh commented Mar 30, 2021

chris-durand left a comment

salkinium commented Mar 30, 2021

salkinium commented Mar 30, 2021

salkinium commented Mar 30, 2021


		Unfortunately Windows is not a great fit for the command line tools that modm is
		built on. Consider using the [Windows subsystem for Linux (WSL)][winwsl] and

[docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks #592

[docs/tools] Rewrite installation/getting started guides, add HAL support matrix, fixes for Windows, more CI checks #592

Conversation

salkinium commented Mar 24, 2021 • edited Loading

rleh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

salkinium commented Mar 27, 2021 • edited Loading

rleh commented Mar 27, 2021

salkinium commented Mar 27, 2021 • edited Loading

rleh commented Mar 27, 2021

salkinium commented Mar 28, 2021 • edited Loading

salkinium commented Mar 28, 2021

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 • edited Loading

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 • edited Loading

rleh commented Mar 28, 2021

rleh commented Mar 28, 2021

rleh commented Mar 28, 2021

salkinium commented Mar 28, 2021 • edited Loading

salkinium commented Mar 28, 2021 • edited Loading

salkinium commented Mar 30, 2021

rleh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rleh commented Mar 30, 2021

chris-durand left a comment

Choose a reason for hiding this comment

salkinium commented Mar 30, 2021

salkinium commented Mar 30, 2021

salkinium commented Mar 30, 2021

salkinium commented Mar 24, 2021 •

edited

Loading

salkinium commented Mar 27, 2021 •

edited

Loading

salkinium commented Mar 27, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading

salkinium commented Mar 28, 2021 •

edited

Loading