Polaris Client Library

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

Frame Store

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

The store is a ring buffer and wraps around every ~130k messages.

Frames can be selectively downloaded by their sequence number through the store CSP service, and provides access to the full LoRa 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_lora_store_mirror() for this functionality.

Both the normal frame request and mirror frames pass received frames to a callback function matching sl_polaris_lora_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_lora_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_LORA_STORE_BITMAP_SIZE] = {0xff};
// Request from CSP node 20, call callback for each frame
sl_polaris_lora_store_read(20, 1000, 0, bitmap, frameprint_cb, NULL);
}

Typedefs

typedef int (*sl_polaris_lora_frame_cb_t)(sl_polaris_lora_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_lora_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_lora_store_mirror_recv(uint8_t node, uint32_t timeout, sl_polaris_lora_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.
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_lora_store_read(uint8_t node, uint32_t timeout, uint32_t start, uint8_t *bitmap, sl_polaris_lora_frame_cb_t cb, void *arg)

Request LoRa frames from store.

This function requests a number of received LoRa 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_LORA_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 to is 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 the filtered channel.

The number of captured samples must be 8192 for SL_POLARIS_LORA_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_lora_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_LORA_SAMPLEBUF_SOURCE_RAW SL_POLARIS_LORA_SAMPLEBUF_SOURCE_CHAN
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_lora_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_LORA_SAMPLEBUF_SOURCE_RAW SL_POLARIS_LORA_SAMPLEBUF_SOURCE_CHAN
dest – Destination identifier. Must be one of: SL_POLARIS_LORA_SAMPLEBUF_DEST_CSP SL_POLARIS_LORA_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.

int sl_polaris_lora_sample_trigger_host(uint8_t node, uint32_t timeout, uint8_t flags, uint16_t repsiz, uint32_t samples, uint32_t freq, uint32_t id, uint8_t host, uint8_t port)

Save sample buffer data.

This function is used to trigger a sample and send the reply data to another host.

Parameters:

node – CSP address of the Polaris node.
timeout – Timeout of the command in milliseconds.
flags – Can be ORed value of: SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_SEQ SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_ID SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_FASTXMIT SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_RAWSPEC
repsiz – Reply size of each CSP frame.
samples – Number of samples to store.
freq – Frequency to sample. Use 0 to keep current frequency.
id – Identification number of sample.
host – Destination host address.
port – Destination port number.

Returns:

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

int sl_polaris_lora_sample_trigger_buffer(uint8_t node, uint32_t timeout, uint8_t flags, uint16_t repsiz, uint32_t samples, uint32_t freq, uint32_t id, uint32_t *out, size_t outlen)

Save sample buffer data.

This function is used to trigger a sample and store the reply data in a preallocated buffer.

Parameters:

node – CSP address of the Polaris node.
timeout – Timeout of the command in milliseconds.
flags – Can be ORed value of: SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_SEQ SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_ID SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_FASTXMIT SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_RAWSPEC
repsiz – Reply size of each CSP frame.
samples – Number of samples to store.
freq – Frequency to sample. Use 0 to keep current frequency.
id – Identification number of sample.
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.

Bootloader

This file contains functions to configure the boot process on a Polaris 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 SD-card using BTP and can then be flashed to the alternate partition using the

sl_polaris_lora_bootloader_flash_alternate function.

Functions

int sl_polaris_lora_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_polaris_lora_bootloader_flash_alternate(uint8_t node, uint32_t timeout, const char *filename, uint32_t *crc)

Flash image file from SD-card to alternate partition.

This function flashes a firmware file from the SD-card 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_polaris_lora_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_polaris_lora_bootloader_checksum_alternate(uint8_t node, uint32_t timeout, uint32_t size, uint32_t *crc)

Calculate checksum of alternate partition contents.

This function calculates the CRC32C checksum of the contents of the alternate partition, and returns the result in the crc argument. The calculation always starts from the beginning of the alternate partition.

Parameters:

node – CSP address of the property node.
timeout – Timeout of the command in milliseconds.
size – Number of bytes to checksum.
crc – Returned CRC32C checksum of flashed file.

Returns:

0 on success, negative error code otherwise.

int sl_polaris_lora_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.

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_lora_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_LORA_DEFAULT_ADDRESS: Default CSP address.

SL_POLARIS_LORA_PORT_SAMPLEBUF: CSP ports.

SL_POLARIS_LORA_PORT_STORE

SL_POLARIS_LORA_PORT_BOOTLOADER

SL_POLARIS_LORA_PORT_SHELL

SL_POLARIS_LORA_PORT_STORE_MIRROR_RECV: Default mirror frame receive port.

SL_POLARIS_LORA_ERR_NONE: Error codes.

SL_POLARIS_LORA_ERR_INVAL

SL_POLARIS_LORA_ERR_IO

SL_POLARIS_LORA_ERR_NOMEM

SL_POLARIS_LORA_ERR_BUSY

SL_POLARIS_LORA_SAMPLEBUF_READ_REQ

SL_POLARIS_LORA_SAMPLEBUF_READ_REP

SL_POLARIS_LORA_SAMPLEBUF_READ_CHUNK

SL_POLARIS_LORA_SAMPLEBUF_FREE

SL_POLARIS_LORA_SAMPLEBUF_TRIG_REQ

SL_POLARIS_LORA_SAMPLEBUF_TRIG_REP

SL_POLARIS_LORA_SAMPLEBUF_SOURCE_RAW

SL_POLARIS_LORA_SAMPLEBUF_SOURCE_CHAN

SL_POLARIS_LORA_SAMPLEBUF_DEST_CSP

SL_POLARIS_LORA_SAMPLEBUF_DEST_SDCARD

SL_POLARIS_LORA_SAMPLEBUF_FL_FORCE_INTRAM

SL_POLARIS_LORA_SAMPLEBUF_READ_CHUNK_SAMPLES

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_FLOWCTRL: Wait for 1-byte ACK for each frame.

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_OTHERHOST: Reply to rephost:repport.

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_SEQ: Add reply frame sequence number.

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_ID: Add trigger ID to reply frames.

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_FASTXMIT: Allow 2 frames in flight.

SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_RAWSPEC: Sample raw spectrum (count MUST be 8192).

SL_POLARIS_LORA_STORE_FRAME

SL_POLARIS_LORA_STORE_MIRROR_REQ

SL_POLARIS_LORA_STORE_MIRROR_REP

SL_POLARIS_LORA_STORE_READ_REQ

SL_POLARIS_LORA_STORE_READ_REP

SL_POLARIS_LORA_STORE_MAX_DATALEN

SL_POLARIS_LORA_STORE_FRAME_OVERHEAD

SL_POLARIS_LORA_STORE_BITMAP_SIZE

SL_POLARIS_LORA_BOOTLOADER_SET_REQ

SL_POLARIS_LORA_BOOTLOADER_SET_REP

SL_POLARIS_LORA_BOOTLOADER_FLASH_REQ

SL_POLARIS_LORA_BOOTLOADER_FLASH_REP

SL_POLARIS_LORA_BOOTLOADER_ERASE_REQ

SL_POLARIS_LORA_BOOTLOADER_ERASE_REP

SL_POLARIS_LORA_BOOTLOADER_CHECKSUM_REQ

SL_POLARIS_LORA_BOOTLOADER_CHECKSUM_REP

SL_POLARIS_LORA_BOOTLOADER_VERIFY_REQ

SL_POLARIS_LORA_BOOTLOADER_VERIFY_REP

SL_POLARIS_LORA_BOOTLOADER_SET_KEY

SL_POLARIS_LORA_BOOTLOADER_FLASH_KEY

SL_POLARIS_LORA_BOOTLOADER_ERASE_KEY

SL_POLARIS_LORA_BOOTLOADER_FILENAME_MAX

SL_POLARIS_LORA_SHELL_RUN_REQ

SL_POLARIS_LORA_SHELL_RUN_REP

SL_POLARIS_LORA_SHELL_RUN_KEY

SL_POLARIS_LORA_SHELL_RUN_MAX

Functions

static inline const char *sl_polaris_lora_strerror(uint8_t error)

struct sl_polaris_lora_req_t

Public Members

uint8_t type

struct sl_polaris_lora_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_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_lora_samplebuf_read_rep_t

Public Members

uint8_t type

uint8_t error

uint32_t id

uint32_t addr

struct sl_polaris_lora_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_lora_samplebuf_free_req_t

Public Members

uint8_t type

uint8_t flags

uint32_t addr

struct sl_polaris_lora_samplebuf_free_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_samplebuf_trig_req_t

Public Members

uint8_t type: Must be SL_POLARIS_LORA_SAMPLEBUF_TRIG_REQ.

uint8_t flags: Flags.

uint8_t host: Reply to host if SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_OTHERHOST.

uint8_t port: Reply to port if SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_OTHERHOST.

uint16_t repsiz: Reply packet size.

uint32_t id: Trigger ID to add if SL_POLARIS_LORA_SAMPLEBUF_TRIG_FL_ID.

uint32_t freq

Channel frequency in Hz.

Set to 0 to keep current

uint32_t count: Number of samples.

struct sl_polaris_lora_samplebuf_trig_rep_t

Public Members

uint8_t type: Must be SL_POLARIS_LORA_SAMPLEBUF_TRIG_REP.

uint8_t error: Error code.

struct sl_polaris_lora_store_frame_t

Public Members

uint8_t type: Must be SL_POLARIS_LORA_STORE_FRAME.

uint8_t error: Error code.

uint32_t seq: Sequence number of this frame.

int32_t frequency_offset: Frequency offset in Hz.

int16_t symbol_power: Symbol power dB.

int16_t noise_power: Signal power dB.

uint8_t spreading_factor: spreading factor, SF

uint8_t code_rate: code rate

uint8_t payload_crc_enabled: Payload crc enabled.

uint64_t time: Time of reception (nanoseconds since 1/1/1970).

uint8_t length: Number of bytes in data field.

uint8_t data[255]: LoRA payload data.

struct sl_polaris_lora_store_mirror_req_t

Public Members

uint8_t type

uint8_t dest_node

uint8_t dest_port

uint32_t timeout_ms

struct sl_polaris_lora_store_mirror_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_store_read_req_t

Public Members

uint8_t type

uint32_t start

uint8_t bitmap[32]

struct sl_polaris_lora_store_read_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_bootloader_set_req_t

Public Members

uint8_t type

uint8_t flags

uint8_t boots

uint32_t key

struct sl_polaris_lora_bootloader_set_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_bootloader_flash_req_t

Public Members

uint8_t type

uint8_t flags

uint32_t key

uint8_t filename[40]

struct sl_polaris_lora_bootloader_flash_rep_t

Public Members

uint8_t type

uint8_t error

uint32_t checksum

struct sl_polaris_lora_bootloader_erase_req_t

Public Members

uint8_t type

uint8_t flags

uint32_t key

struct sl_polaris_lora_bootloader_erase_rep_t

Public Members

uint8_t type

uint8_t error

struct sl_polaris_lora_bootloader_checksum_req_t

Public Members

uint8_t type

uint8_t flags

uint32_t size

struct sl_polaris_lora_bootloader_checksum_rep_t

Public Members

uint8_t type

uint8_t error

uint32_t checksum

struct sl_polaris_lora_bootloader_verify_req_t

Public Members

uint8_t type

uint8_t flags

uint8_t partition

struct sl_polaris_lora_bootloader_verify_rep_t

Public Members

uint8_t type

uint8_t error

uint32_t size

uint32_t checksum

struct sl_polaris_lora_shell_run_req_t

Public Members

uint8_t type: Must be SL_POLARIS_LORA_SHELL_RUN_REQ.

uint8_t flags: Flags, currently unused - set to zero.

uint32_t key: Must be SL_POLARIS_LORA_SHELL_RUN_KEY.

uint8_t cmd[100]: Command to execute.

struct sl_polaris_lora_shell_run_rep_t

Public Members

uint8_t type: Must be SL_POLARIS_LORA_SHELL_RUN_REP.

uint8_t error: Error code.