Serial adapters
Connectors (serial ports) are exposed on the XO laptop motherboard which allow developers to perform advanced diagnostics. When hooked up to another computer, the serial console allows you to:
- View firmware messages as the system is booting (even before the display is initialized)
- Interrupt the booting process at the firmware level and execute forth commands
- View kernel messages as Linux is booting (even before the display is initialized)
- Access a root shell
A special cable and adapter board is needed for this. If your development efforts would benefit from having this connection available, please approach your OLPC technical contact directly or ask on the devel mailing list. Alternatively, you can construct your own adapter based on the detailed information below.
The connectors
To access the connectors, you must disassemble the laptop to the point where you can access the top side of the motherboard. See Disassembly top for instructions.
Here is what the connector looks like:
XO-1
The XO-1 laptop has two serial ports provided for low level debugging. One (J1) is connected to the serial console on the main processor (Southbridge, actually). The second (CN24) is connected directly to the embedded controller on the motherboard. The connector is just below the yellow block labelled "+3.3V Power Supply" on the photo at XO Motherboard
XO-1.5
The XO-1.5 has a serial port connected to the main processor. The white connector can be found directly to the left of the DCON chip, up and to the left of the RAM (refer to XO 1.5 Motherboard). The connector is labelled "J4".
XO-1.75
The XO-1.75 has five serial ports:
- UART 1, is connected to the CPU, has a difficult to access pinout on a diagnostics port, is generally not used,
- UART 2, is not connected,
- UART 3, CN8, connected to the CPU, has the usual white connector pinout, and is used by CForth and Open Firmware,
- UART 4, CN23, connected to the CPU, has the usual white connector pinout, is used by CForth and potentially for kernel debugging,
- CN14 connected to the embedded controller, has the usual white connector pinout, is used by the EC firmware only.
XO-4
The XO-4 has three serial ports:
- UART 1, CN23, connected to the CPU, has the usual white connector pinout, and is used by CForth and Open Firmware,
- UART 2, CN18, connected to the CPU, is usually not populated, is used by CForth and potentially for kernel debugging,
- CN19, under the heat spreader, connected to the embedded controller, has the usual white connector pinout, is used by the EC firmware only.
The XO-4 has two additional serial ports that are not available for use:
- UART 3, is not configured and has no connector,
- UART 4, is connected to the touchscreen controller for reprogramming.
How do I get one?
OLPC-ready serial adapters are available for a small charge from http://iLoveMyXO.com directly from their blog at http://iLoveMyXO.wordpress.com
See OLPC's Spare Parts page as well as http://twitter.com/iLoveMyXO for possible late-breaking availability announcements.
Connecting up
The OLPC serial kit includes a cable which you can connect to the connector identified above. The other end of this cable gets plugged into the serial board (also included in the serial kit). The connector on the serial board is annotated with the colours of the wires - make sure to line the connector up correctly.
On the other side of the serial board, you will see a USB B-type connector. Taking a regular USB A-to-B connection cable (not provided by OLPC, but you can find these at any computer shop, they are the same cables typically used for USB printers), connect this board to the USB port of the other computer where you will be performing the diagnosis. The device will then be recognised as a USB-serial port, and you are good to go.
Software
The TTL<->USB chip is a a FT232R made by FTDI and has drivers for all major operating systems. The serial console can then be operated through any standard terminal application using the following settings:
- 115200 baud
- 8 data bits
- No parity
- 1 stop bit
- Handshake disabled
- Hardware flow control disabled
- In the USB modes the hardware flow control pins are wired so that they are de-asserted. Therefore the hardware flow control setting does not matter. The RS232 flow control lines on the DB9 were left unconnected and can float such that the flow control is asserted. So in RS232 modes hardware flow control must be disabled.
- Initialization string: none
- Reset string: none
Linux
Plug in the adapter and the kernel will create a device /dev/ttyUSB0, or later.
To connect to the serial console, use screen:
screen -L /dev/ttyUSB0 115200
- the -L flag creates a log file, such as screenlog.0,
- replace /dev/ttyUSB0 with whatever device is appropriate,
- the 115200 specifies the baud rate,
When screen is running:
- what you type is sent to the serial console,
- incoming serial console data is displayed,
Several keyboard shortcuts can be used:
- use ctrl+a ctrl+d to detach from the screen, then to reattach: screen -r,
- use ctrl+a ctrl+b to send a BREAK. Open Firmware responds to a BREAK by interrupting the currently executing code. Linux can be configured to respond to a BREAK.
- use ctrl+a ctrl+a to send a ctrl+a,
- use ctrl+a K to close the screen "window" for the connection and terminate screen.
Some things that might go wrong:
- if you use an XO as the host, screen may be missing because it is not included in our builds, you may install it using yum.
- screen is configured slightly differently across our builds with respect to the terminate key, ctrl+a \ works on 11.2.0, but not 10.1.3, but ctrl+a K works with both.
- some hosts, including XOs with recent OLPC OS builds, include a USB modem detector, modemmanager, which opens any newly plugged serial adaptor, configures it for 57600 baud, and transmits AT commands to elicit a response from a modem. This may interfere. Either connect the coloured serial cable after starting screen, or remove ModemManager package, or stop the process, or edit the udev rules to exclude the serial adaptor.
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ENV{ID_MM_DEVICE_IGNORE}="1"
- if you use an XO as the host, with power management enabled, the /dev/ttyUSB0 device may disappear as a result of suspend. This will terminate screen. Either turn off power management, or prevent it from interfering by prefixing the command with olpc-nosleep, or just restart screen if you can afford to lose output.
- on particularly old systems, the ftdi driver may be missing and you may need to upgrade the kernel.
- when you have many serial adapters, it can be difficult to figure out which one is which. Look for device aliases at /dev/serial/by-path or /dev/serial/by-id. The by-path aliases are quite long, but are unique by USB socket.
An older option is to use minicom, however this adds complex configuration and menus. minicom is also packaged in major Linux distributions. Run "minicom -s" to configure the serial port with the settings suggested above. Adjust the device path (e.g. /dev/ttyUSB0). Then connect the USB adapter and run "minicom".
If you are running minicom on Fedora and get "Device /dev/ttyUSB0 lock failed: Operation not permitted" errors, re-create the /var/lock/lockdev directory -- more info at https://bugzilla.redhat.com/show_bug.cgi?id=722814 .
Windows
Download and install the driver using the instructions
The hardware will appear as a COM device and can be operated through HyperTerminal (included in a standard Windows install).
It is likely that COM1 and COM2 are already present and that the USB adaptor will appear as a new COM port, COM3 (or above) when connected and the driver is loaded. Configure Hyperterminal for this device.
With the USB adaptor not connected to anything apart from the Windows PC, typing on Hyperterminal should light up one LED, D1 on the adaptor and there will be no echo on the PC screen. Temporarily bridging the Tx and Rx terminals will light up both D1 and D2 and echo text typed on the PC screen. If you can get this far, you know that the adaptor is working and subject to Baud rate etc. it should be able to communicate with the XO.
Testing the USB adaptor is working, bridge Tx and Rx
Macintosh
The FTDI driver is not included in Mac OS X. Download and install the driver using the instructions.
The hardware will appear as /dev/tty.usbserial-SN, where SN is the serial number.
screen is also included in Mac OS X, and works well. The default port settings are adequate, with the exception of the baud rate. To connect, identify the name of the device in /dev, and start screen like this:
screen /dev/tty.usbserial-A6008ShI 115200
(A6008Shl is the serial number in this example, shell autocomplete makes this unimportant, because you may typically press tab after the letters usb)
Use ctrl-a k to kill window, which causes screen to terminate.
Remote Linux
How to provide remote serial adapter access to someone on the internet. On the host that has the serial adapter USB side plugged into it:
- install the ser2net package,
- configure /etc/ser2net.conf, deleting unnecessary entries and adding
8097:telnet:0:/dev/ttyUSB0:115200
- start ser2net
service ser2net start
- ssh to some remote host that both people have an account on, using a reverse port forward,
ssh -R 8097:localhost:8097 $REMOTE_HOST
Then tell the other person to type "telnet 0 8097" on that remote host.
Open Firmware
How to use an XO as a serial terminal to another XO, using a USB serial adapter.
You will require:
- an XO to act as host, with a build of Open Firmware after svn 3517,
- a USB serial adaper,
- a USB cable, type A male to type B female,
- an XO to act as target.
Preparation:
- connect the target XO to the USB serial adapter,
- connect the B end of the USB cable to the serial adapter,
- connect the A end of the USB cable to the host XO,
- download usb.fth to a USB drive,
- on the host XO, get to the Ok prompt, insert the USB drive, and load the program:
ok fl u:\usb.fth
Starting:
- start the program:
ok serial
The program supports some key sequences used by screen:
- ctrl+a k or ctrl+a ctrl+d to exit,
- ctrl+a ctrl+b to send a break,
- ctrl+a ctrl+a to send a ctrl+a,
- ctrl+a C to clear the screen.
Logging
How to record a log of the session:
ok serial-log u:\file.log
Remote
How to use an XO as a network serial adapter for another XO, using a USB serial adapter.
- follow the preparation steps above,
- configure Open Firmware networking,
- start a telnet server:
ok telnetd
- note the IP address displayed,
- connect with telnet to the server, and start the serial program,
% telnet 10.0.0.1 ok serial
(Note that serial-log does not work in this context, because telnetd bypasses the multiplexor used by serial-log. Fixed in svn 3518.)
Peer to peer
How to use an XO as a serial terminal (host) to another XO (without using any USB serial adapters):
- download serial.fth to a USB drive,
- on the XO acting as host, get to the Ok prompt, insert the USB drive, and load the program,
ok fl u:\serial.fth
- start the program
ok serial
- connect a crossover cable,
- turn on the target.
Caution: the program turns off the Open Firmware serial console when it starts, to avoid unpleasant interaction between the Open Firmware ok prompt and any connected device. Connecting the cable before the program is started may result in each laptop screaming at the other repeatedly.
A crossover cable, to join two OLPC-supplied serial cables, consists of the following:
| host pin (cable colour) | target pin (cable colour) | purpose |
|---|---|---|
| GND (orange) | GND (orange) | ground |
| RX (red) | TX (green) | display data, target to host |
| TX (green) | RX (red) | keyboard data, host to target |
The 3.3V (black) pin is not connected.
A crossover cable may also be fabricated from two PCB connectors, or using wire soldered to the connector pads.
References:
- mailing list post,
- git repository via web,
- git://dev.laptop.org/users/quozl/olpc-firmware-terminal.git git repository.
Reassembling the system
After connecting and testing the serial console, you might want to reassemble the system. If you want to have the serial cable still accessible for quick connection of the serial board, you have a couple of options:
Run it through the side
There are some holes in the white plastic where the green side-bumper normally gets hooked on (directly to the right of the power button and game keys). You can run the cable through here. You will not be able to properly reattach the side-bumper, you can leave it off or attach it loosely at an angle.
Jam it under the back cover
If you look carefully you will see that in some places, the back cover of the laptop does not make as forceful contact with the rest of the laptop in some places. You can run the cable through here.
When re-attaching the back cover, you'll have to apply some force and screw it in well. The cable will probably break at some point due the pressure here. However, it's still serving well on my XO after 2 years.
XO-1.5 caveats
On the XO-1.5, the serial board must be connected before the laptop boots. If it is connected later, it will not work until the laptop is rebooted.
On the XO-1.5, the serial port shares resources with the camera. Only one can be used at a time. If the serial board is detected at boot time, it will be used. The via-camera Linux driver attempts to detect that serial is being used and then prevents itself from loading. If this check is not working for some reason, you will see a load of junk on the serial console when the driver loads.
The exclusivity between serial and camera means that using the serial board to diagnose camera issues on the XO-1.5 is not possible.
The XO-1.5 requires the 3rd generation serial board detailed below.
Serial boards
Unless otherwise stated, OLPC will always ship the most recent serial adapter generation. Details of older devices are only for historical reference.
First generation serial adapter
The original adapter that came with the XO-1 ´´ATest´´ boards was very simple and only does +3.3V serial to RS232 voltage level conversion. This only works on the XO-1.
Second generation serial adapter
The second generation adapters are able to do the conversion from LVTTL (3.3V TTL) to RS232 and USB. The also have a mode for converting RS232 to USB. In the RS232 modes they are able to work with both straight and NULL modem cables. Because of this they are a bit more complicated than the first generation adapters. They only work on XO-1.
This complexity is in the form of 2 jumper blocks on the adapters. Blocks J4 and J6.
J4: Mode select block
J4 selects between the 3 modes of operation.
Mode 1: TTL<->USB
- Jumper 1&2, 5&6
Mode 2: RS232<->USB
- Jumper 3&4, 7&8
Mode 3: TTL<->RS232
- Jumper 2&4, 6&8
Note: in the same PCB this conventions are clearly marked
J6: Null Modem block
In the RS232 modes 2 & 3, J6 will swap the TX and RX lines. Normally changing these jumpers is not necessary.
- RS232 NULL Modem: 1&2, 5&6
- RS232 Normal: 3&4, 7&8
To make the adapter appear like a serial port you would find on a PC you would use normal wiring. Connection between the adapter and the PC would use a NULL modem or crossover cable. Just like you would use if you were connecting 2 PC's to each other.
If you are using a serial cable that is wired to be straight through then you would use NULL modem wiring.
If you are using Mode 1 then the settings for J6 do not make any difference because the DB9 is not used.
Third generation serial adapter
The current generation of serial adapter is USB-only and does not have any jumper for configuration - just connect it up and go. It supports XO-1, XO-1.5 and XO-1.75.
Electrical details
If you want to understand more about these connectors or if you want to construct your own serial adapter board, the following information will be of use.
The signals levels are 0v/3.3volt TTL.
XO Serial Ports - electrical interface
The pinout of the serial connector on the laptop is:
| Pin | Function |
|---|---|
| 1 | varies by model, see below |
| marked on PCB with white circle near the connector designator. | |
| 2 | TX transmit serial data |
| 3 | RX receive serial data |
| 4 | GND return |
| marked with a small number 4. |
XO-1
J1 Pin 1 is +3.3V supply provided by the laptop for use by the serial adapter.
In addition, the EC serial connector (CN24) has an additional pin (5), used to provide a clock for programming the serial ROM in recovery mode. This pin expects a +3.3V compatible 65 MHz clock signal, if used. The EC serial port may be used for monitoring by connecting a laptop/serial adapter cable to the first four pins of the connector.
The Pinout of the EC serial connector is identical to that of J1 except for the extra pin 5. The 4 pin connector works fine when plugged up to the EC serial port if its justified to Pin 1.
XO-1.5
Pin 1 is an input SERIAL_EN to the VX855, used to sense whether a serial adapter is present, and if so enable the serial port and disable the camera. As a result, the camera indicator is lit.
In Open Firmware use enable-serial to enable the serial adaptor if either this mechanism doesn't work, or if an adapter is connected after Open Firmware is started.
The mechanism can be tested also by connecting pin 3 (RX) to pin 1 (SERIAL_EN), since RX has a pullup resistor inside the laptop.
XO-1.75
Pin 1 is not connected.
XO-4
Pin 1 is not connected.
XO Serial Ports - physical interface
Both connectors are very close (though not quite identical) to a 1.25 pitch MOLEX picoblade. The latter will fit perfectly.
The authoritative drawing for from the manufacturer can be found at File:J1 CN24 male.pdf and File:J1 CN24 female.pdf. The dimensions are listed as CKT 4 for the J1 and CKT 5 for CN21 - both one row.
Generally the plastic connector is sold separate from the metal socket. And you assemble those by crimping a wire to the socket and then inserting it into the connector. The type of socket used requires a special crimping tool.
Some vendors sell ready made 150mm or 300mm cables; with a socket on one and and a tinned lead on the other - which means you can postpone buying the expensive crimp tool for a bit.
Molex numbers
Datasheets: http://www.molex.com/molex/products/datasheet.jsp?part=active/0530470410_PCB_HEADERS.xml (wire to board header) and http://www.molex.com/molex/products/datasheet.jsp?part=active/0510210400_CRIMP_HOUSINGS.xml (terminal and receptacle).
Right angle Molex Pico Blade 1.24 (0.49") PCB 90 degree headers (male, connector) and matching cable sockets (female); SMD is used on the board; the non SMD version can be made to fit and is slightly easier to solder; and much easier to source.
| Connector | pins | board header (male) | receptacle on cable (female) |
|---|---|---|---|
| J1 | 4 | 53048-0410 (non SMD) | 51021-0400 |
| 4 | 53261-0471 (SMD) | 51021-0400 | |
| CN24 | 5 | 53048-0510 (non SMD) | 51021-0500 |
| 5 | 53261-0571 (SMD) | 51021-0500 |
Along with matching sockets (above female connectors are just the 'plastic receptacles'), see item 50125/50133 (http://www.molex.com/catalog/pdf/MX51021.pdf) depending on wire thickness.
Technical drawings of the board socket: http://www.molex.com/pdm_docs/sd/532610271_sd.pdf and for the receptacle http://www.molex.com/pdm_docs/sd/510210400_sd.pdf (J1) or http://www.molex.com/pdm_docs/sd/510210500_sd.pdf (CN24)
Digikey numbers
Equivalent digikey numbers (of above MOLEX-es):
| Connector | pins | board header (male) | receptacle on cable (female) |
|---|---|---|---|
| J1 | 4 | WM7622CT-ND | WM1722-ND |
| CN24 | 5 | WM7623CT-ND | WM1723-ND |
See DigiKey page 1 and DigiKey page 2 for more details.
Depending on the wire thickness - you will need 4 or 5 sockets to wire things up - which have digikey number WM1775-ND (22AW) or WM1142CT-ND (24AQ). The Crimp tools are WM9931-ND, WM9978-ND, WM9932-ND or WM9933-ND depending on the wire.
RS-Component numbers
RS Components only has the receptacles:
| Connector | pins | receptacle on cable (female) |
|---|---|---|
| J1 | 4 | 279-9162 (http://nl.rs-online.com/web/2799162.html) |
| CN24 | 5 | 447-6580(http://nl.rs-online.com/web/4476580.html) |
And a 300mm socket to socket premade wire can be found at # 279-9522 (http://nl.rs-online.com/web/2799522.html) - or alternatively you can order individual sockets and crimp these.
Power
The device is powered from either the 3.3V from the laptop or by USB. Both may be plugged up at the same time.
Schematics and Board Layout
Hooking up the second-generation serial adapter
On an XO-1 C board, the J1 pinout is: 2 - TX serial data, 3 - RX serial data, 4 - common ground. When the adapter_cable that came with my mini-adapter gets plugged into J1, an orangy wire connects to pin 4 (ground).
The other end of my adapter_cable has a male 5-prong plug, whereas the mini-adapter itself has a female 6-wire_socket receptacle. Unless the adapter_cable is correctly plugged in, the mini-adapter setup will not work.
Holding the mini-adapter component-side up, at the cable receptacle the PCB markings label the 1st (top) wire_socket as 'GND'. I inserted the plug end of my adapter_cable so that the orangy wire connected to that wire_socket. That let the two data wires in the cable connect to the 4th+5th wire_sockets (labeled TXO and RXI) on the receptacle. Now the serial adapter connection worked.
Third Party Adapters
Very similar adapters are readily available at relatively low cost. Some examples include:
- DLP EVAL232R (EVAL232R)
- FTDI Basic Breakout (DEV-08772)
- FTDI Breakout Board (BOB-00718)