swc_api.h

SPARK Wireless Core Application Programming Interface.

Copyright: Copyright (C) 2026 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.

SWC_LEGACY_PAN_ID_INVALID_RANGE 0xF000: Legacy PAN ID is only 12-bit. The 4 MSBs are invalid and can’t be used.

SWC_PAN_ID_INVALID_RANGE 0x8000: PAN ID is only 15-bit. The MSB is invalid and can’t be used.

SWC_RESERVED_PAN_ID 0x0000: Reserved PAN ID use for pairing purpose.

SWC_NETWORK_ID_MASK 0xFF: Network ID mask.

SWC_INVALID_BROADCAST_NETWORK_ID 0xFF: Broadcast address is invalid during normal operation in network ID.

Typedefs

typedef struct wps_connection wps_connection_t: Opaque wps_connection structures from the wps layer.

typedef struct swc_cfg swc_cfg_t: Wireless Core configuration.

typedef struct swc_concurrency_cfg swc_concurrency_cfg_t: Wireless Core concurrency configuration.

typedef struct swc_radio_handle swc_radio_handle_t: SPARK Radio handle structure combining a single radio instance and its associated calibration data. It is used to manage radio configuration, calibration, and runtime state within the SPARK Wireless Core.

typedef struct swc_node_cfg swc_node_cfg_t: Wireless node configuration.

typedef struct swc_statistics swc_statistics_t: Wireless statistics.

typedef struct swc_qos_indicators swc_qos_indicators_t: Wireless Quality of Service (QoS) indicators.

typedef enum swc_radio_id swc_radio_id_t: Identifies each radio unit by a unique ID.

Note

Each enum value corresponds to a specific radio HAL structure index, simplifying the selection and management of the appropriate radio hardware abstraction layer based on the radio ID.

typedef enum swc_multi_radio_select_mode swc_multi_radio_select_mode_t: SWC radio selections.

typedef struct swc_connection_cfg swc_connection_cfg_t: Wireless connection configuration.

typedef struct swc_connection_concurrency_cfg swc_connection_concurrency_cfg_t: Wireless connection concurrency configuration.

typedef struct swc_connection_fallback_cfg swc_connection_fallback_cfg_t: Wireless connection fallback 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_channel_cfg swc_fallback_channel_cfg_t: Wireless fallback channel configuration.

typedef struct wps_channel swc_channel_t: Wireless channel object.

typedef struct swc_fallback_info swc_fallback_info_t: Wireless fallback information.

typedef enum swc_status swc_status_t: The SPARK Wireless Core status.

Enums

enum swc_radio_id

Identifies each radio unit by a unique ID.

Note

Each enum value corresponds to a specific radio HAL structure index, simplifying the selection and management of the appropriate radio hardware abstraction layer based on the radio ID.

Values:

enumerator SWC_RADIO_ID_1 = 0: Radio 1 HAL structure index.

enumerator SWC_RADIO_ID_2 = 1: Radio 2 HAL structure index.

enumerator SWC_RADIO_ID_MAX = 2: Always keep this last to know the count of radio.

enum swc_multi_radio_select_mode

SWC radio selections.

Values:

enumerator SWC_MULTI_RADIO_SELECT_MODE_ALGO: Let the multi radio algorithm select the radio.

enumerator SWC_MULTI_RADIO_SELECT_MODE_RADIO1: Always select radio 1.

enumerator SWC_MULTI_RADIO_SELECT_MODE_RADIO2: Always select radio 2.

enumerator SWC_MULTI_RADIO_SELECT_MODE_COUNT: Radio selection mode count.

enum swc_status

The SPARK Wireless Core status.

Values:

enumerator SWC_STATUS_STOPPED: The Wireless Core is stopped.

enumerator SWC_STATUS_RUNNING: The wireless core module is running.

Functions

