Simulating devices with QEMU

Install West

Install Dependencies

Linux

1. Install dependencies with apt:

   sudo apt update
   sudo apt install --no-install-recommends git cmake ninja-build gperf \
   ccache dfu-util device-tree-compiler wget python3-dev python3-pip \
   python3-setuptools python3-tk python3-venv python3-wheel xz-utils file \
   make gcc gcc-multilib g++-multilib libsdl2-dev

2. West requires CMake version 3.20.0 or higher. Check the version that your package manager installed:

   $ cmake --version
   cmake version 3.16.3

   If you have an older version, Ubuntu 20.04 systems can add the Kitware repository which maintains the newest release:

   wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
   sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main'
   sudo apt update
   sudo apt install cmake
   cmake --version

   If the Kitware repository doesn't work for you (ie: your system is not running Ubuntu 20.04), you can build the stable version of CMake from source.

Install West

We recommend creating a python3 virtual environment to avoid running into tooling incompatibilities.

Install within a virtualenv

1. Create your workspace directory:

   mkdir ~/undefined

2. Create a new virtual environment:

   Even though we haven't pulled down Zephyr yet, we can create the virtual environment in the place where we will pull down Zephyr.

   python3 -m venv ~/undefined/.venv

3. Activate the virtual environment:

   source ~/undefined/.venv/bin/activate

   Whenever the virtual environment is active, your shell's prompt will be prefixed with (.venv).

   Deactivate the virtual environment when you're done by running deactivate.

   note

   Anytime you need to use west or Zephyr, remember to re-activate the virtual environment.

4. Now, use pip to install west (beginning with the wheel dependency):

   Because we're in a python3 virtualenv, we don't need to specify pip3 and can just use pip (because virtual env knows the best version to use)

   pip install wheel
   pip install west

Install globally

1. Create your workspace directory:

   mkdir ~/undefined

2. Use pip3 to install west (beginning with the wheel dependency):

   pip3 install wheel
   pip3 install west

MacOS

1. Start by installing dependencies with brew:

   brew install cmake ninja gperf python3 ccache qemu dtc

Install West

We recommend creating a python3 virtual environment to avoid running into tooling incompatibilities.

Install within a virtualenv

1. Create your workspace directory:

   mkdir ~/undefined

2. Create a new virtual environment:

   Even though we haven't pulled down Zephyr yet, we can create the virtual environment in the place where we will pull down Zephyr.

   python3 -m venv ~/undefined/.venv

3. Activate the virtual environment:

   source ~/undefined/.venv/bin/activate

   Whenever the virtual environment is active, your shell's prompt will be prefixed with (.venv).

   Deactivate the virtual environment when you're done by running deactivate.

   note

   Anytime you need to use west or Zephyr, remember to re-activate the virtual environment.

4. Now, use pip to install west (beginning with the wheel dependency):

   Because we're in a python3 virtualenv, we don't need to specify pip3 and can just use pip (because virtual env knows the best version to use)

   pip install wheel
   pip install west

Install globally

1. Create your workspace directory:

   mkdir ~/undefined

2. Use pip3 to install west (beginning with the wheel dependency):

   pip3 install wheel
   pip3 install west

Windows

Package Manager: Chocolatey

Using Chocolatey and cmd.exe

The chocolatey package manager needs to be installed to fetch software packages required by Zephyr. These instructions must be run in a cmd.exe command prompt. The required commands differ on PowerShell.

1. Install chocolatey

2. Open an Administrator cmd.exe window:

   • press the Windows key
   • type cmd.exe
   • right-click the result, and choose Run as Administrator

3. Disable global confirmation to avoid having to confirm the installation of individual programs:

   choco feature enable -n allowGlobalConfirmation

4. Use choco to install the required dependencies:

   choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
   choco install ninja gperf python git dtc-msys2 wget 7zip

5. Close the window and open a new cmd.exe window as a regular user to continue

Install West

west is the Zephyr "meta tool" that will allow you to build firmware, install packages, and flash firmware. There are various dependencies required, depending upon your operating system (OS), because west is Python based.

Install within a virtualenv

1. Create your workspace directory:

   cd %HOMEPATH%
   mkdir undefined

2. Create a new virtual environment:

   cd %HOMEPATH%
   python -m venv undefined\.venv

3. Activate the virtual environment:

   ## cmd.exe
   undefined\.venv\Scripts\activate.bat
   
   ## PowerShell
   undefined\.venv\Scripts\Activate.ps1

   Once activated your shell will be prefixed with (.venv). The virtual environment can be deactivated at any time by running deactivate.

   note

   Remember to activate the virtual environment whenever you need to use the west command.

4. Install west:

   Now, use pip to install west.

   pip install west

Install globally

1. Create your workspace directory:

   cd %HOMEPATH%
   mkdir undefined

