Tutorial (Serial) console access via 'USB-UART/Gadget mode' on Linux/Windows/OSX

[chwe]

Access to a console can be mandatory when you SBC doesn't work as expected (e.g Network or HDMI output doesn't work). When SSH/Display access isn't possible access to console via UART is the best way to get a clue where your SBC hangs. This short tutorial should give you an introduction how this works. For some boards, armbian implements an USB gadget mode (a 'fake' serial console over microUSB) describen below. As a reminder an USB-UART bridge is always prefered over USB gadget mode whenever possible (UART get's initialized before the gadget driver and also before HDMI, means even if you don't get a proper output from HDMI or gadget mode console, it is possible that UART will give you the needed information).

 

Prerequisites:

We need an Terminal program to access the console. If you use Linux on your host system I prefer picocom (something like minicom will also do the job) which can be installed:

on debian a like systems:

sudo apt-get install picocom

from arch community repo:

https://www.archlinux.org/packages/community/x86_64/picocom/

 

on fedora systems:

yum install picocom

on Mac OS X:

brew install picocom

on Widows we use PuTTY:

Spoiler

(source: https://de.wikipedia.org/wiki/PuTTY#/media/File:PuTTY_Ubuntu.png --> putty on ubuntu)

 

https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

 

UART USB Adapter:

There are various USB-UART bridges e.g FT232 (and fakes of them, cause FDTI is expensive ), CH340/1,PL2303 or CP2102

Normally it doesn't matter which one you use. I prefer the (probably fake) FDTI on the right side, but the CH341 does also a good job:

The only thing which is needed is that the signal-level matches with your SBCs needs (this is mostly 3.3V expect some Odroids e.g HC1 which has only 1.8V!).  Most of these USB-UART bridges have jumpers for 5V and 3.3V, make sure that you use the 3.3V.  

You've to figure out which pins on your SBC are debug UART (they've mostly a own 3 pin header, sometimes it's on the large pin header e.g. Tinkerboard) and then connect:

GND --> GND
RX  --> TX
TX  --> RX

You've to check dmesg (linux) or run devmgmt.msc (windows) to know which device you use. 

Linux:

[256597.311207] usb 3-2: Product: USB2.0-Serial
[256597.402283] usbcore: registered new interface driver ch341
[256597.402341] usbserial: USB Serial support registered for ch341-uart
[256597.402392] ch341 3-2:1.0: ch341-uart converter detected
[256597.404012] usb 3-2: ch341-uart converter now attached to ttyUSB0

--> Device will be /dev/ttyUSB0

Windows:

for windows 10 (https://www.google.ch/search?client=opera&q=find+arduino+port+windows+10&sourceid=opera&ie=UTF-8&oe=UTF-8)

Quote

Open the Device Manager window by right-clicking the Windows 10start button in the lower left of the screen and then selecting Device Manager on the menu that pops up. In Device Manager, expandPorts (COM & LPT) and you should see a COM port which will be your Arduino as shown in the image below.

Something like the picture in USB Gadget Mode part of the tutorial should show up)

 

Armbians default settings are (expect some RK devices):

For Picocom:

picocom -b 115200 -r -l /dev/ttyUSB0

and for some RK devices:

picocom -b 1500000 -r -l /dev/ttyUSB0

For PuTTY:

You've to set configuration in 'Serial'. COM11 is just an example and needs to be checked first, Speed (baud) needs to be changed when you deal with the few RK boards which need 1500000.

 

OS X:

TBD

should be similar to Linux whereas the naming differs a bit. See: https://forum.odroid.com/viewtopic.php?f=53&t=841 as an example with minicom.

 

Normally you connect the USB-UART bridge to your host computer (and the SBC) and start picocom/putty before you power the board to ensure you get the full bootlog and not only parts of it. 

 

USB Gadget Mode

Several board (see list) for which official armbian images exist (or csc images can be built) have no HDMI display. On those boards there's USB gadget mode driver activated so that you can have console access to them via USB connection. The following short tutorial describes how you can access to console from Linux (don't have a windows machine here at the moment, I may check it later):

 

