# Trinket Fake USB Serial

## Overview

Warning: 

The Trinket has a USB port that is used for bootloading. But the Trinket can only become a low-speed USB device because of its limited hardware. USB standards prevents low speed USB devices to truly act as virtual serial ports, which is why we cannot use a serial terminal to communicate with the Trinket directly.  
  
_However_ **,** there's a work-around for this problem. In Windows, you can emulate a fake serial port bridge using a utility named **com0com**. In this tutorial, you'll see how we can write a middle-man program that communicates with the Trinket and **com0com** , so that a serial terminal (such as the one built into Arduino IDE) can talk with the other end of **com0com.**

Danger: 

Danger: 

There are two pieces of code involved here:

- Arduino library named **TrinketFakeUsbSerial**
- A PC app named **TrinketFakeUsbSerialHostSW**

The other pieces of software involved  

- **LibUsbDotNet** , which makes it easy for me to use libusb-win32 to write TrinketFakeUsbSerialHostSW for Windows
- **com0com** , which emulates the two fake serial ports (only required on Windows)
- Some sort of serial terminal (Arduino IDE, Hyperterminal, Teraterm, RealTerm, Putty, etc)

Below is a diagram showing how data flows between the different components: ![](https://cdn-learn.adafruit.com/assets/assets/000/011/618/medium800/trinket_flowchart.png?1381725137)

Below is a demonstration video (the code sketch is in the Usage Demo section of this tutorial, the video should be viewed in 720p and full screen if you want to read the text on screen)

http://www.youtube.com/watch?v=Tt38wUjvH1k

# Trinket Fake USB Serial

## How it works

Warning: 

![](https://cdn-learn.adafruit.com/assets/assets/000/011/619/medium800/trinket_flowchart.png?1381725589)

Since virtual serial port protocol isn't allowed for low speed devices. We have to find another way to communicate.  
  
First, understand that all communication on a USB bus is always initiated by the host (the computer).  
  
The most basic useful data transaction is a control transfer, which carries two parts: a setup packet and a data packet. Basically, the setup packet says how many bytes are in the data packet, and which way the data packet goes. We use control transfers for data going from the computer to the Trinket.  
  
To get data going from the Trinket to the computer, we open an interrupt-in endpoint to send it. The computer will automatically ask "is there anything in the endpoint" once every 2 ms, and if Trinket answers "yes", then the transfer begins.  
  
The middle-man software I wrote (named **TrinketFakeUsbSerialHostSW** ) will communicate with the Trinket using LibUsbDotNet, which is a libusb-win32 wrapper for C#. The data is relayed to a fake serial port created by com0com.

# Trinket Fake USB Serial

## Install for Windows

Warning: 

Everything you need to download is on github, click the button to download a zip

[Download the Trinket Fake USB Files](https://github.com/adafruit/Adafruit-Trinket-USB/blob/master/TrinketFakeUsbSerial_allfiles_20131014d.zip?raw=true)
(note: all the source code is available: [https://github.com/adafruit/Adafruit-Trinket-USB/](https://github.com/adafruit/Adafruit-Trinket-USB/) )  
  
[Install the Arduino library](http://arduino.cc/en/Guide/Libraries "Link: http://arduino.cc/en/Guide/Libraries") as if it was any other Arduino library, read the readme.txt file, the source code, and the example sketch to see how to use it.  
  
Install [com0com](http://com0com.sourceforge.net/), then use it to setup a pair of fake serial ports (see screenshot to see my configuration, you can use any port number you want)

![](https://cdn-learn.adafruit.com/assets/assets/000/011/620/medium800/trinket_com0com_screenshot.png?1381727646)

This is the point where you write your own sketches to use the TrinketFakeUsbSerial library in any way you'd like. Get creative!  
  
Please read the source code of the library, the readme file, and the example sketch. It will help you understand how to use the library. It works mostly like HardwareSerial, so you can use print and println, along with other inherited functions.

When you try to connect a Trinket loaded with a sketch containing the TrinketFakeUsbSerial library, Windows will fail to find a device driver. The zip file you downloaded contains the device driver you need, so you have to tell Windows where they are. The driver is unsigned so there might be a security warning, install it anyways.

![](https://cdn-learn.adafruit.com/assets/assets/000/011/621/medium800/trinket_win_driver_install.png?1381728224)

You've also downloaded the executable named TrinketFakeUsbSerialHostSW.exe , when you need to use the serial terminal with Trinket, this executable must be running in the background.

![](https://cdn-learn.adafruit.com/assets/assets/000/011/623/medium800/trinket_app_screenshot.png?1381730267)

![](https://cdn-learn.adafruit.com/assets/assets/000/011/622/medium800/trinket_systray_screenshot.png?1381729368)

Remember, if you use com0com to setup COM12 and COM13, then use TrinketFakeUsbSerialHostSW to open COM12, and use your serial terminal to open COM13. The com0comsoftware will create a data-pipe between the two different # ports.  
  
Don't try to open COM12 using both, it won't work. Don't try to open COM13 using both, it won't work.  
  
(You don't have to use 12 or 13, you can really use any unused number)

# Trinket Fake USB Serial

## Usage Demo

Warning: 

http://www.youtube.com/watch?v=Tt38wUjvH1k

The video above should be viewed in 720p and full screen if you want to read the text on screen  
  
The sketch used in the demo is posted below

```auto
#include "TrinketFakeUsbSerial.h"

void setup()
{
  TFUSerial.begin();
}

void loop()
{
  TFUSerial.task(); // this should be called at least once every 10 ms

  if (TFUSerial.available()) {
    char c = TFUSerial.read();
    if (c == 'a')
    {
      TFUSerial.println("hello world");
    }
    else if (c == 'b')
    {
      TFUSerial.println(millis(), DEC);
    }
  }
}
```

# Trinket Fake USB Serial

## Install for Linux / Mac

Warning: 

I managed to write a Python script that does the same thing as the Windows application, except it's not a system tray application. It needs to be launched through the command line or using a script.  
  
Since it's a Python script that uses cross platform modules, the whole script is also cross platform and thus it works on Linux and Mac OS X.

Danger: 

First you need these items installed:

- [Python 2.7](http://www.python.org/download/releases/2.7.5/) (Python 3 will not work)
- [PyUSB](http://sourceforge.net/apps/trac/pyusb/)
- [pySerial](http://pyserial.sourceforge.net/)

(note: you can install the two modules using [easy\_install](http://pythonhosted.org/distribute/easy_install.html) , if you are having trouble installing these, please check Google to find some Python tutorials on installing modules!)  
  
Second, to replicate the role of com0com, use this command:  
```auto
socat PTY,link=COM8 PTY,link=COM9
```

to create COM8 and COM9, use any number you want  
  
Finally, to run the Python script...  
  
The download package is located: [https://github.com/adafruit/Adafruit-Trinket-USB/blob/master/TrinketFakeUsbSerial\_allfiles\_20131014...](https://github.com/adafruit/Adafruit-Trinket-USB/blob/master/TrinketFakeUsbSerial_allfiles_20131014d.zip?raw=true "Link: https://github.com/adafruit/Adafruit-Trinket-USB/blob/master/TrinketFakeUsbSerial\_allfiles\_20131014d.zip?raw=true") , the py file is inside the zip archive.  
  
Using your command line terminal, navigate to where the py file is located, and then run this command:

```auto
python TrinketFakeUsbSerialHostSW.py -p <portname>
```

The script should then run forever. It should gracefully handle connections and disconnections for you, but errors will show up on the screen.

To view more command line options (options for silencing errors, or show more detailed connection status) for the script, run this command:

```auto
python TrinketFakeUsbSerialHostSW.py -h
```

# Trinket Fake USB Serial

## USB HID Terminal Alternative

Warning: 

Another way of communicating with the Trinket uses HID to pass raw USB messages back and forth. This technique was created by Ray's Hobby. The key difference between Ray's method and the method discussed above is:

- Ray's method uses a HID profile, thus no driver installations are required at all
- Compared to the Fake USB method uses a custom profile with a libusb driver
- Ray's method uses a customized serial terminal that he wrote himself
- The Fake USB method works with most generic serial terminal programs, but requires running a background application to act as a "bridge"

For a lot more information check out [http://rayshobby.net/?p=7363](http://rayshobby.net/?p=7363) where the technique is talked about in detail  
Ray's code is not specifically designed for Trinket, so to make it work with Trinket, I have forked Ray's github for this project and made modifications to his code so that it also works with the Trinket.

[Visit the forked and modified github repo](https://github.com/adafruit/rayshobby-hid-serial-trinket)
You can download all the files from the github repo above.  
  
The only changes are:

- changed usbconfig.h to include different pin assignments
- added the oscillator calibration function required for ATtiny
- adjusted clock speed for Trinket

I did not modify Ray's host software at all. It works with his software without any modifications. His software is written using [Processing.org](http://processing.org/), and while the executables are also included, you should have [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed in order to use them. The host software should work on any platform that can run Processing.org applications (or any platform that can run Java, meaning Windows, Linux, and Mac should all work).  
  
When you have downloaded all the files, [install the Arduino library as usual](http://arduino.cc/en/Guide/Libraries). You can then try compiling your own sketches using the library, or try running one of the provided example sketches.  
  
Then to use the serial terminal, either run the host software that you've already downloaded. You may use Processing.org to open the host software, or use one of the provided precompiled executables specific to your operating system.  
Danger: 


## Related Guides

- [NeoPixel Bracelet](https://learn.adafruit.com/neopixel-bracelet.md)
- [Camera LED Ring Light](https://learn.adafruit.com/camera-ring-led-light.md)
- [Guardian Robot – Zelda BOTW](https://learn.adafruit.com/guardian-robot-zelda-botw.md)
- [Kaleidoscope Eyes (Trinket-Powered NeoPixel LED Ring Goggles)](https://learn.adafruit.com/kaleidoscope-eyes-neopixel-led-goggles-trinket-gemma.md)
- [Celebration Spectacles](https://learn.adafruit.com/celebration-spectacles.md)
- [Pro Trinket as a USB HID Mouse](https://learn.adafruit.com/pro-trinket-usb-hid-mouse.md)
- [Trinket Ultrasonic Rangefinder](https://learn.adafruit.com/trinket-ultrasonic-rangefinder.md)
- [Pro Trinket Rotary Encoder](https://learn.adafruit.com/pro-trinket-rotary-encoder.md)
- [NeoPixie Dust Bag](https://learn.adafruit.com/neopixel-pixie-dust-bag.md)
- [Adafruit Arduino IDE Setup](https://learn.adafruit.com/adafruit-arduino-ide-setup.md)
- [Trinket Powered Rover](https://learn.adafruit.com/trinket-powered-rover.md)
- [Galaxy Pendant](https://learn.adafruit.com/life-proof-led-necklace.md)
- [Trinket React Counter](https://learn.adafruit.com/trinket-react-counter.md)
- [Adafruit PyRuler](https://learn.adafruit.com/adafruit-pyruler.md)
- [Storage humidity and temperature monitor](https://learn.adafruit.com/storage-humidity-and-temperature-monitor.md)