Project Guidelines

This article outlines best practices for maximizing the capabilities of the SPARK SDK as well as the advantages of adhering to its architecture.

The SDK is designed to be integrated as an external package into user projects. Applications should rely on the public SDK APIs, public headers, CMake targets, and release libraries provided by the SDK package. The SDK release still provides source files for public components, examples, BSP, backend, middleware, modules, and libraries, while selected internal Wireless Core and SPARK Radio PHY implementation files are provided through prebuilt static libraries.

Best Practices

Inclusion as a package: It is encouraged that the SDK be included into projects as an external package, meaning that it can be updated via a drop-in replacement. In the SDK release package, public source files and headers remain available, while selected internal Wireless Core and SPARK Radio PHY implementation files are provided through prebuilt static libraries.

Source File Integrity: Direct modification of SDK source files is discouraged to ensure that updates do not overwrite customizations or introduce compatibility issues. It is suggested to extend the functionality through project-specific code and public SDK APIs.

Public Interface Usage: Applications should use the public SDK headers and documented APIs. Wireless Core and SPARK Radio setup should be performed through swc_api.h. Internal Wireless Core layers, such as link/, protocol_stack/, xlayer/, and SPARK Radio PHY implementation sources are removed from the SDK release package and are provided through prebuilt static libraries. They are therefore not available as application-level source dependencies.

Build System Independence: Create an independent CMakeLists.txt file within the project’s root directory, rather than using the SDK’s top-level CMakeLists.txt. Include and link the necessary SDK components through the SDK CMake targets and public include paths. For SDK release packages, the build system also resolves the required prebuilt static libraries.

Backend Flexibility: The SDK is designed for the injection of custom backend implementations. This ensures the integration of hardware-specific functionalities by adhering to the facades defined in each SDK code component.

Note

A code component—such as a module, library, or application—is a distinct section of source code designed for a specific functionality.

Advantages

Ease of Maintenance: Separating the project from the SDK simplifies updates and ensures that ongoing work is not adversely affected.

Reduced Errors: Maintaining this separation significantly reduces the risk of introducing errors, contributing to a more stable and predictable development environment.

Scalability: This architectural approach allows more efficient project scaling. Project-specific modifications remain isolated, leaving the SDK package unaltered, which facilitates scaling and customization.

Release Compatibility: Relying on public SDK APIs, CMake targets, and provided release libraries keeps applications compatible with the SDK release package, where selected internal Wireless Core and SPARK Radio PHY implementation sources are encapsulated in prebuilt static libraries.

Migrating from the Previous SDK Architecture

Previous SDK versions exposed more Wireless Core and SPARK Radio PHY implementation files directly in the release package. In the new SDK architecture, the public application interface is preserved, but part of the Wireless Core and SPARK Radio PHY implementation is provided through prebuilt static libraries.

Applications should be migrated to the new structure by depending only on the public SDK API, public include directories, and SDK CMake targets.

When migrating an existing application or custom project:

  • Include the Wireless Core public API through swc_api.h.

  • Do not include headers from internal Wireless Core implementation folders such as link/, protocol_stack/, or xlayer/.

  • Do not include or compile SPARK Radio PHY implementation sources directly from the application project.

  • Link against the SDK swc target when using CMake.

  • For non-CMake projects, add the matching Wireless Core prebuilt static library from core/wireless/prebuilt/.

  • For non-CMake projects, add the matching SPARK Radio PHY prebuilt static library from driver/spark_radio/sr_phy/prebuilt/ as a dependency of the Wireless Core library.

  • Keep the BSP, backend, middleware, module, and application sources required by the application.

  • Use compile definitions equivalent to the selected SDK configuration.

  • Use CPU, FPU, ABI, and linker settings compatible with the selected SDK target.

The SPARK Radio setup and access path is now centralized through the Wireless Core public API. Application-level SPARK Radio configuration must be done through swc_api.h. The SPARK Radio PHY library is used internally by the Wireless Core and is not exposed as a public application API.

Note

The swc and sr_phy CMake target names are preserved. Existing CMake applications that link against swc should not need to link directly against the prebuilt archive names. The SDK build system selects the required static libraries according to the active configuration.

Important

Projects that previously compiled internal Wireless Core or SPARK Radio PHY sources directly must be updated. Those implementation files are no longer part of the public SDK release structure and should not be treated as application dependencies.

Compile-time SWC / WPS defines set in the application do not recompile the prebuilt library. Options that used to be flipped by application-level #define are now selected by picking the corresponding library variant in core/wireless/prebuilt/. In particular, WPS_ENABLE_PHY_STATS_PER_BANDS → choose a _stats_band variant.

Prebuilt Library Variants

The SDK release package provides prebuilt static libraries for the Wireless Core and the SPARK Radio PHY. The library selected by the build system depends on the application configuration.

The Wireless Core prebuilt libraries use the following naming rule:

swc_api_<transceiver>_<radio_topology>_<mcu_arch>[_stats_band][_qspi]_lib.a

The SPARK Radio PHY prebuilt libraries use the following naming rule:

