<?xml version="1.0" encoding="UTF-8"?>
<chapter id="chapter_firmware">
    <title>Getting and Building the Firmware</title>
    <section id="building_fw_intro">
        <title>Introduction</title>
        <para>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.</para>
    </section>

    <section id="getting_a_toolchain">
        <title>Getting a Toolchain</title>
        <para>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
        <ulink url="http://bb.osmocom.org/trac/wiki/toolchain">SIMtrace wiki</ulink>
        for more information about getting a toolchain.
        </para>
    </section>

    <section id="getting_the_firmware">
        <title>Getting and Building the Firmware</title>

        <para>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
        <command>git</command> to clone the repository.
        <screen>
$ git clone https://gitea.osmocom.org/sim-card/openpcd
        </screen>
        </para>
    
        <para>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.
        <screen>
$ 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 ../..
        </screen></para>
    </section>
    <section id="firmware_details">
        <title>Firmware Details</title>
        <para>
        The handling for the DFU part can be found in the <filename>src/dfu</filename>
        directory, it also provides low-level USB routines to work with USB Device
        Port (UDP). These functions will be called from the main payload.
        </para>
        <para>The operating system part is in <filename>src/os</filename> 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
        <filename>src/simtrace</filename> and this includes programming the two USART,
        configuring the bus switch according to the mode.
        </para>
    </section>

    <section id="firmware_programming_sam_ba">
        <title>Initial Firmware Programming</title>
        <para>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 <filename>sam</filename> application. The
        SAM-BA mode can be easily entered by following the below procedure.</para>

        <procedure>
            <title>Entering SAM-BA Mode</title>
            <step><para>Unplug the SIMtrace Hardware from USB.</para></step>
            <step><para>Short TEST to VCC (3.3V) pin by using the Jumper. Leave PA0, PA1, PA2 unconnected.</para></step>
            <step><para>Power up the SIMtrace Hardware from USB.</para></step>
            <step><para>Wait for 20 seconds.</para></step>
            <step><para>Unplug the SIMtrace Hardware from USB.</para></step>
            <step><para>Open/Remove the Jumper.</para></step>
        </procedure>

        <figure>
            <title>TEST Jumper</title>
            <mediaobject><imageobject>
                <imagedata fileref="images/shortTEST.jpg" width="12cm"/>
            </imageobject></mediaobject>
        </figure>

        <note><title>v1.0p/v1.1p Hardware Owners</title>
            <para>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:
            <itemizedlist>
                <listitem><para>Press the RESET button while powering up.</para></listitem>
                <listitem><para>In addition, remove the jumper and put it back.</para></listitem>
            </itemizedlist>

            As soon as the two LEDs go off, the SAM-BA mode is properly entered.
            </para>
        </note>
        <para>The <command>sam</command> 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.
        <screen>
$ ./sam7 --exec set_clock --exec unlock_regions --exec "flash ../openpcd/firmware/main_simtrace.samba"
        </screen>
        <note><title>Silent failures</title>
        <para>The <command>sam</command> 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 <command>--exec</command> commands.</para>
        </note>
        </para>
    </section>

    <section id="firmware_programming_dfu">
        <title>Device Firmware Update</title>
        <para>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
        <command>dfu-util</command> on the USB Host.</para>
        <para>The <command>dfu-util</command> application might be already
        packaged for your distribution, the source code can be found on the
        <ulink url="http://dfu-util.gnumonks.org/">dfu-util.gnumonks.org</ulink>
        website. To update the main part of the firmware simply do:
        <screen>
$ dfu-util -d 16c0:0762 -a0 -D ./main_simtrace.bin -R
        </screen></para>
    </section>

    <section id="firmware_programming_upgrade">
        <title>Upgrading to v0.4 Firmware</title>
        <para>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.
        </para>

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

    <section id="firmware_serial_console">
	<title>Serial Console for debugging</title>
	<para>The serial console operates at 115200 bauds with 8n1 and no flow control.</para>
    </section>
</chapter>
