# SRS-3 Client Library

The Satlab SRS-3 client library provides remote access to the receiver using functions that wrap CSP protocol messages.

## Bootloader

This file contains functions to configure the boot process on a SRS-3 system.

The system is delivered with a factory firmware flashed in the first half of internal flash. An alternate image can be flashed on orbit in the “alternate

partion” in the second half of internal flash. An alternate firmware image (ending in “-alt.bin”) must be transferred to the NOR-flash using BTP and can then be flashed to the alternate partition using the

sl_srs3_bootloader_flash_alternate function.

Functions

int sl_srs3_bootloader_set_alternate(uint8_t node, uint32_t timeout, uint8_t boots)

  Request boot of the alternate image.

  The `boots` argument can be set 0 to boot the factory firmware. Note that a system reset, e.g. using CSP reboot or external power cycle, is required after this command to actually boot the image.

  After `boots` boot cycles, the system will return to the factory firmware.

  Parameters:

    - node – CSP address of the property node.

    - timeout – Timeout of the command in milliseconds.

    - boots – Number of boots to boot the alternate image.

  Returns:

    0 on success, negative error code otherwise.

int sl_srs3_bootloader_flash_alternate(uint8_t node, uint32_t timeout, const char *filename, uint32_t *crc)

  Flash image file from NOR-flash to alternate partition.

  This function flashes a firmware file from the NOR-flash to the alternate flash partion. It is not necessary to erase the partition first.

  The system calculates the checksum of the file and verifies the contents of the flash after programming. The calculated checksum is returned in the `crc` argument and can be used to verify the value on ground.

  Flashing and verifying a firmware image typically takes 15-30 seconds, so ensure that the timeout is set sufficiently high.

  It is not possible to flash an image when the alternate image is running. It must be performed from the factory image.

  Warning

  The firmware file must be an “-alt” variant binary.

  Parameters:

    - node – CSP address of the property node.

    - timeout – Timeout of the command in milliseconds.

    - filename – Filename of the remote file to flash.

    - crc – Returned CRC32C checksum of flashed file.

  Returns:

    0 on success, negative error code otherwise.

int sl_srs3_bootloader_erase_alternate(uint8_t node, uint32_t timeout)

  Erase alternate image partition.

  Erase the contents of the alternate firmware partition.

  Erasing the alternate firmware partition typically takes 10-15 seconds, so ensure that the timeout is set sufficiently high.

  It is not possible to erase the alternate image partition when the alternate image is running. It must be performed from the factory image.

  Parameters:

    - node – CSP address of the property node.

    - timeout – Timeout of the command in milliseconds.

  Returns:

    0 on success, negative error code otherwise.

int sl_srs3_bootloader_verify(uint8_t node, uint32_t timeout, uint8_t partition, uint32_t *size, uint32_t *checksum)

  Verify partition image.

  This function verifies the image in either the primary or alternate partion.

  Parameters:

    - node – CSP address of the property node.

    - timeout – Timeout of the command in milliseconds.

    - partition – Partition number. 0 for primary, 1 for alternate.

    - size – Read size of image.

    - checksum – Calculated checksum of image.

  Returns:

    0 on success, negative error code otherwise.

## Ground Watchdog

This file provides functions for resetting and reading the ground watchdog timer.

Defines

SL_SRS3_GWDT_RESET_KEY

Functions

static inline int sl_srs3_gwdt_reset(uint8_t node, uint32_t timeout, uint32_t key)

  Reset ground watchdog timer.

  Helper function to reset the ground watchdog timer property.

  Parameters:

    - node – CSP address of the SRS-3 node.

    - timeout – Timeout of the command in milliseconds.

    - key – Must be SL_SRS3_GWDT_RESET_KEY.

  Returns:

    0 on success, and a negative error code on error.

