swc_api.h

SPARK Wireless Core Application Programming Interface.

Copyright

Copyright (C) 2021 SPARK Microsystems International Inc. All rights reserved.

License

This source code is proprietary and subject to the SPARK Microsystems Software EULA found in this package in file EULA.txt.

Author

SPARK FW Team.

Defines

SWC_BROADCAST_ADDRESS 0xFF

Destination address to use for broadcasting

Typedefs

typedef struct swc_cfg swc_cfg_t

Wireless Core configuration.

typedef struct swc_hal swc_hal_t

Wireless Core hardware abstraction layer.

typedef struct swc_node_cfg swc_node_cfg_t

Wireless node configuration.

typedef struct swc_node swc_node_t

Wireless node.

typedef struct swc_statistics swc_statistics_t

Wireless statistics.

typedef struct swc_radio_cfg swc_radio_cfg_t

Wireless radio configuration.

typedef struct swc_connection_cfg swc_connection_cfg_t

Wireless connection configuration.

typedef struct swc_connection swc_connection_t

Wireless connection.

typedef struct swc_channel_cfg swc_channel_cfg_t

Wireless channel configuration.

typedef struct swc_fallback_info swc_fallback_info_t

Wireless fallback information.

Functions

void swc_init(swc_cfg_t cfg, swc_hal_t *hal, swc_error_t *err)

Wireless Core initialization.

This is the first API call that needs to be made when initializing and configuring the Wireless Core.

Parameters

• cfg – [in] Wireless Core configuration.

• hal – [in] Board specific functions.

• err – [out] Wireless Core error code.

swc_node_t *swc_node_init(swc_node_cfg_t cfg, swc_error_t *err)

Initialize the local device.

This sets global device parameters.

Parameters

• cfg – [in] Wireless radio configuration.

• err – [out] Wireless Core error code.

Returns

Node handle.

void swc_node_add_radio(swc_node_t *node, swc_radio_cfg_t cfg, swc_hal_t *hal, swc_error_t *err)

Initialize and line a radio wireless node.

This must be called for every radio the wireless node is using. Most systems operate a single radio, but a dual radio configuration is also supported for specific use cases.

Parameters

• node – [in] Node handle.

• cfg – [in] Wireless radio configuration.

• hal – [in] Board specific functions.

• err – [out] Wireless Core error code.

swc_connection_t *swc_connection_init(swc_node_t *node, swc_connection_cfg_t cfg, swc_hal_t *hal, swc_error_t *err)

Initialize a connection.

A connection abstracts a one-way data flow between 2 devices (e.g., a coordinator and a node).

Parameters

• hal – [in] Board specific functions.

• node – [in] Node handle.

• cfg – [in] Wireless connection configuration.

• err – [out] Wireless Core error code.

Returns

Connection handle.

void swc_connection_add_channel(swc_connection_t *conn, swc_node_t *node, swc_channel_cfg_t cfg, swc_error_t *err)

Configure channels to use for a wireless connection.

Parameters

• conn – [in] Connection handle.

• node – [in] Node handle.

• cfg – [in] Wireless channel configuration.

• err – [out] Wireless Core error code.

void swc_connection_set_tx_success_callback(swc_connection_t *conn, void (*cb)(void *conn), swc_error_t *err)

Set the callback function to execute after a successful transmission.

Note

If ACKs are enabled, this callback is triggered when the ACK frame is received. If ACKs are disabled, it triggers every time the frame is sent (if the callback is configured).

Parameters

• conn – [in] Connection handle.

• cb – [in] Callback function.

• err – [out] Wireless Core error code.

void swc_connection_set_tx_fail_callback(swc_connection_t *conn, void (*cb)(void *conn), swc_error_t *err)

Set the callback function to execute after an unsuccessful transmission.

Note

If ACKs are enabled, this callback is triggered if an ACK is not received after a transmission. If ACKs are disabled, it never triggers since every transmission is considered a success.

Parameters

• conn – [in] Connection handle.

• cb – [in] Callback function.

• err – [out] Wireless Core error code.

void swc_connection_set_tx_dropped_callback(swc_connection_t *conn, void (*cb)(void *conn), swc_error_t *err)

