Advanced features of the USBC-TKEY

Accessing the integrated command line

In addition to the ability to sniff the USB PD data, the TKEY also has an integrated command line that exposes additional features. To access the command line a USB serial device must be created, which can then be accessed with a variety of tools.

From a shell prompt, enter the following command:

echo '18d1 500A' | sudo tee /sys/bus/usb-serial/drivers/generic/new_id

For reference:

    – 18d1 is the Vendor ID (VID) of the Plugable USBC-TKEY (the same as Google’s ‘twinkie’)
    – 500A is the Product ID (PID) of the Plugable USBC-TKEY(the same as Google’s ‘twinkie’)
    – tee is a command that takes a standard input stream and adds it to a file. In the command above, we add the TKEY as a serial device using its USB VID and PID.

You should now be able to see a new serial device in the /dev directory, typically similar to ttyUSBx where the x is a number.

To access the internal command line several different applications that can connect to serial device can be used. The ‘minicom’ application is popular, but a quick and easy application to use is ‘screen’. For example, assuming the TKEY is now associated with ttyUSB0 on your system you could enter the following to access the command line:

sudo screen /dev/ttyUSBx 115200

This will clear your shell prompt window, and you will most likely have to press Enter to receive the ‘>’ prompt indicating the TKEY is waiting for input. Type ‘HELP’ to see a list of all available commands and you should see output similar to the following:

command line help_cropped

Note, in Ubuntu 14.04 the ‘modemmanager’ application may start injecting AT commands at the prompt as it will erroneously think the TKEY is a communication device. The application will give up after a short time period, but you can also elect to kill the process by issuing this command in a standard shell prompt before accessing the TKEY:

sudo service modemmanager stop 2>/dev/null

