Zaloguj
Wstęp
Od czego zaczyna się każdy kurs programowania w dowolnym języku? Tradycyjnie pierwszym etapem nauki jest napisanie i uruchomienie programu Hello World, wyświetlającego wiadomość powitalną w konsoli. To pozornie łatwe zadanie okazuje się bardzo cennym doświadczeniem z punktu widzenia programistów. Sukces (na tym etapie) oznacza nie tylko poprawne wykonanie instrukcji, ale przede wszystkim udaną konfigurację środowiska i przygotowanie do wdrażania coraz bardziej skomplikowanych zagadnień.
W obszarze systemów wbudowanych (embedded) ta tradycja również obowiązuje, jednak przybiera nieco inną formę. Wyświetlenie fragmentu tekstu zastępowane jest przez miganie diodą LED. Wykonując ten nieskomplikowany program zyskujemy jeszcze więcej informacji, niż w przypadku jego klasycznej wersji. Oprócz sprawdzenia środowiska programistycznego, weryfikujemy również, czy nasz podstawowy „kawałek” sprzętu działa zgodnie z oczekiwaniami. Ponadto testujemy sprawność interfejsu komunikacyjnego, czyli posiadanego programatora/debuggera.
Uruchomienie Hello World z migającą diodą będzie naszym głównym celem w niniejszym artykule, którym rozpoczynamy kurs programowania układów Nordic nRF5340. W kolejnych częściach serii będziemy przybliżać coraz bardziej zaawansowane zagadnienia. Zaprezentujemy między innymi różne aspekty systemu operacyjnego Zephyr, a także postaramy się uruchomić kilka projektów korzystających z komunikacji Bluetooth Low Energy (BLE).
Platforma sprzętowa
Zacznijmy od garści informacji o układzie nRF5340. Producent prezentuje go jako pierwszy na świecie bezprzewodowy SoC (system-on-chip) z dwoma procesorami Arm Cortex-M33. Wśród cech produktu wymieniane są między innymi Bluetooth 5.4, HS-SPI, QSPI, USB oraz NFC. Procesor aplikacyjny ma 1 MB pamięci Flash i 512 KB RAM oraz jest w stanie działać z częstotliwością do 128 MHz.
W naszym kursie będziemy korzystać z zestawu deweloperskiego nRF5340 DK[1]. Ze względu na pełne wsparcie tej płytki, możemy szybko uruchomić na niej wiele gotowych przykładów. Posiadacze własnych PCB z układem nRF5340 – lub innym wspieranym przez Zephyra – mogą napotkać pewne trudności przy pierwszym uruchomieniu. Dlatego w dalszej części pokażemy też, jak dodać wsparcie nowej płytki.
Platforma nRF5340 DK wyposażona została w debugger SEGGER J-Link, co ułatwi nam rozpoczęcie programowania. W zestawie dodatkowych peryferiów znajdują się między innymi: zewnętrzna pamięć Flash, 4 przyciski, port USB, elementy do sterowania zasilaniem oraz GPIO wyprowadzone na kilku złączach. Płytka wyposażona jest również w 4 LED-y – mamy więc wszystko, czego potrzebujemy do uruchamiania pierwszych programów.
Przygotowanie środowiska
Podstawowym składnikiem naszego środowiska programistycznego będzie nRF Connect SDK [2]. Jest to pakiet oprogramowania pozwalającego budować aplikacje do bezprzewodowych urządzeń opartych na układach nRF52, nRF53, nRF70 i nRF91 – zintegrowany z systemem Zephyr i zawierający wiele gotowych przykładów, sterowników oraz bibliotek.
Zgodnie z zaleceniami producenta wybieramy instalację korzystającą z Visual Studio Code wraz z dedykowanym rozszerzeniem. Jedną z zalet tej ścieżki jest jej niezależność od używanego systemu operacyjnego. Istnieje alternatywna opcja budowania środowiska bez edytora, oparta jedynie na linii poleceń, jednak tę drogę rekomendujemy bardziej zaawansowanym użytkownikom [3].
Tworząc zalecane środowisko instalujemy kolejno następujące oprogramowanie:
- Narzędzia nRF Command Line Tools [4]. W zależności od systemu operacyjnego, załączone oprogramowanie SEGGER J-Link może wymagać dodatkowych kroków w czasie instalacji.
- System kontroli wersji Git [5].
- Edytor Visual Studio Code [6].
- Rozszerzenie nRF Connect for VS Code Extension Pack [7]. Całą paczkę znajdziemy wyszukując jej nazwę w widoku Extensions, który wybieramy klikając jego ikonę na pasku aktywności Activity Bar, domyślnie znajdującym się po lewej stronie okna VS Code (rysunek 1).
- Pakiet narzędzi nRF Connect SDK. Wybieramy na pasku aktywności widok naszego świeżo zainstalowanego rozszerzenia. Powinniśmy zobaczyć sekcję WELCOME z przyciskiem Install Toolchain (rysunek 2) – należy kliknąć go, a następnie wskazać wersję, która zostanie zainstalowana. W kursie będziemy korzystali z wersji v2.6.0.
- Baza kodu nRF Connect SDK. Teraz, zamiast przycisku Install Toolchain, w sekcji WELCOME powinniśmy zobaczyć listę kilku opcji (rysunek 3). Jedną z nich będzie Manage SDKs – należy je kliknąć, a następnie wskazać wersję, która zostanie zainstalowana. W kursie będziemy korzystali z wersji v2.6.0.
Jeżeli wszystko przebiegło pomyślnie, przy polu Manage SDKs zobaczymy wersję zainstalowanego oprogramowania (rysunek 4).
W tym momencie mamy wstępnie skonfigurowane środowisko i możemy przejść do tworzenia nowego projektu.
Pierwszy program
Zaczynamy od utworzenia nowej aplikacji – klikamy Create a new application w sekcji WELCOME. Wyświetlona zostanie lista, z której wybieramy Create a blank application (rysunek 5).
Następnie podajemy ścieżkę do aplikacji wraz z jej nazwą (rysunek 6). W naszym przypadku będzie to hello_world.
Projekt został utworzony, a w widoku Explorer powinniśmy zobaczyć kilka nowych plików. Jednym z nich jest .gitignore (rysunek 7), co wskazuje, że aplikacja utworzona została jako repozytorium Git.
Ponieważ system budowania oparty został o CMake [8], wśród plików automatycznie dodanych do projektu natrafimy na CMakeLists.txt, którego zawartość prezentuje listing 1.
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(hello_world)
target_sources(app PRIVATE src/main.c)
Listing 1. Plik CMakeLists.txt
Warto zwrócić uwagę na fakt, że podczas załączania pakietu Zephyr (find_package), tworzy się również target o nazwie app, do którego dodawany jest następnie nasz plik źródłowy (target_sources).
W repozytorium dostępny jest również plik prj.conf, stanowiący fragment ustawień systemu Kconfig. Póki co pozostanie on pusty, gdyż nie będziemy zmieniać domyślnych opcji, jednak do tematu konfiguracji jeszcze wrócimy. W pliku main.c, znajdującym się w folderze src, znajdziemy kod widoczny na listingu 2.
int main(void)
{
return 0;
}
Listing 2. Plik main.c
Nie wykonuje on wprawdzie żadnego szczególnego zadania, ale to nie przeszkodzi nam w jego zbudowaniu. W tym celu powinniśmy utworzyć nową konfigurację budowania aplikacji. W widoku nRF Connect, w sekcji APPLICATIONS, pod nazwą naszej świeżo utworzonej aplikacji klikamy Add build configuration (rysunek 8).
Pojawi się okno z wyborem różnych ustawień dotyczących budowania projektu (rysunek 9). W polu Board wybieramy konfigurację naszej płytki deweloperskiej, czyli nrf5340dk_nrf5340_cpuapp. Pozostałe opcje pozostawiamy domyślne, co oznacza między innymi, że pliki wynikowe trafią do folderu build.
Klikamy przycisk Build Configuration – działanie takie, oprócz wygenerowania konfiguracji, spowoduje również zbudowanie aplikacji.
Pod nazwą aplikacji pojawiła się nasza nowa konfiguracja, a pod nią dwie nowe sekcje (rysunek 10).
Pierwsza z nich – czyli HELLO_WORLD – zawiera odnośniki do źródeł oraz wyników budowania. Z kolei sekcja ACTIONS pozwoli nam między innymi wgrać program na płytkę, jednak zanim przejdziemy do tego etapu, wprowadzimy zmiany potrzebne do prawidłowej pracy naszego Hello World.
Miganie diodą
Podmieniamy zawartość pliku main.c na kod odpowiedzialny za miganie diodą, widoczny na listingu 3.
#include <zephyr/drivers/gpio.h>
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_NODELABEL(led0), gpios);
int main(void)
{
if (!gpio_is_ready_dt(&led))
{
return 0;
}
gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
while (1)
{
gpio_pin_toggle_dt(&led);
k_msleep(1000);
}
return 0;
}
Listing 3. Implementacja migania diodą w pliku main.c
Aby w pełni opisać powyższy kod, musielibyśmy teraz przybliżyć, czym są struktury devicetree. To temat, który zasługuje na głębszą analizę i zajmiemy się nim nieco później. W tej chwili ważne są tylko dwie informacje dotyczące obiektu gpio_dt_spec led:
- zawiera on wszystkie dane potrzebne do sterowania naszym LED-em, czyli: port, pin, oraz dodatkowe flagi, które m.in. definiują stan aktywny,
- tworzony jest na podstawie node’a led0 w devicetree i to tam są konfigurowane jego parametry.
Pozostały kod okazuje się już dość jednoznaczny. Na samym początku funkcji main sprawdzamy za pomocą gpio_is_ready_dt, czy port skojarzony z naszym pinem został odpowiednio zainicjalizowany. Następnie mamy funkcję gpio_pin_configure_dt do konfiguracji pinu. Ustawiamy pin jako wyjście, które początkowo będzie znajdować się w stanie aktywnym. Pętla while odpowiedzialna jest za cykliczne zmienianie stanu diody co jedną sekundę (użyta została tu funkcja gpio_pin_toggle_dt , która zmienia stan pinu na przeciwny).
Pora zbudować nasz nowy kod poprzez kliknięcie Build w sekcji ACTIONS. Zwróć uwagę na zakładkę TERMINAL w dolnej części okna VS Code, która pozwala na śledzenie procesu budowania (rysunek 11). Widok z podsumowaniem zajętości pamięci przez aplikację najczęściej oznacza sukces.
Widzimy w terminalu, że proces budowania polegał na wykonaniu w linii poleceń komendy west build. Okazuje się, że wiele elementów graficznego interfesju użytkownika tak naprawdę jedynie uruchamia narzędzie west z odpowiednimi argumentami, których szczegółowy opis znajdziemy w dokumentacji [9].
Warto zwrócić uwagę na jeszcze jedną cechę interfejsu graficznego. Jeśli przemieszczamy kursor nad daną opcją, często pojawiają się obok niej specjalne ikony, dzięki którym można wykonać szereg dodatkowych operacji. W przypadku opcji Build szczególnie interesująca okazuje się zapętlona strzałka (rysunek 12) – po kliknięciu wykona ona Pristine Build, czyli całkowite przebudowanie wszystkich plików projektu. Zalecamy używanie tej opcji, gdy dokonujesz jakichkolwiek modyfikacji związanych z konfiguracją aplikacji.
Wgrywanie aplikacji
Pomyślne zbudowanie projektu oznacza, że w folderze build/zephyr pojawi się zestaw plików wynikowych, a wśród nich zephyr.hex, który będziemy wgrywać na płytkę. Najpierw podłączamy nRF5340 DK do komputera przez złącze Micro-USB znajdujące się na krótszej krawędzi płytki. Następnie otwieramy sekcję CONNECTED DEVICES, widniejącą poniżej ACTIONS (rysunek 13). Powinniśmy zobaczyć numer seryjny wbudowanego w płytkę J-Linka. Jeśli nie pojawił się od razu po podłączeniu, należy kliknąć zapętloną strzałkę po prawej stronie sekcji CONNECTED DEVICES.
Jeśli upewniliśmy się, że nRF Connect wykrywa naszą płytkę, pozostało jedynie kliknąć opcję Flash w sekcji ACTIONS. Podobnie jak w przypadku procesu budowania, również proces wgrywania możemy śledzić w terminalu (rysunek 14).
W tym momencie dioda podpisana na płytce jako LED1 powinna migać (na PCB diody numerowane są od 1 do 4, natomiast w kodzie indeksowane są od 0). Jeżeli chcielibyśmy wybrać inny LED, wystarczy zmienić identyfikator led0 w main.c – w linii z definicją struktury gpio_dt_spec – na led1, led2 lub led3. To, w jaki sposób odbywa się powiązanie naszego obiektu LED z konkretnym pinem, wyjaśni się, kiedy utworzymy swoją własną konfigurację płytki.
Definicja nowej płytki
Załóżmy, że realizujemy własny projekt urządzenia wyposażonego w SoC nRF5340, w którym do każdego z czterech wybranych pinów mamy podpięty LED. Jeśli chcemy, by Zephyr był w stanie zbudować aplikację na tego typu płytkę, musimy w ściśle określony sposób go o tym poinformować [10].
W artykule co prawda wciąż korzystamy z naszego zestawu nRF5340 DK, ale bez przeszkód możemy symulować sytuację, w której nRF Connect SDK nie wie nic o tym zestawie.
Do realizacji naszych celów po raz kolejny użyjemy interfejsu graficznego. W sekcji WELCOME klikamy Create a new board. Pojawia się okno konfiguracji (rysunek 15), w którym zaczynamy od podania nazwy nowej płytki – w naszym przypadku będzie to LED PCB.
W kolejnym kroku podajemy identyfikator płytki (rysunek 16). Skorzystamy z automatycznie wygenerowanej nazwy led_pcb.
Następnie wyszukujemy nRF5340 i otrzymujemy listę trzech opcji do wyboru (rysunek 17). Wyjaśnijmy, jakie są między nimi różnice? Po pierwsze: określenia Secure i Non-secure dotyczą podziału zasobów na część bardziej i mniej zabezpieczoną. Tego tematu w tym momencie nie będziemy rozwijać, jednak zachęcamy do zapoznania się z dokumentacją [11].
Po drugie: nazwy cpuapp i cpunet oznaczają procesory application oraz network, z których składa się nRF5340. W tym miejscu konfiguracji mamy możliwość wyboru, na który z nich chcemy pisać kod. Do obszernego tematu tworzenia aplikacji na oba procesory wrócimy jeszcze w kolejnych artykułach.
Na razie zostajemy przy opcji nrf5340_cpuapp QKAA (Secure).
W kolejnym kroku wybieramy projekt, do którego dołączona zostanie nowa specyfikacja płytki (rysunek 18). Nasz hello_world powinien być tu widoczny od razu, możemy zatem przejść dalej.
Na koniec wpisujemy nazwę firmy, która wyprodukowała naszą płytkę (rysunek 19). Możemy wpisać tutaj dowolny ciąg znaków.
Efektem końcowym będzie zestaw plików utworzony w nowym katalogu boards (rysunek 20).
Znajdziemy w nim pliki obligatoryjne dla każdej płytki. Dotyczy to również wcześniej wybieranej nrf5340dk_nrf5340_cpuapp – podobny zestaw przeznaczony do niej znajdziemy w samym SDK, widocznym w systemie budowania.
Warto w pierwszej kolejności zajrzeć do led_pcb.dts. Skupimy się na początkowej części, pokazanej na listingu 4.
// SPDX-License-Identifier: Apache-2.0
/dts-v1/;
#include <nordic/nrf5340_cpuapp_qkaa.dtsi>
/{
model = "LED PCB";
compatible = "goodbyte,led-pcb";
chosen {
zephyr,sram = &sram0;
zephyr,flash = &flash0;
zephyr,code-partition = &slot0_partition;
};
};
Listing 4. Początek pliku led_pcb.dts
Plik rozpoczyna się od określenia wersji składni, w której został napisany (/dts-v1/;). Następnie załączamy plik nordic/nrf5340_cpuapp_qkaa.dtsi opisujący nasz procesor. W devicetree pliki z rozszerzeniem dtsi zawierają definicje dostępnego sprzętu. Warto zapamiętać, że domyślnie każdy node jest wyłączony, więc wymaga odblokowania, by można było go używać.
W linii 7 zaczyna się definicja głównego node’a. Właściwość model zawiera opis płytki, natomiast klucz compatible jest specjalną właściwością, decydującą o tym, czym jest dany node. Nie będziemy tutaj wchodzić w szczegóły binding’ów, niemniej chętnych Czytelników odsyłamy do lektury dokumentacji [12].
Przejdźmy teraz do plików Kconfig:
- Kconfig.board – daje możliwość zdefiniowania własnych ustawień naszej płytki.
- Kconfig.defconfig – służy do ustawiania nowych wartości różnych opcji konfiguracyjnych płytki.
- led_pcb_defconfig – zawiera domyślną konfiguracje Kconfig danej płytki. Opcje tutaj wybrane mogą ulec nadpisaniu w projektowym pliku prj.conf – zwyczajowo umieszcza się tutaj konfiguracje zawsze prawdziwe dla naszej płytki.
Całość specyfikacji płytki dopełnia plik board.cmake – znajdują się w nim ustawienia flashowania i debugowania. Nie musimy tutaj nic modyfikować, gdyż domyślna konfiguracja uwzględnia używane przez nas narzędzia nrfjprog oraz J-Link.
Dodajmy teraz konfigurację budowania dla naszej nowej płytki. Robimy to analogicznie jak wcześniej, przy czym tym razem w polu Board wybieramy led_pcb (rysunek 21).
Od teraz w sekcji APPLICATIONS mamy do wyboru dwie konfiguracje budowania naszej aplikacji (rysunek 22). Nowa domyślna nazwa folderu z plikami wynikowymi to build_1.
Niestety, tym razem próba zbudowania projektu nie ma szans powodzenia. W pliku main.c używamy wyjścia LED, które w kontekście naszej nowej płytki jeszcze w ogóle nie istnieje. Z tego względu musimy wykonać kilka modyfikacji. Zaczniemy od pliku led_pcb.dts, do którego dopisujemy na końcu kod widoczny na listingu 5.
leds
{
compatible = "gpio-leds";
led0: led_0 {
gpios = <&gpio0 28 GPIO_ACTIVE_LOW>;
label = "Green LED 0";
};
led1: led_1 {
gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
label = "Green LED 1";
};
led2: led_2 {
gpios = <&gpio0 30 GPIO_ACTIVE_LOW>;
label = "Green LED 2";
};
led3: led_3 {
gpios = <&gpio0 31 GPIO_ACTIVE_LOW>;
label = "Green LED 3";
};
};
};
&gpiote {
status = "okay";
};
&gpio0 {
status = "okay";
};
Listing 5. Kod dodawany do pliku led_pcb.dts
Każdy node diody jest „kompatybilny” z ogólnym urządzeniem gpio-leds. To oznacza, że może zawierać takie pola, jak gpios oraz label. Tylko pierwsze z nich jest wymagane i zawiera informacje o pinie skojarzonym z daną diodą. Wpisana konfiguracja wynika bezpośrednio ze schematu połączeń na naszej płytce (rysunek 23). Przykładowo, możemy odczytać, że LED2 (indeks 1) zaświeci się, kiedy na P0.29 (port 0, pin 29) pojawi się stan niski.
W tym momencie warto zaznaczyć, że wpisane w identyfikatory led_0, led_1, led_2 i led_3 to nazwy nowego node’a (node name). Z kolei led1 czy led3 to etykiety node’a (node label), za pomocą których możemy się do niego odnosić w kodzie C/C++ lub w samym devicetree.
Kolejnym krokiem jest dodanie do pliku prj.conf linii CONFIG_GPIO=y. Dzięki temu moduł GPIO zostaje dołączony do kompilacji. Jednak dlaczego wcześniej dla płytki nrf5340dk_nrf5340_cpuapp (build) tej opcji nie dodawaliśmy? Okazuje się, że Nordic – w domyślnej konfiguracji swojej płytki nRF5340 DK – już tę opcję włączył, a możemy się o tym przekonać zaglądając do pliku nrf5340dk_nrf5340_cpuapp_defconfig (znajdziemy go w SDK).
Poza głównym nodem/włączamy dodatkowe peryferia gpio0 oraz gpiote, zmieniając ich status na okay. Skąd wzięliśmy informacje o tym, co należy odblokować? Wiemy, że nasza dioda korzysta z gpio0, a w nrf5340_cpuapp.dtsi, który jest pośrednio załączany do naszego pliku .dts, znajduje się node pokazany na listingu 6.
{
compatible = "nordic,nrf-gpio";
gpio-controller;
reg = <0x50000000 0x1000>;
#gpio-cells = <2>;
status = "disabled";
port = <0>;
gpiote-instance = <&gpiote>;
};
Listing 6. Fragment pliku nrf5340_cpuapp.dtsi definiujący node gpio0
Możemy zauważyć, że status ma domyślną wartość disabled, więc – bez naszej modyfikacji w pliku led_pcb.dts – peryferium nie zostałoby poprawnie zainicjalizowane. To samo dotyczy node’a gpiote skojarzonego z gpio0 .
Mając tak skonfigurowaną płytkę, możemy zbudować nasz projekt i ponownie wykonać operację wgrywania kodu maszynowego do pamięci Flash. Zwróć uwagę, że wcześniej budowaliśmy ten sam kod źródłowy na inną płytkę niż teraz, a plik main.c od tego czasu w ogóle się nie zmienił. To się nazywa przenośność!
Jeżeli napotkasz problemy na etapie konfiguracji, poniżej znajdziesz kilka ścieżek, do których warto zajrzeć.
- build_1/zephyr/zephyr.dts – finalny opis naszego sprzętu, biorący pod uwagę wszystko, z czego skorzystaliśmy oraz co nadpisaliśmy z domyślnych ustawień w plikach .dtsi,
- build_1/zephyr/include/generated/devicetree_generate.h – nagłówek, który powstaje na podstawie pliku zephyr.dts i który w naszym przypadku jest pośrednio dołączany do main.c przez zephyr/drivers/gpio.h,
- build_1/zephyr/.config – wszystkie dostępne opcje Kconfig wraz z informacją, czy zostały ustawione oraz jakie są ich ewentualne wartości.
Podsumowanie
W artykule pokazaliśmy, jak w kilku krokach można rozpocząć przygodę z programowaniem układu nRF5340. Opisaliśmy, jak to zrobić mając zarówno oficjalnie wspieraną płytkę, jak i sprzęt w całości zaprojektowany oraz wykonany przez nas. Jak nietrudno zauważyć, więcej czasu na początku projektu spędzamy w części konfiguracyjnej, niż pisząc kod. Wiedza o tym, gdzie i jakie opcje należy wybrać w danym projekcie, jest kluczowa do skorzystania z pełnego potencjału systemu Zephyr.
Krzysztof Kierys
Paweł Jachimowski
Odnośniki w tekście
1. https://www.nordicsemi.com/Products/Development-hardware/nRF5340-DK
2. https://www.nordicsemi.com/Products/Development-software/nRF-Connect-SDK/GetStarted#infotabs
3. https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/installation/install_ncs.html
4. https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools/Download?lang=en#infotabs
5. https://git-scm.com/downloads
6. https://code.visualstudio.com/download
7. https://marketplace.visualstudio.com/items?itemName=nordic-semiconductor.nrf-connect-extension-pack
8. https://cmake.org/about/
9. https://docs.zephyrproject.org/latest/develop/west/index.html
10. https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html
11. https://docs.zephyrproject.org/latest/services/tfm/overview.html
12. https://docs.zephyrproject.org/latest/build/dts/bindings.html
13. https://infocenter.nordicsemi.com/index.jsp? topic=%2Fug_nrf52832_dk%2FUG%2Fdk%2Fhw_buttons_leds.html
