You need to install GIT, Python 3, CMake, GNU Embedded Toolchain for ARM, Picotool (optional) and Doxygen (optional). For the development itself we recommend using VS Code, but you can use any editor/environment you like.
For beginners, we recommend the Automated Install; for advanced users who regularly develop for ARM, we recommend the Manual Install.
The starting point for both installation methods.
git clone https://github.com/bastl-instruments/kastle2.git
The easiest way to get started is with Nix — an isolated development environment that automatically installs all the requirements. It runs natively on macOS/Linux and won't interfere with your existing system tools. Thanks very much to @euphemism for creating the Nix‑based development setup.
Make sure Nix is installed (check with nix --version). If it's not, install it from the official website.
Enable Flakes by adding this line to ~/.config/nix/nix.conf:
experimental-features = nix-command flakes
Go into the kastle2 folder and start the Nix development environment. The first setup may take a few minutes, subsequent shells are fast.
nix develop .#
This shell automatically runs ./configure.sh on first use (when the build folder doesn't exist).
Go into code/build and run make to build all firmwares or make <app-name> to build a specific one.
Launch your editor from within the Nix shell so it inherits the environment variables.
cd code/build
make wave-bard
make wave-bard-with-samples
code
You can find the compiled firmwares inside code/build/output.
If you successfully installed the Kastle 2 Development shell, jump to the Debugging section to continue.
If you have already ARM Toolchain installed make sure it's version 14.2.1 20241119 or above by running:
arm-none-eabi-gcc --version
In case you have more than one ARM Toolchains installed (eg. you are using Daisy Toolchain), you can run this to get the specific one for the Raspberry Pi Pico platform:
$PICO_TOOLCHAIN_PATH/arm-none-eabi-gcc --version
Make sure you have Homebrew installed. Then run these.
brew install cmake git python picotool doxygen
brew install --cask gcc-arm-embedded
If gcc-arm-embedded install through brew fails, download the ARM Toolchain manually from the official ARM website. Select the arm-none-eabi and your platform (macOS x86_64, macOS Apple sillicon). Download the archive, extract it eg to /Users/username/arm_kastle. Then add this into ~/.zshrc:
export PICO_TOOLCHAIN_PATH=/Users/username/arm_kastle/bin
sudo apt update
sudo apt install git cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential libstdc++-arm-none-eabi-newlib doxygen
If you want to upload the code automatically using USB, download and build picotool using this tutorial: https://github.com/raspberrypi/picotool You can find a detailed tutorial how to build it in Getting started with Pico document, around page 25.
After installing the packages, make sure that the ARM compiler is the required version or later, as described in the "Manual Install" section above.
If you are running Ubuntu, you need to be on the version 25.04 (Plucky Puffin) or later to get the correct one. If upgrading a WSL Ubuntu install, it may be necessary to remove the snapd package before upgrading.
sudo pacman -Syu
sudo pacman -S git cmake arm-none-eabi-gcc arm-none-eabi-newlib doxygen
The easiest way is to follow the Raspberry Pi Pico-series guide.
This applies to MacOS and Linux installations.
Kastle 2 is compatible both with the original Pico SDK 1.x and new 2.x. We strongly recommend to use the latest 2.x release to make sure everything works. Navigate to a folder you want the SDK to be downloaded and clone the repository:
git clone https://github.com/raspberrypi/pico-sdk.git
Inside this folder, run this command in order to download additional libraries.
git submodule update --init
In your environment set PICO_SDK_PATH to the SDK location.
Add this line into ~/.bashrc. Tilde symbol ~ is your user's home directory. If the file doesn't exist, create it.
export PICO_SDK_PATH=/path/to/your/pico-sdk
Add this line into ~/.zshrc. Tilde symbol ~ is your user's home directory. If the file doesn't exist, create it.
export PICO_SDK_PATH=/path/to/your/pico-sdk
If you used VS Code for editing .zshrc or .bashrc file, restart it for the export to make effect.
Open the whole project folder (not just code subfolder) and run task called configure. Or use CMake extension to configure it. Then you can run build_and_upload_usb to upload the code into Kastle 2 via USB. If the USB upload doesn't work, turn off the Kastle 2 and hold SHIFT and power it on to enter the bootloader mode. Or use build_and_upload_jlink for J-Link upload. See section below for the available debuggers.
./configure.sh
mkdir code/build
cd code/build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
And then copy code/build/output/kastle2-xxxx.uf2 manually onto the Kastle 2 mounted as USB drive.
If you want to compile just a single project, just type in make template or make wave-bard.
At Bastl we use the -O3 optimization flag even for Debug builds, because we can't run the existing code without optimizations. The builds also include -g for debug symbols. Since our development and testing time is limited, we usually don't bother recompiling the code using the Release flag, because we would need to retest every feature and sound signature all over again to make sure everything runs correctly.
Real-time code stepping and debugging is possible while the code is being executed. For that, Kastle 2 needs to be connected via SWD interface (SWDIO, SWCLK...) on the bottom side of the PCB. For each debug pin the PCB contains two locations to choose from (only one needs to be connected). This method also lets you upload firmware faster than UF2 method using USB.
We have predefined profiles for the Raspberry Pi Debug Probe and Segger J-Link. In case you have an experience with other probes, feel free to write us with your experience and we can add it to the list.
If you don't have any probe and you have a Raspberry Pi Pico laying around, you can make your own probe using it. You can follow eg. this tutorial.
Solder cable to the pins depending on your platform.
Warning
Soldering the connector and other board modification void the official warranty and you do it at your own risk.
Raspberry Pi Debug Probe requires: SWDIO, SWCLK, GND.
Segger J-Link Debug Probe requires: SWDIO, SWCLK, GND, VDD, RESET.
Or 3D print the provided Kastle 2 enclosure, so you can access the cable easily without drilling the original enclosure:
For wiring the Citadel follow the instructions at the Citadel README file.
Make sure you have Cortex Debug extension installed. Go to Run and Debug section and select J-Link Debug or Pico Probe according to which of debug probes you have. Starting the debug process automatically builds the code and uploads it to the Kastle 2.
The generated documentation is hosted here: Kastle 2 Code Documentation
For building your own, run VS Code command make_docs or cd manually into code folder and run doxygen command.
The docs are located in code/docs/output and are in gitignore to keep the repository clean.