2. Use pip3 to install west:

   pip install -U west

Install Golioth Firmware SDK

Linux

1. With west installed, grab the Zephyr SDK:

   cd ~
   west init -m https://github.com/golioth/golioth-firmware-sdk.git --mr v0.12.1 --mf west-zephyr.yml ~/golioth-zephyr-workspace
   cd golioth-zephyr-workspace/modules/lib/golioth-firmware-sdk
   git submodule update --init --recursive
   west update
   info

   Depending on your internet and I/O speed, west update can take upwards of 5 or 10 minutes.

2. Tell west to automatically configure CMake:

   west zephyr-export

3. Install the remaining dependencies:

   Install within a virtualenv

   pip install -r ~/golioth-zephyr-workspace/zephyr/scripts/requirements.txt

   Install globally

   pip3 install -r ~/golioth-zephyr-workspace/zephyr/scripts/requirements.txt

MacOS

1. With west installed, grab the Zephyr SDK:

   cd ~
   west init -m https://github.com/golioth/golioth-firmware-sdk.git --mr v0.12.1 --mf west-zephyr.yml ~/golioth-zephyr-workspace
   cd golioth-zephyr-workspace/modules/lib/golioth-firmware-sdk
   git submodule update --init --recursive
   west update
   info

   Depending on your internet and I/O speed, west update can take upwards of 5 or 10 minutes.

2. Tell west to automatically configure CMake:

   west zephyr-export

3. Install the remaining dependencies:

   Install within a virtualenv

   pip install -r ~/golioth-zephyr-workspace/zephyr/scripts/requirements.txt

   Install globally

   pip3 install -r ~/golioth-zephyr-workspace/zephyr/scripts/requirements.txt

Windows

1. With west installed, download the Zephyr SDK:

   cd c:\
   west init -m https://github.com/golioth/golioth-firmware-sdk.git --mr v0.12.1 --mf west-zephyr.yml golioth-zephyr-workspace
   cd golioth-zephyr-workspace/modules/lib/golioth-firmware-sdk
   git submodule update --init --recursive
   west update
   info

   Depending on your internet and I/O speed, west update can take upwards of 5 or 10 minutes.

2. Tell west to automatically configure CMake:

   west zephyr-export

3. Install the remaining dependencies:

   Install within a virtualenv

   pip install -r %HOMEPATH%\golioth-zephyr-workspace\zephyr\scripts\requirements.txt

   Install globally

   pip3 install -r %HOMEPATH%\golioth-zephyr-workspace\zephyr\scripts\requirements.txt

Toolchain check

If you've been using some of the other tutorials on this site, you may have been changing the toolchain, specifically if you used the ESP32. Type the following:

export -p | grep "ZEPHYR"

This should list the following variable

• ZEPHYR_TOOLCHAIN_VARIANT

If these are set to Espressif, change them to use the default zephyr toolchain (part of the SDK you installed above)

Linux

On Linux we compile (non-Espressif) Zephyr using the Zephyr SDK. Do you have that installed? If not, go check out this page on the Zephyr getting started docs.

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-x.y.z

caution

Be sure to fill in the sdk name that matches your Zephyr SDK install!

Mac OS

As stated in the Zephyr Getting Started Guide, the toolchains are more manual for Mac and Windows

For ARM based components, you will need to install the GNU ARM Embedded toolchain somewhere on your machine and then point to it. It will likely look something like this:

export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=/home/you/Downloads/gnu_arm_embedded

Windows

As stated in the Zephyr Getting Started Guide, the toolchains are more manual for Mac and Windows

For ARM based components, you will need to install the GNU ARM Embedded toolchain somewhere on your machine (the recommendation is at c:\ for windows, hello 1995) and then point to it. It will likely look something like this:

export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=C:\gnu_arm_embedded

Add credentials to sample

Navigate to the Golioth directory within Zephyr

cd ~/golioth-zephyr-workspace/modules/lib/golioth

This is also the place we will build Zephyr from.

Modify the sample you'd like to build (ie. the hello sample)

nano samples/hello/prj.conf

At the bottom of the page, add your credentials for your device:

CONFIG_GOLIOTH_SAMPLE_HARDCODED_PSK_ID="DEVICE_CRED_ID"
CONFIG_GOLIOTH_SAMPLE_HARDCODED_PSK="DEVICE_PSK"

Save and exit (ctrl+x in nano)

Build for a QEMU Device

At this point, you can build a Golioth Zephyr project:

west build -b qemu_x86 samples/hello -p

and run it:

west build -t run

This should have the same effect as running on a piece of hardware, as in the Golioth NCS Build Environment or Golioth Zephyr Build Environment quickstart guides

For more on networking, see the QEMU page on the Zephyr Docs