# Firmware Update

The SRS-3 uses two firmware images: a primary image containing factory firmware that can only be updated on ground, and an alternate image that can also be updated on-orbit using CSP.

## Primary Image

The SRS-3 primary image can be updated on ground using the provided Satlab JTAG/serial adapater. The update procedure requires a Linux development machine and OpenOCD version 0.11.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 Getting Started.

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:

    satlab@satlab:~$ tar xvf srs3-v2.3.0.tar.xz
    srs3-v2.3.0/flash.py
    srs3-v2.3.0/srs3-v2.3.0.bin
    srs3-v2.3.0/srs3-v2.3.0-alt.bin
    srs3-v2.3.0/CHANGELOG.rst
    satlab@satlab:~$ cd srs3-2.3.0
    satlab@satlab:~/srs3-v2.3.0$ ./flash.py srs3-v2.3.0.bin
    [+] Satlab firmware flash tool v1.2.0
    [+] Flashing image using OpenOCD srs3-v2.3.0.bin
    [+] Succesfully flashed the firmare to the board

## Alternate Image

The alternate image can be updated via CSP, by first uploading the `srs3-alt.bin` image file using BTP, and then flashing it to the alternate partition. For BTP, the SRS-3 uses a basic flash file system backend with 4 files named `flash0` to `flash3` to hold images. Uploads to these files must use a block size of 128, which can specified using the `-s 128` argument to the `btp` command. After the image has been uploaded to one of the 4 flash files, it can be written to the alternate partition with the `srs3 boot flash` command and verified using `srs3 boot verify`. The alternate image can then be booted for a number of subsequent boots, using the `srs3 boot set` command.

The listing below shows the steps when executed using `satctl`. Note that the checksum returned by `srs3 boot flash` is the CRC32C of the binary image file, while the checksum returned by `srs3 boot verify` is a checksum embedded in the image itself. They are thus not expected to be the same.

    [satctl] btp -n21 -f -s128 push srs3-alt.bin flash0
    100% [########################################] 208360
    27.6 kbit/s (205184 bytes in 58.097s)
    [satctl] srs3 timeout 20000
    [satctl] srs3 boot flash flash0
    Flashing "flash0" to alternate boot partition
    Flashed image, checksum = 48674bc7
    [satctl] srs3 boot verify
    Alternate image is OK! (size 208356, checksum 6E7C093C)
    [satctl] srs3 boot set 1
    Setting alternate firmware boot for 1 boots
    Success - Reboot to boot alternate image
    [satctl] srs3 reboot