The files provided along with this README are part of the Smart Card Detective
(SCD). The SCD is meant to provide an open framework for EMV research and
digital forensics, enabling users to analyze transactions.

The software is given under the BSD 2-clause license (FreeBSD):
http://www.opensource.org/licenses/bsd-license.php

VERSION
Current version of the software is 2.4.0
Last updated: 24 April 2012.

See the CHANGELOG file for comments on what's new (there are many updates!).

REQUIREMENTS

In order to compile this project you need the avr-libc and avr-gcc tools.
Please use avr-libc version 1.7.0 or higher as the previous versions have
problems with the malloc functions. See http://www.nongnu.org/avr-libc/ for more
information.

To install all the necessary tools I recommend using either

a) my script (for any linux distribution):
http://www.cl.cam.ac.uk/~osc22/files/install_avr_tools.sh
(please see the comments at the start of the script for additional requirements)

b) The latest AVR-GCC debian packages:
http://www.wrightflyer.co.uk/avr-gcc/

Alternatively you can use your distro installation of avr tools but make sure
you are using the required avr-libc version (1.7.0). Unfortunately the
distribution versions are generally outdated.

On Windows you can try using WinAVR and/or AVR Studio. However if you want to
build and debug the project I highly recommend working under Unix.


BUILD
Compile the project using the command "make all"

In order to program via JTAG or USB without root access you must create the following
rule files under /etc/udev/rules.d (ubuntu, probably similar on other distros):

45-atmel.rules:
    ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2103", MODE="0660", GROUP="plugdev"
    ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2107", MODE="0660", GROUP="plugdev"

98-lufa-virtualserial.rules:
    SUBSYSTEM=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="204b", MODE="660", GROUP="plugdev"
    BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="204b", MODE="660", GROUP="plugdev"

    SUBSYSTEM=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="2044", MODE="660", GROUP="plugdev"
    BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="2044", MODE="660", GROUP="plugdev"

    SUBSYSTEM=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="204f", MODE="660", GROUP="plugdev"
    BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="204f", MODE="660", GROUP="plugdev"

    SUBSYSTEM=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="206f", MODE="660", GROUP="plugdev"
    BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="206f", MODE="660", GROUP="plugdev"

99-dfu_programmer.rules:
    BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="*", MODE="666", GROUP="root"

DEBUG/PROGRAM

I recommend using an AVR Dragon for programming and debugging of your chip. Use
avrdude to program your chip. 

Use the following commands to program:
    "make program-dragon": program the SCD using avrdude and the AVR Dragon.
    "make program-dragon-dfu": similar to "program-dragon" but include the bootloader so that you can later program the SCD via USB.
    "make program-dfu": program the SCD via USB using dfu-programmer (you need the bootloader preinstalled on the SCD).

Use the following commands to debug:
    "make avarice": allow debugging of the application using the SCD and AVR Dragon (next use "make debug").
    "make debug": connect avr-gdb to avarice (once avarice is running).
    "make debug-insight": similar to "make debug" but using the INSIGHT interface of GDB.

HARDWARE CHANGES IN NEWER VERSIONS OF SCD

The new hardware version sold by Smart Architects has the smart card detector
switch inverted. If you have one of this boards (from 2012 onwards), then
remove the comments on this line of the Makefile:

## CFLAGS += -D INVERT_ICC_SWITCH

and recompile and build the source code. Then program the SCD with the
modified code.


SET FUSES
For the first time using the board you might need to set up the fuses for correct operation of the SCD.
This can be done easily typing the following command:
    "make set-dragon-fuses"
as the name suggests, you need to use the AVR Dragon or similar JTAG programmer.

DOCUMENTATION
You can find the documentation in HTML format for the source code in the doc/ folder.
Point your browser to the doc/html/index.html file.

For more information about the software and how to get the SCD check the forum
of the Smart Card Detective at:
http://www.smartcarddetective.com/forum/

Copyright (C) Omar Choudary (omar.choudary@cl.cam.ac.uk)
http://cl.cam.ac.uk/~osc22/scd/

