From 907ef04f4c5a6f38f4299fff81662e21a3eaed55 Mon Sep 17 00:00:00 2001 From: puddly <32534428+puddly@users.noreply.github.com> Date: Mon, 6 May 2024 17:18:25 -0400 Subject: [PATCH] Update documentation to reflect current firmware builder (#59) * Update documentation * Clarify Yellow radio and project scope --- README.md | 146 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 81 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index da52e27b..45074332 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,91 @@ # Silicon Labs firmware builder repository - -This repository contains Dockerfiles and GitHub actions which build Silicon Labs -firmware for Home Assistant Yellow and SkyConnect. - -It uses the Silicon Labs Gecko SDK and proprietary Silicon Labs tools such as -the Silicon Labs Configurator (slc) and the Simplicity Commander standalone -utility. - -## Building locally - -To build a firmware locally the build container can be reused. Simply start the -container local with this repository bind-mounted as /build, e.g. - -```sh -docker run --rm -it \ - --user builder \ - -v $(pwd):/build -v ~/.gitconfig:/home/builder/.gitconfig \ - ghcr.io/nabucasa/silabs-firmware-builder:4.2.3 +This repository contains tools for building firmwares for the Home Assistant Connect +ZBT-1/SkyConnect and the Home Assistant Yellow's IEEE 802.15.4 radio. The firmware +manifests are entirely generic, however, and are intended to be written easily for any +Silicon Labs EFR32 device. + +It uses the Silicon Labs Gecko SDK and proprietary Silicon Labs tools such as the +Silicon Labs Configurator (slc) and the Simplicity Commander standalone utility. + +## Background +The projects contained within this repository are configured for the BRD4001A dev kit +with a BRD4179B (EFR32MG21) module. This allows base projects to be debugged using +the Simplicity Studio IDE. These base projects are then retargeted for other boards +using manifest files. For example, the [`skyconnect_ncp-uart-hw.yaml`](https://github.com/NabuCasa/silabs-firmware-builder/blob/main/manifests/skyconnect_ncp-uart-hw.yaml) +manifest file retargets the base firmware to the SkyConnect/Connect ZBT-1. + +## Setting up Simplicity Studio (for development) +If you are going to be developing using Simplicity Studio, note that each project can +potentially use a different Gecko SDK release. It is recommended to forego the typical +Simplicity Studio SDK management workflow and manually manage SDKs: + +1. Clone a specific version of the Gecko SDK: + ```bash + # For macOS + mkdir ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2 + cd ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2 + + git clone -b v4.4.2 https://github.com/SiliconLabs/gecko_sdk . + git checkout -b branch_tag + ``` + +2. Open preferences, navigate to **Simplicity Studio > SDKs**, click the `Add SDK...` button, and browse to the above location. +3. Once the SDK is added, select its entry and click `Add Extension...`. +4. In this repo, add the extensions under `gecko_sdk_extensions`. + +Repeat this process for every necessary SDK version. + +Base projects can now be built normally. + +> [!TIP] +> If you have build issues after switching commits, make sure to delete any +> `gecko_sdk_*` folders from the Simplicity working tree. + +## Building with a firmware manifest (for building device firmware) +Command line building requires: +- [`slc-cli`](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-tools-slc-cli/02-installation) +- [Simplicity Commander](https://www.silabs.com/developers/mcu-programming-options) (`commander`) +- The exact Gecko SDK version required by the project. Note that this doesn't have to be a Git working tree, you can use [a GitHub release](https://github.com/SiliconLabs/gecko_sdk/releases). +- A compatible toolchain. Take a look at the `Dockerfile` for the necessary toolchains. + +> [!TIP] +> If you have set up Simplicity Studio on macOS, everything will be automatically +> detected with the exception of `slc-cli`. This is the only tool you need to download. + +`slc-cli` maintains its own SDK and extension trust store so you first must trust all +SDK extensions for every SDK you plan to use: + +```bash +slc signature trust --sdk ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2 +slc signature trust --sdk ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2 --extension-path ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2/extension/nc_efr32_watchdog_extension ``` -To generate a project, use `slc generate`. To replicate/debug build issues in -an existing GitHub action, it is often helpful to just copy the command from -the "Generate Firmware Project" step. E.g. to build the Multiprotocol firmware -for Yellow: - -```sh - slc generate \ - --with="MGM210PA32JIA,simple_led:board_activity" \ - --project-file="/gecko_sdk/protocol/openthread/sample-apps/ot-ncp/rcp-uart-802154.slcp" \ - --export-destination=rcp-uart-802154-yellow \ - --copy-proj-sources --new-project --force \ - --configuration="" -``` +`tools/build_project.py` is the main entry point for building firmwares. Provide paths +to potential SDKs and toolchains with the `--sdk` and `--toolchain` flags. The build +tool will automatically determine which SDK and toolchain to use. -To build the EmberZNet firmware for SkyConnect +> [!TIP] +> If you have set up Simplicity Studio on macOS, the default toolchain and SDK paths are +> automatically found so these flags can be omitted. -```sh - slc generate \ - --with="EFR32MG21A020F512IM32" \ - --project-file="/gecko_sdk/protocol/zigbee/app/ncp/sample-app/ncp-uart-hw/ncp-uart-hw.slcp" \ - --export-destination=ncp-uart-hw-skyconnect \ - --copy-proj-sources --new-project --force \ - --configuration="SL_IOSTREAM_USART_VCOM_RX_BUFFER_SIZE:64,EMBER_APS_UNICAST_MESSAGE_COUNT:20,EMBER_NEIGHBOR_TABLE_SIZE:26,EMBER_SOURCE_ROUTE_TABLE_SIZE:200," -``` - -Apply patches to the generated firmware (Note: some firmwares also need patches -to be applied to the SDK, see GitHub Action files): - -```sh -cd ncp-uart-hw-skyconnect -for patchfile in ../EmberZNet/SkyConnect/*.patch; do patch -p1 < $patchfile; done -``` - -Then build it using commands from the "Build Firmware" step: - -```sh -make -f ncp-uart-hw.Makefile release -``` +```bash +pip install ruamel.yaml # Only dependency -### Update patches +python tools/build_project.py \ + # The following SDK and toolchain flags can be omitted on macOS + --sdk ~/SimplicityStudio/SDKs/gecko_sdk_4.4.0 \ + --sdk ~/SimplicityStudio/SDKs/gecko_sdk_4.4.2 \ + --toolchain '/Applications/Simplicity Studio.app/Contents/Eclipse/developer/toolchains/gnu_arm/10.3_2021.10' \ + --toolchain '/Applications/Simplicity Studio.app/Contents/Eclipse/developer/toolchains/gnu_arm/12.2.rel1_2023.7' \ -If you want to change patches, instead of applying them using patch, it is -easier to initialize a temporary git repo and apply them using git. Then ammend -commits or add new commits ontop, and regenerate the patches: + --manifest manifests/skyconnect_ncp-uart-hw.yaml \ + --build-dir build \ + --output-dir output \ -```sh -git init . -git add . -git commit -m "initial commit" -git am ../EmberZNet/SkyConnect/*.patch - -git format-patch -N --output-directory=../EmberZNet/SkyConnect/ HEAD~2 + # Generate `.gbl`, `.out`, and `.hex` firmwares + --output gbl \ + --output out \ + --output hex ``` +Once the build is complete, the firmwares will be in the `output` directory.