= SIMtrace Firmware =

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

There is a {{{simtrace}}} Makefile target in the git://git.gnumonks.org/openpcd.git 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 [wiki:toolchain], i.e. the same way that you build [wiki:GettingStarted OsmocomBB].

{{{
git clone git://git.gnumonks.org/openpcd.git
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 [http://dfu-util.gnumonks.org/ dfu-util]. * main_simtrace.samba -- [http://www.openpcd.org/Sam7dfu sam7dfu] + simtrace image. to be loaded via SAM-BA, using sam7utils (see below).

=== 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. {{{
sudo aptitude install libreadline-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
}}}

==== 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

Image(shortTEST.jpg)

Now when the board is attached to USB, lsusb should show : {{{
Bus 002 Device 015: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader
}}}

'''note for v1.0p boards''': sometimes the 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. The
reason in unknown, but 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.

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

==== Flashing the firmware ====

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"
}}}
to flash the samba image using libusb : {{{
sudo ./sam7 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"
}}}

if you want to use sam7 multiple times, remove the loaded module after each run: {{{
sudo rmmod sam_ba
}}}

==== sam7utils for x86 ====

On x86, sam7utils will be compiled to communicate with the board using POSIX.

The board should be attached to a node. On ubuntu 10.10, the usb device 03eb:6124 is mapped on /dev/ttyACM0 using the cdc_cam module. If not mapped, use usbserial : {{{
sudo rmmod usbserial
sudo modprobe usbserial vendor=0x03EB product=0x6124
}}}

Now replug board. It should map to /dev/ttyUSBx (use dmesg to know which).

==== sam7utils for amd64 ====

On amd64, sam7utils will be compiled to communicate with the board using libusb.

On ubuntu 10.10 & 11.04, 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 (using libusb for 10.10 and serial for 11.04). {{{
sudo rmmod cdc_acm
}}}

=== DFU ===

The Device Firmware Upgrade (DFU) can be used to replace the SIMtrace payload.

To get dfu-util: {{{
sudo apt-get install dfu-util
}}}

To flash the firmware: {{{
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.

Bugs

Currently there is a bug in the firmware that makes the device fail to enumerate on OSX. We provide an alternative hacked firmware until we have resolved the issue properly.

Version History * v0.2 Fixes ATR handling for older SIMcards.