===============
Firmware Update
===============

The Polaris firmware can be updated on ground using the provided Satlab JTAG/serial adapater. The update procedure requires a Linux development machine and OpenOCD version 0.10.0 or later, which can be installed from http://openocd.org/ or most distribution package managers. Please ensure that the ``udev`` permissions are also configured as described in :ref:`starting`. 

Firmware packages are distributed as a ``tar.xz`` archive. The package includes a script, ``flash.py``, which wraps the OpenOCD commands and flashes the board:

.. NOTE::
   For on-orbit updates, please see the :ref:`btp` and :ref:`polaris-bootloader` section.

.. code-block:: none

    satlab@satlab:~$ tar xvf polaris-v1.0.0.tar.xz
    polaris-v1.0.0/satlab-jtag.cfg
    polaris-v1.0.0/flash.py
    polaris-v1.0.0/polaris-v1.0.0.bin
    satlab@satlab:~$ cd polaris-v1.0.0
    satlab@satlab:~/polaris-v1.0.0$ ./flash.py polaris-v1.0.0.bin
    [+] Satlab Polaris firmware flash tool v1.0.0
    [+] Calling OpenOCD to flash polaris-v1.0.0.bin:
    Open On-Chip Debugger 0.10.0
    Licensed under GNU GPL v2
    For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
    Info : FTDI SWD mode enabled
    atsame70q21
    adapter speed: 1800 kHz
    cortex_m reset_config sysresetreq
    Info : flash bank command
    adapter speed: 1800 kHz
    Info : clock speed 1800 kHz
    Info : SWD DPIDR 0x0bd11477
    Warn : Silicon bug: single stepping will enter pending exception handler!
    Info : atsame70q21.cpu: hardware has 8 breakpoints, 4 watchpoints
    target halted due to debug-request, current mode: Thread
    xPSR: 0x61000000 pc: 0x00417690 psp: 0x204087e8
    Info : device id = 0xa1020e00
    cleared protection for sectors 0 through 127 on flash bank 0
    target halted due to debug-request, current mode: Thread
    xPSR: 0x01000000 pc: 0x0041b08c msp: 0x20406cf0
    ** Programming Started **
    auto erase enabled
    Info : erasing lock regions 0-27...
    Info : erasing lock region 0
    Info : erasing lock region 1
    Info : erasing lock region 2
    Info : erasing lock region 3
    Info : erasing lock region 4
    Info : erasing lock region 5
    Info : erasing lock region 6
    Info : erasing lock region 7
    Info : erasing lock region 8
    Info : erasing lock region 9
    Info : erasing lock region 10
    Info : erasing lock region 11
    Info : erasing lock region 12
    Info : erasing lock region 13
    Info : erasing lock region 14
    Info : erasing lock region 15
    Info : erasing lock region 16
    Info : erasing lock region 17
    Info : erasing lock region 18
    Info : erasing lock region 19
    Info : erasing lock region 20
    Info : erasing lock region 21
    Info : erasing lock region 22
    Info : erasing lock region 23
    Info : erasing lock region 24
    Info : erasing lock region 25
    Info : erasing lock region 26
    Info : erasing lock region 27
    wrote 458752 bytes from file polaris-v1.0.0.bin in 8.860412s (50.562 KiB/s)
    ** Programming Finished **
    ** Verify Started **
    verified 453276 bytes in 10.500954s (42.154 KiB/s)
    ** Verified OK **
    ** Resetting Target **
    shutdown command invoked
    [+] Succesfully flashed the firmare to the board