static inline int sl_srs3_gwdt_counter(uint8_t node, uint32_t timeout, uint32_t *counter)

  Read ground watchdog timer.

  Helper function to read the current ground watchdog timer counter. The counter holds the remaing time in seconds before the ground watchdog timer resets the system.

  Parameters:

    - node – CSP address of the SRS-3 node.

    - timeout – Timeout of the command in milliseconds.

    - counter – Pointer where the current counter is stored.

  Returns:

    0 on success, and a negative error code on error.

## Remote Command

This file provides functions for running debug shell commands remotely.

It is meant as a debugging aid and should not be required during normal operation of the device.

Functions

int sl_srs3_shell_run(uint8_t node, uint32_t timeout, const char *cmd)

  Run debug shell command.

  This function allows debug shell commands to be run on the Polaris system. The command is evaluated on the remote systems, and the command return value is returned. Output from the command is not available.

  Parameters:

    - node – CSP address of the property node.

    - timeout – Timeout of the command in milliseconds.

    - cmd – Command to execute

  Returns:

    0 on success, and a negative error code on error.

## Protocol Specification

Defines

SL_SRS3_DEFAULT_ADDRESS

SL_SRS3_PORT_BOOTLOADER

SL_SRS3_PORT_SHELL

SL_SRS3_ERR_NONE

  Error codes.

SL_SRS3_ERR_INVAL

SL_SRS3_ERR_IO

SL_SRS3_ERR_NOMEM

SL_SRS3_ERR_BUSY

SL_SRS3_BOOTLOADER_SET_REQ

SL_SRS3_BOOTLOADER_SET_REP

SL_SRS3_BOOTLOADER_FLASH_REQ

SL_SRS3_BOOTLOADER_FLASH_REP

SL_SRS3_BOOTLOADER_ERASE_REQ

SL_SRS3_BOOTLOADER_ERASE_REP

SL_SRS3_BOOTLOADER_VERIFY_REQ

SL_SRS3_BOOTLOADER_VERIFY_REP

SL_SRS3_BOOTLOADER_SET_KEY

SL_SRS3_BOOTLOADER_FLASH_KEY

SL_SRS3_BOOTLOADER_ERASE_KEY

SL_SRS3_BOOTLOADER_FILENAME_MAX

SL_SRS3_SHELL_RUN_REQ

SL_SRS3_SHELL_RUN_REP

SL_SRS3_SHELL_RUN_KEY

SL_SRS3_SHELL_RUN_MAX

struct sl_srs3_req_t

  Public Members

  uint8_t type

struct sl_srs3_rep_t

  Public Members

  uint8_t type
  uint8_t error

struct sl_srs3_bootloader_set_req_t

  Public Members

  uint8_t type
  uint8_t flags
  uint8_t boots
  uint32_t key

struct sl_srs3_bootloader_set_rep_t

  Public Members

  uint8_t type
  uint8_t error

struct sl_srs3_bootloader_flash_req_t

  Public Members

  uint8_t type
  uint8_t flags
  uint32_t key
  uint8_t filename[40]

struct sl_srs3_bootloader_flash_rep_t

  Public Members

  uint8_t type
  uint8_t error
  uint32_t checksum

struct sl_srs3_bootloader_erase_req_t

  Public Members

  uint8_t type
  uint8_t flags
  uint32_t key

struct sl_srs3_bootloader_erase_rep_t

  Public Members

  uint8_t type
  uint8_t error

struct sl_srs3_bootloader_verify_req_t

  Public Members

  uint8_t type
  uint8_t flags
  uint8_t partition

struct sl_srs3_bootloader_verify_rep_t

  Public Members

  uint8_t type
  uint8_t error
  uint32_t size
  uint32_t checksum

struct sl_srs3_shell_run_req_t

  Public Members

  uint8_t type

    Must be SL_SRS3_SHELL_RUN_REQ.

  uint8_t flags

    Flags, currently unused - set to zero.

  uint32_t key

    Must be SL_SRS3_SHELL_RUN_KEY.

  uint8_t cmd[100]

    Command to execute.

struct sl_srs3_shell_run_rep_t

  Public Members

  uint8_t type

    Must be SL_SRS3_SHELL_RUN_REP.

  uint8_t error

    Error code.