SIM card related Projects » SIMtrace

**%{background:yellow}WARNING: this project only applies to the first generation SIMtrace hardware, which uses the Atmel AT91SAM7S micro-controller. This project is not supported anymore. The hardware and software are still working, but won't get updates. This project is now replaced by project:simtrace2, which uses the SAM3S replacement micro-controller. Patches to add support for the Atmel AT91SAM7S in the simtrace2 software are welcome.%**

h1. SIMtrace Firmware

The Firmware for the AT91SAM7S device was written by reusing a lot of the code for the "OpenPCD":http://www.openpcd.org/

RFID reader.  

There is a simtrace Makefile target in the https://gitea.osmocom.org/sim-card/openpcd repository containing the latest firmware code.

Eventually, the OS part of [[OpenPCD]]/OpenPICC/SIMtrace will be separated.  At that point, the firmware source can become

part of simtrace.git

h2. Building the firmware

Precondition: You need to set your PATH in a way that contains an arm-elf-gcc toolchain.

<pre>

git clone https://gitea.osmocom.org/sim-card/openpcd

cd openpcd/firmware

make -f Makefile.dfu BOARD=SIMTRACE

make BOARD=SIMTRACE DEBUG=1 TARGET=main_simtrace

cat dfu.bin main_simtrace.bin > main_simtrace.samba

cd ../..

</pre>

h3. Firmware parts

The firmware build process creates two images:

* dfu.bin -- the sam7dfu 2nd level bootloader. It implements the USB DFU (Device Firmware Upgrade) profile.

* main_simtrace.bin -- the actual simtrace program. To be loaded via DFU, using "dfu-util":http://dfu-util.gnumonks.org/.

* main_simtrace.samba -- "sam7dfu":http://www.openpcd.org/Sam7dfu + simtrace image. to be loaded via SAM-BA, using sam7utils (see below).

h2. Flashing the firmware

There are two ways to flash the firmware:

* DFU: over USB and simple.

* SAM-BA: for AT91SAM7S without DFU installed, or when DFU fails.

h3. DFU

SIMtrace comes with the Device Firmware Upgrade (DFU) already installed.

To install it on a new AT91SAM7S, use the SAM-BA procedure below.

DFU can be used to replace the SIMtrace payload.

To get dfu-util:

<pre>

sudo apt-get install dfu-util

</pre>

To flash the firmware:

<pre>

sudo dfu-util -d 16c0:0762 -a0 -D ./main_simtrace.bin -R

</pre>

dfu-util should reset the board and use the DFU bootloader.

Try the command a second time if it did not work at first.

If this still does not work, power up the board while pressing the *BOOTLOADER* button.

h3. SAM-BA

The SAM-BA mode is provided by the AT91SAM7S.

This can be used at any time, even if the firmware bricks the device.

To flash the new firmware, sam7utils is used.

h4. sam7utils

SAM-BA images contain a full NOR flash image.  They can be used in case the sam7dfu bootloader was corrupted,

and can be installed either using the *sam7* program released by Atmel, or via JTAG based flashing.

Installing firmware using SAM-BA is a bit cumbersome and requires strict adherence to a sequence of USB cable

plugging/unplugging and jumper setting, waiting, jumper removal, etc.

sam7utils will be used to flash the *main_simtrace.samba* image over SAM-BA.

<pre>

sudo aptitude install libreadline-dev libusb-dev

wget http://www.openpcd.org/dl/sam7utils-0.2.1-bm.tar.bz2

tar xf sam7utils-*.tar.bz2

cd sam7utils

./configure --prefix=/usr/local

make AM_CFLAGS=""

</pre>

h4. Entering the SAM-BA mode

The first time you flash the device, you will have to use the SAM-BA method using the main_simtrace.samba image.

To put the board into SAM-BA mode, use the following steps:

* unplug the board

* short TEST to VCC (3.3V) pin using a jumper. leave PA0,PA1,PA2 unconnected.

* power up the board

* wait 20s

* unplug board

* remove jumper

!shortTEST.jpg!

Now when the board is attached to USB, lsusb should show :

<pre>

Bus 002 Device 015: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader

</pre>

*note*: sometimes switching to SAM-BA mode is not working.

This is the case if the 2 LEDs are on when powering up the board while VCC and TEST is shorted.

This is because PA0 should be pulled up to enter the SAM-BE mode, but the internal pull-up does not seem to be used.

There are several methods to correct this:

* press the RESET button while powering up

* touch PA0 (pin 48, on the right upper corner) with a piece of metal

* short PA0 and PA1 (pin 48 and 47, next to each other on the right upper corner)

As soon as the LEDs go off, the SAM-BA mode is working.

*note for SIMtace v1.3 boards*: Because of a [[SIMtraceHardware#v13|hardware design bug] if you produced the board yourself you have to cut a path on the board and write the board version on flash the first time you install the firmware Follow the detailed [wikiProductionFlashingV13 instructions]].

For more information about SAM-BA, please refer to the Atmel documentation on the AT91SAM7S component.

h4. Flashing the firmware with sam7

You can flash with sam7utils using libusb or POSIX.

It may happen that sam7 loads a sam_ba module at the end.

If you want to use sam7 multiple times, remove the loaded module after each run:

<pre>

sudo rmmod sam_ba

</pre>

h5. flashing using libusb

sam7utils tries to compile with libusb, so to access the device directly.

If libusb is not present, you must flash using serial.

On ubuntu the usb device 03eb:6124 is mapped on /dev/ttyACMx using the cdc_cam module.

Remove it while the board is plugged, so sam7utils is able to communicate with it.

<pre>

sudo rmmod cdc_acm

</pre>

to flash the samba image using libusb :

<pre>

sudo ./sam7 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"

</pre>

h5. using POSIX

If libusb is not present, sam7utils will be compiled to communicate with the board using POSIX.

If the device is not mapped to a node, use usbserial :

<pre>

sudo rmmod usbserial

sudo modprobe usbserial vendor=0x03EB product=0x6124

</pre>

to flash the samba image using serial :

<pre>

sudo ./sam7 -l /dev/ttyUSB0 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"

</pre>

h2. Serial

The debug serial is available with 115200 baud and 8n1 with no flow control

h2. Bugs

With high speed SIM cards some bytes inside an APDU can be skipped. This is more likely to happen in a virtualized environment. The workaround is to decrease the buffer size inside the firmware. 

h2. Version History

* v0.2 Fixes ATR handling for older SIMcards.

* v0.4 fixes wrong Fi/Di computation in some cases

* v0.5 fixes SIMtrace crashes, lost bytes, WDT expiration and many other issues