• install picocom
• connect your board via USB to your host computer (it should be one which is able to power an SBC via its USB port)
• check dmesg for the device showing up: 

  [184372.603816] usb 3-2: Product: Gadget Serial v2.4
  [184372.603818] usb 3-2: Manufacturer: Linux 4.14.65-sunxi with musb-hdrc
  [184372.660041] cdc_acm 3-2:2.0: ttyACM0: USB ACM device
  [184372.660402] usbcore: registered new interface driver cdc_acm
  [184372.660403] cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters

   

• connect to it via picocom (in this case 'picocom /dev/ttyACM0'): 

  chwe@chwe-acer:~$ picocom /dev/ttyACM0
  picocom v2.2
  
  port is        : /dev/ttyACM0
  flowcontrol    : none
  baudrate is    : 9600
  parity is      : none
  databits are   : 8
  stopbits are   : 1
  escape is      : C-a
  local echo is  : no
  noinit is      : no
  noreset is     : no
  nolock is      : no
  send_cmd is    : sz -vv
  receive_cmd is : rz -vv -E
  imap is        : 
  omap is        : 
  emap is        : crcrlf,delbs,
  
  Type [C-a] [C-h] to see available commands
  
  Terminal ready
  Debian GNU/Linux 9 orangepizero ttyGS0
  
  orangepizero login: root
  Password: 
  You are required to change your password immediately (root enforced)
  Changing password for root.
  (current) UNIX password: 

   

I assume if you use the same settings in something like putty on windows and you check which 'serial' device shows up in *where windows shows connected devices - I forgot it* you should be able to access it from windows (someone motivated may confirm this).  

For Windows:

run devmgmt.msc and search for the serial device (in this case COM3) and connect to it via PuTTY (thanks to @hjc):

