Heya, Thanks for visiting!

This guide will go over compiling the firmware, flashing it to your device, and emulating your first device. I was successful using Windows 8(not 8.1) but that doesn't mean it came without the challenges. Hopefully this guide can steer you clear of any head-banging issues.

If you need help making/assembling your own Facedancer board, follow this guide I made previously.

Getting started

Inspect your board for any solder bridges, cold joints, etc. Use a multimeter in continuity mode to test. This is important as you are connecting this to your precious pc.

Plug in the host side to your pc via USB 2.0. I ran into Blue Screen issues on Windows 8 using USB 3.0.

If you want to be cautious, plug it in on an old pc first and see if it enumerates without issue. You could even use a USB Isolator like this(I have one).

You should see the Rx and Tx Leds blink a bit. It should automatically start finding drivers. When it is done, in Device Manager, you should have USB Serial Converter under the Universal Serial Bus controllers category and a USB Serial Port(COMx) under Ports (COM & LPT) category.

Getting the code

All of the firmware is available in the goodfet svn repo. To download the repo, download and install TortoiseSVN. Now create a folder where you want to store the svn(avoid spaces in the path). I chose Downloads/goodfet_svn. TortoiseSVN is a shell extension so that means it adds entries to your right-click context menu. Right click the folder you just created and click SVN Checkout... TortoiseSVN Checkout. In the URL field enter: https://svn.code.sf.net/p/goodfet/code/trunk/ and press OK. All of the files should download and you will get a green checkmark on all the files and directories.

Checkout Dialog

The client folder refers to more of the host-side stuff. The firmware folder applies to the stuff you program into your device.

After you got it all downloaded you need to add the client directory to your path environment variable. ex: C:\Users\madli_000\Downloads\goodfet_svn\client;

Note: You will need to exit your console(cmd prompt) every time you update an environment variable for them to take effect. To set or modify an environment variable, you can use setx somekey somevalue in cmd prompt. Or go to control panel: Control Panel->System and Security->System->Advanced System Settings->Environment Variables. If you are adding directories to the path variable, just separate them with a semicolon(;).

Compiling the Code

You can use curl -O http://goodfet.sourceforge.net/dist/facedancer21.hex in cmd prompt to get a compiled hex file(not sure how up to date it is). You can just build your own by following the rest below.

  • Install 32 bit Python 2.7.x. Add python to your path environment variable; ex. C:\Python27_32bit\;C:\Python27_32bit\Scripts;. If you don't add it to your path you will have to call python via its full path every time like "C:\Python27_32bit\python.exe".

  • Install pyserial by running this command pip install pyserial. If you need the pip command: Use these Windows binaries and first install setuptools. Then install pip. If you didn't add python to your path in the previous step you will have to use pip's full path like: "C:\Python27_32bit\Scripts\pip.exe" install pyserial

  • Install MinGW. Add it to your path environment variable; ex. C:\MinGW\bin

  • Download the mspgcc zip. Create a 3rd_party folder inside your MinGW installation (C:\MinGW\3rd_party). Copy the mspgcc zip into this folder. Now unzip it. Add the bin folder inside where you unzipped to your path environment variable; ex. C:\MinGW\3rd_party\mspgcc-20120406-p20120911\bin

  • Install GOW: lightweight alternative to Cygwin. It should be already added to your path but just check to make sure; ex. C:\Program Files (x86)\Gow\bin

  • Add the environment variable board with the value of facedancer21.

cd to the firmware folder in the svn(ex. cd "C:\Users\madli_000\Downloads\goodfet_svn\firmware"). Run make clean install in cmd prompt. This will probably error out(like the message below) but do not worry. you still generated/compiled the goodfet.hex file we need.

make (e=2): The system cannot find the file specified.
make: *** [install] Error 2

Flashing the code

It is important to understand the COMX, ttySX, port X relationship. Simply put, ttySX and port X are zero indexed so they will be one less than COMX. ex. COM7=ttyS6=port 6

Run in CMD Prompt. Adjust to your setup.
"C:\Python27_32bit\python.exe" "C:\Users\madli_000\Downloads\goodfet_svn\client\goodfet.bsl" --comport=6 --speed=38400 --debug -e -p "C:\Users\madli_000\Downloads\goodfet_svn\firmware\goodfet.hex"
OR if you added python to your path and are in the client directory
python goodfet.bsl --comport=6 --speed=38400 --debug -e -p "../firmware/goodfet.hex"

A lot of stuff should scroll in your cmd prompt. When it is done it should say: 5374 bytes programmed. You can see the full output of this being successful with DEBUG=3 in goodfet.bsl in this pastebin.

You can run "C:\Python27_32bit\python.exe" goodfet.bsl -h to find out what all those parameters mean.

Emulating your first USB Device (Communicating through the TARGET port)

Now that your board is all set up, it is time to get into the action.

Plug in another cable in the TARGET end and into another PC or your own(haven't tried).

In the client svn directory, run python goodfet.maxusbhid in cmd prompt.

You should see the lights start to blink pretty solid. On the second PC, in Device Manager you should see HID Keyboard Device under the keyboards category.

Device Manager: HID Keyboard Device

Here is the full console output of running that command.

Running into issues?

This guide is mostly from my memory as I didn't want to uninstall everything just to try to step back through it. If you running into an issue, try these things below and then contact me and tell me what I forgot.

  • Try Cygwin. I couldn't get it to program but maybe you will be succesful. You will need the devel/make and the python package.
  • If using Cygwin, try adding the environment variable CYGWIN with the value of reset_com. See this documentation for more details.
  • Try setting the environment variable GOODFET to ttyS6 or 6. This is sometimes used in some of the scripts if it can't find a port.

Command Cheatsheet

Command Description
make clean install Same as make clean and make install. Use in the firmware svn directory to compile and create the goodfet.hex
python goodfet.bsl --comport=6 --speed=38400 --debug -e -p "../firmware/goodfet.hex" Use in the client svn directory to Program the board with the compiled hex on COM7(change port to your situation).
python goodfet.bsl -h Show the help text for goodfet.bsl. Shows all possible arguments, etc.
python goodfet.maxusbhid Use in the client svn directory to emulate a HID Keyboard device.
python -m serial.tools.list_ports List all serial ports. Does not always work properly