Polaris Client Library

The Polaris client library provides remote access to the receiver using functions that wrap CSP protocol messages.

Frame Store

Each received AIS message is tagged with a 32-bit sequence number and stored in NOR-flash with reception metadata (estimated center frequency offset, signal level) and a 64-bit timestamp (number of nanoseconds since midnight on January 1st, 1970).

All 1-5 slot messages are stored in the same store, and consumes 256 bytes of NOR flash, including metadata, independent on the number of slots in the message. The store is a ring buffer and wraps around every 261120 messages.

Frames can be selectively downloaded by their sequence number through the store CSP service, and provides access to the full AIS messages and metadata.

If an external store is preferred, the mirror mode can be used to forward all received frames to another CSP node. Refer to sl_polaris_store_mirror() for this functionality.

Both the normal frame request and mirror frames pass received frames to a callback function matching sl_polaris_frame_cb_t() prototype.

The example below shows a simple frame callback function that just prints the length and first byte of received frames, and a request_frames() function that requests the last 8 frames from the CSP node on address 20. Error handling has been left out for brevity.

static int frameprint_cb(sl_polaris_store_frame_t *frame, void *arg)
{
    printf("Got a %u byte frame and the first byte is %02hhx\n",
           frame->length, frame->data[0]);
    return 0;
}

void request_frames(void)
{
     // Prepare bitmap for 8 frames
     uint8_t bitmap[SL_POLARIS_STORE_BITMAP_SIZE] = {0xff};
     // Request from CSP node 20, call callback for each frame
     sl_polaris_store_read(20, 1000, 0, bitmap, frameprint_cb, NULL);
}

Typedefs

typedef int (*sl_polaris_frame_cb_t)(sl_polaris_store_frame_t *frame, void *arg)

Frame callback function prototype.

Callback function prototype used by store mirror and read functions.

Param frame:

Pointer to structure with frame data. The structure data has been converted to host byte order.

Param arg:

Arbitrary data pointer passed from the mirror/read function call. Can be used to pass any additional data required by the callback function.

Return:

0 to continue iteration over received frames, or a non-zero value to abort the iteration.

Functions

int sl_polaris_store_mirror(uint8_t node, uint32_t timeout, uint8_t dest_node, uint8_t dest_port, uint32_t time_ms)

Request store frame mirroring.

This function requests the Polaris to mirror received frames to another CSP system.

The time_ms specifies the amount of time the system should keep sending frames. This ensures that the receiver will eventually stop sending frames if the mirror client no longer waits for frames. A client can extend the mirror period by sending a new mirror request before the timeout expires.

Parameters:
  • node – CSP address of the Polaris node.

  • timeout – Timeout of the command in milliseconds.

  • dest_node – Destination CSP address.

  • dest_port – Destination CSP port.

  • time_ms – Milliseconds the system should mirror frames for.

Returns:

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

int sl_polaris_store_mirror_recv(uint8_t node, uint8_t port, uint32_t timeout, sl_polaris_frame_cb_t cb, void *arg)

Receive mirror frames from device.

This function requests frame mirroring and calls the cb function for each received frame. It automatically refreshes the mirror timeout every 60 seconds.

Parameters:
  • node – CSP address of the Polaris node.

  • port – Mirror frame receive port.

  • timeout – Timeout of the command in milliseconds.

  • cb – Frame callback function.

  • arg – Pointer argument passed to callback function.

Returns:

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

int sl_polaris_store_read(uint8_t node, uint32_t timeout, uint32_t start, uint8_t *bitmap, sl_polaris_frame_cb_t cb, void *arg)

Request AIS frames from store.

This function requests a number of received AIS frames from the store. Frames are selected using a starting sequence number and a bitmap. The last sequence number to be received can be read using the store.seq property or start=0 can be used to request the most recent frames.

Frames are requested backwards from start, i.e. the start fields selects the maximum sequence number to request.

The bitmap field is used to request selected messages backwards from the start sequence number. If bit n is set, the receiver will send the message with sequence number start - n, i.e. bit 0 must be set to request the message with sequence number start. Bit 0 is the bit immediately after the start field and bit 255 is the last bit in the packet.

E.g. to request messages with sequence number 10, 9, 8, 7, 2 and 1 set:

start = 10, bitmap = [0xf0, 0xc0, 0x00, 0x00, …, 0x00]

