search

RIOT-OS / RIOT

RIOT - The friendly OS for IoT
https://riot-os.org
GNU Lesser General Public License v2.1
4.87k stars 1.98k forks source link

doc/boards: information concerning access to RIOT shell #17453

Open krzysztof-cabaj opened 2 years ago

krzysztof-cabaj commented 2 years ago

Description

When I try connecting to RIOT shell flashed at RPi-pico board, I cannot find any details concerning connection in board documentation. This could be a problem, especially for users not familiar with microcontrollers. After some investigation of documentation for dozen boards, I find that this information is inconsistent and, in many boards, missing. For example, sections that contain this kind of information are titled: Accessing STDIO via UART, Using UART, STDIO configuration or simply STDIO - to mention a few. Sometimes this title does not correspond to reality, for example, title Accessing STDIO via UART and the first sentence: "STDIO of RIOT is directly available over the USB port" ... where board uses CDC-ACM USB module. Only in the documentation of one board I find a connection baud rate, however few are used.

In this issue I would like to introduce and discuss some common style of such information. Of course, all information could be found in the Internet or simply checked/guessed, but such information, especially for people starting with RIOT would be beneficial.

Section title: Accessing RIOT shell

Necessarily information:

This section should be placed just after the section describing the flashing procedure.

Useful links

Sample connection description using this style: PR #17454

I'm looking forward comments and suggestions.

maribu commented 1 year ago

With https://github.com/RIOT-OS/RIOT/pull/17454 merged, can this be considered as solved?

krzysztof-cabaj commented 1 year ago

I open this issue to note some lacks in board documentation - which could be a problem for newbie. I checked today first 8th boards in the documentation and only 5 has any information concerning accessing RIOT shell, but many mentioned in this issue, in my opinion important information is lacking. I don't count but I think similar ratio is in nucleo boards ... and probably in all other boards.

On one hand, the issue is unsolved - and there is still undone work in boards documentation concerning this issue topic. But, from the other hand, nobody adds such description to other boards.

If you think that there is chance that somebody else could add such description to boards documentation we could leave this issue opened.