The definitive reference to all the available commands and their function is the public firmware source code available from the Google repository (https://chromium.googlesource.com/chromiumos/platform/ec/+/master/board/twinkie/ with the injector.c file being the focus) You can also type HELP plus the command for more information about a specific command.

While going over every command is outside the scope of this document, here are a few common useful examples.

The ‘twinkie’ command (named as such for codename of the original Google device) contains several useful features. Entering ‘help twinkie’ provides some of the options available:

help twinkie output_cropped

It is worth noting at this point that the ‘twinkie’ command has an alias, ‘tw’ and they can be used interchangeably, and will be shown as such in all subsequent examples (many other commands have short aliases as well).

Two very useful options are the ‘vbus’ and ‘vconn’ commands. The vbus command measures the VBUS voltage and current draw while the vconn command measures the VCONN voltage. In this example both commands have been issued while connected to a fully charged MacBook 12” laptop:

vbus and vconn output_cropped

Another useful command is the ‘cc’ command which allows you to measure the instantaneous voltage readings on both CC lines:

tw cc output_cropped

The Type-C specification provides a table to help interpret these readings, Table 4-25 Voltage on Sink CC pins (Multiple Source Current Advertisements):

Interpret CC voltage

In this instance, the 925mV you see on CC1 indicates that you’re in the vRd-1.5, so that’s a 1.5A power source advertisement from the charger.

Another way to get the voltage readings on both CC lines is with the ADC command:

adc command output_cropped

The TKEY can also be used to add resistors to the CC1 and CC2 lines. For example, when connected to a power source (in this case an Apple MacBook Type-C charger using a C to C cable and the TKEY disconnected from the MacBook or sink), the values of the CC lines are read. By issuing a ‘resistor’ command (abbreviated to ‘res’) along with the ‘rd’ parameter twice will add a pull-down resistor (5.1kOhm) to each CC line. Reading the cc values again will show the effect. To remove the resistors, issue a ‘tw res none none’ command to remove them. See the example below:

Insert and remove resistors

Using the USBC-TKEY as a Power Sink

When first entering the integrated command line, the TKEY will be operating as sniffer but has the ability to act as a sink (a device that consumes power). In order to access this functionality, enter the command ‘tw sink’ and the TKEY will reboot and enter sink mode.

Once rebooted and after the TKEY detects a power source has been connected, it will negotiate a power contract. The LED of the TKEY will be green to indicate 5V, red for 20V and blue for all other voltages.

From the new command line, the maximum negotiated voltage can be changed. For example, this command sets a limit of 12V:

pd 0 dev 12

An example of switching to this mode and entering the various commands follows:

sink emulation

** Note, this example was run while using the Minicom utility to show consistancy after the TKEY reboot **

Flashing the firmware

Your Plugable USBC-TKEY comes pre-flashed from the factory so you can start using it right away. We provide instructions for flashing your own firmware as a courtesy should you wish to try experimenting with building your own via the instructions provided by Google here → https://www.chromium.org/chromium-os/twinkie

Just be aware that if you elect to flash the firmware you do so at your own risk! Plugable will only provide support when using Plugable’s latest firmware revision.

1. Make sure that both the USB OTG Micro-B to Female A and USB A to A cables are connected as shown in the photo below and connect the whole assembly to a USB 2.0 port on system running Ubuntu Linux 14.04

firmware flash cable config (Mobile)

2. Open a shell prompt, and enter the following commands to install the dfu-util tools (http://dfu-util.sourceforge.net/) which will be used to flash the firmware on the Plugable USBC-TKEY.

sudo apt-get update 
sudo apt-get install dfu-util

3. To list the dfu devices your host machine can see, use the following command:

dfu-util -l

If the host machine is able to see your Plugable USBC-TKEY, you should see output similar to the example below:

dfu-util list_cropped

In this example two DFU devices are found for each Plugable USBC-TKEY.
They are actually DFU interfaces for the same chip, and the STM32F072 microcontroller chip used in Plugable USBC-TKEY exposes two DFU interfaces:

    – Internal Flash – alt =0
    – Option bytes – alt=1

To flash the firmware, we need to make sure the internal flash interface is chosen.

4. To start flashing the Plugable firmware, enter the following command (the file you download may have a different name, please substitute accordingly):

sudo dfu-util -a 0 -s 0x08000000 -D combined.bin

Make sure to be in the same directory where you downloaded the firmware image file or you can simply replace the file name (combined.bin) with the full path to the file:
(For example: sudo dfu-util -a 0 -s 0x08000000 -D ~/downloads/combined.bin)

For reference, here are descriptions of what each parameter in the previous represents:

    -a : specify the Alt setting of the DFU Interface by name or by number which, in our case, has to be 0 or internal flash.
    -s : specify target address in memory
    -D : Write firmware from into device

5. While the flashing command is being executed, there will be no progress indicator, and the shell prompt might seem hang. Don’t worry, it is working! If it wasn’t, an error message would appear. Wait approximately 1-2 minutes to allow the firmware flashing to complete. When complete, you should see output similar to this:

Completed TKEY Flash_cropped

Thanks
The creation of this document would not have been possible without the excellent information posted by the Google team at https://www.chromium.org/chromium-os/twinkie, upon which we relied heavily. Our many thanks to the Google engineers who designed this device and for their assistance in bringing the unit to market under an open source license.

Useful Reference links
Google reference for the ‘twinkie’, upon which the USBC-TKEY is based:
https://www.chromium.org/chromium-os/twinkie

Google mailing list for ‘twinkie’ related questions:
http://groups.google.com/a/chromium.org/group/chromium-os-discuss

Chromium OS Cable and Adapter Tips and tricks:
https://www.chromium.org/chromium-os/cable-and-adapter-tips-and-tricks

Benson Leung’s Google Plus Page:
https://plus.google.com/+BensonLeung

Benson Leung’s USB Type C Explained:
https://plus.google.com/collection/0Vdov

Benson Leung’s USB Type C news:
https://plus.google.com/collection/EKnov

USB 3.1 Specification:
http://www.usb.org/developers/docs/