The bitmap argument must be SL_POLARIS_STORE_BITMAP_SIZE bytes (currently 32, allowing up to 256 frames per request).

Parameters:
  • node – CSP address of the Polaris node.

  • timeout – Timeout of the command in milliseconds.

  • start – Start frame request number. Use 0 to request from most recent frame.

  • bitmap – Bitmap of frames from start to request.

  • cb – Frame callback function.

  • arg – Pointer argument passed to callback function.

Returns:

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

Sample Buffer

This file provides functions used to read raw or store sample data from the Polaris sample buffer via CSP.

The source can be either short (fixed length) bursts of full spectrum data or variable length samples from one of the 4 AIS channels.

The number of captured samples must be 8192 for SL_POLARIS_SAMPLEBUF_SOURCE_RAW source.

Samples are 32-bit words consisting of 16-bit IQ channels.

Note

The sample commands write data into external SDRAM, which is automatically enabled and kept powered on after sampling. This results in a higher power consumption after the first sample request is received.

Functions

int sl_polaris_sample_read(uint8_t node, uint32_t timeout, uint8_t source, uint32_t *out, size_t outlen)

Read data from sample buffer.

The Polaris device will send the samples via CSP to the requesting node address immediately after request.

Parameters:
  • node – CSP address of the Polaris node.

  • timeout – Timeout of the command in milliseconds.

  • source – Sample source identifier. Must be one of: SL_POLARIS_SAMPLEBUF_SOURCE_RAW SL_POLARIS_SAMPLEBUF_SOURCE_CH1 SL_POLARIS_SAMPLEBUF_SOURCE_CH2 SL_POLARIS_SAMPLEBUF_SOURCE_CH3 SL_POLARIS_SAMPLEBUF_SOURCE_CH4

  • out – Pointer to output data array.

  • outlen – Size of the output array in bytes (must be 4x number of samples).

Returns:

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

int sl_polaris_sample_store(uint8_t node, uint32_t timeout, uint8_t source, uint8_t dest, size_t samples, uint32_t id)

Save sample buffer data.

This function is used to store raw sample data on the Polaris device for later download using BTP.

Parameters:
  • node – CSP address of the Polaris node.

  • timeout – Timeout of the command in milliseconds.

  • source – Sample source identifier. Must be one of: SL_POLARIS_SAMPLEBUF_SOURCE_RAW SL_POLARIS_SAMPLEBUF_SOURCE_CH1 SL_POLARIS_SAMPLEBUF_SOURCE_CH2 SL_POLARIS_SAMPLEBUF_SOURCE_CH3 SL_POLARIS_SAMPLEBUF_SOURCE_CH4

  • dest – Destination identifier. Must be one of: SL_POLARIS_SAMPLEBUF_DEST_CSP SL_POLARIS_SAMPLEBUF_DEST_MEM SL_POLARIS_SAMPLEBUF_DEST_SDCARD

  • samples – Number of samples to store.

  • id – Identification number of sample. Samples stored to the SD-card will be named s<id>.bin, e.g. s1000.bin for sample ID 1000.

Returns:

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

Bootloader

This file contains functions to configure the boot process on a Polaris system.

The system uses two boot slots: slot 0 and slot 1. On system boot, a small bootloader application selects which of the two slots to boot based on a non-volatile state stored in FRAM.

Each firmware slot has a set of properties:

  • status: either STABLE, TESTING, or DISABLED.

  • attempts: remaining boot attempts.

  • priority: higher priority number indicate higher preference to boot.

The current bootloader status can be queried using sl_polaris_bootloader_get_status or shown with the boot status shell command.

A firmware slot is bootable if status is not DISABLED and attempts > 0. The highest priority bootable slot is selected for boot.

If no bootable slot is found, e.g. because all slots have attempts = 0, attempts for all slots are reset to the default value (3) and another search for a bootable slot is performed. If a bootable slot is still not found, slot 0 is selected for boot.

Before booting the selected slot, the bootloader decrements remaining attempts for the slot. It is up to the booted firmware image to reset remaining attempts to indicate a successful boot. For slots where status is STABLE, the firmware will do so automatically after 120 seconds uptime upon successful boot. For slots where status is TESTING, the attempts must be reset using sl_polaris_bootloader_boot_success or alternatively using the boot success shell command.

