Flashing » History » Revision 7
Revision 6 (tsaitgaist, 09/04/2019 02:16 PM) → Revision 7/8 (tsaitgaist, 09/04/2019 02:30 PM)
{{>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>
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]] install the @bossac@ utility to flash using the SAMBA protocol
<pre>
sudo apt install bossac
</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 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>
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]] install the @bossac@ utility to flash using the SAMBA protocol
<pre>
sudo apt install bossac
</pre>
# 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>
