Raspbian Stretch Lite could use a warning about its nonfunctional serial console

[marshallpierce]

https://www.raspberrypi.org/downloads/raspbian/ makes no mention of the fact that the serial console doesn't work out of the box on a RPi 3, and that you need to do the config.txt shenanigans in https://learn.adafruit.com/adafruits-raspberry-pi-lesson-5-using-a-console-cable/enabling-serial-console to get it working.

Better still, the .img could ship in a functioning state by default... As a new user of Raspbian (but not linux), this was pretty surprising: a distro that has a preconfigured user, but literally no way to log in as that user by default. Is this actually a desirable state for some arcane reason I'm not seeing?

[lurch]

IIRC the UART normally used for the serial console, is used by the bluetooth interface on the RPi 3 and Zero W.
https://www.raspberrypi.org/documentation/configuration/raspi-config.md has an easy-to-use option for enabling the serial console (which of course assumes that you're able to login using a locally-attached keyboard and monitor).

ISTR that there was lots of discussion about the UART being disabled-by-default when the RPi 3 first came out.

[marshallpierce]

OK, I don't need to reopen the UART discussion. My point is that given the loads of tutorials out there indicating that you can turn on a RPi and use its serial port (and the history of this working with previous models), it would be good to provide an easier path to the relevant change.

[lurch]

Adding a single line to the bottom of a text file isn't really that difficult is it? This documentation repo isn't really the place to be discussing this, but what kind of "easier path to the relevant change" did you have in mind? Perhaps http://pibakery.org/ is the kind of easy-to-use setup interface you're looking for?

I assume you must be aware of how small a minority of RPi users will ever want to connect to the serial console?

[marshallpierce]

I didn't say it was difficult. I'm saying that the need to add it is effectively hidden from anyone who doesn't already know to search for enabling UART on a Raspberry Pi 3.

If breaking a formerly commonplace method of initial setup without so much as a pointer that "hey, if you're used to doing X, you need to make change Y" seems like a good thing to do to you, then I guess I give up; I don't know how to explain any more plainly that that's poor impression to leave a user with.

Edit: to be clear, what I'm suggesting is adding a note to, say, https://www.raspberrypi.org/downloads/raspbian/ or https://www.raspberrypi.org/documentation/installation/installing-images/README.md that there are model-specific steps that need to be taken to get the serial console working, otherwise the myriad tutorials out there about using a serial console with RPi will get you nowhere.

[lurch]

Apologies if I gave the wrong impression, but I'm also only a community member like yourself, and my views may not reflect the views of the Raspberry Pi Foundation, etc. etc. 😃

[Doug-Wyman]

I am a lurker and need to comment.  Had I not seen this discussion, a project I have been working on (GPS) would have been delayed.I have a USB device coming.  That said, it is also arguable that if someone is going to be using a serial port they are or should belurking also.

…

On Thu, 2018-02-08 at 20:18 -0800, Andrew Scheller wrote: Apologies if I gave the wrong impression, but I'm also only a community member like yourself, and my views may not reflect the views of the Raspberry Pi Foundation, etc. etc. 😃 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.       {"api_version":"1.0","publisher":{"api_key":"05dde50f1d1a384dd78767c5 5493e4bb","name":"GitHub"},"entity":{"external_key":"github/raspberry pi/documentation","title":"raspberrypi/documentation","subtitle":"Git Hub repository","main_image_url":"https://cloud.githubusercontent.com /assets/143418/17495839/a5054eac-5d88-11e6-95fc- 7290892c7bb5.png","avatar_image_url":"https://cloud.githubusercontent .com/assets/143418/15842166/7c72db34-2c0b-11e6-9aed- b52498112777.png","action":{"name":"Open in GitHub","url":"https://github.com/raspberrypi/documentation"}},"updat ***@***.*** in #819: Apologies if I gave the wrong impression, but I'm also only a community member like yourself, and my views may not reflect the views of the Raspberry Pi Foundation, etc. etc. 😃 "}],"action":{"name":"View Issue","url":"#819 #issuecomment-364330746"}}}

[lurch]