Each firmware slot can be flashed from the other using the sl_polaris_bootloader_flash function or the boot flash shell command. During the firmware update, the slot being updated is automatically set to DISABLED to prevent it from being booted. If the update is completed successfully, the slot status is set to TESTING. The user can then change the preferred slot to the updated slot using sl_polaris_bootloader_set_preferred or the boot prefer shell command. When successfully booted, the user can decide to keep the slot in TESTING and manually reset attempts as a safeguard, or mark the slot as STABLE to enable automatic reset of remaining attempts.

Functions

int sl_polaris_bootloader_flash(uint8_t node, uint32_t timeout, uint8_t slot, const char *filename)

Flash image file from SD-card to firmware slot.

This function flashes a firmware file from the SD-card to a firmware slot.

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 the currently booted firmware slot.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • slot – Firmware slot to flash (0 or 1).

  • filename – Filename of the remote file to flash.

Returns:

0 on success, negative error code otherwise.

int sl_polaris_bootloader_get_status(uint8_t node, uint32_t timeout, struct sl_polaris_bootloader_status *status)

Get bootloader status.

This function reads the current bootloader status.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • status – Status is returned in this structure.

Returns:

0 on success, negative error code otherwise.

int sl_polaris_bootloader_boot_success(uint8_t node, uint32_t timeout)

Mark boot successful.

This function marks the current boot successful and resets the boot attempts for the booted slot to the default value. For testing slots, this function needs to be called before attempts reaches 0, to keep the slot bootable.

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_polaris_bootloader_set_preferred(uint8_t node, uint32_t timeout, uint8_t slot)

Set the preferred boot slot.

This function is used to set the preferred slot to boot. It modifies the priorities of all boot slots to ensure the selected slot has the highest. If also reset the attempts of the preferred slot to the default value.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • slot – Firmware slot to prefer (0 or 1).

Returns:

0 on success, negative error code otherwise.

int sl_polaris_bootloader_set_slot_status(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t status)

Set slot status.

This function is used to set the status of a slot.

To prevent deadlock, it is not possible to set the status of the booted slot to DISABLED. Likewise, only the booted slot can be set to STABLE.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • slot – Firmware slot to change status of (0 or 1).

  • status – New status for slot.

Returns:

0 on success, negative error code otherwise.

int sl_polaris_bootloader_set_slot_priority(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t priority)

Set slot priority.

This function is used to set the priority of a slot. Bootable slots with higher priority are preferred.

It is usually not necessary to call this function directly. Use sl_polaris_bootloader_set_preferred instead.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • slot – Firmware slot to change status of (0 or 1).

  • priority – New priority for slot.

Returns:

0 on success, negative error code otherwise.

int sl_polaris_bootloader_set_slot_attempts(uint8_t node, uint32_t timeout, uint8_t slot, uint8_t attempts)

Set slot attempts.

This function is used to set the remaining boot attempts of a slot.

It is usually not necessary to call this function directly. Use sl_polaris_bootloader_set_preferred and sl_polaris_bootloader_boot_success instead.

Parameters:
  • node – CSP address of the property node.

  • timeout – Timeout of the command in milliseconds.

  • slot – Firmware slot to change status of (0 or 1).

  • attempts – New attempts for slot.

Returns:

0 on success, negative error code otherwise.

struct sl_polaris_bootloader_status

Public Members

uint8_t slot_booted

Booted slot.

uint8_t slot_preferred

Preferred slot.

uint8_t slot0_status

Slot 0 status.

uint8_t slot0_attempts

Slot 0 priority.

uint8_t slot0_priority

Slot 0 remaining boot attempts.

uint8_t slot0_valid

Slot 0 contents state.

uint8_t slot1_status

Slot 1 status.

uint8_t slot1_attempts

Slot 1 priority.

uint8_t slot1_priority

Slot 1 remaining boot attempts.

uint8_t slot1_valid

Slot 1 contents state.

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_polaris_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

This file specifies the available CSP services and ports on the Polaris receiver.

It should not be necessary for clients to use these definitions directly. Instead, use the wrapper functions from this library which handles the protocol and performs necessary byte order conversion.

Defines

SL_POLARIS_DEFAULT_ADDRESS

Default CSP address.

SL_POLARIS_PORT_SAMPLEBUF

CSP ports.

SL_POLARIS_PORT_STORE
SL_POLARIS_PORT_BOOTLOADER
SL_POLARIS_PORT_SHELL
SL_POLARIS_PORT_BOOTLOADER2
SL_POLARIS_PORT_STORE_MIRROR_RECV

