Porting Checklist

This checklist is designed to assist in integrating the SPARK SDK with custom boards, ensuring that all necessary components are correctly integrated and nothing is missed.

1. Implement the BSP for a Custom User Board.

2. Implement the Backend of the SPARK Wireless Core Facade.

3. Implement the Backend of the SPARK Audio Core Facade if the target application requires it.

4. Implement the Backend of the SDK Application Facade.

1 - Implement the BSP for a Custom User Board

The BSP must be provided and will be used by the Wireless Core, the Audio Core, and the application itself. It is also responsible for providing a functional and initialized free-running timer to serve as the system tick. Therefore, the specific functions that need to be implemented will depend on the requirements of the following steps.

SDK’s structure guidelines

• Create a new folder, such as bsp/new_bsp/src/ within the SDK, and include all BSP files in it.

• Create the bsp/new_bsp/CMakeLists.txt file to compile the files of the new BSP.

• Include the new BSP in bsp/CMakeLists.txt by adding a new add_subdirectory(new_bsp) instruction.

Tip

To determine which functions are needed, examine the facades of the Wireless and Audio Cores, as well as the application, to identify the specific functions they require.

Attention

Developers should plan their IRQ needs to ensure the most critical tasks receive prompt processing. For more information regarding the IRQ priorities used by SPARK, see IRQ Priority Scheme.

2 - Implement the Backend for the SPARK Wireless Core Facade

To integrate the Wireless Core, the backend for its facade needs to be implemented. This backend relies on the functions of the new BSP.

SDK’s structure guidelines

Facade

• The facade for the SPARK Wireless Core is located in core/wireless/facade/swc_hal_facade.h of the SDK.

Backend

• Create a new folder, such as backend/new_bsp_backend/, where all backends for the new BSP will be implemented.

• Create a new folder, such as backend/new_bsp_backend/wireless_core_backend/, to contain the Wireless Core Backend.

• Implement the wireless_core_backend.c for the new BSP in the newly created folder.

• Create the CMakeLists.txt file next to the backend implementation to link the Wireless Core Backend with the new BSP.

• Include the new backend in backend/CMakeLists.txt by adding a new add_subdirectory(new_bsp_backend) instruction.

SPI - Single Radio

• [ ] swc_hal_radio_1_context_switch

• [ ] swc_hal_set_radio_1_irq_callback

• [ ] swc_hal_set_radio_1_non_blocking_transfer_callback

• [ ] swc_hal_radio_1_disable_irq_it

• [ ] swc_hal_radio_1_enable_irq_it

• [ ] swc_hal_radio_1_disable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_enable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_read_irq_pin

• [ ] swc_hal_radio_1_set_reset_pin

• [ ] swc_hal_radio_1_reset_reset_pin

• [ ] swc_hal_radio_1_end_transfer

• [ ] swc_hal_radio_1_begin_transfer

• [ ] swc_hal_radio_1_transfer_full_duplex_blocking

• [ ] swc_hal_radio_1_transfer_full_duplex_non_blocking

• [ ] swc_hal_radio_1_is_transfer_busy

• [ ] swc_hal_get_tick_free_running_timer

• [ ] swc_hal_get_free_running_timer_frequency_hz

SPI - Dual Radio

Radio 1

• [ ] swc_hal_radio_1_context_switch

• [ ] swc_hal_set_radio_1_irq_callback

• [ ] swc_hal_set_radio_1_non_blocking_transfer_callback

• [ ] swc_hal_radio_1_disable_irq_it

• [ ] swc_hal_radio_1_enable_irq_it

• [ ] swc_hal_radio_1_disable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_enable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_read_irq_pin

• [ ] swc_hal_radio_1_set_reset_pin

• [ ] swc_hal_radio_1_reset_reset_pin

• [ ] swc_hal_radio_1_end_transfer

• [ ] swc_hal_radio_1_begin_transfer

• [ ] swc_hal_radio_1_transfer_full_duplex_blocking

• [ ] swc_hal_radio_1_transfer_full_duplex_non_blocking

• [ ] swc_hal_radio_1_is_transfer_busy

• [ ] swc_hal_get_tick_free_running_timer

• [ ] swc_hal_get_free_running_timer_frequency_hz

Radio 2

• [ ] swc_hal_radio_2_context_switch

• [ ] swc_hal_set_radio_2_irq_callback

• [ ] swc_hal_set_radio_2_non_blocking_transfer_callback

• [ ] swc_hal_radio_2_disable_irq_it

• [ ] swc_hal_radio_2_enable_irq_it

• [ ] swc_hal_radio_2_disable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_2_enable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_2_read_irq_pin

• [ ] swc_hal_radio_2_set_reset_pin

• [ ] swc_hal_radio_2_reset_reset_pin

• [ ] swc_hal_radio_2_end_transfer

• [ ] swc_hal_radio_2_begin_transfer

• [ ] swc_hal_radio_2_transfer_full_duplex_blocking

• [ ] swc_hal_radio_2_transfer_full_duplex_non_blocking

• [ ] swc_hal_radio_2_is_transfer_busy

Dual Radio Timer

• [ ] swc_hal_multi_radio_timer_init

• [ ] swc_hal_set_multi_radio_timer_callback

• [ ] swc_hal_timer_multi_radio_timer_start

• [ ] swc_hal_timer_multi_radio_timer_stop

• [ ] swc_hal_timer_multi_radio_timer_set_period

• [ ] swc_hal_timer_multi_radio_timer_set_max_period

• [ ] swc_hal_get_timer_multi_frequency_hz

QSPI - Single Radio

• [ ] swc_hal_radio_1_context_switch