This is an old topic that has been covered several times previously, see e.g. RPi-Distro/repo#22
(I'm not disagreeing that this could be better documented, but for the small minority if users this affects I don't think https://www.raspberrypi.org/downloads/raspbian/ is the right place to mention it IMHO)
*shrug*

[JamesH65]

Open to suggestion on where and how this could be improved.

…

On 9 February 2018 at 08:05, Andrew Scheller ***@***.***> wrote: This is an old topic that has been covered several times previously, see e.g. RPi-Distro/repo#22 <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_RPi-2DDistro_repo_issues_22&d=DwMFaQ&c=DpyQ_ftY536pf7wCBQXXU58xADDRY77THQzJu1OmzOo&r=w09_2ePv8G3zRjoV19Wm1Q6rI7CDlOns4PuRv2hHkek&m=HKH7bV9lHi9gZTO48OcZwo2zICdGv0NWiViGL3s2EQM&s=ZsvvmwTwLHyP-8hBkoxUOcxTveyhnIO_YK398jiUEcY&e=> (I'm not disagreeing that this could be better documented, but for the small minority if users this affects I don't think https://www.raspberrypi.org/downloads/raspbian/ is the right place to mention it IMHO) *shrug* — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_raspberrypi_documentation_issues_819-23issuecomment-2D364363289&d=DwMFaQ&c=DpyQ_ftY536pf7wCBQXXU58xADDRY77THQzJu1OmzOo&r=w09_2ePv8G3zRjoV19Wm1Q6rI7CDlOns4PuRv2hHkek&m=HKH7bV9lHi9gZTO48OcZwo2zICdGv0NWiViGL3s2EQM&s=IXNqqm9TAl8ay5DUuit0dxOc745aCYwsEe0CehSAV94&e=>, or mute the thread <https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_notifications_unsubscribe-2Dauth_ADqrHdClssbREEzoJLrlRimZUyqqvkEyks5tS-5FxYgaJpZM4R-5FNMb&d=DwMFaQ&c=DpyQ_ftY536pf7wCBQXXU58xADDRY77THQzJu1OmzOo&r=w09_2ePv8G3zRjoV19Wm1Q6rI7CDlOns4PuRv2hHkek&m=HKH7bV9lHi9gZTO48OcZwo2zICdGv0NWiViGL3s2EQM&s=umgElejEWtosLmbXPD_7ob9HTyR-Tcl_jS5_5E-XfPQ&e=> .

-- James Hughes Principal Software Engineer, Raspberry Pi (Trading) Ltd

[marshallpierce]

I think this particular bit of knowledge fits into a bit of a hole in the current layout of the documentation. Perhaps it will help to see the path I took to get here.

Context: Got Sparkfun's RPi 3 starter kit. This is my 3rd RPi (but my first RPi 3 w/ Raspbian), and I've been using Linux for many years. All I wanted to do was enable ssh so I could then forget about being physically proximal to the hardware. So, some quick searching confirmed (via many many people describing how to do it) that the FTDI UART/USB thing should be all I needed to easily perform that task.

Starting from the [root of Documentation](root of Documentation, https://www.raspberrypi.org/documentation/), I check out Setup. Nothing too surprising there -- I'm using Stretch Lite instead of Noobs because this RPi will be headless, and of course no keyboard or monitor because the internet tells me this serial dongle should work fine.

Next, Installation. Easy enough. I write stretch lite to the card, put it in the appropriate slot, and boot it up. I can see the appropriate LEDs come on, and it gets an IP from my DHCP server (via Ethernet). Of course, serial doesn't work. I go back and look carefully at tutorials that showed serial being easy and painless, and double check that hardware flow control is off, etc. Eventually I give up searching and go ask in IRC, where someone connects the dots and explains the UART boot config situation.

This is why I think that https://www.raspberrypi.org/documentation/installation/ is probably a good place to put such a warning. Verifying that the install boots and functions normally is a pretty typical part of installation, and it's where I would have expected to find any post-SD-card-copying instructions on getting a working system. The next section, Usage, implicitly requires that you be able to log in, so there does seem to be a gap there.

[lurch]

All I wanted to do was enable ssh so I could then forget about being physically proximal to the hardware.

Ah, so I guess you must have missed the Option 3 on https://www.raspberrypi.org/documentation/remote-access/ssh/README.md then? ;-)

Eventually I give up searching and go ask in IRC, where someone connects the dots and explains the UART boot config situation.

There's also https://www.raspberrypi.org/documentation/configuration/uart.md which didn't seem too hard to find?

[marshallpierce]

Ah, so I guess you must have missed the Option 3 on https://www.raspberrypi.org/documentation/remote-access/ssh/README.md then? ;-)

That's clever that you can do it without ever actually having local access, but given that 99.9999% of all configuration for a system requires local access, I claim that my assumption of "get local access, then proceed to ssh" is reasonable. Be that as it may, it's orthogonal to the issue here...

There's also https://www.raspberrypi.org/documentation/configuration/uart.md which didn't seem too hard to find?

It's easy to find if you already know that the problem is UART related, which I did not, and I think it's reasonable to assume most people will not.

[JamesH65]

Are you saying that because of the use of phrases serial console and UART, people are getting confused?

Technically the Pi has a UART which can be used as a serial console.

I'm still not sure what people want to change here, happy to look at PR's should people have an idea of how this can be improved.

[marshallpierce]

I'll make a PR with some hopefully clarifying notes when I have a moment.

[JamesH65]

@marshallpierce Did you ever have the chance to knock up something? I do not remember seeing anything coming through as a PR.