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

The SRS-4 software consists of two firmware images and a single bootloader. Both firmware images
can be upgraded on-orbit using CSP while the bootloader can only be upgraded on ground.

The ``sys.boot.slot`` property shows which firmware image is currently running. The ``boot status``
command can be used to see additional information about the state of the two firmware images:

.. code-block:: none

    [satctl] srs4 boot status
    [slot 0] booted, preferred
    status:   stable
    priority: 1
    attempts: 2
    contents: valid

    [slot 1]
    status:   stable
    priority: 0
    attempts: 3
    contents: valid

By default, the SRS-4 will always boot the stable image with the highest priority, which is
indicated by the ``preferred`` keyword in the example above. Booting any of the
images for a number of boots can be configured using :ref:`BLIB<blib>`.
A firmware image can be marked as stable using :ref:`BLIB<blib>`, but it will also be marked stable
automatically after an uptime of 120 seconds.

Satlab supplies the ``blib-update`` script that simplifies the firmware update process by wrapping
the process outlined below into a single command.

.. code-block:: none

    satlab@satlab:~$ blib-update -d 24 --mark-stable -c <can_device> <path_to_.slim_file>

The ``blib-update`` tool is part of ``satctl`` which can be obtained here: https://resources.satlab.com/software/satctl/

Manual Firmware Update
======================

The ``boot flash`` command can be used to update a firmware image. Firmware images are stored
in SLIM (SatLab IMage) files. The SLIM file must already be transferred to the SRS-4 using :ref:`BTP<btp>`.
Firmware file uploads must use a block size of 128, which can be specified using the ``-s 128``
argument to the ``btp`` command. The name of the new SLIM file must be ``flash0``.

The example below shows how a ``.slim`` file can be moved to the SRS-4 and flashed to slot 1
from slot 0 using satctl:

.. code-block:: none

    [satctl] srs4 btp remove -t 60000 flash0
    [satctl] srs4 btp push -c100 -s128 -i60000 <path_to_.slim_file> flash0
    [satctl] srs4 boot flash flash0 1
    Flashing "flash0" to slot 1
    Flashed image OK
    [satctl] srs4 boot prefer 1
    [satctl] srs4 reboot

It is also possible to complete the flashing process using the serial interface instead:

.. code-block:: none

    [srs-4] boot flash flash0 other
    Flashing image from flash0 to slot 1
    Successfully flashed image
    [srs-4] boot prefer other
    [srs-4] reboot

.. NOTE::
    It is not possible to overwrite the booted image.

The SRS-4 automatically marks the boot as successful 120 seconds after a successful boot. It is
also possible to do this programmatically.

More information regarding boot options of the two firmware images can be found in the :ref:`blib`.

Bootloader Image
================

The bootloader can only be updated using the ``boot loader flash`` command. It is not possible to
update it remotely via CSP. A bootloader image is stored as a part of a firmware image. It is therefore
not required to specify a file name when updating the bootloader.

.. NOTE::
    The bootloader can only be updated from slot 1.

The example below shows how to update and verify the bootloader image:

.. code-block:: none

    [srs-4] boot loader flash
    Flash bootloader? [y/N] y
    [srs-4] boot loader verify
    Bootloader matches embedded

Recovery Update
===============

The SRS-4 firmware can be updated on ground using the provided Satlab JTAG/serial adapter. The update procedure requires a Linux development machine and OpenOCD version 0.12.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:

.. code-block:: none

    satlab@satlab:~$ tar xf satlab-srs4-v2.0.0.tar.xz
    satlab@satlab:~$ cd satlab-srs4-v2.0.0/firmware
    satlab@satlab:~$ ./flash.py srs4-v2.0.0-recovery.bin
    [+] Satlab firmware flash tool v1.2.0
    [+] Flashing image using OpenOCD srs4-v2.0.0-recovery.bin
    [+] Succesfully flashed the firmare to the board

A full remote firmware update according to the steps above must now be performed to ensure the FPGA bitstream is updated accordingly.
