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 SIMtrace 2, which uses the SAM3S replacement micro-controller. Patches to add support for the Atmel AT91SAM7S in the simtrace2 software are welcome.
The Firmware for the AT91SAM7S device was written by reusing a lot of the code for the OpenPCD
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
Building the firmware¶
Precondition: You need to set your PATH in a way that contains an arm-elf-gcc toolchain.
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 ../..
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.
- main_simtrace.samba -- sam7dfu + simtrace image. to be loaded via SAM-BA, using sam7utils (see below).
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.
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:
sudo apt-get install dfu-util
To flash the firmware:
sudo dfu-util -d 16c0:0762 -a0 -D ./main_simtrace.bin -R
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.
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.
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.
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=""
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
Now when the board is attached to USB, lsusb should show :
Bus 002 Device 015: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader
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 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.
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:
sudo rmmod sam_ba
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.
sudo rmmod cdc_acm
to flash the samba image using libusb :
sudo ./sam7 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"
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 :
sudo rmmod usbserial sudo modprobe usbserial vendor=0x03EB product=0x6124
to flash the samba image using serial :
sudo ./sam7 -l /dev/ttyUSB0 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"
The debug serial is available with 115200 baud and 8n1 with no flow control
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.
- 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