# Getting and Building the Firmware

## Introduction

The Firmware is the Software that is running on the Microcontroller of the SIMtrace hardware. The Firmware itself consists out of a couple of components for different parts of the system. Besides the source code for the firmware you will also need to have an ARM Cross-Compile Toolchain, a copy of the SAM7 utilities to initially program the device or recover from a fatal error and dfu-util to update the main part of the firmware using the Device Firmware Update (DFU) mode.

## Getting a Toolchain

The toolchain needs to include a GCC newer than 3.4 and it may not be an EABI toolchain. EABI toolchains fail to properly link the SIMtrace binary. You can easily build a toolchain yourself or use one of the known working pre-built ones. Please see the SIMtrace wiki for more information about getting a toolchain.

## Getting and Building the Firmware

The SIMtrace firmware is based on the OpenPCD RFID Reader Firmware and the SIMtrace firmware code is located in the OpenPCD repository. You can use the `git` to clone the repository.

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

The firmware consists out of two separate binaries that will be concatted and flashed into the NOR flash of the microcontroller. The main part is the dfu program that will handle basic USB functionality and respond to Device Firmware Update (DFU) requests to allow to update the firmware in the NOR or execute software in RAM.

    $ 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 Details

The handling for the DFU part can be found in the `src/dfu` directory, it also provides low-level USB routines to work with USB Device Port (UDP). These functions will be called from the main payload.

The operating system part is in `src/os` it provides basic hardware control and services to be used by the main application, this includes USB enumeration, Watchdog programming, running the mainloop, interrupt dispatching. The main application for SIMtrace can be found in `src/simtrace` and this includes programming the two USART, configuring the bus switch according to the mode.

## Initial Firmware Programming

In case the NOR Flash of the SAM7 Microcontroller is either blank or has become corrupted the Microcontrollers support entering a mode called SAM-BA which then allows flashing the device using the `sam` application. The SAM-BA mode can be easily entered by following the below procedure.

### Entering SAM-BA Mode

1. Unplug the SIMtrace Hardware from USB.

2. Short TEST to VCC (3.3V) pin by using the Jumper. Leave PA0, PA1, PA2 unconnected.

3. Power up the SIMtrace Hardware from USB.

4. Wait for 20 seconds.

5. Unplug the SIMtrace Hardware from USB.

6. Open/Remove the Jumper.

### TEST Jumper

### v1.0p/v1.1p Hardware Owners

Sometimes the SAM-BA mode is not entered. This is the case when the two LEDs are on when powering up the SIMtrace Hardware with the Jumper set. The reason for this is unknown but there are several workarounds:

- Press the RESET button while powering up.

- In addition, remove the jumper and put it back.

As soon as the two LEDs go off, the SAM-BA mode is properly entered.

The `sam` application can be compiled to either use libusb or normal files to program the device, depending on the drivers used you will need to configure the application one way or another. The programming can then be done using the below command.

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

### Silent failures

The `sam` can silently fail when not finding or being able to configure the device properly. It is best to enter the interactive mode by not providing any `--exec` commands.

## Device Firmware Update

The Device Firmware Update (DFU) part of the firmware will be booted first, it is checking if a button is active or if the software reset reason was for DFU and then activates the DFU part or jumps to the main application. DFU can be activated at any time using `dfu-util` on the USB Host.

The `dfu-util` application might be already packaged for your distribution, the source code can be found on the dfu-util.gnumonks.org website. To update the main part of the firmware simply do:

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

## Upgrading to v0.4 Firmware

Upgrading to v0.4 requires flashing both the Bootloader and the SIMtrace application. The procedure is first to flash the bootloader, then the SIMtrace application and finally reset the device.

    $ dfu-util -d 16c0:0762 -a 1  -D ./dfu.bin
    $ dfu-util -d 16c0:0762 -a 0  -D ./main_simtrace.bin
    ... reset the device

## Serial Console for debugging

The serial console operates at 115200 bauds with 8n1 and no flow control.