Default mirror frame receive port.

SL_POLARIS_ERR_NONE

Error codes.

SL_POLARIS_ERR_INVAL
SL_POLARIS_ERR_IO
SL_POLARIS_ERR_NOMEM
SL_POLARIS_ERR_BUSY
SL_POLARIS_SAMPLEBUF_READ_REQ
SL_POLARIS_SAMPLEBUF_READ_REP
SL_POLARIS_SAMPLEBUF_READ_CHUNK
SL_POLARIS_SAMPLEBUF_FREE
SL_POLARIS_SAMPLEBUF_SOURCE_RAW
SL_POLARIS_SAMPLEBUF_SOURCE_CH1
SL_POLARIS_SAMPLEBUF_SOURCE_CH2
SL_POLARIS_SAMPLEBUF_SOURCE_CH3
SL_POLARIS_SAMPLEBUF_SOURCE_CH4
SL_POLARIS_SAMPLEBUF_SOURCE_AIS1_CH87B
SL_POLARIS_SAMPLEBUF_SOURCE_AIS2_CH88B
SL_POLARIS_SAMPLEBUF_SOURCE_AIS3_CH75
SL_POLARIS_SAMPLEBUF_SOURCE_AIS4_CH76
SL_POLARIS_SAMPLEBUF_DEST_CSP
SL_POLARIS_SAMPLEBUF_DEST_MEM
SL_POLARIS_SAMPLEBUF_DEST_SDCARD
SL_POLARIS_SAMPLEBUF_FL_FORCE_INTRAM
SL_POLARIS_SAMPLEBUF_FL_SYNC_PPS
SL_POLARIS_SAMPLEBUF_READ_CHUNK_SAMPLES
SL_POLARIS_STORE_FRAME
SL_POLARIS_STORE_MIRROR_REQ
SL_POLARIS_STORE_MIRROR_REP
SL_POLARIS_STORE_READ_REQ
SL_POLARIS_STORE_READ_REP
SL_POLARIS_STORE_FRAME2
SL_POLARIS_STORE_CHANNEL_MASK
SL_POLARIS_STORE_FLAGS_MASK
SL_POLARIS_STORE_FLAGS_OFFSET
SL_POLARIS_STORE_MAX_DATALEN
SL_POLARIS_STORE_FRAME_OVERHEAD
SL_POLARIS_STORE_BITMAP_SIZE
SL_POLARIS_SHELL_RUN_REQ
SL_POLARIS_SHELL_RUN_REP
SL_POLARIS_SHELL_RUN_KEY
SL_POLARIS_SHELL_RUN_MAX
SL_POLARIS_BOOTLOADER2_STATUS_REQ
SL_POLARIS_BOOTLOADER2_STATUS_REP
SL_POLARIS_BOOTLOADER2_BOOT_SUCCESS_REQ
SL_POLARIS_BOOTLOADER2_BOOT_SUCCESS_REP
SL_POLARIS_BOOTLOADER2_SET_PREFERRED_REQ
SL_POLARIS_BOOTLOADER2_SET_PREFERRED_REP
SL_POLARIS_BOOTLOADER2_FLASH_REQ
SL_POLARIS_BOOTLOADER2_FLASH_REP
SL_POLARIS_BOOTLOADER2_SET_SLOT_STATUS_REQ
SL_POLARIS_BOOTLOADER2_SET_SLOT_STATUS_REP
SL_POLARIS_BOOTLOADER2_SET_SLOT_PRIORITY_REQ
SL_POLARIS_BOOTLOADER2_SET_SLOT_PRIORITY_REP
SL_POLARIS_BOOTLOADER2_SET_SLOT_ATTEMPTS_REQ
SL_POLARIS_BOOTLOADER2_SET_SLOT_ATTEMPTS_REP
SL_POLARIS_BOOTLOADER2_BOOT_SUCCESS_KEY
SL_POLARIS_BOOTLOADER2_SET_PREFERRED_KEY
SL_POLARIS_BOOTLOADER2_FLASH_KEY
SL_POLARIS_BOOTLOADER2_SET_SLOT_STATUS_KEY
SL_POLARIS_BOOTLOADER2_SET_SLOT_PRIORITY_KEY
SL_POLARIS_BOOTLOADER2_SET_SLOT_ATTEMPTS_KEY
SL_POLARIS_BOOTLOADER2_STATUS_SLOT_DISABLED
SL_POLARIS_BOOTLOADER2_STATUS_SLOT_TESTING
SL_POLARIS_BOOTLOADER2_STATUS_SLOT_STABLE
SL_POLARIS_BOOTLOADER2_FILENAME_MAX
struct sl_polaris_req_t