• [ ] swc_hal_set_radio_1_irq_callback

• [ ] swc_hal_set_radio_1_non_blocking_transfer_callback

• [ ] swc_hal_radio_1_disable_irq_it

• [ ] swc_hal_radio_1_enable_irq_it

• [ ] swc_hal_radio_1_disable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_enable_non_blocking_transfer_irq_it

• [ ] swc_hal_radio_1_read_irq_pin

• [ ] swc_hal_radio_1_set_reset_pin

• [ ] swc_hal_radio_1_reset_reset_pin

• [ ] swc_hal_radio_1_end_transfer

• [ ] swc_hal_radio_1_begin_transfer

• [ ] swc_hal_radio_1_transfer_half_duplex_rx_blocking

• [ ] swc_hal_radio_1_transfer_half_duplex_rx_non_blocking

• [ ] swc_hal_radio_1_transfer_half_duplex_tx_blocking

• [ ] swc_hal_radio_1_transfer_half_duplex_tx_non_blocking

• [ ] swc_hal_radio_1_is_transfer_busy

• [ ] swc_hal_radio_1_set_access_mode_spi

• [ ] swc_hal_radio_1_set_access_mode_qspi

• [ ] swc_hal_get_tick_free_running_timer

• [ ] swc_hal_get_free_running_timer_frequency_hz

Note

The weak implementations of the Wireless Core Facade for radio 2 and QSPI are located in the swc_hal_facade.c file in the core/wireless/facade/ folder.

Refer to the SPARK Wireless Core article for more details on each function.

3 - Implement the Backend for the SPARK Audio Core Facade

Like the Wireless Core, the Audio Core also requires specific functions to manage audio packets and control the codec on the board.

Note

The implementation of this backend is only required for audio applications. Therefore, only audio-related applications will include and utilize this facade.

SDK’s structure guidelines

Facade

• The facade for the SPARK Audio Core is located in core/audio/sac_hal_facade.h of the SDK.

Backend

• Create a new backend/new_bsp_backend/audio_core_backend/ folder to contain the Audio Core Backend.

• Implement the audio_core_backend.c for the new BSP in the newly created folder.

• Create the CMakeLists.txt file next to the backend implementation to link the Audio Core Backend with the new BSP.

Single Radio and Dual Radio

Initialisation

• [ ] sac_facade_audio_endpoint_init

Clock Drift Compensation (CDC) Processing Stage

• [ ] sac_facade_cdc_processing_init

• [ ] sac_facade_cdc_format_stats

Private Codec Functions

Since the interfaces for the producer and consumer endpoints each require three function pointers for the tasks action, start and stop, it is recommended to implement and use the following static private functions in the backend of the Audio Core:

I2S Audio Interface

From audio_core_i2s_backend.c:

The Producer

• [ ] ep_i2s_action_produce

• [ ] ep_i2s_start_produce

• [ ] ep_i2s_stop_produce

The Consumer

• [ ] ep_i2s_action_consume

• [ ] ep_i2s_start_consume

• [ ] ep_i2s_stop_consume

USB Audio Interface

From audio_core_tinyusb_backend.c:

Note

This backend is made specifically for the TinyUSB library. If another USB stack is used, the function names and function calls should be adapted accordingly.

The Producer

• [ ] ep_tusb_action_produce

• [ ] ep_tusb_start

• [ ] ep_tusb_stop

The Consumer

• [ ] ep_tusb_action_consume

• [ ] ep_tusb_start

• [ ] ep_tusb_stop

Refer to the SPARK Audio Core article for more details on each function.

4 - Implementing the Backend for the SDK Application

The application will then use functions provided by the BSP. The final step is to implement the backend for the application’s facade to ensure all necessary functionality is integrated. The Hello World application will be used as an example in this porting checklist, but all SDK applications share the a similar structure.

SDK’s structure guidelines

Common Facade / Backend

To avoid duplicated code, a common facade / backend was implemented to regroup common functions. When creating a new backend, the developer has the choice to either implement everything in the application’s backend or to reuse the common backend and only implement the missing functions in the application’s backend. For this example, we will reuse the common backend.

Facade

• The common facade is located in app/example/common/common_facade.h of the SDK.

• The facade for the Hello World application is located in app/example/hello_world/facade/hello_world_facade.h of the SDK.

Creating a new application Backend

1. Create a new folder, such as backend/new_bsp_backend/common_backend/, to contain the common backend.

2. Implement the common_backend.c for the new BSP in the newly created folder.

3. Create the CMakeLists.txt file next to the backend implementation to link the common backend with the new BSP.

4. Apply the same steps for the Hello World application backend (hello_world_backend/hello_world_backend.c).

Facade Functions to Implement

Common Facade Functions

• [ ] facade_context_switch_trigger

• [ ] facade_set_context_switch_handler

• [ ] facade_board_init

• [ ] facade_tx_conn_status

• [ ] facade_rx_conn_status

• [ ] facade_delay

• [ ] facade_print_string

• [ ] facade_print_error_string

• [ ] facade_notify_enter_pairing

• [ ] facade_notify_not_paired

• [ ] facade_notify_pairing_successful

• [ ] facade_led_all_off

• [ ] facade_get_tick_ms

• [ ] facade_wait_for_interrupt

Hello World Application Facade Functions

• [ ] facade_get_certification_mode

• [ ] facade_set_button_callbacks

• [ ] facade_button_handling

• [ ] facade_packet_generation_set_timer_callback

• [ ] facade_packet_generation_timer_init

• [ ] facade_packet_generation_timer_start

• [ ] facade_packet_generation_timer_stop

Refer to the Hello World section for more details on the application’s behavior.