153 lines
7.3 KiB
XML
153 lines
7.3 KiB
XML
<?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>
|