Set the callback function to execute after the ARQ module discards a frame.

Note

If ARQ is enabled, the frame can be dropped because the time deadline or the retry count deadline has been reached. If ARQ is disabled, it never triggers.

Parameters

• conn – [in] Connection handle.

• cb – [in] Callback function.

• err – [out] Wireless Core error code.

void swc_connection_set_rx_success_callback(swc_connection_t *conn, void (*cb)(void *conn), swc_error_t *err)

Set the callback function to execute after a successful frame reception.

Note

A reception is considered successful when the frame destination address matches the local address or the broadcast address and the CRC checks.

Parameters

• conn – [in] Connection handle.

• cb – [in] Callback function.

• err – [out] Wireless Core error code.

void swc_connection_set_throttling_active_ratio(swc_connection_t *conn, uint8_t active_ratio, swc_error_t *err)

Set the percentage of allocated timeslots to use.

The throttling feature reduces the usable bandwidth in order to reduce power consumption. By default, the active ratio is set to 100%. For example. if a ratio of 50% is set, only 1 timeslot out of 2 will be usable by the connection. The transceiver will stay asleep in unused timeslots.

Parameters

• conn – [in] Connection handle.

• active_ratio – [in] Percentage of the allocated timeslots to use, from 0 to 100.

• err – [out] Wireless Core error code.

void swc_connection_get_payload_buffer(swc_connection_t *conn, uint8_t **payload_buffer, swc_error_t *err)

Get a buffer from the connection queue.

Parameters

• conn – [in] Connection handle.

• payload_buffer – [out] Free payload buffer if available, NULL otherwise.

• err – [out] Wireless Core error code.

void swc_connection_send(swc_connection_t *conn, uint8_t *payload_buffer, uint16_t size, swc_error_t *err)

Enqueue a payload buffer in the connection transmission queue.

Parameters

• conn – [in] Connection handle.

• payload_buffer – [in] Buffer containing the payload to transmit.

• size – [in] Size of the payload.

• err – [out] Wireless Core error code.

uint16_t swc_connection_receive(swc_connection_t *conn, uint8_t **payload_buffer, swc_error_t *err)

Retrieve a payload buffer from the connection reception queue.

Parameters

• conn – [in] Connection handle.

• payload_buffer – [in] Address of the buffer where to put the payload.

• err – [out] Wireless Core error code.

Returns

Size of the payload.

void swc_connection_receive_complete(swc_connection_t *conn, swc_error_t *err)

Free the last received payload buffer from the connection reception queue.

Parameters

• conn – [in] Connection handle.

• err – [out] Wireless Core error code.

uint16_t swc_connection_receive_to_buffer(swc_connection_t *conn, uint8_t *payload, uint16_t size, swc_error_t *err)

Copy the received frame to the payload buffer and free the queue.

Parameters

• conn – [in] Connection handle.

• payload – [out] Pointer to the output buffer.

• size – [in] Size of the output buffer.

• err – [in] Wireless Core error code.

Returns

Size of the payload.

void swc_setup(swc_node_t *node, swc_error_t *err)

Wireless Core setup.

This is the last API call that needs to be made when initializing and configuring the Wireless Core.

Parameters

• node – [in] Node handle.

• err – [out] Wireless Core error code.

void swc_connect(swc_error_t *err)

Start Wireless Core network activity.

This is called once the Wireless Core initialization and configuration is done (i.e., after swc_setup()).

Parameters

err – [out] Wireless Core error code.

void swc_disconnect(swc_error_t *err)

Stop Wireless Core network activity.

Parameters

err – [out] Wireless Core error code.

swc_fallback_info_t swc_connection_get_fallback_info(swc_connection_t *conn, swc_error_t *err)

Get information used when the fallback mode is enabled.

This is used by a node receiving data through a connection with fallback enabled. The information retrieved here must be sent back to the original sender usually through an auto-reply timeslot.

Parameters

• conn – [in] Connection handle.

• err – [out] Wireless Core error code.

Returns

Fallback information.

uint32_t swc_get_allocated_bytes(void)

