User Tools

Site Tools


doc:hardware:port.serial

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:hardware:port.serial [2013/02/11 06:05]
karlpinc Add kermit, since it's now open source --
doc:hardware:port.serial [2016/01/31 13:52] (current)
danitool [Terminal software] delete picocom duplicate, info about udev rule
Line 1: Line 1:
 +====== Serial Console ======
 +Most routers come with an [[wp>​Universal asynchronous receiver/​transmitter|UART]] integrated into the [[doc:​hardware:​soc|System-on-chip]] and its pins are routed on the [[wp>​Printed circuit board|Printed Circuit Board (PCB)]] to allow debugging, firmware replacement or serial device connection (like modems). The **[[doc:​techref:​bootloader]]** is responsible for listening on it.
  
 +  * -> [[doc:​hardware:​port.serial]] (this article)
 +    * -> [[doc:​hardware:​port.serial.cables]] (homemade cables)
 +    * -> [[doc:​hardware:​port.serial.utilization]]
 +      * -> [[doc:​howto:​generic.debrick]] there is content on utilizing JTAG  (link to it or from it, don't leave double content!)
 +      * -> [[doc:​techref:​bootloader]]
 +      * -> [[doc:​techref:​bootloader:​uboot]]
 +      * -> [[doc:​techref:​bootloader:​uboot.config]]
 +
 +
 +So in contrast to the [[doc:​hardware:​port.JTAG|JTAG-Port]],​ the Serial Port needs some software running on the CPU so we can use it! If the bootloader is damaged, or doesn'​t offer such a feature, the port is useless.
 +
 +{{page>​meta:​infobox:​cleanup&​noheader&​nofooter&​noeditbtn}}
 +
 +
 +Many people get along without a serial console for their device because they'​re able to flash a working firmware the first time - or are able to apply various recovery methods - and do all their communicating with the device over a network. ​ However, due to characteristics of their bootloaders,​ or because they aren't yet fully supported, for some devices it can be quite handy to have a compatible serial console available.
 +
 +Most devices supported by OpenWrt include a serial port. These serial ports typically provide a console to the bootloader and, when the firmware has booted, a console to the running system. Typically, a console to the bootloader will allow you to configure a network, fetch and flash a new firmware, which can be a life-saver when the firmware is broken. A console to the running system will let you correct a misconfigured network.
 +
 +===== Router Serial Connector Ports / Points =====
 +
 +All [[soc]]s have some sort of [[wp>​Universal asynchronous receiver/​transmitter|UART]],​ often in combination with a [[wp>​RS-232]]-Interface connected with the [[wp>​Printed circuit board|PCB]]. Now depending on the model, the device'​s serial port could be available
 +  * as a 9-pin D connector accessible from the exterior of the case, 
 +  * as pin headers on the PCB,
 +  * as unpopulated holes in the PCB.
 +
 +For help with the latter two, see [[soldering]]. But even if there is 9-pin D connector, beware the Voltage levels!
 +
 +Hint: in case of unpopulated holes try fitting the pins from a disassembled SubD9 male plug into the holes instead of soldering the cable directly to the board. Fit perfectly on unbricked Asus and TP-Link routers and leaves no trace. ​
 +
 +If the serial port is not readily accessible from the exterior of the device enclosure, you have some choices:
 +
 +  * modify the enclosure, either to allow passage of a cable or to attach a convenient connector, e.g.:
 +    * a 9-pin D connector (this is a good choice if you are going to build a level-shifter into the interior of the enclosure, so as to provide a standard +/- 12V interface externally);​
 +    * a 1/8-inch stereo headphone jack (this is a good choice if you are simply bringing the lines to the exterior)
 +  * open the case to attach to header pins or holes, as needed, this is a good choice if:
 +    * opening the enclosure is easy;
 +    * access to the serial port is needed only very occasionally;​ and/or
 +    * you have many devices you would rather not modify.
 +
 +===== Serial modes =====
 +
 +Sometimes by shortcutting some pins, connecting them to ground or to power you can change the serial mode. Some of them can help you to restore the bootloader since they allow you to write directly to memory or load something to ram through the serial connection, which can be useful for restoring a bootloader. Also if the original bootloader is password protected with this method you can replace it with a custom bootloader and bypass it.
 +
 +For example in lantiq danube socs the default mode is CFG 01, but changing to CFG 04 which is known as UART mode allows you to upload to ram through the serial connection and automatically execute a bootloader in ascii format through the serial connection.
 +
 +It is recommended that you don't try blindly to shortcut or connect to anything the pins as it can brick the device. Find documentation before doing anything.
 +
 +===== Voltage levels =====
 +
 +{{page>​meta:​infobox:​dangerous&​noheader&​nofooter&​noeditbtn}}
 +
 +|{{:​meta:​icons:​tango:​48px-dialog-warning.svg.png?​nolink}}| **Caution:​** Very few devices have standard [[wp>​RS-232]] +/- 12V serial ports, but in many OpenWrt-supported devices the serial ports operate at TTL voltage (sometimes 5V, most often 3.3V) levels, meaning you cannot use a standard serial or USB to serial cable: it will fry your board. |
 +
 +In order for the serial console to work, the logic levels on the wires should match those expected by your device. ​ The first step therefore is to determine which voltage levels are required. ​ Often, you can find this documented on the OpenWrt wiki or elsewhere.
 +
 +Check your device'​s voltage levels with this chart. For detailed description look [[http://​www.interfacebus.com/​voltage_threshold.html|here.]] In addition these levels are averages for the type of devices shown. ​
 +
 +{{:​doc:​hardware:​chart-ic-voltage-switching-levels-grpah.png|}}
 +
 +===== Talking and Listening =====
 +You will need a terminal emulation program on your computer, such as minicom, hyperterminal,​ etc.  The terminal emulation program needs to be configured to be compatible with your device, in particular, with regard to baud rate and flow control. ​ If you are using only three wires (GND, TX, and RX) then hardware flow control should be turned off; you aren't using the pins (RTS and CTS) necessary for it to work.  Rarely, the baud rate that the device expects //might// be different in the bootloader and the running firmware; if so, you'll need to modify the baud rate settings in your terminal emulator after the firmware boots up.
 +
 +Troubleshooting parts:
 +If you get something like this during the bootcycle (output is garbled)
 +
 +  ����������������������������������|� 2000-2008 Broadcom Corporation.
 +  Init Arena
 +  Init Devs.
 +  This is ���������������������?​����������?​����BCM4wXX����������������LJ����������0735750 - 0x80)
 +  BSS:        0x80739790 -   ​0x80���4���������~�~������߇~����������������������������������5.10
 +  The boot is CFE
 +
 +then probably the GND is not connected (soldered?) well. The router wont listen to any keyboard actions.
 +After solving the problem output should look fine.
 +
 +Another possible cause for the garbled output is wrong serial port speed, try different settings, most common ones are 9600, 38400 and 115200 bps.
 +
 +If you successfully receive router bootup logs but seem unable to send data (e.g. some keyboard input which might be required to intercept bootup, and where you're unable to stop continued kernel bootup), then this may be due to having configured the connection as hardware flow control rather than software (happened on TL-WDR3600 in my case).
 +
 +==== Terminal software ====
 +**Linux/​Posix:​**
 +  * [[man>​screen]]:​ the most simple, example: <​code>​screen /​dev/​ttyUSB0 115200</​code>​
 +  * [[http://​linux.die.net/​man/​8/​picocom|picocom]]:​ <​code>​picocom -b 115200 /​dev/​ttyUSB0</​code>​ if you need to send uboot.asc files via serial. ​ once connected you can open another terminal to send boot code as follows<​code>​cat openwrt-lantiq-ram-u-boot.asc > /​dev/​ttyUSB0</​code>​
 +  * [[http://​cutecom.sourceforge.net/​|CuteCom]] with a friendly KDE4 GUI
 +  * [[man>​Minicom]] (for POSIX systems)
 +  * [[http://​www.kermitproject.org/​|kermit]],​ a mature terminal emulator
 +  * [[man>​cu]] (part of the Taylor UUCP package, for POSIX systems)
 +  * [[http://​www.chiark.greenend.org.uk/​~sgtatham/​putty/​|Putty]]
 +
 +<WRAP center round info 60%>
 +Under a Desktop OS Linux distro the access to the serial adapter requires root permissions. We can override this behavior by making an udev rule. Create the file ''/​etc/​udev/​rules.d/​60-ttyUSBx.rules''​ with this content:
 +<code bash>​KERNEL=="​ttyUSB[0-9]", ​             MODE="​0666"</​code>​
 +This way you can access to USB UART device as a normal user.
 +</​WRAP>​
 +
 +
 +**Windows:​**
 +  * Hyperterm (comes with many versions of MS Windows)
 +  * [[http://​www.chiark.greenend.org.uk/​~sgtatham/​putty/​|Putty]] v0.59 or newer (now with serial console support!)
 +  * [[https://​sites.google.com/​site/​terminalbpp/​|Bray'​s Terminal]]
 +  * [[http://​www.vandyke.com/​products/​securecrt/​|Vandyke SecureCRT]] (commercial but very good)
 +**Other:**
 +  * Pocketterm ​ (for Palm PDAs)
 +  * [[http://​www.gnu.org/​software/​screen/​|GNU Screen]] (available on most OSes, including Windows (cygwin)) can connect to a serial device. The format is:<​code>​screen {path to device} {baud rate},​{options}</​code>​A common set of options (for setting 8N1) is ''​cs8,​-parenb,​-cstopb''​. For example, to connect to an Asus WL-520GU (115200 baud, 8N1) with a USB-serial adapter on OSX: <​code>​screen /​dev/​tty.SLAB_USBtoUART 115200,​-parenb,​-cstopb,​cs8</​code>​The command on Linux is the same with a different device path. For other routers, you may need to adjust the speed and options.
 +
 +==== Use your old PDA as a console ====
 +Since many older PDAs (e.g. Palm series) have TTL serial connections already, you can use them to get a direct serial connection to the router.
 +
 +Solder the RX, TX, and ground (but **never** Vcc) TTL-level connectors on the OpenWrt box to the PDA's TTL level serial connectors.
 +
 +Example: Palm IIIc, [[http://​www.neophob.com/​serendipity/​index.php?​url=archives/​121-Reuse-your-old-Palm-as-Serial-Console.html]].
 +
 +==== Use another OpenWrt router as a console ====
 +First [[doc/​recipes/​terminate.console.on.serial|disable the console]] in the router you want to use it as a serial console adapter and install screen in it. Connect to the target router the serial pins, and then execute screen in the first router:
 +<​code>​screen /dev/ttyS0 115200</​code>​
 +
 +==== Physical Connection ====
 +
 +==== Router with USB port ====
 +
 +For routers with a built in USB-connector (such as WNDR3700 for example), simply plugging in a USB-serial converter and installing the appropriate software will provide a serial console to the router.
 +
 +  * Install the appropriate packages, e.g. kmod-usb-serial and kmod-usb-serial-ftdi for FTDI based converters or kmod-usb-serial-pl2303 for prolific based converters
 +
 +  * Add the new serial port to /​etc/​inittab,​ (if you have multiple adaptors find the right one in /​proc/​tty/​driver/​usbserial):​\\ <code bash>​ttyUSB0::​askfirst:/​bin/​ash --login</​code>​
 +
 +Be aware, using this method relies on the kernel loading the modules so will only work once OpenWRT is up and running. ​ It won't bring you the possibility to use the bootloader console to reflash since the USB drivers on the router won't be running.
 +
 +==== Router with serial port / header / pins ====
 +In order to interact with your device over its serial port, you need a minimum of three wires connected: a ground (GND); transmit (TX); and receive (RX).  It is possible to get useful information about what is happening with only GND and RX, but in order to fix a problem you will usually also need TX.  Your computer'​s TX should be connected to the device'​s RX, and your computer'​s RX should be connected to the device'​s TX.  The computer'​s GND should connect the the device'​s GND.  That way, what you say will get heard by the device and what the device says will get heard by your computer. ​ This is often called a "​null-modem"​ configuration.
 +
 +Some things to consider:
 +
 +  * If your computer has a serial port, you can use a level-shifter (as necessary) and a "​null-modem cable"​.
 +  * If your computer has a USB port, then:
 +    * if your device uses standard RS232 logic levels, you can use a standard USB-serial converter along with a standard "​null-modem cable"
 +    * if your device uses TTL logic levels, you can use a USB-serial cable with a serial to TTL adaptor or a USB to TTL adaptor (that use the right TTL voltage) and a connector suitably wired to connect to your device.
 +  * If your computer has neither a serial port or a USB port, you are in trouble!
 +
 +These days, computer manufacturers are dropping RS232 serial ports, while USB ports are increasingly ubiquitous. ​ Particularly if you need to TTL logic levels, USB is probably the way to go since you can get the right logic levels (the voltage) integrated in the USB-TTL converter.
 +
 +See [[doc:​hardware:​port.serial.cables]] ​ for a variety of ways to make the physical connection from PC to router using homemade or commercial USB-serial and serial-serial cables.
 +===== Serial port pinouts =====
 +Pinouts for your model can often be found on your model'​s page: [[toh:​start]]
 +
 +===== Finding Serial Console =====
 +First, check the OpenWrt wiki page describing your hardware and do a Google search. Most of the time, the serial port(s), if they exist, have already been documented by others. If methods listed here are not enough for you, consider to go deeper reading http://​www.devttys0.com/​2012/​11/​reverse-engineering-serial-ports/​
 +
 +Finding an UART on a router is fairly easy since it only needs 3 signals (without modem signaling) to work: GND, TX and RX (often accompanied by VCC). Since your router is very likely to have its I/O pins working at 3.3V ([[wp>​Transistor–transistor logic|TTL]] level voltage), you'll need [[doc:​hardware:​port.serial#​usb.to.rs232.ttl.converter.module]] or a level shifter such as a Maxim MAX232 to change the level from 3.3V to your computer level which is usually at 12V.
 +
 +Check the table of hardware [[toh:​start]] for your router and if you don't find serial pinout there try looking for a populated or unpopulated 4-pin header, which can be far from the SoC (signals are relatively slow) and usually with tracks on the top or bottom layer of the PCB, and connected to the TX and RX.
 +
 +Once found, you can easily check where is the GND, which is connected to the same ground layer than the power connector. The VCC should be fixed at 3.3V and connected to the supply layer ; the TX is also at 3.3V level, but using a multimeter as an ohm-meter, if you find an infinite resistance between the TX and VCC pins, it means they'​re distinct signals (else, you'll need to find the correct TX or VCC pin). The RX and GND are by default at 0V, so you can check them using the same technique.
 +
 +If you don't have a multimeter, a simple trick that usually works is using a speaker or a LED to determine the 3.3V signals. Additionally,​ most PCB designers will draw a square pad to indicate pin number 1.
 +
 +Once found, just interface your level shifter with the device, and the serial port on the PC on the other side. Most common baud rates for the off-the-shelf devices are 9600, 38400 and 115200 with 8-bits data, no parity, 1-bit stop.
 +
 +==== Piezoelectric buzzer method ====
 +  - Use a Piezoelectric buzzer and attach its ground (usually black) wire to a ground point on the router; the back of the power regulators are usually good candidates, but check this with a multimeter/​voltmeter.
 +  - Use the other wire to probe any of the header pins which may be pre-installed,​ or any of the component holes which look like they could have header pins installed into (typically in a row of 4 pins for a serial port). ​ Reset the router. ​ The bootloader/​linux bootup messages will only happen for a few seconds, and after that, the serial console will be silent - so even if you have the right pin you will not hear anything.
 +  - Once you get the right pin, the Piezoelectric buzzer should make a screeching sound much like that of a 56kbps connection.
 +
 +==== Digital multimeter method ====
 +Typically there are four pins to identify: GND - Ground, Vcc - 3.3VDC or 5VDC, TXD - Transmit data, and RXD - Receive data.  There may be additional/​extra pins.  Every router is different.
 +  - Locate the set of four/​five/​more pins that are most likely to be the serial console.
 +  - Set the multimeter to measure resistance/​continuity. ​ Place the black probe on a known ground point and use the red probe to check each of the pins.  Whenever you see zero or nearly zero ohms resistance, that pin should be the GND connection.
 +  - Switch the multimeter to measure DC voltage on a scale greater than 10 but less than 100 volts. ​ Meters vary, but you should be able to select a range greater than five volts. ​ Place the black probe on the known ground point again, and with the router powered on, use the red probe to check the remaining pins of the port for steady 3.3V or 5V DC.  When you find it, that pin should be the Vcc connection.
 +  - This leaves two pins to identify: RXD and TXD.  It's easiest to find the router'​s TXD pin first, because all the console output from the boot process appears there. Connect the RXD pin of your level shifter to one of the remaining console pins and re-start the router. ​ You should have a terminal window connected to the serial port at the correct bitrate and parity, and you've connected the proper pin, you should see output data the router'​s startup process. ​ If not, try another pin, restarting the router until you receive valid output. ​ Now you've located the serial port TXD connection.
 +  - The only pin remaining is RXD, where the serial port receives data from your terminal session. ​ Connect the TXD pin of your level shifter to the remaining pin (or multiple pins) until you find the one that correctly echoes characters you type in your terminal session.
 +
 +==== Logic analyzer/​oscilloscope ====
 +A more accurate method would be to use either a logic analyzer or an oscilloscope,​ but these are expensive and for the basic task of locating a serial pin a little overkill. ;-)
 +
 +===== Serial port speed =====
 +If you want to change serial port speed read [[doc/​recipes/​serialbaudratespeed|this article]].
 +
 +{{tag>​wip}}