Installing the ZCAN IOT SDK manually¶
Note
If you prefer to install the toolchain manually, or if you run into problems during the installation process, see the following documentation for instructions.
To manually install the ZCAN IOT SDK, you must install all required tools and clone the ZCAN IOT SDK repositories. See the following sections for detailed instructions.
The first two steps, Installing the required tools and Installing the toolchain, are identical to the installation in Zephyr. If you already have your system set up to work with the Zephyr OS, you can skip these steps.
See Supported operating systems for information on the supported operating systems and Zephyr features.
Installing the required tools¶
The installation process is different depending on your operating system.
The recommended way for installing the required tools on Windows is to use Chocolatey, a package manager for Windows. Chocolatey installs the tools so that you can use them from a Windows command prompt.
To install the required tools, follow the Install dependencies section for Windows in Zephyr’s Getting Started Guide.
To install the required tools on Linux, follow the Install dependencies section for Linux in Zephyr’s Getting Started Guide. Additional information is available in the Install Requirements and Dependencies section.
Note
You do not need to install the Zephyr SDK. We recommend to install the compiler toolchain separately, as detailed in Installing the toolchain.
To install the required tools, follow the Install dependencies section for macOS in Zephyr’s Getting Started Guide.
Install Homebrew and install the required tools using the brew
command line tool.
Also see macOS alternative setup instructions for additional information.
If you are interested in building Project Connected Home over IP applications, install also the GN meta-build system to generate the Ninja files that the ZCAN IOT SDK uses.
To install the GN tool, complete the following steps:
Download the latest version of the GN binary archive for Windows from the GN website.
Extract the
zip
archive.Ensure that the GN tool is added to your
PATH
environment variable.
To install the GN tool, complete the following steps:
Download the GN binary archive and extract it by using the following commands:
mkdir ${HOME}/gn && cd ${HOME}/gn wget -O gn.zip https://chrome-infra-packages.appspot.com/dl/gn/gn/linux-amd64/+/latest unzip gn.zip rm gn.zip
Add the location of the GN tool to the system PATH. For example, if you are using
bash
, run the following commands:echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bashrc source ${HOME}/.bashrc
To install the GN tool, complete the following steps:
Download the GN binary archive and extract it by using the following commands:
mkdir ${HOME}/gn && cd ${HOME}/gn wget -O gn.zip https://chrome-infra-packages.appspot.com/dl/gn/gn/mac-amd64/+/latest unzip gn.zip rm gn.zip
Add the location of the GN tool to the system PATH. For example, if you are using
bash
, run the following commands:echo 'export PATH=${HOME}/gn:"$PATH"' >> ${HOME}/.bashrc source ${HOME}/.bashrc
Installing the toolchain¶
To be able to cross-compile your applications for Xtensa targets, you must install version 8.0.15 Xplorer.
Important
Make sure to install the version that is mentioned above. Other versions might not work with this version of the ZCAN IOT SDK.
Note that other versions of the ZCAN IOT SDK might require a different toolchain version.
To set up the toolchain, complete the following steps:
Download the Xplorer for your operating system.
Make sure that the folder name does not contain any spaces or special characters.
If you want to build and program applications from the command line, define the environment variables for the XCC toolchain. Depending on your operating system:
Open a command prompt and enter the following commands (assuming that you have installed the toolchain to
c:\gnuarmemb
; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):set ZEPHYR_TOOLCHAIN_VARIANT=xcc set XCC_TOOLCHAIN_PATH=c:\usr\xtensa
Open a terminal window and enter the following commands (assuming that you have installed the toolchain to
~/gnuarmemb
; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):export ZEPHYR_TOOLCHAIN_VARIANT=xcc export XTENSA_TOOLCHAIN_PATH="~/usr/xtensa"
Open a terminal window and enter the following commands (assuming that you have installed the toolchain to
~/gnuarmemb
; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):export ZEPHYR_TOOLCHAIN_VARIANT=xcc export XTENSA_TOOLCHAIN_PATH="~/usr/xtensa"
Set the environment variables persistently. Depending on your operating system:
Add the environment variables as system environment variables or define them in the
%userprofile%\zephyrrc.cmd
file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a command prompt.Define the environment variables in the
~/.zephyrrc
file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a terminal window.Define the environment variables in the
~/.zephyrrc
file as described in `Setting up the build environment`_. This will allow you to avoid setting them every time you open a terminal window.
Getting the ZCAN IOT SDK code¶
The ZCAN IOT SDK consists of a set of Git repositories.
Every ZCAN IOT SDK release consists of a combination of these repositories at different revisions. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, ZCAN-sdk.
Note
The latest state of development is on the master branch of the ZCAN-sdk repository. To ensure a usable state, the ZCAN-sdk repository defines the compatible states of the other repositories. However, this state is not necessarily tested. For a higher degree of quality assurance, check out a tagged release.
Therefore, unless you are familiar with the development process, you should always work with a specific release of the ZCAN IOT SDK.
To manage the combination of repositories and versions, the ZCAN IOT SDK uses West (Zephyr’s meta-tool).
The main repository, ZCAN-sdk, contains a `west manifest file`_, west.yml
, that determines the revision of all other repositories.
This means that ZCAN-sdk acts as the manifest repository, while the other repositories are project repositories.
You can find additional information about the repository and development model in the development model section.
See the west documentation for detailed information about the tool itself.
Installing west¶
Install west by entering the following command:
pip3 install west
pip3 install --user west
pip3 install west
You only need to do this once.
Like any other Python package, the west tool is updated regularly. Therefore, remember to regularly check for updates:
pip3 install -U west
pip3 install --user -U west
pip3 install -U west
Cloning the repositories¶
Tip
If you cloned the ZCAN IOT SDK repositories before they were moved to the nrfconnect GitHub organization and want to update them, follow the instructions in repo_move.
To clone the repositories, complete the following steps:
Create a folder named
ZCAN-IOT
. This folder will hold all ZCAN IOT SDK repositories.Open a command window in the
ncs
folder.Determine what revision of the ZCAN IOT SDK you want to work with. The recommended way is to work with a specific release.
To work with a specific release, the revision is the corresponding tag (for example,
v0.0.1
). You can find the tag in the Release notes of the release.To work with a development tag, the revision is the corresponding tag (for example,
v1.2.99-dev1
)To work with a branch, the revision is the branch name (for example,
master
to work with the latest state of development).To work with a specific state, the revision is the SHA (for example,
224bee9055d986fe2677149b8cbda0ff10650a6e
).
Initialize west with the revision of the ZCAN IOT SDK that you want to check out, replacing ZSDK_revision with the revision:
west init -m https://gitee.com/ZCAN-IOT/ZCAN-sdk
For example, to check out the v0.0.1 release, enter the following command:
west init -m https://gitee.com/ZCAN-IOT/ZCAN-sdk
To check out the latest state of development, enter the following command:
west init -m https://gitee.com/ZCAN-IOT/ZCAN-sdk
Note
If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need more information.
Initializing west with a specific revision of the manifest file does not lock your repositories to this version. Checking out a different branch or tag in the ZCAN-sdk repository and running
west update
changes the version of the ZCAN IOT SDK that you work with.This will clone the manifest repository ZCAN-sdk into
ZCAN-sdk
.Enter the following command to clone the project repositories:
west update
Export a Zephyr CMake package. This allows CMake to automatically load the boilerplate code required for building ZCAN IOT SDK applications:
west zephyr-export
Your directory structure now looks similar to this:
ncs
|___ .west
|___ bootloader
|___ modules
|___ ZCAN-sdk
|___ ZCAN-xlib
|___ zephyr
|___ ...
Note that there are additional folders, and that the structure might change. The full set of repositories and folders is defined in the manifest file.
Updating the repositories¶
If you work with a specific release of the ZCAN IOT SDK, you do not need to update your repositories, because the release will not change. However, you might want to switch to a newer release or check out the latest state of development.
To manage the ZCAN-sdk
repository (the manifest repository), use Git.
To make sure that you have the latest changes, run git fetch origin
to fetch the latest code from the ZCAN-sdk repository.
Checking out a branch or tag in the ZCAN-sdk
repository gives you a different version of the manifest file.
Running west update
will then update the project repositories to the state specified in this manifest file.
Note
If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need more information.
For example, to switch to release v0.0.1 of the ZCAN IOT SDK, enter the following commands in the ZCAN-IOT/ZCAN-sdk
directory:
git fetch origin git checkout v0.0.1 west update
To update to a particular revision (SHA), make sure that you have that particular revision locally before you check it out (by running git fetch origin
):
git fetch origin
git checkout 224bee9055d986fe2677149b8cbda0ff10650a6e
west update
To switch to the latest state of development, enter the following commands:
git fetch origin
git checkout origin/master
west update
Note
Run west update
every time you change or modify the current working branch (for example, when you pull, rebase, or check out a different branch).
This will bring the project repositories to the matching revision defined by the manifest file.
Installing additional Python dependencies¶
The ZCAN IOT SDK requires additional Python packages to be installed.
Use the following commands to install the requirements for each repository.
Open a command prompt in the ZCAN-IOT
folder and enter the following commands:
pip3 install -r zephyr/scripts/requirements.txt pip3 install -r ZCAN-sdk/scripts/requirements.txt pip3 install -r bootloader/mcuboot/scripts/requirements.txt
Open a terminal window in the ZCAN-IOT
folder and enter the following commands:
pip3 install --user -r zephyr/scripts/requirements.txt pip3 install --user -r ZCAN-sdk/scripts/requirements.txt pip3 install --user -r bootloader/mcuboot/scripts/requirements.txt
Open a terminal window in the ZCAN-IOT
folder and enter the following commands:
pip3 install -r zephyr/scripts/requirements.txt pip3 install -r ZCAN-sdk/scripts/requirements.txt pip3 install -r bootloader/mcuboot/scripts/requirements.txt
Setting up the command line build environment¶
If you want to build and program your application from the command line, you must set up your build environment by defining the required environment variables every time you open a new command prompt or terminal window.
See Important Environment Variables information about the various relevant environment variables.
Define the required environment variables as follows, depending on your operating system:
Navigate to the ZCAN-IOT
folder and enter the following command: zephyr\zephyr-env.cmd
If you need to define additional environment variables, create the file %userprofile%\zephyrrc.cmd
and add the variables there.
This file is loaded automatically when you run the above command.
Navigate to the ZCAN-IOT
folder and enter the following command: source zephyr/zephyr-env.sh
If you need to define additional environment variables, create the file ~/.zephyrrc
and add the variables there.
This file is loaded automatically when you run the above command.
Navigate to the ZCAN-IOT
folder and enter the following command: source zephyr/zephyr-env.sh
If you need to define additional environment variables, create the file ~/.zephyrrc
and add the variables there.
This file is loaded automatically when you run the above command.