Get the number of bytes allocated in the memory pool.

Returns

Number of bytes allocated in the memory pool.

void swc_free_memory(void)

Free the memory to reconfigure the wireless core.

void swc_connection_callbacks_processing_handler(void)

Function to call to process the Wireless Core callback queue.

The callbacks are TX ACK, TX NACK and RX. It is suggested to configure a software interrupt (SWI) and put this function into its IRQ handler. The Wireless Core can then trigger it with a call to the context_switch() function from its HAL structure.

struct swc_cfg

#include <swc_api.h>

Wireless Core configuration.

Public Members

uint32_t *timeslot_sequence

Network schedule as an array of timeslot durations in microseconds

uint32_t timeslot_sequence_length

Number of timeslots in the timeslot sequence

uint32_t *channel_sequence

RF channels as an array of channel numbers

uint32_t channel_sequence_length

Number of channels in the channel sequence

bool fast_sync_enabled

Enable fast synchronization for low data rate links

bool random_channel_sequence_enabled

Enable random channel sequence concurrency mechanism

bool rdo_enabled

Enable the random datarate offset concurrency mechanism

uint8_t *memory_pool

Memory pool instance from which memory allocation is done

uint32_t memory_pool_size

Memory pool size in bytes

struct swc_hal

#include <swc_api.h>

Wireless Core hardware abstraction layer.

Public Members

swc_radio_hal_t radio_hal[WPS_RADIO_COUNT]

Radio HAL

void (*context_switch)(void)

Context switch function pointer

uint64_t (*get_tick_quarter_ms)(void)

Get tick quarter ms function pointer

struct swc_node_cfg

#include <swc_api.h>

Wireless node configuration.

Public Members

swc_role_t role

Network role

uint16_t pan_id

Personal area network 12-bit ID

uint8_t coordinator_address

Coordinator device’s 8-bit address; Same as local_address if local device is the Coordinator

uint8_t local_address

Local device’s 8-bit address

swc_sleep_level_t sleep_level

Sleep depth the transceiver will put itself when not active

struct swc_node

#include <swc_api.h>

Wireless node.

Public Members

uint8_t radio_count

Number of radio added to the node

swc_node_cfg_t cfg

Wireless node configuration

wps_node_t *wps_node_handle

Low-level node handler

wps_radio_t *wps_radio_handle

Low-level radio handler

struct swc_statistics

#include <swc_api.h>

Wireless statistics.

Public Members

uint32_t packet_sent_and_acked_count

Increments when an acknowledge frame is received after sending a packet

uint32_t packet_sent_and_not_acked_count

Increments when an acknowledge frame is not received after sending a packet

uint32_t no_packet_tranmission_count

Increments when there is nothing to send at the start of a TX timeslot

uint32_t packet_dropped_count

Increments when a packet is dropped by the Wireless Core due to its timeout mechanism

uint32_t tx_timeslot_occurrence

Increments for every TX timeslot the connection goes through

float tx_used_capacity_pc

Percentage of TX timeslots used for transmission over the total number of TX timeslots

uint32_t packet_successfully_received_count

Increments when a packet is received and the CRC checks

uint32_t no_packet_reception_count

Increment when nothing is received at the start of a RX timeslot

uint32_t rx_timeslot_occurrence

Increments for every RX timeslot the connection goes through

uint32_t packet_duplicated_count

Increments when a packet is received but is discarded because it is a duplicate of a previously received packet

uint32_t packet_overrun_count

Increments when a packet is received but is discarded because the Wireless Core reception queue is full

struct swc_radio_cfg

#include <swc_api.h>

Wireless radio configuration.

Public Members

swc_irq_polarity_t irq_polarity

State of the radio IRQ pin when asserted

swc_spi_mode_t spi_mode

Radio SPI interface timing setting

struct swc_connection_cfg

#include <swc_api.h>

Wireless connection configuration.

Public Members

char *name

Name of the connection as a character string

uint8_t source_address

Address of the transmitting node

uint8_t destination_address

Address of the receiving node

uint8_t max_payload_size

Maximum size in bytes the payload can ever be

uint32_t queue_size

