- Generated by
1.9.8
|
K-FSW ec10f94
Modular flight software on Zephyr, for small satellites
|
K-FSW is a west workspace. The k-fsw repository has the manifest and the application; west checks out Zephyr and the other four K-FSW repositories next to it.
The commands in this manual assume:
Run the project scripts from the workspace root; they activate .venv themselves. Plain west commands need the environment activated, or .venv/bin/west.
CI uses Ubuntu 24.04 and Python 3.12. Other Linux distributions work if they meet the Zephyr 4.4.0 requirements.
| Tool | Needed for |
|---|---|
| Git, CMake 3.20.5+, Ninja, devicetree compiler, host compiler | Workspace and native build |
Python 3.12+, venv, west, Zephyr Python requirements | Configuration, build and tests |
Zephyr SDK with arm-zephyr-eabi | MCU images |
| Doxygen | HTML manual and API |
| Pandoc and WeasyPrint | PDF manual |
| clang-format and cppcheck | Quality checks |
| Valgrind | Memory checks |
| socat and tmux | Two-node and Robot terminal tests |
| OpenOCD, USB access, serial tools | Flashing, debugging and hardware tests |
Follow the Zephyr getting started guide for the host packages and the SDK. On Ubuntu:
On an AArch64 host, leave out gcc-multilib and g++-multilib. Install a Zephyr SDK that works with Zephyr 4.4.0, either where Zephyr finds it or with ZEPHYR_SDK_INSTALL_DIR set.
In an empty directory, clone the manifest repository:
Create the Python environment and install west:
Initialize west from the local manifest and check out the pinned revisions:
Install Zephyr's Python requirements and export its CMake package:
Initialize the submodules:
The submodules are the Robot terminal runner and the Yamcs configuration. The application build doesn't need them.
When k-fsw/west.yml changes:
west update may say it left a local branch behind, and usually leaves each dependency on a detached HEAD at the manifest commit. That is normal. Commit or stash your work in the dependencies first.
This builds the linux target (native_sim/native/64) into build/linux/. The executable is:
The generic command does the same:
The script prints the target, board, output directory and pristine mode before calling west build. Normal builds are incremental (KFSW_PRISTINE=auto). After changing the board, toolchain or modules, force a full reconfigure:
Don't edit build/linux/zephyr/.config by hand; change the Kconfig, .conf or overlay and rebuild.
The script builds if needed and starts the executable with a persistent flash file. Startup looks like:
The native UART driver also prints a PTY for CSP. Keep using the current terminal for the shell.
After @READY, try:
Node 1 can't ping node 2 until a peer and a serial bridge are running. tests/csp-smoke.sh and the Robot terminal suite set that up.
Press Ctrl-C to stop the node. The flash file is kept, so saved parameters and FTP files are still there on the next run.
To see what a build was configured with:
Other useful files:
version and status print the board the image was built for.
Build both CI targets from clean directories:
Or one at a time:
CI only builds these two. The FRDM and Pico profiles build the same way:
See Boards and targets for what each profile includes.
Connect the NUCLEO through its ST-LINK, then build and flash:
Capture 30 seconds of console output:
Use /dev/serial/by-id/ paths on a bench:
A terminal program needs 115200 8N1. This is the ST-LINK console; the CSP link is on USART3, see CSP and links.
To debug with Zephyr's OpenOCD runner, start the server:
Then, in another terminal:
debug.sh starts GDB through west. A VS Code Cortex-Debug configuration can use the same ELF and OpenOCD server instead.
While working, run the checks that cover your change:
To run the full software sequence:
See Tests for focused checks and bench tests.
Install Doxygen for the HTML and the PDF dependencies in the workspace environment:
Build both:
The output is not committed:
Serve the HTML from the workspace:
The HTML includes the C API; the PDF only has the manual.
Activate the workspace environment:
If .venv has no west, install it with that environment's Python.
From the workspace root:
Don't clone a branch into that directory by hand; west checks out the pinned revision.
Check the Zephyr SDK installation and set, for example:
Then build with KFSW_PRISTINE=always so CMake picks up the new toolchain.
Use a /dev/serial/by-id/ path and export KFSW_SERIAL, or the variable the test asks for. Check the group permissions and that no other terminal has the device open.
Commands depend on Kconfig. Check the target .conf and the generated .config. The FRDM and Pico profiles have no CSP, parameter, storage, UART or FTP commands.
The Linux runner keeps its flash file between runs; tests use their own files. For a clean start, move build/linux/kfsw-storage.bin aside or use the simulator's flash erase options.
Read Architecture and Zephyr integration before adding a service or target, Contributing before changing a dependency, and Shell commands for the shell.
1.9.8