SIM card related Projects » SIMtrace 2

{{>toc}}

h1. Flashing

There are several ways to flash [[Wiki#Firmware|firmware images]], depending on your board, the image you want to flash, and the state of your device.

h1. SIMtrace2 board

This section will cover the flashing methods for the [[Wiki#SIMtrace v2|SIMtrace board]].

h2. DFU

*precondition*: a functioning application firmware or DFU bootloader must already be installed.

SIMtrace2 comes with a USB DFU bootloader pre-installed which allows to flash the application firmware over USB using the @dfu-util@ utility.

To check if you have a functioning application firmware or DFU bootloader, power the board:

* if both green and red LEDs are on, you should have a functioning application firmware

* if only the green LED is on, the application firmware is missing, but the DFU bootloader is present

* in case the application firmware is buggy, you can force the board to boot the DFU bootloader: on the board keep the *BOOTLOADER* button pressed while re-plugging the USB connector (pressing the *RESET* might not be sufficient)

!{width:20%}simtrace-board-buttons.jpg!

* if the USB DFU bootloader is missing, defective, or needs to be updated, use the JTAG or SAM-BA methods to flash the DFU bootloader.

To update the application firmware over the DFU bootloader, we will use @dfu-util@:

# get @dfu-util@:

<pre>

sudo apt-get install dfu-util

</pre>

# check if the board and DFU bootloader are detected:

<pre>

sudo dfu-util --list

...

Found Runtime: [1d50:60e3] ver=0002, devnum=20, cfg=1, intf=1, path="2-3.1", alt=0, name="UNKNOWN", serial="..."

</pre>

# get the "latest firmware":http://ftp.osmocom.org/binaries/simtrace2/firmware/latest or [[Wiki#Development|build it]]. Here we will use the _trace_ application firmware as example:

<pre>

wget https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/simtrace-trace-dfu-latest.bin

</pre>

# flash the firmware using @dfu-util@:

<pre>

sudo dfu-util --device 1d50:60e3 --cfg 1 --alt 1 --reset --download simtrace-trace-dfu-latest.bin

</pre>

# the green and red LED should turn on, showing the application firmware is flashed and started

h2. SAM-BA

The SAM3S micro-controller comes with an embedded bootloader called SAM-BA, allowing to flash firmware over USB.

The SAM-BA bootloader can be used to flash the DFU bootloader.

This method should be used if:

* no firmware is flashed on the device, or it has been erased (no LED turns on when the board is powered)

* the DFU bootloader is buggy

* you want to update the DFU bootloader

You can also activate the SAM-BA bootloader by erasing the flash content (this is not reversible):

# short the *ERASE* pin on the top of the board with the nearby 3V3 pin using a jumper or tweezers

!{width:20%}simtrace-jumper-mini.jpg!

# re-plug the USB connector and wait 1 second (pressing the *RESET* button is not sufficient)

# remove the jumper shorting *ERASE* to 3V3

# no LED should turn on

# to verify if the SAM-BA bootloader has been started:

** using @lsusb@ you should find the following entry:

<pre>

ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader

</pre>

** using @journalctl -f@ ensure the board has been recognized as USB ACM device:

<pre>

kernel: usb 2-2: new full-speed USB device number 4 using xhci_hcd

kernel: usb 2-2: New USB device found, idVendor=03eb, idProduct=6124

kernel: usb 2-2: New USB device strings: Mfr=0, Product=0, SerialNumber=0

kernel: cdc_acm 2-2:1.0: ttyACM0: USB ACM device

kernel: usbcore: registered new interface driver cdc_acm

kernel: cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters

</pre>

To flash using the SAM-BA bootloader:

# [[Flashing#Install-bossa|install bossa]]

# download the DFU bootloader:

<pre>

wget https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/simtrace-dfu-flash-latest.bin

</pre>

# flash the USB DFU bootloader using @bossac@ (note: @erase@ ensures no main application remains so to force booting the USB DFU bootloader; @boot=1@ ensures the micro-controller will boot from the internal flash instead of the embedded bootloader next time it is powered up)

<pre>

sudo bossac --port=/dev/ttyACM0 --usb-port=1 --erase --verify --boot=1 --write simtrace-dfu-flash-latest.bin

</pre>

# re-plug the USB connector (be sure the *ERASE* pin is not shorted). If the DFU bootloader has been flashed correctly:

** only the green LED should be on

** the USB device should be listed as SIMtrace instead od SAMBA

<pre>

lsusb

...

Bus 002 Device 024: ID 1d50:60e3 OpenMoko, Inc. Osmocom SIMtrace 2

</pre>

** the DFU bootloader should be recognized:

<pre>

sudo dfu-util --list

...

Found DFU: [1d50:60e3] ver=0000, devnum=24, cfg=1, intf=0, path="2-3.1", alt=1, name="Flash (Application Partition)", serial="UNKNOWN"

Found DFU: [1d50:60e3] ver=0000, devnum=24, cfg=1, intf=0, path="2-3.1", alt=0, name="RAM", serial="UNKNOWN"

</pre>

Once the USB DFU bootloader is flashed, you can flash the application firmware using the [[Flashing#DFU|DFU]] method.

To prevent using @sudo@, grant to current user the permission to access USB serial devices (e.g. @/dev/ttyACM0@). Note: this change only takes effect after re-logging-in

<pre>

sudo adduser $USERNAME dialout

</pre>

h2. JTAG

It is also possible to flash he firmware over JTAG/SWD using the ARM 20-pin JTAG header on the top of the board.

This is mainly meant for [[Wiki#Development|development]] since it also allows to debug the firmware.

To flash the USB DFU firmware using JTAG:

# install the JTAG utility @openOCD@

<pre>

sudo apt install openocd

</pre>

# download the DFU bootloader:

<pre>

wget https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/simtrace-dfu-flash-latest.bin

</pre>

# flash the USB DFU bootloader firmware

<pre>

openocd --file interface/jlink.cfg --file target/at91sam3sXX.cfg --command "init" --command "halt" --command "flash write_bank 0 simtrace-dfu-flash-latest.bin 0" --command "at91sam3 gpnvm set 1" --command "reset" --command "shutdown"

</pre>

#* replace @interface/jlink.cfg@ with the configuration file for your JTAG debugging adapter

#* @at91sam3 gpnvm set 1@ ensures the micro-controller will boot from the internal flash (i.e. not from the embedded SAM-BA bootloader)

The SAM3S also offers the low pin-count SWD alternative to JTAG, allowing to use an inexpensive ST-Link V2 (clone) to flash (and debug):

<pre>

openocd --file interface/stlink-v2.cfg --command "set CPUTAPID 0x2ba01477" --file target/at91sam3sXX.cfg --command "init" --command "halt" --command "flash write_bank 0 simtrace-dfu-flash-latest.bin 0" --command "at91sam3 gpnvm set 1" --command "reset" --command "shutdown"

</pre>

SWD pinout:

!{width:20%}simtrace_swd.jpg!

Once the USB DFU bootloader is flashed, after re-plugging the USB connector, you can flash the main application firmware using the DFU method.

h1. sysmoQMOD

This section will cover the flashing methods for the [[Wiki#sysmoQMOD|sysmoQMOD board]].

The sysmoQMOD has two SAM3S micro-controllers, each emulating the card for two modems:

* ST12 is the micro-controller on the right (when the power jack is on top), and emulates cards for the two right-most modems

* ST34 is the micro-controller on the left (when the power jack is on top), and emulates cards for the two left-most modems

* each card slot has one red LED nearby (e.g. two per micro-controllers) to show the status of the firmware

All the following procedures can be independently performed on each of the SAM3S micro-controllers, providing you use the corresponding USB path/device names.

h2. DFU

*precondition*: a functioning application firmware or DFU bootloader must already be installed.

sysmoQMOD comes with a USB DFU bootloader pre-installed which allows to flash the application firmware over USB using the @dfu-util@ utility.

To check if you have a functioning application firmware or DFU bootloader (per micro-controller and set of two modems/card slot), power the board:

* if both red LEDs are on, you should have a functioning application firmware

* if only one red LED is on, the application firmware is missing, but the DFU bootloader is present

* in case the application firmware is buggy, you can force the board to boot the DFU bootloader: short the TX and RX pins next to the micro-controller while powering the board.

!{width:20%}sysmoqmod-dfu.jpg!

* if the USB DFU bootloader is missing, use the SAM-BA method to flash the DFU bootloader.

To update the application firmware over the DFU bootloader, we will use @dfu-util@:

# get @dfu-util@:

<pre>

sudo apt-get install dfu-util

</pre>

# check if the board and DFU bootloader are detected (here for both micro-controllers):

<pre>

sudo dfu-util --list

...

Found Runtime: [1d50:4004] ver=0002, devnum=36, cfg=1, intf=2, path="2-2.1", alt=0, name="UNKNOWN", serial="UNKNOWN"

Found Runtime: [1d50:4004] ver=0002, devnum=37, cfg=1, intf=2, path="2-2.4", alt=0, name="UNKNOWN", serial="UNKNOWN"

</pre>

# get the "latest firmware":http://ftp.osmocom.org/binaries/simtrace2/firmware/latest or [[Wiki#Development|build it]].

<pre>

wget https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/qmod-cardem-dfu-latest.bin

</pre>

# flash the firmware using @dfu-util@:

<pre>

sudo dfu-util --device 1d50:4004 --cfg 1 --alt 1 --path "2-2.1" --reset --download qmod-cardem-dfu-latest.bin

</pre>

# both red LEDs should turn on, showing the application firmware is flashed and started

h2. SAM-BA

If none of the LEDs are on, the flash of the micro-controller might have been erased.

In this case, the SAM3S micro-controller should start the embedded bootloader called SAM-BA, allowing to flash firmware over USB.

The SAM-BA bootloader can be used to flash the DFU bootloader.

To verify if the SAM-BA bootloader has been started:

* using @lsusb@ you should find the following entry:

<pre>

ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader

</pre>

* using @journalctl -f@ ensure the board has been recognized as USB ACM device:

<pre>

kernel: usb 2-2: new full-speed USB device number 4 using xhci_hcd

kernel: usb 2-2: New USB device found, idVendor=03eb, idProduct=6124

kernel: usb 2-2: New USB device strings: Mfr=0, Product=0, SerialNumber=0

kernel: cdc_acm 2-2:1.0: ttyACM0: USB ACM device

kernel: usbcore: registered new interface driver cdc_acm

kernel: cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters

</pre>

To flash using the SAM-BA bootloader:

# [[Flashing#Install-bossa|install bossa]]

# download the DFU bootloader:

<pre>

wget https://ftp.osmocom.org/binaries/simtrace2/firmware/latest/qmod-dfu-flash-latest.bin

</pre>

# flash the USB DFU bootloader using @bossac@ (note: @erase@ ensures no main application remains so to force booting the USB DFU bootloader; @boot=1@ ensures the micro-controller will boot from the internal flash instead of the embedded bootloader next time it is powered up)

<pre>

sudo bossac --port=/dev/ttyACM0 --usb-port=1 --erase --verify --boot=1 --write qmod-dfu-flash-latest.bin

</pre>

# Re-power the board. If the DFU bootloader has been flashed correctly:

** only one red LED should be on

** the USB device should be listed as OpenMoko/"quad modem" instead of SAMBA

<pre>

lsusb

...

Bus 002 Device 024: ID 1d50:4004 OpenMoko, Inc.

</pre>

** the DFU bootloader should be recognized:

<pre>

sudo dfu-util --list

...

Found DFU: [1d50:4004] ver=0010, devnum=58, cfg=1, intf=0, path="2-2.4", alt=1, name="Flash (Application Partition)", serial="UNKNOWN"

Found DFU: [1d50:4004] ver=0010, devnum=58, cfg=1, intf=0, path="2-2.4", alt=0, name="RAM", serial="UNKNOWN"

</pre>

Once the USB DFU bootloader is flashed, you can flash the application firmware using the [[Flashing#DFU-2|DFU]] method.

To prevent using @sudo@, grant to current user the permission to access USB serial devices (e.g. @/dev/ttyACM0@). Note: this change only takes effect after re-logging-in

<pre>

sudo adduser $USERNAME dialout

</pre>

If no LED is on and the SAM-BA bootloader is not present, or you require to update the DFU bootloader, please contact the customer support of sysmocom.

h1. Install bossa

"BOSSA":https://github.com/shumatech/BOSSA is a flash programming utility for Atmel's SAM family of flash-based ARM microcontrollers.

It allows to flash the DFU bootloader on the SAM3S micro-controller used on the SIMtrace2 boards.

h2. Debian/Ubuntu

Debian (10, buster) and Ubuntu (19.04, disco) only provide pacjages for bossa-cli v1.3 from 2012 ("debian":https://packages.debian.org/buster/bossa-cli, "ubuntu":https://packages.ubuntu.com/disco/bossa-cli).

This is too old and does not support the SAM3S micro-controller used in SIMtrace2.

Thus you will have to install the current version of bossa (v1.9.1 from 2018-08 as of 2019-09):

# install the required libraries

<pre>

sudo apt install libwxgtk3.0-dev libreadline-dev

</pre>

# install required tools

<pre>

sudo apt install wget

</pre>

# get the current bossa

<pre>

wget https://github.com/shumatech/BOSSA/archive/1.9.1.tar.gz

</pre>

# decompress archive

<pre>

tar xf 1.9.1.tar.gz

</pre>

# compile bossa

<pre>

cd BOSSA-1.9.1/

make

</pre>

# install the bossa command line tool to your system (bossa does not provide install scripts)

<pre>

sudo cp bin/bossa* /usr/local/bin/

</pre>

# clean up

<pre>

cd ..

rm -r BOSSA-1.9.1/

rm 1.9.1.tar.gz

</pre>

h2. Arch

Install the "AUR":https://wiki.archlinux.org/index.php/AUR package "bossa":https://aur.archlinux.org/packages/bossa/ (v1.9.1 from 2018-08 as of 2019-09).

<pre>

pacaur -S bossa

</pre>