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

The system can be updated remotely via CSP using the protocol specified in :ref:`btp` and :ref:`blib` sections. For example, to update the software via CAN using satctl, first check the currently booted slot using ``polaris boot status``:

.. code-block:: none

    satlab@satlab:~$ satctl -c can0
    Satlab Control Application v1.22.0
    Copyright (c) 2014-2025 Satlab A/S <satlab@satlab.com>

    Run 'help' for a list of available commands

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

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

In this example, slot 0 is booted and preferred, i.e. it is currently running and will be attempted again on the next boot. A booted slot can not update itself, so in this case slot 1 should be updated. First mount the file system and transfer the update SLIM file to the device using BTP:

.. code-block:: none

    [satctl] polaris prop set conf.fs.mount 1
    [satctl] polaris btp push -f polaris-v2.0.0.slim /
    100% [########################################] 3338132 
    240.6 kbit/s (3333492 bytes in 108.239s)

Next, increase the timeout to account for the flashing time and run ``polaris boot flash`` with the target slot and SLIM file to perform the flashing. The slot is automatically disabled until the flashing completes successfully.

.. code-block:: none
 
    [satctl] polaris timeout 30000
    [satctl] polaris boot flash 1 /polaris-v2.0.0.slim
    Flashing "/polaris-v2.0.0.slim" to slot 1
    Flashed image OK

To boot the updated slot, switch the preferred slot to slot 1 and reboot the system. Both the ``sys.boot.slot`` property and the bootloader status now shows slot 1 as booted:

.. code-block:: none

    [satctl] polaris boot prefer 1
    [satctl] polaris reboot
    [satctl] polaris uptime
    10 seconds
    [satctl] polaris prop get sys.boot.slot
    1
    [satctl] polaris boot status 
    [slot 0]
    status:   stable
    priority: 0
    attempts: 3
    contents: valid

    [slot 1] booted, preferred
    status:   testing
    priority: 1
    attempts: 2
    contents: valid

Since the slot has status ``testing``, the boot needs manual confirmation of a successful boot to reset boot attempts. Mark the boot successful to reset boot attempts for slot 1 using ``polaris boot success``:

.. code-block:: none

    [satctl] polaris boot success 
    [satctl] polaris boot status 
    [slot 0]
    status:   stable
    priority: 0
    attempts: 3
    contents: valid

    [slot 1] booted, preferred
    status:   testing
    priority: 1
    attempts: 3
    contents: valid

The bootloader status now shows 3 remaining boot attempts for slot 1. 

Recovery Update
---------------

The Polaris 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-polaris-v2.0.0.tar.xz
    satlab@satlab:~$ cd satlab-polaris-v2.0.0/firmware
    satlab@satlab:~$ ./flash.py polaris-v2.0.0-recovery.bin 
    [+] Satlab firmware flash tool v1.2.0
    [+] Flashing image using OpenOCD polaris-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.
