docs/Serial.md

   1 # Using a serial interface with U-boot and libreCMC
   2
   3 A serial interface (console) provides a means of debugging or
   4 unlocking features hidden from the user. Most computing devices
   5 have a serial interface whether it is broken out by the manufacture or not.
   6
   7 In the case of devices that run libreCMC, a serial console is used
   8 to configure U-boot and debug libreCMC if the network interface can't
   9 be brought up. These instructions outline the basics of using
  10 a serial console with a USB to serial cable.
  11
  12
  13
  14 ## The basics
  15
  16 There are a few different standards for serial interfaces, but here we are
  17 providing just the basics. There are 3 different connections that we care
  18 about : Transmit (TX), Receive (RX) and Ground (GND). Depending on the
  19 serial cable, the color coding could be different. The common coloration
  20 is RX is Green, TX is white and GND is black*.
  21
  22 These three wires will be connected to a pin header on the board or might need
  23 to be soldered to pads. Many device manufactures are kind enough to provide a
  24 header and indicate where the serial interface is. Look for silkscreen labeling
  25 with : GND, TX, RX. Sometimes additional work is needed to break out a stable
  26 serial interface.
  27
  28 * Many serial cables ship with the color corresponding to the connection on the board,
  29 so TX and RX are effectively reversed.
  30
  31 Some routers use the following standard:
  32 ```
  33          __________________
  34         |            |     |
  35         | .   .   .  |  .  |              <- Inside of the router (you may need to do some soldering)
  36         |____________|_____|
  37
  38           |   |    \     \
  39           *  GND   RX    TX
  40 ```
  41
  42 In this case, transmit is in the marked off box.
  43
  44
  45
  46 ```
  47          _________________
  48         |                 |
  49         | .   .   .    .  |
  50       * |_________________|
  51
  52           |   |    \     \
  53         GND   RX    TX   Vcc
  54
  55 ```
  56
  57 Some might use a dot to indicate GND, etc...
  58
  59 TPE-R1100 example:
  60
  61 ![alt text](images/serial.png "TPE-R1100 Serial")
  62
  63 Warning: NEVER connect the red wire to the device / router! You will most likely fry it because
  64 many routers use 3.3V for Vcc instead of the 5V provided by USB.
  65
  66 ## Getting a console
  67
  68 In order to communicate with the device, we need a terminal application to interact with
  69 the serial port provided by the USB to serial cable. In this case, we are going to use GNU Screen.
  70 Make sure that the GNU Screen package is installed and make sure that your user is part of the
  71 `dialout` group.
  72
  73 Before we can use the terminal application, we need to know the baud rate at which the serial
  74 console will be provided. With most devices running libreCMC and u-boot, this most likely will
  75 be 115200
  76
  77 ## Putting it all together
  78
  79
  80 1) Plug in / wire up the serial cable to the board.
  81
  82 2) Plug the USB part of the serial cable into an available USB port.
  83
  84 3) run `screen /dev/ttyUSB0 115200` or (if you are NOT part of the `dialout` group) `sudo screen /dev/ttyUSB0 115200`
  85 Please note that the serial device might have a different name (ttyUSB(n), ttyS0, etc...).
  86
  87 4) Power on the device you are connecting to.
  88
  89 5) You should see ledgible ASCII text scroll by.
  90
  91 If the device gets all the way through the boot process, the libreCMC banner will appear with
  92 a shell prompt:
  93
  94 ```
  95                     ____  _____  ____
  96   _ _ _            |  __||     ||  __|
  97  | (_) |__ _ _ ___ | |   | | | || |
  98  | | | '_ \ '_/ -_)| |__ | | | || |__
  99  |_|_|_.__/_| \___||____||_|_|_||____|
 100  -----------------------------------------
 101
 102 root@libreCMC:~#
 103
 104 ```