→ Check out the preceding part of this tutorial series before starting on this: nRF Connect SDK Tutorial series - Part 0
This part of the NCS Tutorial series will be short and concise and will get you up and running with NCS and your board as quickly as possible. The first section will demonstrate how to build and run a “hello world” sample on your board, and the second section will provide you with the most vital information for the beginning phase for your particular board.
As mentioned in Part 0, you should choose a board and set <board> and <board_variant> accordingly. This applies to this part as well, and when you see one of these variables use your chosen value instead.
Contents
In this setup, the sample will be put outside the nrf folder. This is a cleaner and more modular approach than building it directly in the nrf folder since you keep the project detached from the nRF Connect SDK.
It should look like this:
cmake_minimum_required(VERSION 3.13.1) include($ENV{ZEPHYR_BASE}/../nrf/cmake/boilerplate.cmake) include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE) project(NONE) target_sources(app PRIVATE src/main.c)
CONFIG_SERIAL=y CONFIG_UART_0_NRF_UARTE=y
These lines are required in order to see the logging from a serial terminal and will enable the serial driver and the UARTE peripheral. However, it is actually not necessary to enable these, as they are already enabled by default in NCS for the listed boards. E.g. in the board folder for the nRF9160 DK the configurations are set inside nrf9160_pca10090_defconfig. I included them anyway to make you familiar with the prj.conf file.
The main.c file should look like this:
#include <zephyr.h> #include <sys/printk.h> void main(void) { printk("Hello World!\n"); }
There is a guide in the Toolchain Manager on how to build and run a project, Open Toolchain Manager (TM) app and click on "First step to build" to see it.
For the record, I will go through the process here as well.
Two important environment variables to set are the Zephyr base and the GNU ARM Embedded Toolchain directory, however, if you've installed NCS through the TM, these will be set automatically. In SES, click on Tools→Options→nRF Connect and you will see the value of these variables:
E.g. if you are building with the board variant nrf9160_pca10090ns, it should look like this:
If you are using the nRF9160 DK, make sure SW5 is set to nRF91
After resetting the board, you should see the following log inside one of the terminals:
*** Booting Zephyr OS build v2.1.99-ncs1 *** Hello World!
If you've installed NCS through the Toolchain Manager it is not necessary to set any environmental variables since everything is set automatically upon installation and runs out of the box. Please skip section 1.3.1 and go straight to section 1.3.2 Build and flash if this is the case for you.
In order to build the application using west, some environment variables need to be set, specifically the toolchain and the Zephyr base. Even though you're not using the TM and are building any of the samples or applications directly in the nrf folder it is not necessary to set the Zephyr base, since the CMake tool will locate it automatically when building your application through west build. However, in this tutorial, we keep the project detached from the SDK and the environmental variable ZEPHYR_BASE needs to be set (if NCS is installed manually).
west build
ZEPHYR_BASE
If you follow the NCS documentation you'll be told to set environmental variables through the cmd file zephyr-env.cmd. This is a nice way of doing it if you are working with different projects, and don't want the env. variables to interfere, but you'll have to run the cmd file every time you open the command line.
For this tutorial, let's add the toolchain environmental variables to the whole system instead. Follow these steps:
setx -m ZEPHYR_TOOLCHAIN_VARIANT "gnuarmemb"
setx -m GNUARMEMB_TOOLCHAIN_PATH c:\gnuarmemb
C:\WINDOWS\system32>setx -m ZEPHYR_TOOLCHAIN_VARIANT "gnuarmemb" && setx -m GNUARMEMB_TOOLCHAIN_PATH c:\gnuarmemb SUCCESS: Specified value was saved. SUCCESS: Specified value was saved.
C:\my_projects\hello_world>echo %GNUARMEMB_TOOLCHAIN_PATH% & echo %ZEPHYR_TOOLCHAIN_VARIANT% c:\gnuarmemb gnuarmemb
Let's set the Zephyr base.
set ZEPHYR_BASE=C:\Nordic_SDK\ncs\zephyr
C:\my_projects\hello_world>set ZEPHYR_BASE=C:\Nordic_SDK\ncs\zephyr
echo %ZEPHYR_BASE%
C:\my_projects\hello_world>echo %ZEPHYR_BASE% C:\Nordic_SDK\ncs\zephyr
There are mainly two different ways of setting ZEPHYR BASE, by using set or setx. The former one (set), which is used above, will set it temporary and immediately in the current shell and the latter (setx), which was used when setting the toolchain env. variables, will set it permanently with the need to reopen the shell. Pick the option that suits you best.
ZEPHYR BASE
set
setx
Let's get the sample running.
It is important to open the shell (either bash or the command prompt) from the Toolchain Manager when building your project, since all the tools from C:\Users\<user_name>\ncs\v1.2.0\toolchain will only be accessible then.
cd C:/my_projects/hello_world
west build -b <board_variant>
... MINGW64 /c/my_projects/hello_world $ west build -b <board_variant> -- west build: build configuration: source directory: C:\my_projects\hello_world build directory: C:\my_projects\hello_world\build (created) . . .
If the build process was successful, you should see a folder named build inside the hello_world folder:
The build folder should contain the following files and folders (it may vary slightly depending on the choice of <board_variant>):
If you are using the nRF9160DK, make sure SW5 is set to nRF91
west flash
The nRF9160 SiP incorporates an LTE modem, which makes it possible to run cellular IoT applications. The modem always operates in a non-secure domain (read more about this in External domain access control on the infocenter), and the application must do the same in order to communicate with it. Therefore, all the samples in <..>/nrf/samples/nrf9160 as well as the asset_tracker, have to be built as nonsecure in order to work.
To build a sample as non-secure, the board nrf9160_pca10090ns (corresponds to <board_variant>) must be used. When building an application using this board, the following configurations will be set:
→ CONFIG_TRUSTED_EXECUTION_NONSECURE: This will make the application non-secure and make it run in the non-secure domain
→ CONFIG_TRUSTED_EXECUTION_NONSECURE
→ CONFIG_SPM: This will build the SPM sample.
→ CONFIG_SPM
To get a deeper understanding of secure/non-secure environments, jump forward to section 1.6 Secure vs. nonsecure in part 2 of this tutorial series.
After the build process is complete, the file merged.hex (<..>nrf\samples\nrf9160\<sample>\build\zephyr\merged.hex) is generated, which contains both the SPM sample in addition to the application. When running west flash, this hex file will be chosen and get programmed onto the chip. Similarly in SES Nordic Edition, if you program the chip through Build→Build Solution, the merged.hex file will get flashed.
Let's try to build the AT Client sample on the nRF9160 DK using SES. It is demonstrated how to build this sample in the NCS documentation as well as the nRF9160 Getting Started Guide, but for the record, let's do it again:
Your ncs location may differ, open the Toolchain Manager app and click on settings to see the location.
*** Booting Zephyr OS build v2.1.99-ncs1 *** Flash region Domain Permissions 00 0x00000 0x08000 Secure rwxl 01 0x08000 0x10000 Non-Secure rwxl . . . 24 NRF_GPIOTE1 Non-Secure OK 25 NRF_REGULATORS Non-Secure OK SPM: NS image at 0xc000 SPM: NS MSP at 0x20026fb8 SPM: NS reset vector at 0xd1d9 SPM: prepare to jump to Non-Secure image. *** Booting Zephyr OS build v2.1.99-ncs1 *** The AT host sample started
Check out the section AT Client→Building and running for more generic explanations and instructions on how to test the example to see if everything works as expected.
If you would like to use west instead, follow the steps below
west build -b nrf9160_pca10090ns
→ If you are encountering any errors, you may have to update the modem firmware to the latest version, check out Getting Started with nRF9160 DK→Updating the Modem for instructions on how to do this.
→ If you have problems connecting the nRF9160 to nRF Connect for Cloud, you may have to update the nRF for Cloud certificates, check out the guide nRF Connect for Cloud Certificate Update for guidance on how this can be achieved.
→ Be aware that PSM and/or eDRX is not supported on all networks yet, or that some networks do not allow roaming SIM cards to use those features. As a consequence, applications such as the Asset Tracker won't work correctly.
→ Getting Started with nRF9160 DK (some of the content in this tutorial is outdated, and if you are encountering any problems, please create a Devzone ticket)
→ nRF Cloud Certificate Update
→ Working with nRF9160
The nRF5340 SoC incorporates two processors, the network core and the application core. The BLE controller has to run on the network core while the BLE host usually runs on the application core in addition to the application (Read more about the BLE Stack Architecture and the BLE Layers in the Zephyr documentation). As mentioned in the NCS documentation, Working with nRF5340, the network core has to be programmed with the Bluetooth: HCI RPMsg sample in order to run a BLE sample on the nRF5340. If that is done, the application core can be programmed with any of the samples in <..>\nrf\samples\bluetooth.
Let's demonstrate how to build the BLE Peripheral LBS sample on the nRF5340 PDK using SES:
*** Booting Zephyr OS build v2.1.99-ncs1 *** Starting Bluetooth Peripheral LBS example I: 6 Sectors of 4096 bytes I: alloc wra: 0, fd8 I: data wra: 0, 1c I: No ID address. App must call settings_load() Bluetooth initialized Advertising successfully started
west build -b nrf5340_dk_nrf5340_cpunet && west flash
west build -b nrf5340_dk_nrf5340_cpuapp && west flash
→ Working with nRF5340
If you have any questions regarding this tutorial, please create a ticket in DevZone.
→ Check out the next part of this tutorial series: nRF Connect SDK Tutorial - Part 2
If you use NCS v1.2.0 the initial CMakeLists.txt will work. Currently, this tutorial is written for NCS v1.2.0. However, I am in the process of updating it to NCS v1.3.0 and hopefully it will be released soon
When I followed this instruction on the stage of "Open nRF Connect SDK Project" I had an error:
CMake Error at /home/roman/nordic/ncs/nrf/cmake/boilerplate.cmake:12 (include): include could not find load file: /boards/deprecated.cmake Call Stack (most recent call first): CMakeLists.txt:2 (include) nrf5340pdk_nrf5340_cpuapp.dts.pre.tmp:95.42-107.3: Warning (unique_unit_address_if_enabled): /soc/peripheral@50000000/flash-controller@39000: duplicate unit-address (also used in node /soc/peripheral@50000000/kmu@39000) nrf5340pdk_nrf5340_cpuapp.dts.pre.tmp:369.19-375.3: Warning (unique_unit_address_if_enabled): /soc/peripheral@50000000/clock@5000: duplicate unit-address (also used in node /soc/peripheral@50000000/power@5000) nrf5340pdk_nrf5340_cpuapp.dts.pre.tmp:616.31-617.5: Warning (unique_unit_address_if_enabled): /reserved-memory/image@20000000: duplicate unit-address (also used in node /reserved-memory/image_s@20000000) also defined at nrf5340pdk_nrf5340_cpuapp.dts.pre.tmp:636.14-638.3 error: UART_0_NRF_UARTE (defined at drivers/serial/Kconfig.nrfx:31) is assigned in a configuration file, but is not directly user-configurable (has no prompt). It gets its value indirectly from other symbols. See http://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_UART_0_NRF_UARTE.html and/or look up UART_0_NRF_UARTE in the menuconfig/guiconfig interface. The Application Development Primer, Setting Configuration Values, and Kconfig - Tips and Best Practices sections of the manual might be helpful too. CMake Error at /home/roman/nordic/ncs/zephyr/cmake/kconfig.cmake:217 (message): command failed with return code: 1 Call Stack (most recent call first): /home/roman/nordic/ncs/zephyr/cmake/app/boilerplate.cmake:506 (include) CMakeLists.txt:3 (include)
include($ENV{ZEPHYR_BASE}/../nrf/cmake/boilerplate.cmake) include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
find_package(Zephyr HINTS $ENV{ZEPHYR_BASE})
Great tutorial.
When attempting to Build and flash - using SEGGER Embedded Studio for nRF52840-pca10056 on macOS we ran into a couple of issues:
1. Unclear whether one should create a Segger .proj file. We assume one should point to directory created earlier in tutorial, however it doesn't have a .proj file, so we created a new one and added main.c. Unclear if ok to leave `Toolchain Root Directory = $(StudioDir)/gcc/$(GCCTarget)/bin` or need to change this.
(Note: When opening Segger, it initially pointed to a Hello world file that is located in same dir as the Segger application, however that sub dir doesn't have a CMakeLists.tx file, so didn't seem right either.)
2. After opening`File → Open nRF Connect SDK Project...` , configuring and pressing <ok> the project starts to build, but we got a CMake error. We determined there was an extra space in value for
Tools->Options->nRF Connect ->Additional CMake Options `-D WEST=/usr/local/bin/west`
(should be `-DWEST=...`
3. Once above was fixed, we were able to start building, however the build failed when compiling uart_nrfx_uarte.c. Several MACRO are undefined, including UARTE_CONFIG and DT_NORDIC_NRF_UARTE_UART_0_CURRENT_SPEED. Reported build error is
uart_nrfx_uarte.c:1396:9: error: 'DT_NORDIC_NRF_UARTE_UART_0_LABEL' undeclared here4. To address this plunged into the Kconfig settingsProject->Configure nRF Connect .. which brings up a GUI for setting KconfigIn top right corner entered UARTE in search box. In the displayed driver optionsselected `Modules -> nrfx drivers ->Enable UARTE driver` and `Enable UARTE0 instance`Hit configure and then rebuild. Even after this, we get same error and can't see any obvious Kconfig errors. Note: Segger editor shows which MACROs and #define that are true,which is very useful when hunting down Kconfig problems.At this point stumped on how to move forward....
for those using the toolchain manger, you need to run all of your terminal commands using the git-bash.exe termianl in the NCS/toolchain folder.
Thanks for the input. You can use -b to set the board in west.