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

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 swc_cfg swc_cfg_t: Wireless Core configuration.

typedef struct swc_concurrency_cfg swc_concurrency_cfg_t: Wireless Core concurrency configuration.

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

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

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_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, void (*callback)(void), 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.
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 *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 *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_concurrency_cfg(swc_concurrency_cfg_t cfg, swc_error_t *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.

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_enable_legacy_sfd(swc_node_t *node, uint16_t legacy_pan_id, swc_error_t *err)

Enable the usage of legacy SFDs for backward compatibility.

Parameters:

node – [in] A pointer to the node handle structure.
legacy_pan_id – [in] The PAN ID use in old firmware.
err – [out] Wireless Core error code.

void swc_radio_module_init(swc_node_t *const node, swc_radio_id_t radio_id, bool calibrate, swc_error_t *err)

Initializes a specified radio module within the given node.

Note

This function configures a radio module with default settings and performs necessary initializations including power cycling, reading from non-volatile memory (NVM), and calibrating the radio according to these settings. This must be called for every radio module connected to the device. Most systems operate a single radio, but a dual radio configuration is also supported for specific use cases.

Parameters:

node – [in] A pointer to the node handle structure.
radio_id – [in] The identifier of the radio module to initialize.
calibrate – [in] Choose between recalibrating the module afresh or using previously saved calibration data.
err – [out] Wireless Core error code.

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

Set the state of the radio IRQ pin when asserted.

Note

This function must be invoked after swc_radio_module_init to take affect.

Note

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

Parameters:

node – [in] Node handle.
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_node_t *node, swc_radio_id_t radio_id, swc_spi_mode_t spi_mode, swc_error_t *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:

node – [in] Node handle.
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(const swc_node_t *const node, void (*cb)(void *node), swc_error_t *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:

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

void swc_node_set_sleep_level(swc_node_t *node, swc_sleep_level_t sleep_level, swc_error_t *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:

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

bool swc_node_is_low_power_allowed(const swc_node_t *const node, swc_error_t *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:

node – [in] Node handle.
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 *err)

Get the radio’s 64-bit serial number.

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

Get the radio’s 8-bit product model.

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

Get the radio’s 8-bit product version.

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

swc_connection_t *swc_connection_init(swc_node_t *const node, swc_connection_cfg_t cfg, 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:

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

Returns:

Connection handle.

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

Get a beacon connection configuration.

Parameters:

node – [in] Node handle.
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.

void swc_connection_add_channel(swc_connection_t *const conn, const swc_node_t *const 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_add_fallback_channel(swc_connection_t *const conn, const swc_node_t *const node, swc_channel_cfg_t main_cfg, swc_fallback_channel_cfg_t cfg, uint8_t channel_index, uint8_t fallback_index, swc_error_t *err)

Configure a fallback channel to use for a wireless connection.

Parameters:

conn – [in] Connection handle.
node – [in] Node 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_tx_success_callback(swc_connection_t *const 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).

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.
err – [out] Wireless Core error code.

void swc_connection_set_tx_fail_callback(swc_connection_t *const 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.

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.
err – [out] Wireless Core error code.

void swc_connection_set_tx_dropped_callback(swc_connection_t *const 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.

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.
err – [out] Wireless Core error code.

void swc_connection_set_rx_success_callback(swc_connection_t *const 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.

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.
err – [out] Wireless Core error code.

void swc_connection_set_event_callback(swc_connection_t *const conn, void (*cb)(void *conn), swc_error_t *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.
err – [out] Wireless Core error code.

void swc_connection_set_fec_ratio(swc_connection_t *conn, swc_fec_ratio_t ratio, swc_error_t *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(swc_connection_t *conn, swc_node_t *node, uint8_t auto_reply_payload_size, swc_error_t *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.
node – [in] Node 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(swc_connection_t *conn, swc_error_t *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.

void swc_connection_set_acknowledgement(swc_connection_t *conn, bool enabled, swc_error_t *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(swc_connection_t *conn, swc_node_t *node, bool enabled, swc_error_t *err)

Enable/disable credit flow control on target connection.

Note

This function must be called after swc_connection_set_acknowledgement.

Note

By default, credit flow control is disabled.

Parameters:

conn – [in] Connection handle.
node – [in] Node 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(swc_connection_t *conn, swc_node_t *node, bool enabled, uint32_t try_deadline, uint32_t time_deadline, swc_error_t *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_acknowledgement.

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.
node – [in] Node 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 *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_connection_set_modulation(swc_connection_t *conn, swc_modulation_t modulation, swc_error_t *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(swc_connection_t *conn, bool enabled, swc_error_t *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(swc_connection_t *conn, swc_error_t *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_node_t *node, swc_connection_t *conn, uint8_t priority, swc_error_t *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:

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

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

Enable slots priority on a connection.

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:

node – [in] Node handle.
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, swc_connection_concurrency_cfg_t *cfg, swc_error_t *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(swc_connection_t *conn, swc_connection_fallback_cfg_t *cfg, swc_error_t *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 *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 *err)

Get a buffer from the connection queue.

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

Allocate a buffer from the connection queue with required size.

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.

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

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

Reserved pairing addresses are available.

void swc_reserved_address_lock(void)

Disable pairing specific features.

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 *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 *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 *conn, swc_error_t *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(const swc_node_t *const 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.

swc_status_t swc_get_status(void)

Get the wireless core status.

Returns:: The wireless core status.

void swc_connect(swc_error_t *err)

Start Wireless Core process.

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

Processes connection-related callbacks following a context switch.

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.
In an RTOS environment, the context switch should allow the scheduler to prioritize this function for processing.

Note

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

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.

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.

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.

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.

struct swc_node

#include <swc_api.h>

Wireless node.

Public Members

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_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 do when the energy level sensed is still too high after the last energy sensing try.

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.

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

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.