Architecture

Table of Contents

• Repositories
• Dependencies
• Configuration
• Device modules
• Application startup
• State and concurrency
• Time
• Further reading

Repositories

k-fsw builds the application from four reusable repositories. It selects features, binds hardware, and orders startup.

Repository	Contents
k-fsw	Application startup, target configuration, shell adapters, tools, integration tests, docs, and west.yml
kfsw-platform	Time, reset cause, watchdog, retained reset notes, and storage over Zephyr
kfsw-services	Boot, logging, parameters, persistence, files, commands, events, health, housekeeping, and firmware update
kfsw-comms	libcsp setup, one router, routes, UART/KISS and CAN interfaces
kfsw-modules	Device and subsystem clients, including UHF, button/LED, and temperature examples

Shared code goes in the repository listed above. Shell handlers parse arguments, call a public API and print the result.

Zephyr supplies the kernel, drivers, filesystem integration, shell, and build tools. libcsp supplies the network stack; libparam supplies the remote parameter codec. The manifest pins K-FSW forks; each keeps its upstream licence.

Dependencies

The application can use all four repositories. Services use platform APIs and, when needed, communications. Communications uses libcsp and platform support. Device modules declare the dependencies they need. None of these layers depends on k-fsw/app.

Local parameters and persistence can run with CSP disabled:

CONFIG_KFSW_PARAM=y
CONFIG_KFSW_PARAM_PERSISTENCE=y
CONFIG_KFSW_STORAGE=y
CONFIG_KFSW_PARAM_CSP=n
CONFIG_KFSW_CSP=n

FTP needs CSP and storage. The remote parameter adapter needs CSP and the local parameter core. Kconfig checks these dependencies.

Configuration

Input	Sets
west.yml	Exact dependency revisions
config/targets/<target>.env	Zephyr board and local tool defaults
app/prj.conf, board .conf, profile .conf	Enabled software and defaults
Board devicetree and overlays	Devices, wiring, and flash partitions
app/src/main.c	Initialization order and error handling

Use west manifest --resolve to inspect revisions. See Boards and targets for profiles and Zephyr integration for generated configuration. Changing RTOS requires adapting the Zephyr APIs used by the selected code; moving to another Zephyr board usually changes configuration and device bindings.

Device modules

A module has its own device state, public API and parameter table. The application selects it and passes its definition set to PARAM.

• radio-uhf reports the selected Holybro SiK identity and expected serial configuration. The UART/KISS data path is in kfsw-comms.
• boton_test handles debouncing, the press count, the last press time and the LED state. Table 67 exposes its values. Use kfsw_boton_test_get_status() for a consistent snapshot of all five fields.
• temperature-sensor-example reads a configured sensor and publishes samples and status in table 51.

Hardware is selected in devicetree. A module should not select a board by name or duplicate a router, transport, or service.

Application startup

main.c runs the following stages when their features are enabled:

1. Report the selected UHF identity.
2. Initialize and mount storage.
3. Register parameter tables, restore saved values, and apply boot settings.
4. Initialize device modules and file based operations.
5. Register command definitions.
6. Initialize CSP and interfaces, bind PARAM endpoints, and start the router.
7. Start FTP, direct firmware upload, command, and housekeeping CSP servers.
8. Initialize housekeeping and its collection worker.
9. Initialize the watchdog and start health supervision.
10. Apply shell settings, enable supply monitoring, and set native host time.
11. Emit @BOOT and @READY; enter the application health-report loop.

Persistence needs storage and registered parameter tables. Network services need initialized CSP; FTP and the other worker servers start after the router.

Startup logs errors and carries on with the stages that don't depend on the failed one. @READY means startup has finished, not that every service started; check storage info, csp info or the service status. The shell prompt can appear before @READY.

State and concurrency

State	Kept in and protected by
Storage readiness	Platform storage mutex
Parameter values	Each component's storage; PARAM validation and callbacks
Parameter index	PARAM mutex and bounded static index
Persistence workspace	Persistence mutex and PARAM locking
Button and LED snapshot	Module mutex
CSP routes and interfaces	Communications; initialized once
UART/KISS receive state	One context per interface
FTP client	One static workspace, serialized by a mutex
FTP server	One worker; overlapping requests return busy
Events	Bounded RAM ring protected by a short spinlock

Parameter reads of individual fields do not provide a consistent multi-field snapshot. Use the module's snapshot API when the fields must agree.

After passing a packet to a send call, don't reuse or free it, even if the send fails.

Time

kfsw_time_monotonic_ms() and kfsw_time_monotonic_us() return elapsed time for deadlines and durations. Resolution depends on the selected Zephyr clock source.

The CSP clock API gives wall time from the RTC for timestamps. Setting it doesn't change monotonic deadlines.

Further reading

• Services and storage covers the services, storage and parameter formats.
• CSP and links covers packet flow, interfaces and routes.
• Contributing covers changing a dependency and its manifest pin.
• Project status lists known limits and test results.