Public Members

uint8_t type
struct sl_polaris_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_samplebuf_read_req_t

Public Members

uint8_t type
uint8_t source
uint8_t dest
uint8_t flags
uint32_t id
uint32_t samples
struct sl_polaris_samplebuf_read_rep_t

Public Members

uint8_t type
uint8_t error
uint32_t id
uint32_t addr
struct sl_polaris_samplebuf_read_chunk_t

Public Members

uint8_t type
uint8_t error
uint16_t seq
uint16_t total
uint32_t data[32]
struct sl_polaris_samplebuf_free_req_t

Public Members

uint8_t type
uint8_t flags
uint32_t addr
struct sl_polaris_samplebuf_free_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_store_frame_t

Public Members

uint8_t type

Must be SL_POLARIS_STORE_FRAME2.

uint8_t error

Error code.

uint32_t seq

Sequence number of this frame.

uint64_t time

Time of reception (nanoseconds since 1/1/1970)

uint8_t channel_and_flags

AIS channel this message was received on and pps flags.

bit 0-1: channel from 0 to 3 bit 2-4: reserved bit 5: pps synchronized samples bit 6: pps time set bit 7: pps valid

int16_t power_deci_dbm

Signal power in 1/10 dBm.

int16_t frequency_hz

Estimated frequency offset.

uint8_t length

Number of bytes in data field.

uint8_t data[160]

Raw AIS message, excludes flag bytes, includes FCS.

struct sl_polaris_store_mirror_req_t

Public Members

uint8_t type
uint8_t dest_node
uint8_t dest_port
uint32_t timeout_ms
struct sl_polaris_store_mirror_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_store_read_req_t

Public Members

uint8_t type
uint32_t start
uint8_t bitmap[32]
struct sl_polaris_store_read_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_shell_run_req_t

Public Members

uint8_t type

Must be SL_POLARIS_SHELL_RUN_REQ.

uint8_t flags

Flags, currently unused - set to zero.

uint32_t key

Must be SL_POLARIS_SHELL_RUN_KEY.

uint8_t cmd[100]

Command to execute.

struct sl_polaris_shell_run_rep_t

Public Members

uint8_t type

Must be SL_POLARIS_SHELL_RUN_REP.

uint8_t error

Error code.

struct sl_polaris_bootloader2_status_req_t

Public Members

uint8_t type
uint8_t flags
struct sl_polaris_bootloader2_status_rep_t

Public Members

uint8_t type
uint8_t error
uint8_t slot_booted
uint8_t slot_preferred
uint8_t slot0_status
uint8_t slot0_attempts
uint8_t slot0_priority
uint8_t slot0_valid
uint8_t slot1_status
uint8_t slot1_attempts
uint8_t slot1_priority
uint8_t slot1_valid
struct sl_polaris_bootloader2_boot_success_req_t

Public Members

uint8_t type
uint32_t key
struct sl_polaris_bootloader2_boot_success_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_bootloader2_set_preferred_req_t

Public Members

uint8_t type
uint32_t key
uint8_t slot
struct sl_polaris_bootloader2_set_preferred_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_bootloader2_flash_req_t

Public Members

uint8_t type
uint8_t flags
uint32_t key
uint8_t slot
uint8_t filename[40]
struct sl_polaris_bootloader2_flash_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_bootloader2_set_slot_status_req_t

Public Members

uint8_t type
uint32_t key
uint8_t slot
uint8_t status
struct sl_polaris_bootloader2_set_slot_status_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_bootloader2_set_slot_priority_req_t

Public Members

uint8_t type
uint32_t key
uint8_t slot
uint8_t priority
struct sl_polaris_bootloader2_set_slot_priority_rep_t

Public Members

uint8_t type
uint8_t error
struct sl_polaris_bootloader2_set_slot_attempts_req_t

Public Members

uint8_t type
uint32_t key
uint8_t slot
uint8_t attempts
struct sl_polaris_bootloader2_set_slot_attempts_rep_t

Public Members

uint8_t type
uint8_t error