Queue size in number of frames

swc_modulation_t modulation

Frame modulation

swc_fec_level_t fec

Frame forward error correction level

int32_t *timeslot_id

ID of timeslots used by the connection

uint32_t timeslot_count

Number of timeslots used by the connection

bool allocate_payload_memory

Whether or not payload memory allocation is managed by the connection (true) or the application (false)

bool fragmentation_enabled

Whether or not frame fragmentation is managed by the connection (true) or the application (false) when using payloads bigger than max_payload_size

bool ack_enabled

Whether or not ACK frames are sent (RX connection) or receive (TX connection) on the connection

bool arq_enabled

Whether or not retransmissions are enabled (needs ACK enabled)

uint32_t try_count

Maximum number of tries (0 is infinite) before a frame is dropped (needs ARQ enabled)

uint32_t time_deadline

Maximum amount of time (0 is infinite) in increment of 250 us (e.g. 4 is 1 ms) a frame can sit in the queue before it is dropped (needs ARQ enabled)

struct swc_connection_cfg::[anonymous] arq_settings

Settings for the automatic repeat request feature (Set only if ARQ is enabled)

bool auto_sync_enabled

Whether or not dummy frames are sent out by the Wireless Core if there is no application data in the queue

bool cca_enabled

Whether or not energy is sensed on the channel before trying to transmit

uint8_t threshold

Energy level considered too high for a successful transmission, from 0 (extremely unsensitive, i.e. lots of energy sensed on the channel will still yield to a transmission) to 47 (extremely sensitive, i.e. little energy sensed on the channel will make the transmission abort)

Size of the payload in bytes that triggers the fallback mode

uint8_t try_count

Number of energy sensings to do before the fail action is executed

uint16_t retry_time

Amount of time between energy sensings in increments of 48.8 us (e.g. 10 is ~500 us)

swc_cca_fail_action_t fail_action

Action to do when the energy level sensed is still too high after the last energy sensing try

struct swc_connection_cfg::[anonymous] cca_settings

Settings for the clear channel assessment feature (Set only if CCA is enabled)

bool throttling_enabled

Whether or not this connection supports throttling

bool rdo_enabled

Whether or not the random datarate offset value is sent on this connection

bool fallback_enabled

Whether ot not this connection can dynamically change its power settings based on the sent payload size

int8_t tx_pulse_count_offset

Offset on the pulse count to apply when going into fallback mode

int8_t tx_pulse_width_offset

Offset on the pulse width to apply when going into fallback mode

int8_t tx_pulse_gain_offset

Offset on the pulse gain to apply when going into fallback mode

uint8_t cca_try_count

CCA try count to use when in fallback mode (Set only if CCA is enabled)

struct swc_connection_cfg::[anonymous] fallback_settings

Settings for the fallback mode feature (Set only if fallback is enabled)

struct swc_connection

#include <swc_api.h>

Wireless connection.

Public Members

uint8_t channel_count

Number of channels added to the connection

swc_connection_cfg_t cfg

Wireless connection configuration

swc_statistics_t stats

Wireless connection statistics

frag_connection_t *frag_conn_handle

Low-level fragmentation handle

wps_connection_t *wps_conn_handle

Low-level connection handle

struct swc_channel_cfg

#include <swc_api.h>

Wireless channel configuration.

Public Members

uint8_t frequency

Frequency of the channel in increments of 40.96 MHz (e.g., 183 for 7.5 GHz)

uint8_t tx_pulse_count

Pulses number of the transmitted frames, from 1 to 3

uint8_t tx_pulse_width

Pulses width of the transmitted frames, from 0 (narrow) to 7 (large)

uint8_t tx_pulse_gain

Pulses amplitude of the transmitted frames, from 0 (max gain: 0 dB) to 3 (min gain: -1.8 dB)

uint8_t rx_pulse_count

Pulses number of the received frames, from 1 to 3, corresponding to the tx_pulse_count of the incoming frames

struct swc_fallback_info

#include <swc_api.h>

Wireless fallback information.

Public Members

int32_t link_margin

Link margin value

uint32_t cca_fail_count

CCA fail count value