sr_phy_<transceiver>_<radio_topology>_<mcu_arch>[_qspi]_lib.a

The variant fields are:

Field

Values

Description

transceiver

sr1000, sr1100

Selected SPARK Radio transceiver family.

radio_topology

single, dual

Single-radio or dual-radio configuration.

mcu_arch

m4, m33

MCU architecture used by the selected board.

stats_band

stats_band

Optional Wireless Core variant with PHY statistics per band enabled. This suffix applies only to swc_api libraries.

qspi

qspi

Optional QSPI variant. This suffix applies to both swc_api and sr_phy libraries when QSPI is supported by the selected configuration.

For example:

swc_api_sr1000_single_m4_lib.a
swc_api_sr1000_dual_m33_stats_band_lib.a
swc_api_sr1100_single_m33_qspi_lib.a
sr_phy_sr1000_single_m4_lib.a
sr_phy_sr1100_single_m33_qspi_lib.a

When using the SDK CMake build system, applications should link against the SDK targets, such as swc. The build system selects the matching prebuilt libraries according to the active configuration.

When porting to a non-CMake IDE, the IDE project must link both the Wireless Core prebuilt library and the matching SPARK Radio PHY prebuilt library for the selected configuration.

Important

QSPI is not supported on sr1000 configurations. QSPI is also not supported with sr1100 dual-radio configurations.

Please reach out to SPARK support if your platform or configuration is not covered by the supported variant combinations listed above.

Debugging Release Package Builds

In the SDK release package, selected Wireless Core and SPARK Radio PHY implementation files are provided through prebuilt static libraries. As a result, source-level debugging into internal Wireless Core layers, and internal SPARK Radio PHY implementation code, is not available in release-package builds.

Application code, custom backend code, BSP code, Audio Core code, middleware, modules, and other source components that remain part of the release package can still be debugged normally at the source level.

When investigating wireless-related issues in a release-package build, collect the available public diagnostics before filing an issue. This may include swc_stats_* output, the result returned by swc_get_status(), relevant HAL/backend logs, application logs, and any linker map or call stack information that helps identify where the issue occurs.

Contact SPARK support for suspected issues inside the Wireless Core or SPARK Radio PHY prebuilt libraries. This includes crashes or faults traced to addresses inside those libraries, unexpected Wireless Core behavior, or PHY-level anomalies that cannot be inspected at the source level from the release package.

Porting to Non-CMake IDEs

The SDK release package is validated using the SDK CMake build system. However, applications can be ported to other embedded IDEs if the IDE project reproduces the same build inputs selected by the SDK configuration.

When using an IDE that does not directly consume the SDK CMake files, the application project must provide an equivalent configuration.

At minimum, the IDE project must:

  • Add the application sources.

  • Add the required BSP, backend, middleware, module, and library sources used by the application.

  • Add the public SDK include directories required by those sources.

  • Add the Wireless Core public headers.

  • Link the Wireless Core prebuilt static library from core/wireless/prebuilt/.

  • Link the SPARK Radio PHY prebuilt static library from driver/spark_radio/sr_phy/prebuilt/.

  • Link all other SDK support libraries required by the application.

  • Use compile definitions equivalent to the selected SDK configuration.

  • Use compiler, CPU, FPU, ABI, and linker options compatible with the selected target.

  • Use a linker script or scatter file equivalent to the memory layout of the selected board.

Application-level SPARK Radio setup and access must be done through swc_api.h. The SPARK Radio PHY library is a dependency of the Wireless Core library and is not exposed as a public application API.

ABI and FPU Compatibility

The prebuilt Wireless Core and SPARK Radio PHY static libraries provided in the SDK release package are generated with the GNU Arm Embedded toolchain using Thumb instructions and hard-float ABI.

Projects linking against these libraries must use compatible Cortex-M architecture, FPU, and floating-point ABI settings. In particular, the final application must use a hard-float ABI configuration. Projects built with soft-float or softfp ABI settings are not compatible with these prebuilt libraries.

The required compatibility settings are:

Target

CPU

Instruction set

FPU

Float ABI

Cortex-M4

cortex-m4

Thumb

fpv4-sp-d16 or equivalent

hard

Cortex-M33

cortex-m33

Thumb

fpv5-sp-d16 or equivalent

hard

The SDK CMake configuration uses equivalent compiler flags when building applications and generating the prebuilt libraries.

For Cortex-M4 targets:

-mcpu=cortex-m4
-mthumb
-mfpu=fpv4-sp-d16
-mfloat-abi=hard

For Cortex-M33 targets:

-mcpu=cortex-m33
-mthumb
-mfpu=fpv5-sp-d16
-mfloat-abi=hard

Note

The SDK CMake files remain the reference implementation for the build configuration. When porting to another IDE, compare the generated CMake build flags, include paths, compile definitions, linked libraries, and linker options against the IDE project configuration.

Important

Static libraries are toolchain- and ABI-specific. Do not link the hard-float prebuilt libraries provided by the SDK release package into a project built with soft-float or softfp floating-point ABI settings.