void swc_init(swc_cfg_t cfg, swc_node_cfg_t node_cfg, void (*callback)(void), swc_error_t *const 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 network configuration.
node_cfg – [in] Wireless Core local node configuration.
callback – [in] A function pointer to the logic initiating context switches.
err – [out] Wireless Core error code.

void swc_set_certification_mode(bool enabled, swc_error_t *const err)

Enable certification mode for the SWC.

Note

This feature utilizes the application configuration to activate certification mode for the radio. In this mode, the radio transmits at maximum power and emulates acknowledgments according to the application’s settings.

Note

Enabling certification mode disables any features that modify the radio’s wake-up behavior, such as concurrency and latency optimization, to ensure proper acknowledgment emulation.

Note

By default, certification mode is disabled.

Parameters:

enabled – [in] Whether or not certication mode is enabled.
err – [out] Pointer to a variable to store Wireless Core error code.

void swc_set_fast_sync(bool enabled, swc_error_t *const err)

Enable/disable fast synchronization for low data rate links.

Note

This feature is not supported in a dual radio configuration.

Note

By default, fast sync is disabled.

Parameters:

enabled – [in] Whether or not fast synchronization for low data rate links is supported.
err – [out] Wireless Core error code.

void swc_set_legacy_header_packing(bool enabled, swc_error_t *const err)

Enable/disable legacy byte-aligned header packing for backward compatibility.

Note

When enabled, all protocol header fields use their original fixed byte-aligned sizes instead of optimized bit-packed sizes. This ensures wire-level compatibility with SDK version 2.3 and earlier.

Note

By default, legacy header packing is disabled.

Parameters:

enabled – [in] Whether or not legacy header packing is enabled.
err – [out] Wireless Core error code.

void swc_set_concurrency_cfg(swc_concurrency_cfg_t cfg, swc_error_t *const err)

Advance configuration for concurrency mechanism.

Note

By default, RDO is disabled and DDCM enabled when using SWC_CONCURRENCY_MODE_HIGH_PERFORMANCE. RDO is enabled and DDCM is disabled when using SWC_CONCURRENCY_MODE_LOW_PERFORMANCE. Random channel sequence is always on.

Parameters:

cfg – [in] Concurrency configuration.
err – [out] Wireless Core error code.

void swc_node_enable_legacy_sfd(uint16_t legacy_pan_id, swc_error_t *const err)

Enable the usage of legacy SFDs for backward compatibility.

Parameters:

legacy_pan_id – [in] The PAN ID use in old firmware.
err – [out] Wireless Core error code.

swc_radio_handle_t *swc_radio_module_calib(swc_radio_id_t radio_id, swc_error_t *err)

Performs calibration on a SPARK radio module.

Note

Sets up a internal static radio handle for the given radio ID, powers up and configures the radio, initializes its NVM, and executes the calibration procedure. The calibration results are stored in internal static radio handle.

Parameters:

radio_id – [in] ID of the radio to calibrate.
err – [out] Wireless Core error code.

Returns:

The calibrated radio instance with NVM and spectral data.

swc_radio_handle_t *swc_radio_module_load_calib_data(swc_radio_id_t radio_id, const uint8_t *data, size_t size, swc_error_t *err)

Loads radio calibration data into the internal static radio handle.

Note

Copies the calibration data from a byte buffer into the internal static radio handle. The input buffer is expected to contain data previously exported from a calibrated radio handle. This function avoids direct casting from a byte buffer to swc_radio_handle_t, preventing possible unaligned access on architectures that do not support it.

Parameters:

radio_id – [in] ID of the radio to calibrate.
data – [in] Pointer to the buffer containing the stored radio calibration data.
size – [in] Size of the calibration data buffer in bytes.
err – [out] Wireless Core error code.

Returns:

The restored radio instance with NVM and spectral calibration data.

void swc_radio_module_init(swc_radio_handle_t *radio_handle, bool pwr_cycle_saved_calib, swc_error_t *err)

Initialize a specified SWC node radio module with calibration, NVM, and radio data.

Note

Powers up the radio, attaches NVM and calibration data, and allocates memory if needed.

Parameters:

radio_handle – [in] The calibrated radio instance with NVM and spectral data.
pwr_cycle_saved_calib – [in] Flag to prepare the radio for receive saved calibration after a power cycle.
err – [out] Wireless Core error code.

void swc_node_set_radio_irq_polarity(swc_radio_id_t radio_id, swc_irq_polarity_t irq_polarity, swc_error_t *const err)

Set the state of the radio IRQ pin when asserted.

Note

This function must be invoked after swc_radio_module_init to take effect.

Note

By default, SWC_IRQ_ACTIVE_HIGH is used if this function is not called.

Parameters:

radio_id – [in] Radio number.
irq_polarity – [in] Radio’s IRQ polarity.
err – [out] Wireless Core error code.

void swc_node_set_radio_spi_mode(swc_radio_id_t radio_id, swc_spi_mode_t spi_mode, swc_error_t *const err)

Set the radio’s SPI interface timing setting.

Note

This function must be invoked after swc_radio_module_init to take affect.

Note

By default, SWC_SPI_FAST is used if this function is not called.

Parameters:

radio_id – [in] Radio number.
spi_mode – [in] Radio’s SPI mode.
err – [out] Wireless Core error code.

void swc_node_set_low_power_callback(void (*cb)(void *node), swc_error_t *const err)

Set the callback function to indicate that the Wireless Core is ready to enter to lower power mode.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on transition to low power mode.

Parameters:

cb – [in] Callback function.
err – [out] Wireless Core error code.

void swc_node_set_sleep_level(swc_sleep_level_t sleep_level, swc_error_t *const err)

Set the sleep depth the transceiver will put itself when not active.

Note

By default, SLEEP_IDLE is used if this function is not called.

Parameters:

sleep_level – [in] Sleep level.
err – [out] Wireless Core error code.

bool swc_node_is_low_power_allowed(swc_error_t *const err)

Return state if low power mode can be activated.

Note

Use swc_node_is_low_power_allowed function to find out whether low power mode can be active.

Parameters:: err – [out] Wireless Core error code.
Returns:: State if low power mode can be activated.

uint64_t swc_node_get_radio_serial_number(swc_error_t *const err)

Get the radio’s 64-bit serial number.

Note

The serial number has been assigned during manufacturing and is unique among all SPARK transceivers of the same model.

Parameters:: err – [out] Wireless Core error code.
Returns:: Serial number.

uint8_t swc_node_get_radio_product_model(swc_error_t *const err)

Get the radio’s 8-bit product model.

Note

The serial number has been assigned during manufacturing and is unique among all SPARK transceivers of the same model.

Parameters:: err – [out] Wireless Core error code.
Returns:: Product model.

uint8_t swc_node_get_radio_product_version(swc_error_t *const err)

Get the radio’s 8-bit product version.

Note

The serial number has been assigned during manufacturing and is unique among all SPARK transceivers of the same model.

Parameters:: err – [out] Wireless Core error code.
Returns:: Product version.

int swc_format_radio_nvm(char *const buffer, uint16_t size, swc_error_t *const err)

Get a formatted string of the radio’s nvm content.

Parameters:

buffer – [in] Buffer where to put the formatted string.
size – [in] Size of the buffer.
err – [out] Wireless Core error code.

Returns:

The formated string length, excluding the NULL terminator.

bool swc_is_radio_model_sr1x10(swc_error_t *const err)

Verify if the radio’s model is SR1x10.

Parameters:

err – [out] Wireless Core error code.

Return values:

true – Radio model is sr1x10.
false – Radio model is not sr1x10.

swc_connection_t *swc_connection_init(swc_connection_cfg_t cfg, swc_error_t *const err)

Initialize a connection.

Note

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

Parameters:

cfg – [in] Wireless connection configuration.
err – [out] Wireless Core error code.

Returns:

Connection handle.

swc_connection_cfg_t swc_get_beacon_connection_config(uint8_t source_address, const int32_t *const timeslot_id, uint8_t timeslot_count)

Get a beacon connection configuration.

Parameters:

source_address – [in] Source address/beacon transmitter’s address.
timeslot_id – [in] Array of timeslot IDs used by the connection.
timeslot_count – [in] Number of timeslots used by the connection.

Returns:

Pre-configured SWC connection configuration instance for a beacon.

swc_channel_t *swc_channel_list_init(const swc_channel_cfg_t *cfgs, uint8_t count, swc_error_t *const err)

Initialize a list of channels.

Parameters:

cfgs – [in] Array of wireless channel configurations.
count – [in] Number of channels.
err – [out] Wireless Core error code.

Returns:

Array of channel handles.

swc_channel_t *swc_channel_list_init_from_base(swc_channel_cfg_t base_cfg, const uint32_t *const freqs, uint8_t count, swc_error_t *const err)

Initialize a list of channels from a single base configuration and an array of frequencies.

Note

To initialize a list of channel with different pulse configuration, use swc_channel_list_init instead.

Parameters:

base_cfg – [in] Base channel configuration.
freqs – [in] Array of channel frequencies.
count – [in] Number of channels.
err – [out] Wireless Core error code.

Returns:

Array of channel handles.

void swc_connection_set_channels(swc_connection_t *const conn, swc_channel_t *channels, uint8_t count, swc_error_t *const err)

Configure channels to use for a wireless connection using a channel pool.

Parameters:

conn – [in] Connection handle.
channels – [in] Array of channel handles.
count – [in] Number of channels in the array.
err – [out] Wireless Core error code.

void swc_connection_add_channel(swc_connection_t *const conn, swc_channel_cfg_t cfg, swc_error_t *const err)

Configure a channel to use for a wireless connection.

Note

This is a legacy function. It is recommended to use swc_connection_set_channels or swc_channel_list_init_from_base instead to configure channels. This function cannot be used after swc_connection_set_channels is called on the same connection.

Parameters:

conn – [in] Connection handle.
cfg – [in] Wireless channel configuration.
err – [out] Wireless Core error code.

void swc_connection_add_fallback_channel(const swc_connection_t *const conn, swc_channel_cfg_t main_cfg, swc_fallback_channel_cfg_t cfg, uint8_t channel_index, uint8_t fallback_index, swc_error_t *const err)

Configure a fallback channel to use for a wireless connection.

Note

This function can only be used on TX connections.

Parameters:

conn – [in] Connection handle.
main_cfg – [in] Base channel configuration without fallback.
cfg – [in] Wireless channel configuration.
channel_index – [in] Channel index.
fallback_index – [in] Fallback index. 0 is the fallback with the highest payload size threshold.
err – [out] Wireless Core error code.

void swc_connection_set_fallback_channels(swc_connection_t *const conn, swc_channel_t *channels, uint8_t count, uint8_t fallback_index, swc_error_t *const err)

Configure fallback channels to use for a wireless connection using the pool.

Note

This function can only be used on TX connections.

Parameters:

conn – [in] Connection handle.
channels – [in] Array of channel handles.
count – [in] Number of channels in the array.
fallback_index – [in] Fallback index. 0 is the fallback with the highest payload size threshold.
err – [out] Wireless Core error code.

void swc_connection_set_tx_success_callback(swc_connection_t *const conn, void (*cb)(void *conn, void *arg), void *arg, swc_error_t *const 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).

Note

Connection callback setter serve two functions:

They need to be called during connection initialization to let the SWC setup know the memory that need to be allocated for the callback.
They can be called at any time to change the callback function ONLY if they have been previously allocated during the SWC setup.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on TX success.

Parameters:

conn – [in] Connection handle.
cb – [in] Callback function.
arg – [in] Argument to pass to the callback function.
err – [out] Wireless Core error code.

void swc_connection_set_tx_fail_callback(swc_connection_t *const conn, void (*cb)(void *conn, void *arg), void *arg, swc_error_t *const 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.

Note

Connection callback setter serve two functions:

They need to be called during connection initialization to let the SWC setup know the memory that need to be allocated for the callback.
They can be called at any time to change the callback function ONLY if they have been previously allocated during the SWC setup.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on TX fail.

Parameters:

conn – [in] Connection handle.
cb – [in] Callback function.
arg – [in] Argument to pass to the callback function.
err – [out] Wireless Core error code.

void swc_connection_set_tx_dropped_callback(swc_connection_t *const conn, void (*cb)(void *conn, void *arg), void *arg, swc_error_t *const 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.

Note

Connection callback setter serve two functions:

They need to be called during connection initialization to let the SWC setup know the memory that need to be allocated for the callback.
They can be called at any time to change the callback function ONLY if they have been previously allocated during the SWC setup.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on TX dropped.

Parameters:

conn – [in] Connection handle.
cb – [in] Callback function.
arg – [in] Argument to pass to the callback function.
err – [out] Wireless Core error code.

void swc_connection_set_rx_success_callback(swc_connection_t *const conn, void (*cb)(void *conn, void *arg), void *arg, swc_error_t *const 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.

Note

Connection callback setter serve two functions:

They need to be called during connection initialization to let the SWC setup know the memory that need to be allocated for the callback.
They can be called at any time to change the callback function ONLY if they have been previously allocated during the SWC setup.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on RX success.

Parameters:

conn – [in] Connection handle.
cb – [in] Callback function.
arg – [in] Argument to pass to the callback function.
err – [out] Wireless Core error code.

void swc_connection_set_event_callback(swc_connection_t *const conn, void (*cb)(void *conn, void *arg), void *arg, swc_error_t *const err)

Set the callback function to execute after an event occur on the connection.

Note

Use swc_get_event function to know which event occurred.

Note

Connection callback setter serve two functions:

They need to be called during connection initialization to let the SWC setup know the memory that need to be allocated for the callback.
They can be called at any time to change the callback function ONLY if they have been previously allocated during the SWC setup.

Note

By default, NULL is used if this function is not called, meaning no callback is invoked on event (ex: connect or disconnect).

Parameters:

conn – [in] Connection handle.
cb – [in] Callback function.
arg – [in] Argument to pass to the callback function.
err – [out] Wireless Core error code.

void swc_connection_set_fec_ratio(const swc_connection_t *const conn, swc_fec_ratio_t ratio, swc_error_t *const err)

Set the frame forward error correction (FEC) ratio for a connection.

Note

By default, SWC_FEC_1_6_6 is used if this function is not called.

Parameters:

conn – [in] Connection handle.
ratio – [in] FEC ratio.
err – [out] Wireless Core error code.

void swc_connection_optimized_latency(const swc_connection_t *const conn, uint8_t auto_reply_payload_size, swc_error_t *const err)

Optimize latency in target connection.

Note

This feature delays the wakeup of the transceiver each time the queue is empty, allowing more time for the application context to generate a frame. This results in an overall better latency by reducing the minimum time it takes for the SWC to process a frame.

Note

The delay resulting from this feature is equal to the sum of the CCA time and the air time of the frame, which include the auto-reply part. The CCA time is based on the cca_try_count and the cca_retry_time, which are part of the connection_cfg.

Note

This feature can’t be enabled when certification mode is enabled since it modify the wake up of the radio which is critical to properly emulate acknowledge.

Parameters:

conn – [in] Connection handle.
auto_reply_payload_size – [in] Size of the payload in the auto-reply(if any).
err – [out] Wireless Core error code.

void swc_connection_set_fragmentation(const swc_connection_t *const conn, swc_error_t *const err)

Enable fragmentation on the target connection.

Note

This needs to be implemented on both sides of the connection so that the transmitter (TX) can fragment the packet, and the receiver (RX) can aggregate the received payload.

Note

Once this feature is enabled, users will be able to send payloads larger than the provided maximum payload size during connection configuration when using the swc_connection_send method.

Note

By default, fragmentation is disabled. Fragmentation compilation flag must be enabled to use this feature.

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

bool swc_connection_get_fragmentation_enable_state(const swc_connection_t *const conn, swc_error_t *err)

Get the connection frag enable state.

Parameters:

conn – [in] SWC connection instance.
err – [out] Wireless Core error code.

Returns:

bool True if the frag is enable false if not.

void swc_connection_set_acknowledgment(const swc_connection_t *const conn, bool enabled, swc_error_t *const err)

Enable/disable ACK exchange on target connection.

Note

This need to be enable on both device (TX and RX) in order to have proper ACK exchange.

Note

To send payload inside the ACK of a RX connection, configure a TX connection that share the same timeslot as the RX connection and make sure that the AUTO_TIMESLOT macro is used when defining the timeslot.

Note

To receive payload inside the ACK of TX connection, configure a RX connection that share the same timeslot as the TX connection and make sure that the AUTO_TIMESLOT macro is used when defining the timeslot.

Note

By default, a main timeslot has an acknowledge. An auto-reply never has an acknowledge.

Parameters:

conn – [in] Connection handle.
enabled – [in] Whether or not ACK frames are sent (RX connection) or receive (TX connection).
err – [out] Wireless Core error code.

void swc_connection_set_credit_flow_ctrl(const swc_connection_t *const conn, bool enabled, swc_error_t *const err)

Enable/disable credit flow control on target connection.

Note

This function must be called after swc_connection_set_acknowledgment.

Note

By default, credit flow control is disabled.

Parameters:

conn – [in] Connection handle.
enabled – [in] Whether or not credit flow control frames is enabled on target connection.
err – [out] Wireless Core error code.

void swc_connection_set_retransmission(const swc_connection_t *const conn, bool enabled, uint32_t try_deadline, uint32_t time_deadline, swc_error_t *const err)

Enable retransmission of frame with or without condition to drop the frame.

Note

Setting try_deadline and time_deadline to 0 will result in a Guaranteed delivery transmission mode.

Note

Do nothing if ACK is disabled using swc_connection_set_acknowledgment.

Note

The time increment for the parameter time_deadline is in number of tick from the get_tick() hal function.

Note

By default, the retransmission is set to 0, which means infinite retries (guaranteed delivery).

Parameters:

conn – [in] Connection handle.
enabled – [in] Whether or not retransmission are enabled on target connection.
try_deadline – [in] Maximum number of tries (0 is infinite) before a frame is dropped.
time_deadline – [in] Maximum amount of time (0 is infinite) before a frame is dropped.
err – [out] Wireless Core error code.

swc_event_t swc_get_event(const swc_connection_t *const conn)

Return the event notified by the event callback.

Parameters:: conn – [in] Connection handle.
Returns:: Event.

swc_error_t swc_get_event_error(const swc_connection_t *const conn)

Return the error notified by the event callback.

Parameters:: conn – [in] Connection handle.
Returns:: Error.

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

Set the percentage of allocated timeslots to use.

Note

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_set_remote_node_address(uint8_t current_address, uint8_t new_address, swc_error_t *const err)

Change the destination address of a remote node at runtime.

Note

The address change is deferred via the request queue and applied between timeslots to avoid interfering with ongoing transmissions. All connections associated with the remote node will be affected by this change.

Parameters:

current_address – [in] Current 8-bit device address of the remote node.
new_address – [in] New 8-bit device address to assign to the remote node.
err – [out] Wireless Core error code.

void swc_connection_set_modulation(const swc_connection_t *const conn, swc_modulation_t modulation, swc_error_t *const err)

Set the connection’s modulation.

Note

By default, SWC_MOD_IOOK is used if this function is not called.

Parameters:

conn – [in] Connection handle.
modulation – [in] Connection’s modulation.
err – [out] Wireless Core error code.

void swc_connection_set_auto_sync(const swc_connection_t *const conn, bool enabled, swc_error_t *const err)

Enable/disable auto-sync mode.

Note

By default, auto-sync is disabled.

Parameters:

conn – [in] Connection handle.
enabled – [in] Whether or not auto-sync is supported on the connection.
err – [out] Wireless Core error code.

void swc_connection_set_throttling(const swc_connection_t *const conn, swc_error_t *const err)

Enable connection data rate throttling.

Note

By default, throttling is disabled.

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

void swc_connection_set_connection_priority(swc_connection_t *const conn, uint8_t priority, swc_error_t *const err)

Enable connection priority on a connection.

Note

The same priority is used for all the assigned slots of the connection. ‘priority’ and ‘slots_priority’ cannot be used at the same time.

Note

The connection priority feature should be the last API call to configure the connection. Everything that is set after this call will result in an error.

Note

By default, there is no priority between the connections. The first connection added in a timeslot will always have the highest priority.

Parameters:

conn – [in] Connection handle.
priority – [in] Connections’ priority.
err – [out] Wireless Core error code.

void swc_connection_set_connection_slots_priority(swc_connection_t *const conn, const uint8_t *slots_priority, swc_error_t *const err)

Enable slots priority on a connection.

Note

Priorities for the particular timeslots is used by the connection. ‘priority’ and ‘slots_priority’ cannot be used at the same time.

Note

The slots priority feature should be the last API call to configure the connection. Everything that is set after this call will result in an error.

Note

By default, this type of priority is not used.

Parameters:

conn – [in] Connection handle.
slots_priority – [in] Connections’s timeslots priorities.
err – [out] Wireless Core error code.

void swc_connection_set_concurrency_cfg(const swc_connection_t *const conn, const swc_connection_concurrency_cfg_t *const cfg, swc_error_t *const err)

Advance concurrency configuration for connections.

Note

By default, concurrency mechanisms are enabled.

Parameters:

conn – [in] Connection handle.
cfg – [in] Concurrency configuration.
err – [out] Wireless Core error code.

void swc_connection_set_fallback_cfg(const swc_connection_t *const conn, const swc_connection_fallback_cfg_t *const cfg, swc_error_t *const err)

Set the connection’s fallback configuration.

Note

By default, fallback is disabled.

Parameters:

conn – [in] Connection handle.
cfg – [in] Fallback configuration.
err – [out] Wireless Core error code.

void swc_connection_set_tx_sync_frame_on_syncing(const swc_connection_t *const conn, bool enabled, swc_error_t *const err)

Enable or disable sending of sync frame on syncing when the connection queue is not empty.

Note

This prevents the device from polluting the channel with full packet when unsync.

Note

By default, sync frames will be sent when syncing without consuming actual data.

Parameters:

conn – [in] SPARK Wireless Core connection structure.
enabled – [in] Enable or disable the feature.
err – [out] Wireless Core error code.

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

Get a buffer from the connection queue.

Note

This function allocates a buffer of the predefined maximum payload size, regardless of the current packet size.

Parameters:

conn – [in] Connection handle.
payload_buffer – [out] Free payload buffer if available, NULL otherwise.
err – [out] Wireless Core error code.

void swc_connection_allocate_payload_buffer(const swc_connection_t *const conn, uint8_t **const payload_buffer, uint16_t payload_size, swc_error_t *const err)

Allocate a buffer from the connection queue with required size.

Note

This function treats the queue as a continuous memory block, allocating only the exact memory required for each packet. The pointer progresses within the queue’s memory space as packets are allocated one after another. This behavior could allow an application to split its payload into multiple packets to reduce their size.

Note

Since the pointer advances by variable sizes, the allocated memory might not be aligned to the max payload size. For example, if the queue is sized for two 64-byte packets but the first is 2 bytes and the second is 64 bytes, freeing the 2-byte packet only leaves space for 62 bytes due to the 2-byte offset of the second packet. The queue fails to allocate memory for the third packet even if total memory is available.

Parameters:

conn – [in] Connection handle.
payload_buffer – [out] Free payload buffer with required size if available, NULL otherwise.
payload_size – [in] Required size of the buffer.
err – [out] Wireless Core error code.

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

Enqueue a payload buffer in the connection transmission queue.

Note

The payload buffer can be allocated using swc_connection_get_payload_buffer or swc_connection_allocate_payload_buffer.

Note

The user can also pass a buffer from the user space memory. In this case, the SWC will copy the content of the user buffer into the connection queue. The user space memory is thus freed once the function returns.

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(const swc_connection_t *const conn, uint8_t **const payload_buffer, swc_error_t *const 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.

uint16_t swc_connection_receive_get_payload_size(const swc_connection_t *const conn, swc_error_t *const err)

Get the payload size from the connection reception queue.

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

Returns:

Size of the received payload.

void swc_connection_receive_complete(const swc_connection_t *const conn, swc_error_t *const err)

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

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

void swc_reserved_address_unlock(void): Enable pairing specific features.

Note

Reserved pairing addresses are available.

void swc_reserved_address_lock(void): Disable pairing specific features.

Note

Reserved pairing addresses are not available.

uint16_t swc_connection_receive_to_buffer(const swc_connection_t *const conn, uint8_t *const payload, uint16_t size, swc_error_t *const 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.

uint16_t swc_connection_get_enqueued_count(const swc_connection_t *const conn, swc_error_t *const err)

Get the number of frame in the connection queue.

Parameters:

conn – [in] Connection handle.
err – [in] Wireless Core error code.

Returns:

The number of frame in the connection queue.

bool swc_connection_get_connect_status(const swc_connection_t *const conn, swc_error_t *const err)

Return if the connection is connected or disconnected.

Parameters:

conn – [in] Connection handle.
err – [in] Wireless Core error code.

Returns:

True if the connection is connected, False otherwise.

void swc_connection_flush_queue(const swc_connection_t *conn, swc_error_t *err)

Flush the packets in the connection’s queue.

Note

This function can only be ran when the wireless core is disconnected.

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

void swc_setup(swc_error_t *const err)

Wireless Core setup.

Note

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

Parameters:: err – [out] Wireless Core error code.

swc_status_t swc_get_status(void)

Get the wireless core status.

Returns:: The wireless core status.

void swc_connect(swc_error_t *const err)

Start Wireless Core process.

Note

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 *const err)

Stop Wireless Core process.

Parameters:: err – [out] Wireless Core error code.

swc_fallback_info_t swc_connection_get_fallback_info(const swc_connection_t *const conn, swc_error_t *const err)

Get information used when the fallback mode is enabled.

Note

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): Processes connection-related callbacks following a context switch.

Note

This function is intended to be invoked once the context switch has occurred.

Note

In a bare-metal environment, this function should be called from the PendSV_IRQ_handler or similar interrupt handlers related to the context switch triggering mechanism.

Note

In an RTOS environment, the context switch should allow the scheduler to prioritize this function for processing.

void swc_send_tx_flush_request(const swc_connection_t *const conn)

Send a tx flush request to the connection.

Parameters:: conn – [in] SWC connection.

bool swc_config_hardware_interface(void)

Links the necessary functions to allow the wireless core interact with the radio(s).

Return values:

true – Link success.
false – Link fail.

uint8_t swc_connection_get_cca_max_try(swc_connection_t *conn, swc_error_t *err)

Get the maximum cca try count of a connection.

Parameters:

conn – [in] Connection handle.
err – [out] Wireless Core error code.

Returns:

CCA max try count.

swc_cca_fail_action_t swc_connection_get_cca_fail_action(const swc_connection_t *const conn, swc_error_t *err)

Get the CCA fail action of a connection.

Parameters:

conn – [in] SWC connection instance.
err – [out] Wireless Core error code.

Returns:

The CCA fail action of the connection.

bool swc_connection_is_tx(const swc_connection_t *const conn, swc_error_t *err)

Check if the connection is a TX connection.

Parameters:

conn – [in] SWC connection instance.
err – [out] Wireless Core error code.

Returns:

bool True if the connection is a TX connection.

bool swc_connection_is_rx(const swc_connection_t *const conn, swc_error_t *err)

Check if the connection is a RX connection.

Parameters:

conn – [in] SWC connection instance.
err – [out] Wireless Core error code.

Returns:

bool True if the connection is a RX connection.

size_t swc_get_radio_handle_size(void)

Returns the size of the SWC radio handle.

Returns:: The size of the swc_radio_handle_t structure in bytes.

struct swc_cfg

#include <swc_api.h>

Wireless Core configuration.

Public Members

const 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.

const uint32_t *channel_sequence: RF channels as an array of channel numbers.

uint32_t channel_sequence_length: Number of channels in the channel sequence.

swc_concurrency_mode_t concurrency_mode: Concurrency mode.

uint8_t *memory_pool: Memory pool instance from which memory allocation is done.

uint32_t memory_pool_size: Memory pool size in bytes.

uint16_t pan_id: Personal area network ID.

struct swc_concurrency_cfg

#include <swc_api.h>

Wireless Core concurrency configuration.

Public Members

bool random_channel_sequence_enabled: Enable random channel sequence concurrency mechanism.

bool rdo_enabled: Enable the random datarate offset concurrency mechanism.

bool ddcm_enabled: Enable the distributed desync concurrency mechanism.

struct swc_node_cfg

#include <swc_api.h>

Wireless node configuration.

Public Members

swc_role_t role: Network role.

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.

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_invalid_data_size_count: Increments when a packet is received but is discarded because the frame data size is invalid.

uint32_t packet_invalid_header_size_count: Increments when a packet is received but is discarded because the frame header size is invalid.

uint32_t packet_rejected_count: Increments when a packet is received but is discarded because the transceiver marked it as corrupted.

uint32_t packet_overrun_count: Increments when a packet is received but is discarded because the Wireless Core reception queue is full.

uint32_t packet_ack_data_received_count: Increments when a ACK packet is received with data.

uint32_t packet_ack_data_send_count: Increments when a ACK packet is sent with data.

uint32_t cca_pass_count: Increments when a timeslot’s Clear-Channel-Assessment passes and transmission occurs normally.

uint32_t cca_fail_count: Increments when a timeslot’s Clear-Channel-Assessment fails and aborts (or forces) transmission.

uint32_t cca_try_fail_count: Increments when a single Clear-Channel-Assessment trial fails.

uint32_t rssi_avg_raw: Average of all raw RSSI codes from the radio register.

uint32_t rnsi_avg_raw: Average of all raw RNSI codes from the radio register.

uint32_t rssi_inst: Instantaneous RSSI value represented in tenths of dB.

uint32_t rnsi_inst: Instantaneous RNSI value represented in tenths of dB.

uint32_t rssi_avg: Average of all RSSI values in tenths of dB.

uint32_t rnsi_avg: Average of all RNSI values in tenths of dB.

uint32_t link_margin_avg: Average of all Link Margin values in tenth of dB.

uint32_t rssi_block_avg_tenth_db: RSSI block average in tenths of dB.

uint32_t rnsi_block_avg_tenth_db: RNSI block average in tenths of dB.

uint32_t link_margin_block_avg_tenth_db: Link Margin block average in tenths of dB.

uint32_t bytes_sent: Number of bytes sent.

uint32_t bytes_received: Number of bytes received.

uint32_t tx_data_rate_bps: TX datarate in bits per seconds.

uint32_t rx_data_rate_bps: RX datarate in bits per seconds.

uint32_t tick_on_reset: Tick value on statistics reset.

uint32_t tick_since_reset: Tick value since last statistics reset.

struct swc_qos_indicators

#include <swc_api.h>

Wireless Quality of Service (QoS) indicators.

Public Members

uint32_t link_margin: Link margin average, in dB.

uint32_t cca_tries: Number of cca tries.

uint32_t cca_retry_time: CCA delay between each retry, in PLL cycles.

uint32_t isi_indicator: ISI indicator, from 0 to 300 %.

uint32_t total_isi_indicator: Total ISI indicator, from 0 to 300 %.

uint32_t phy_rate_factor: PHY rate factor, to compute CCA times.

uint32_t tx_tries: Number of time TX had a payload to transmit.

uint32_t received_count: Received count to compute average CCA times on RX side.

uint32_t cca_on_time_pll_cycles: CCA on time, in PLL cycles.

struct swc_connection_cfg

#include <swc_api.h>

Wireless connection configuration.

Public Members

const 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.

uint16_t queue_size: Queue size in number of frames.

const int32_t *timeslot_id: ID of timeslots used by the connection.

uint32_t timeslot_count: Number of timeslots used by the connection.

struct swc_connection_concurrency_cfg

#include <swc_api.h>

Wireless connection concurrency configuration.

Public Members

bool enabled: Enable or disable the concurrency mechanism.

uint8_t try_count: Number of energy readings to do before the fail action is executed. Disable the CCA if the value is set to 0.

uint16_t retry_time

Amount of time between energy readings in increments of radio’s PHY rate period (e.g. 48.8 ns at 20.48 MHz).

Maximum value is 1024 cycles.

swc_cca_fail_action_t fail_action: Action to execute when all CCA attempts fail (channel still busy). See swc_cca_fail_action_t.

struct swc_connection_fallback_cfg

#include <swc_api.h>

Wireless connection fallback configuration.

Public Members

bool enabled: Enable or disable the fallback mechanism.

uint8_t fallback_mode_count: Number of fallback modes.

const uint8_t *thresholds: Array of payload size fallback threshold. in descending order. Array size must be equal to fallback_mode_count.

const uint8_t *cca_try_count: Array of number of CCA tries. Array size must be equal to fallback_mode_count.

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.

wps_connection_t *wps_conn_handle: Low-level connection handle.

bool init: Wireless Core Connection initialized status.

bool conn_priority_enabled: Flag to lock configuration of certain features when connection priority is enabled.

bool slot_prio_enabled: Flag to lock configuration of certain features when slot priority is enabled.

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_channel_cfg

#include <swc_api.h>

Wireless fallback channel configuration.

Public Members

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).

struct swc_fallback_info

#include <swc_api.h>

Wireless fallback information.

Public Members

uint8_t link_margin: Link margin value.

uint32_t cca_fail_count: CCA fail count value.

uint32_t cca_tx_fail_count: Number of times all CCA attempts failed.

uint32_t tx_pkt_dropped: Total number of tx dropped packets.

uint32_t cca_event_count: Total number of CCA events.