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

Typedefs

typedef struct wireless_core_hal wireless_core_hal_t

Functions

wps_t *wireless_core_pre_init(wireless_core_hal_t *hal, uint16_t coordinator_address, uint32_t *timeslot_sequence, uint32_t timeslot_sequence_length, uint32_t *channel_sequence, uint32_t channel_sequence_length, uint8_t *memory_pool, uint32_t memory_pool_size, wireless_error_t *err)

Wireless Core pre-initialization.

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

Parameters

  • hal – [in] Board specific functions.

  • coordinator_address – [in] Network coordinator’s 16-bit address.

  • timeslot_sequence – [in] Network schedule as an array of timeslot durations in microseconds.

  • timeslot_sequence_length – [in] Number of timeslots in the timeslot sequence.

  • channel_sequence – [in] RF channels as an array of channel numbers.

  • channel_sequence_length – [in] Number of channels in the channel sequence.

  • memory_pool – [in] Block of RAM for memory allocation.

  • memory_pool_size – [in] Size of the memory pool in bytes.

  • err – [out] Wireless Core error code.

Returns

Wireless Protocol Stack handle.

void wireless_core_post_init(wps_node_t *node)

Wireless Core post-initialization.

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

Parameters

  • node – [in] Node handle.

  • radio – [in] Radio handle.

void wireless_core_connect(void)

Start Wireless Core network activity.

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

void wireless_core_disconnect(void)

Stop Wireless Core network activity.

wps_radio_t *wireless_radio_init(wireless_core_hal_t *hal, wireless_error_t *err)

Initialize a radio.

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

Parameters

  • hal – [in] Board specific functions.

  • err – [out] Wireless Core error code.

Returns

Radio handle.

wps_node_t *wireless_node_init(wps_radio_t *radio, wps_role_t role, sleep_lvl_t sleep_level, uint16_t local_address, wireless_error_t *err)

Initialize the local device.

This sets global device parameters.

Parameters

  • radio – [in] Radio handle.

  • role – [in] Network role.

  • sleep_level – [in] Sleep depth the transceiver will put itself when not active.

  • local_address – [in] Local device’s 16-bit address.

  • err – [out] Wireless Core error code.

Returns

Node handle.

wps_connection_t *wireless_connection_init(wireless_core_hal_t *hal, wps_node_t *node, uint16_t source_address, uint16_t destination_address, uint32_t queue_size, modulation_t modulation, fec_level_t fec, int32_t *timeslot_id, uint32_t timeslot_count, wireless_error_t *err)

Initialize a connection.

A connection abstracts a one-way data flow between 2 devices (e.g., a coordinator and a node). This configures and creates a single connection with default settings. Defaults are:

  • Guaranteed delivery (Retransmissions until an ACK is received).

  • Auto-sync (If data queue is empty, small frames are sent out to keep the synchronization between devices).

Parameters

  • hal – [in] Board specific functions.

  • node – [in] Node handle.

  • source_address – [in] Address of the transmitting node.

  • destination_address – [in] Address of the receiving node.

  • queue_size – [in] Queue size in number of frames.

  • modulation – [in] Frame modulation.

  • fec – [in] Frame forward error correction level.

  • timeslot_id – [in] ID of timeslots used by the connection.

  • timeslot_count – [in] Number of timeslots used by the connection.

  • err – [out] Wireless Core error code.

Returns

Connection handle.

void wireless_connection_add_channels(wps_connection_t *conn, wps_node_t *node, uint8_t number_of_channels, tx_power_settings_t *power_settings, uint8_t rx_pulse_count)

Configure channels to use for a wireless connection.

Parameters

  • conn – [in] Connection handle.

  • node – [in] Node handle.

  • number_of_channels – [in] Number of channels to use, from 1 to 5.

  • power_settings – [in] Output power settings.

  • rx_pulse_count – [in] Pulses configuration of the received frames, from 1 to 3.

void wireless_set_syncing_address(uint16_t syncing_address)

Set network syncing address.

Parameters

syncing_address – [in] The address used to synchronize the network.

void wireless_connection_set_tx_ack_callback(wps_connection_t *conn, void (*cb)(wps_connection_t *conn))

Set the callback function to execute when a ACK is received.

Parameters

  • conn – [in] Connection handle.

  • cb – [in] Callback function.

void wireless_connection_set_tx_nack_callback(wps_connection_t *conn, void (*cb)(wps_connection_t *conn))

Set the callback function to execute when the Wireless Core drops a frame.

Parameters

  • conn – [in] Connection handle.

  • cb – [in] Callback function.

void wireless_connection_set_rx_callback(wps_connection_t *conn, void (*cb)(wps_connection_t *conn))

Set the callback function to execute when the Wireless Core successfully receives a frame.

Parameters

  • conn – [in] Connection handle.

  • cb – [in] Callback function.

void wireless_radio_irq_handler(void)

Function to call in the external interrupt handler servicing the radio IRQ.

void wireless_radio_spi_receive_complete_handler(void)

Function to call in the DMA SPI receive complete IRQ handler.

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

uint32_t wireless_core_get_allocated_bytes(void)

Get the number of bytes allocated in the memory pool.

Returns

Number of bytes allocated in the memory pool.

void wireless_free_memory(void)

Free the memory to reconfigure the wireless core.

struct wireless_core_hal

Public Members

radio_hal_t radio_hal
wps_critical_cfg_t critical
void (*context_switch)(void)
uint64_t (*get_tick_quarter_ms)(void)