Skip to content

Changes

Page history
Update /Troubleshooting/Docked mode authored by Chris Vogel's avatar Chris Vogel
Hide whitespace changes
Inline Side-by-side
Troubleshooting/Docked-mode.md 0 → 100644
View page @ 343c0fba
[[_TOC_]]
# What is it about
Docked mode = attaching the Librem 5 to a dock or usb-c hub that allows to connect display, mouse/touchpad and keyboard.
The ability to use the Librem5 like a classical desktop or notebook when in docked mode is called _convergence_.
# Preconditions for docked mode
For a working connection you need the following things: a [working dock](#Information-about-setups-that-are-known-to-work), a working [pd power connection](#pd-power-delivery) from the usb-c power adaptor through the dock/usb-c-hub to your Librem5, [excellent cabling](#cables).
# cables
## usb-c cables
_"whenever I have had issues with convergence mode on my laptop docks (especially intermittent issues) I've found it to be related to the usb-c cable and orientation"_
@kyle.rankin
### length and quality
The quality of the usb-c cables used to connect power to the dock and the dock to the phone is crucial to success.
If you're not sure that the cables you use are of high quality try cables as short as possible and of the highest quality you can get.
Do not extend cables that are sticking out of your dock by a usb-c extension or convert the plugs format by any converter. Do not use an angel converter.
_"once I sourced a short, high quality usb-c cable I've stuck with it"_
@kyle.rankin
### orientation
There are a lot of usb-c cables out there that do not follow the full specification. They might work well, but only if you find the right orientation.
If you're connection doesn't work, try out turning each plug 180° around until you tried each possible combination.
## video cable
The same quality requirements do apply to the cable you use - in case of a usb-c-hub with video connector - to connect a display to the hub.
Hubs/docks sometimes do not provide very strong video signals and a bad cable will break the displays output or make the picture unstable or distorted.
# PD - power delivery
_"Video output via DP AltMode can't work without a PD contract so the [tracing](#enable-tracing-for-the-tps6598x-driver-module) does help here. Keyboard / mouse don't need a PD contract to function."_
@guido.gunther
[USB PD](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery) is a protocol to agree about the voltage and maximum power delivered by a usb power converter to an usb device.
## Troubleshooting - No charging, no video
The video output of your dock might not work, because there is no agreement about the power delivery between dock and Librem5.
When connected the Librem5 should show you the charging symbol for the battery constantly.
If you suspect the PD not working and being part of the problem you could:
- cut the power to the dock and let it be powered by the Librem5
- try different cables
- try different orientations for the usb-c connections (see above)
### USB connection information
_"Sometimes you get a USB billboard device from the adapter that tells you a bit more but that's not mandatory: http://www.technical-direct.com/en/typec_billboard/ - there isn't good support in Linux userspace but you see it in lsusb and can parse the output from there"_
@guido.gunther
Here's an example:
```
purism@pureos:~$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 005: ID 2020:2060 Qualcomm, Incorporated Qualcomm CDMA Technologies MSM
Bus 001 Device 003: ID 0424:4041 Microchip Technology, Inc. (formerly SMSC) Hub and media card controller
Bus 001 Device 002: ID 0424:2640 Microchip Technology, Inc. (formerly SMSC) USB 2.0 Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 004: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
Bus 004 Device 002: ID 05e3:0626 Genesys Logic, Inc. USB3.1 Hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 004: ID 25a4:9311 USB C USB C Video Adaptor
Bus 003 Device 003: ID 05e3:0610 Genesys Logic, Inc. Hub
Bus 003 Device 002: ID 1a40:0101 Terminus Technology Inc. Hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
```
This is the output of ```lsusb``` on a Librem5 with a Baseus usb-c hub connected. The usb-c hub is powered by a usb-c power adaptor. To look at the type of power delivery you need to look for the _"usb-c video adaptor"_ - in this case it's the device with _vendor:product_ _25a4:9311_.
```
purism@pureos:~$ sudo lsusb -v -d 25a4:9311
[sudo] password for purism:
Bus 003 Device 004: ID 25a4:9311 USB C USB C Video Adaptor
Device Descriptor:
[...]
Billboard Capability:
bLength 48
bDescriptorType 16
bDevCapabilityType 13
iAddtionalInfoURL 4 http://help.vesa.org/dp-usb-type-c/
bNumberOfAlternateModes 1
bPreferredAlternateMode 0
VCONN Power 0 1W
bmConfigured 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
bcdVersion 1.21
bAdditionalFailureInfo 0
bReserved 0
Alternate Modes supported by Device Container:
Alternate Mode 0 : Alternate Mode configuration successful
wSVID[0] 0xFF01
bAlternateMode[0] 0
iAlternateModeString[0] 1 USB C
```
You should get a similar output for your dock/hub. If bAdditionalFailureInfo is 0 the negotiation of a PD contract should have been successfull. wSVID 0xFF01 stands for "DisplayPort Mode" which is the one needed (reference: https://composter.com.ua/documents/USB_Billboard_Revision.1.2.1.pdf).
### Enable tracing for the TPS6598x driver module
The Librem5 has [tracefs (part of the kernels function tracer)](https://www.kernel.org/doc/Documentation/trace/ftrace.rst) mounted by default. This can be used to follow what happens in the driver for the TPS65982 controller chip to debug the negotiating of the Power Delivery (PD) contract.
To enable tracing for the driver use:
```echo 1 | sudo tee /sys/kernel/debug/tracing/events/tps6598x/enable```
To look at the trace:
```sudo cat /sys/kernel/debug/tracing/trace```
Some information about available options for tracing in general can be found in ```sudo less /sys/kernel/tracing/README```
Example output (nexdock360):
```
# tracer: nop
#
# entries-in-buffer/entries-written: 37/37 #P:4
#
# _-----=> irqs-off/BH-disabled
# / _----=> need-resched
# | / _---=> hardirq/softirq
# || / _--=> preempt-depth
# ||| / _-=> migrate-disable
# |||| / delay
# TASK-PID CPU# ||||| TIMESTAMP FUNCTION
# | | | ||||| | |
irq/79-0-003f-215 [002] ..... 350007.992961: tps6598x_irq: event1=PLUG_EVENT|PP_SWITCH_CHANGED|POWER_STATUS_UPDATE|DATA_STATUS_UPDATE|PD_STATUS_UPDATE, event2=
irq/79-0-003f-215 [002] ..... 350008.001966: tps6598x_status: conn: conn-no-Ra, pp_5v0: off, pp_hv: in, pp_ext: off, pp_cable: off, pwr-src: vin-3p3, vbus: vSafe5V, usb-host: no, legacy: no, flags: PLUG_PRESENT|UPSIDE_DOWN
irq/79-0-003f-215 [002] ..... 350008.010808: tps6598x_power_status: conn: 1, pwr-role: sink, typec: usb, bc: sdp
irq/79-0-003f-215 [002] ..... 350008.018753: tps6598x_data_status: DATA_CONNECTION|DATA_UPSIDE_DOWN|USB2_CONNECTION|USB3_CONNECTION
irq/79-0-003f-215 [002] ..... 350008.018879: tps6598x_data_status: DATA_CONNECTION|DATA_UPSIDE_DOWN|USB2_CONNECTION|USB3_CONNECTION
irq/79-0-003f-215 [002] ..... 350008.026765: tps6598x_irq: event1=SOURCE_CAP_MESSAGE_READY|USB_HOST_PRESENT, event2=
irq/79-0-003f-215 [002] ..... 350008.027505: tps6598x_status: conn: conn-no-Ra, pp_5v0: off, pp_hv: in, pp_ext: off, pp_cable: off, pwr-src: vin-3p3, vbus: vSafe5V, usb-host: pd-usb, legacy: no, flags: PLUG_PRESENT|UPSIDE_DOWN
irq/79-0-003f-215 [002] ..... 350008.224504: tps6598x_irq: event1=NEW_CONTRACT_AS_CONSUMER|POWER_STATUS_UPDATE|STATUS_UPDATE, event2=STATUS_UPDATE
irq/79-0-003f-215 [002] ..... 350008.225361: tps6598x_status: conn: conn-no-Ra, pp_5v0: off, pp_hv: in, pp_ext: off, pp_cable: off, pwr-src: vin-3p3, vbus: pd, usb-host: pd-usb, legacy: no, flags: PLUG_PRESENT|UPSIDE_DOWN|DATAROLE
[...]
irq/79-0-003f-215 [002] ..... 350008.844542: tps6598x_irq: event1=ATTENTION_RECEIVED, event2=
irq/79-0-003f-215 [002] ..... 350008.845237: tps6598x_status: conn: conn-no-Ra, pp_5v0: off, pp_hv: in, pp_ext: off, pp_cable: out, pwr-src: vin-3p3, vbus: pd, usb-host: pd-usb, legacy: no, flags: PLUG_PRESENT|UPSIDE_DOWN|DATAROLE|VCONN
irq/79-0-003f-215 [002] ..... 350008.848387: tps6598x_irq: event1=, event2=
```
The lines containing 'tps6598x_status:' reflect the current status of the connection. 'vbus: pd' indicates that a power delivery contract has been negotiated.
## Firmware version of your TPS65982 controller chip
You can find the firmware version of the TPS65982 using the following command:
```
purism@pureos:~$ sudo cat /sys/kernel/debug/tps6598x/0-003f/customer_use
0x4c35445000000200
```
The hexadecimal number is interpreted as follows:
* the beginning is just a name. 0x4c354450 translates to ascii 'L5DP': ```sudo cat /sys/kernel/debug/tps6598x/0-003f/customer_use | cut -c-10 | xxd -r -p```
* the last three bytes contain the actual firmware version - in the example above 0x00, 0x02, 0x00 which in decimal is 0, 2, 0 and translates to firmware version 0.2.0
A valid string for an older firmware version looked like this: ```0x4c35445000000101```. The firmware version here has been 0.1.1.
You can follow the change of the version number through the git repository for the firmware. The changes can be found by comparing the different versions of tps65982-librem5-dp-alt-mode.json. [Here](https://source.puri.sm/Librem5/firmware-tps6598x-nonfree/-/compare/v0.1.1...v0.2.0?from_project_id=1499#c4c7e73a117d39d206c78edbb8900c493730f04c_81_81) you can find the change from version 0.1.1 to 0.2.0.
### Firmware Repository
https://source.puri.sm/Librem5/firmware-tps6598x-nonfree
## Dell docks
Dell uses a 1-wire protocol to talk on the power adapters connection. By doing so they bind there own power adapters to their docks - probably for economic reasons.
To get a Dell usb-c dock working you'll need a compatible Dell power adapter to connect the dock to.
# If all fails, get help
To track down the reason why a setup might not work as expected gather information about your setup and possible errors like described in this article.
You can ask for help on the [forum](https://forums.puri.sm) or directly at Purisms support providing this information.
# Information about setups that are known to work
* https://source.puri.sm/Librem5/firmware-tps6598x-nonfree/-/blob/master/dp-alt-mode-adapters.org
* https://source.puri.sm/Librem5/community-wiki/-/wikis/Tested-Accessories#hubs
* https://source.puri.sm/Librem5/community-wiki/-/wikis/Tested-Accessories#laptop-shells
## USB IDs of your dock/hub
You can help to improve the available information about different usb hubs/docks by adding the dock you tested along with your experience to one of the sources mentioned.
To add a dock to the community wiki and/or to the list contained in the firmware repository you'll need the USB IDs of your hub/dock.
_"Regarding USB-id see https://source.puri.sm/Librem5/firmware-tps6598x-nonfree/-/blob/master/dp-alt-mode-adapters.org - we usally pick that comes closest to the video adaptor (in the baseus case it's 9636:9300 WinUSB USB C Video Adaptor)"_
@guido.gunther
This is the output of ```lsusb``` for a Baseus 8-IN-1 CAHUB-CV0G (Type-C to HDMI*1+USB3.0*3+PD*1+RJ45*1+SD/TF*1) dock:
```
purism@pureos:~/docked_mode$ diff lsusb_undocked.txt lsusb_docked-no-monitor.txt
5a6,12
> Bus 004 Device 003: ID 0b95:1790 ASIX Electronics Corp. AX88179 Gigabit Ethernet
> Bus 004 Device 002: ID 05e3:0626 Genesys Logic, Inc. USB3.1 Hub
> Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
> Bus 003 Device 004: ID 25a4:9311 USB C USB C Video Adaptor
> Bus 003 Device 003: ID 05e3:0610 Genesys Logic, Inc. Hub
> Bus 003 Device 002: ID 1a40:0101 Terminus Technology Inc. Hub
> Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
```
In this case you'd report the vendor:product number of "USB C Video Adaptor" "25a4:9311" along with your findings and experiences for including into the list of [tested hardware](#information-about-setups-that-are-known-to-work).
## Where to report your findings
You can find information about changing this wiki [here](https://source.puri.sm/Librem5/community-wiki/-/wikis/Contribute).
If you do not want to register just to provide some more information, please let us know on the [forum thread](https://source.puri.sm/Librem5/community-wiki/-/wikis/Contribute#feedback) and someone will add your information.
\ No newline at end of file