for windows 10 (https://www.google.ch/search?client=opera&q=find+arduino+port+windows+10&sourceid=opera&ie=UTF-8&oe=UTF-8):

Quote

Open the Device Manager window by right-clicking the Windows 10start button in the lower left of the screen and then selecting Device Manager on the menu that pops up. In Device Manager, expandPorts (COM & LPT) and you should see a COM port which will be your Arduino as shown in the image below.

(even the tutorial is for arduinos, it should be similar for every 'COM device')

 

Currently boards with USB gadget mode:

• bananapim2plus
• bananapim2zero
• nanopifire3
• nanopim3
• nanopineo2
• nanopineocore2
• nanopineoplus2
• orangepizeroplus
• nanopiair
• nanopiduo
• nanopineo
• olimex-som204-a20
• orangepilite
• orangepi-r1
• orangepizero
• orangepizeroplus2-h3
• orangepizeroplus2-h5
• tritium-h3

 

The silly approach

For those, who want to save 1$ for an USB-UART bridge, you can spend 10$ for an OrangePi Zero and use its spare UARTs to log into an other SBC...  SSH --> opi, ttl --> Tinkerboard

For those loving text more than videos:

• SSH to your SBC
• sudo armbian-config --> system --> hardware  to activate an spare UART (in this case it was UART2, will give you ttyS2)
• reboot

• picocom -b 115200 -r -l /dev/ttyS2

   

 

See:  https://asciinema.org/a/B87EOGhc0gx9oikMAGEG94lXR

 

Spoiler

also works with circles... 

 

see: https://asciinema.org/a/bII8nLIfmUnGHXKaylIqoLzXW 

 

Edited October 1, 2018 by chwe
table updated, windows tutorial added, USB-UART added, silly approach added, added some background info

[tkaiser]

17 hours ago, chwe said:

Just a short one which we can link to in case we need it for debugging end-users board

 

Well, if this article is meant to be something for an average Armbian user you should IMO elaborate a bit on what a serial console is and how it's possible over an USB cable. Also not looking at this from the Windows perspective (ignoring +90% of our users?) makes the whole attempt more or less useless. And then I don't understand how you built the list of affected boards (since those the feature has been implemented for are all missing: the inexpensive and headless H2+/H3 boards)

[hjc]

19 hours ago, chwe said:

you should be able to access it from windows (someone motivated may confirm this).  

It works great on Windows Server 2016 (so probably Windows 10, too). Now I'm playing with my NanoPi on the desktop workstation in my office.

 

 

It's easy to use, run devmgmt.msc, find the serial device, then go with putty.

[chwe]

5 hours ago, tkaiser said:

Also not looking at this from the Windows perspective (ignoring +90% of our users?)

If I would have a running windows machine at the moment..  I would test it...  but thanks to @hjc I may copy it partly in the starter..

5 hours ago, tkaiser said:

And then I don't understand how you built the list of affected boards

updated.. I guess there was an u too much in uniq.. But this one should be correct now.

grep "g_serial" * | awk -F. '{print $1}' | uniq

 

5 hours ago, tkaiser said:

average Armbian user you should IMO elaborate a bit on what a serial console is and how it's possible over an USB cable.

If you think the average armbian user doesn't know the console you set the bars low  Calling it a serial console is IMO questionable,  serial drivers are loaded a way earlier in the kernel than g_serial. Whenever possible, we should force people to use a real UART-USB adapter and g_serial should only be 'promoted' if the user doen't have a adapter. 

[chwe]

10 hours ago, tkaiser said:

Well, if this article is meant to be something for an average Armbian user you should IMO elaborate a bit on what a serial console is and how it's possible over an USB cable. Also not looking at this from the Windows perspective (ignoring +90% of our users?)

updated with a short one for USB-UART bridges as well.. I even found an old print screen for PuTTY . Happy(er)? well for the 'how is this possible part' It's a 'fake UART' not sure if this is important from a users perspective... 

[maxlinux2000]

Hi all, is there a way to fix the characters set problem using uart?

 

look the pics below....

the forwarded terminal is using the ttl usb adapter with minicom

the second is via ssh connection

 

both is showing "armbian-config"

[thuyle90]

Hi all,

I'm sorry for comment upon .I am just a beginner and I followed instruction but it seems didn't work with me or I did something wrong. Can anyone please help me?

 

I followed instruction and tried to enable all uart port. But it seems didn't work. 

I'm waiting answer from you. Thank you every one and happy new year

[lanefu]

Try a different program for your uart such as tio

 

Also try

 

export TERM=xterm && reset

 

Or

 

export TERM=linux && reset

[thuyle90]

On 1/3/2021 at 8:37 PM, lanefu said:

Try a different program for your uart such as tio

 

Also try

 

export TERM=xterm && reset

 

Or

 

export TERM=linux && reset

Thank you, I tried also tio and mobaxterm. But it's also not working. 

Can any one help me!

[denni_isl]

On 1/4/2021 at 4:36 PM, thuyle90 said:

Thank you, I tried also tio and mobaxterm. But it's also not working. 

Can any one help me!

 

One should of course use just USB serial adapter.  Try to use minicom or screen.   Here are some info about to set up minicom http://wiki.t-firefly.com/en/ROC-RK3399-PC-PLUS/debug.html#use-serial-debug-on-ubuntu

The main thing is the correct bout rate.  Usually you just have to connect gnd tx and rx (not 3,3 or 5v)

[thuyle90]

On 1/8/2021 at 8:12 PM, denni_isl said:

 

One should of course use just USB serial adapter.  Try to use minicom or screen.   Here are some info about to set up minicom http://wiki.t-firefly.com/en/ROC-RK3399-PC-PLUS/debug.html#use-serial-debug-on-ubuntu

The main thing is the correct bout rate.  Usually you just have to connect gnd tx and rx (not 3,3 or 5v)

thank you denni

[gounthar]

Hello there 👋

Under Windows, does the Putty speed setting override the serial port speed setting?
My COM3 is detected/set at 115200 which works fine with my NanoPi Duo2, but changing to 115000 for my NanoPi R5S does not work.
Any idea?
Thanks.

[Joe Nice]

Hello guys, having problem with devices feedback. I have few odroid devices XU4 and HC1 and none of them receiving input while  typing in putty or minicom. However i may see full boot log in terminal. I tried to disable hardware flow control but it does not work. I do connecting rx to tx and tx to rx and gnd to gnd pins. My usb-ttl adapters: CP1204 and FT232rl