NXP Robotics SDK

The NXP Robotics SDK provides a unified software development environment for building robotics systems on supported NXP platforms. It brings together validated platform software, robotics frameworks, applications, development tooling, and pre-built artifacts into reproducible SDK releases.

The robotics-sdk repository is the SDK’s integration and release layer. It defines supported platform and software-stack combinations, pins compatible revisions of the corresponding source repositories, orchestrates builds through west, and provides access to pre-built artifacts.

Firmware and application sources remain in their respective component repositories rather than being duplicated here. This allows individual projects such as PX4, Zephyr-based firmware, AM32, and robotics applications to retain their native development environments while being integrated and validated as part of a common NXP Robotics SDK release.

Table of contents

Supported platforms and stacks

Platform

PX4

Cerebri

Zephyr

AM32

MR-NAVQ95

✅

❌

❌

❌

MR-VMU-TROPIC

✅

❌

✅

❌

MR-ESC-AM32-MCXA133

❌

❌

❌

✅

MR-MCXN-T1

❌

✅

✅

❌

📝 Note: The exact platform names accepted by the tooling (the value passed to -p/--platform) are the ones printed by west sdk list. Run west sdk list -v to also see the supported stacks, shields and examples for each platform.

Development Workflows

The NXP Robotics SDK supports two development workflows. Pre-built artifacts provide the simplest path for platform evaluation and flashing, while the build-from-source workflow supports development and customization of firmware, applications, configuration, and SDK components.

  • Flow A: getting pre-built images. Download the pre-built artifacts (firmware, and the Linux WIC image for MR-NAVQ95) from the artifact store. This flow does NOT require Docker. All that is needed is Python and west, which can be installed in a Python virtual environment on the host. Use this flow to flash a supported platform without rebuilding anything. See Flow A: getting pre-built images.

  • Flow B: building images from source. Build the firmware for a platform from the pinned upstream sources. Because the SDK spans several software stacks, each with its own toolchain and package dependencies, this flow runs inside a Docker container that bundles every dependency. Docker is only required for this build flow — it provides the cross-platform toolchains (PX4, Zephyr, AM32, etc…) and an isolated, reproducible build environment, so the host does not have to install them. See Flow B: building images from source.

📝 Note: Docker is needed only for Flow B. It is not required to download pre-built images (Flow A).

Requirements

Common requirements

Both flows need:

  • git, to clone this repository.

  • Network access to github.com, from which west resolves and clones the pinned manifest projects. Behind a firewall, make sure the proper proxy and CA certificate are configured (see Corporate network).

Flow A (getting pre-built images) additionally needs only:

  • Python 3 and pip (to create a virtual environment and install west and requests; requests is used by west sdk download).

  • Network access to the artifact store from which the pre-built binaries are downloaded.

Additional requirements for the build-from-source flow

Flow B (building images from source) builds inside a Docker container, so the host additionally needs:

  • Docker (see the installation instructions below).

  • At least 25 GB of free disk space on the filesystem that backs Docker’s storage (/var/lib/docker by default). The final image is around 10 GB, but the build temporarily needs more for downloaded .deb packages, the Zephyr SDKs, and intermediate layers, plus additional space for the checked-out sources and build outputs. If the volume holding /var/lib/docker is small (a common cause of build failures), point Docker’s data-root at a larger disk — see Warning: “No space left on device” during docker build.

  • Network access to github.com, from which the Dockerfile downloads the Zephyr SDKs while building the image. Behind a firewall, make sure the proper proxy host and port are passed to the Docker commands as shown below.

Prerequisites and configuration

Host operating system

The Docker-based build flow (Flow B) is validated on Ubuntu 24.04 LTS. Use Ubuntu 24.04 as the host OS; older releases (e.g. Ubuntu 22.04) are not currently supported and may fail while building the Docker image. The download-only flow (Flow A) is not tied to a specific Ubuntu release — any host with Python 3 and west can download the pre-built artifacts.

Corporate network: proxy and CA certificates

Note: This section applies only when the build is performed from a corporate network.

Building from a corporate network typically requires both a proxy and the corporate CA certificate so that TLS connections (to github.com, package indexes, etc.) succeed inside the Docker build.

  • Proxy. The docker build / docker run examples below accept http_proxy / https_proxy values. These are placeholders of the form http://<proxy>:<port> — replace <proxy> and <port> with the values that apply to the local machine and site. Do not copy the examples verbatim; there is no single proxy that works for everyone. If the host does not need a proxy, omit these arguments entirely.

  • CA certificate. In environments where corporate TLS inspection is enabled, downloads inside the image build can fail with certificate-verification errors. Make the corporate root CA available during the build, for example by copying the .crt into the build context and installing it in the image (/usr/local/share/ca-certificates/ and running update-ca-certificates), or by configuring the CA on the host Docker daemon. Consult the applicable IT documentation for the appropriate certificate file and installation procedure.

Flow A: getting pre-built images

This flow downloads the pre-built artifacts from the artifact store. It does NOT require Docker — only Python and west are needed, installed in a Python virtual environment on the host.

First, make sure git and Python 3 are available. On an Ubuntu-based machine:

sudo apt-get update
sudo apt-get install -y git python3 python3-pip python3-venv

Clone the robotics-sdk repository:

mkdir -p ~/robotics-workdir && cd ~/robotics-workdir

git clone -b robotics-0.7.0 https://github.com/nxp-robotics/robotics-sdk.git

📝 Note: -b selects the branch or tag to use. We recommend always choosing a release branch/tag; for the ROBOTICS_0.7.0 release, use robotics-0.7.0.

Create and activate a Python virtual environment, then install west into it:

python3 -m venv .venv
source .venv/bin/activate

pip install west requests

📝 Note: west sdk download uses the requests package to fetch artifacts from the artifact store, so it must be installed alongside west. Without it, the download fails with The 'requests' package is required for 'west sdk download'.

Initialize west against the cloned manifest:

west init -l robotics-sdk/

Optionally, bring in the SDK’s manifest projects with west update:

west update

📝 Note: west update is optional for this flow. west sdk download fetches pre-built artifacts from the artifact store and does not need the manifest projects to be cloned, so it works right after west init. Run west update only if the manifest projects (e.g. the documentation repository) are also wanted locally.

Download the pre-built binaries for the target platform:

west sdk download -p <platform>

For example, to download the pre-built binaries for the MR-NAVQ95 platform:

west sdk download -p mr-navq95

📝 Note: The downloaded binaries are placed under ~/robotics-workdir/bin.

Flow B: building images from source

Given the number of software stacks supported by the SDK, managing all of their package dependencies on the build machine may be challenging. Because of this, robotics-sdk provides a Dockerfile, which can be used to build a Docker image with all of the package dependencies included in it. Docker is required only for this build flow; it supplies the cross-platform toolchains and an isolated, reproducible build environment.

To get started, make sure Docker is installed on the build machine. For an Ubuntu-based machine, follow these instructions. To check if everything went smoothly with the installation, try to run the hello-world Docker image:

sudo docker run hello-world

Possible pitfall (hello-world)

📝 Note: To allow Docker to be managed by non-root users, follow these instructions. Throughout this guide, it is assumed that sudo is required.

Apart from Docker, a few system packages are required. These can be installed by running:

sudo apt-get update
sudo apt-get install -y git

To prepare the development environment, first clone the robotics-sdk repository by running:

mkdir -p ~/robotics-workdir && cd ~/robotics-workdir

git clone -b <branch> https://github.com/nxp-robotics/robotics-sdk.git

📝 Note: branch is the name of the branch or tag to use. We recommend always choosing a release branch/tag. For the ROBOTICS_0.7.0 release, the name of the branch would be robotics-0.7.0.

For example, to clone the robotics-0.7.0 branch:

mkdir -p ~/robotics-workdir && cd ~/robotics-workdir

git clone -b robotics-0.7.0 https://github.com/nxp-robotics/robotics-sdk.git

A tag can also be passed to the -b option to check out a specific release. For example, to check out the <tag> tag:

mkdir -p ~/robotics-workdir && cd ~/robotics-workdir

git clone -b <tag> https://github.com/nxp-robotics/robotics-sdk.git

📝 Note: Release tags are listed on the repository’s releases/tags page; use the tag that matches the desired release.

Possible pitfall (detached HEAD)

The next step is to build the Docker image:

sudo docker build --build-arg UID=$(id -u) \
		  --build-arg GID=$(id -g) \
		  -t robotics-sdk -f robotics-sdk/Dockerfile .

Possible pitfall (docker build proxy)

Possible pitfall (WSL2)

Possible pitfall (disk space)

Now everything should be ready to go. To start the container, run:

sudo docker run -it -v ~/robotics-workdir:/home/robotics robotics-sdk

Possible pitfall (docker run proxy)

After starting the container, initialize west by running:

west init -l robotics-sdk/

Possible pitfall (git auth)

Optionally, bring in the SDK’s manifest projects with west update:

west update

📝 Note: west update is optional for building. west sdk build sets the platform manifest and runs west update automatically to clone the pinned upstream sources before compiling, so the sources do not have to be fetched by hand first. Run west update manually only when the SDK’s bootstrap manifest projects (e.g. the documentation repository, or the MCXN-T1 ROS2-node apps) are wanted up front.

If everything went well, all of the available platforms can be listed by running:

west sdk list

To build the firmware for a platform, see Build binaries from source in the command reference guide below.

Command reference guide

robotics-sdk uses west to manage all of its components (e.g. building firmware images, downloading pre-built binaries, updating git revisions, etc…). The documentation found below provides an overview of what can be achieved using west and robotics-sdk.

📝 Note: For all commands requiring a platform name as argument (e.g. west sdk build -p <platform>), one of the supported platform names listed by running west sdk list must be used.

📝 Note: For all build or download commands, all of the binaries will be available under ~/robotics-workdir/bin.

  1. Displaying help information

The --help option can be used to display additional information regarding a command or a sub-command (e.g. documentation, supported options, etc…). This option should be used as the “ultimate” source of truth since it should always be up to date.

Examples of how this option could be used:

# print help information about the sdk command
west sdk --help

# print help information about the build sub-command
west sdk build --help

  1. List available platforms

To list all of the available platforms:

west sdk list

# prints additional information such as supported stacks, shields and examples
west sdk list -v

  1. Download pre-built binaries

To download the pre-built binaries:

west sdk download -p <platform>

For example, to download the pre-built binaries for the MR-NAVQ95 platform:

west sdk download -p mr-navq95

  1. Fetch or update a platform’s sources

To set a platform’s manifest and clone (or update to the pinned revision) its upstream sources without building:

west sdk update -p <platform>

For example, to fetch the sources for the MR-NAVQ95 platform:

west sdk update -p mr-navq95

📝 Note: This step is optional before a build. west sdk build performs the same source fetch automatically; use west sdk update only to bring in (or refresh) the sources without compiling.

  1. Build binaries from source

To build all of the available binaries from source for a given platform:

west sdk build -p <platform>

For example, to build all of the available binaries for the MR-NAVQ95 platform:

west sdk build -p mr-navq95

The aformentioned command builds all of the available binaries for the target platform (i.e. all stacks, all examples, etc…). A specific stack can be built by using the --stack option:

west sdk build -p <platform> --stack <stack>

For example, to build the PX4 stack for the MR-NAVQ95 platform:

west sdk build -p mr-navq95 --stack px4

  1. Updating to a new release (tag)

When a new release tag is published, move the robotics-sdk workspace to it by fetching the tags, checking out the new tag, and running west update. From inside the robotics-sdk repository:

cd ~/robotics-workdir/robotics-sdk
git remote update
git checkout <new-tag>
west update

west update after the checkout is needed because the manifest (west.yml) may have changed between releases; it reconciles the SDK-level manifest projects (e.g. robotics-apps, the documentation repository, etc…) with the new tag.

📝 Note: west update here only brings in what is controlled by the SDK’s bootstrap manifest (robotics-apps, docs, etc…). It does NOT fetch the upstream stack sources (PX4, Zephyr, etc…); those are fetched for the selected platform and stack when west sdk build is run.

Possible pitfall (detached HEAD)

Warnings and environment-specific notes

The warnings below only apply in specific situations (corporate networks, WSL2, tag checkouts). They are collected here so that the step-by-step flow above stays easy to follow — consult the relevant one only if it applies to the local setup.

Warning: hello-world on a corporate network

On a corporate network, docker run hello-world pulls the image from Docker Hub and will fail unless Docker can reach the registry through the configured proxy. Configure the Docker daemon proxy (see the Docker documentation) before running the validation step.

Warning: detached HEAD after a tag checkout

Doing a checkout on a tag will put the repository in a detached HEAD state. Run git switch -c <branch> to create a branch.

Warning: docker build proxy on a corporate network

Behind a corporate firewall, the proxies may also need to be specified for the build command, using the --build-arg option. Replace <proxy> and <port> with the local site’s values (see Corporate network):

sudo docker build --build-arg UID=$(id -u) \
		  --build-arg GID=$(id -g) \
		  --build-arg http_proxy=http://<proxy>:<port> \
		  --build-arg https_proxy=http://<proxy>:<port> \
		  -t robotics-sdk -f robotics-sdk/Dockerfile .

Warning: WSL2 DNS resolution during docker build

When building on WSL2, the Docker container may lose DNS resolution for external hosts (e.g. github.com), causing the Zephyr SDK download to fail with Temporary failure in name resolution. Add --network=host to the build command so the container shares the WSL2 network stack directly (see Troubleshooting):

sudo docker build --network=host \
		  --build-arg UID=$(id -u) \
		  --build-arg GID=$(id -g) \
		  -t robotics-sdk -f robotics-sdk/Dockerfile .

Warning: “No space left on device” during docker build

A build that stops with No space left on device (often while unpacking an apt package such as vim-runtime) means the volume backing Docker’s storage (/var/lib/docker by default) filled up — the named package is not the cause. First reclaim space and re-run the build:

df -h                     # which volume (e.g. /var/lib/docker) is full?
docker system df          # space used by images / build cache
docker builder prune -f   # drop stale build cache
docker system prune -af   # remove unused images/containers/networks

If that volume is simply too small and another has room, move Docker’s data-root there. Stop Docker, copy the existing data across (so the current images are kept — skip the copy to start fresh), point Docker at the new path, then restart:

sudo systemctl stop docker
sudo rsync -aP /var/lib/docker/ /large/volume/docker/
echo '{ "data-root": "/large/volume/docker" }' | sudo tee /etc/docker/daemon.json
sudo systemctl start docker
docker info | grep "Docker Root Dir"   # verify the new path, then rm -rf the old one

On Docker Desktop / WSL2 / macOS / Windows, increase the VM’s virtual disk allocation instead (Docker Desktop → Settings → Resources).

Warning: docker run proxy on a corporate network

Behind a corporate firewall, the proxy-related environment variables may also need to be passed to the run command (substitute the local <proxy>/<port>). A full corporate-network invocation typically also uses --network=host (so a proxy on 127.0.0.1 is reachable), mounts the host CA bundle so TLS to external hosts is trusted, and mounts ~/.ssh for git access:

sudo docker run -it -v $(pwd):/home/robotics \
		-v ~/.ssh:/home/robotics/.ssh:ro \
		-e http_proxy=http://<proxy>:<port> \
		-e https_proxy=http://<proxy>:<port> \
		-e ftp_proxy=http://<proxy>:<port> \
		--network=host \
		-v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
		robotics-sdk

Warning: repeated username and password prompts inside the container

If west init / west update keep prompting for a username and password while cloning the github.com/nxp-robotics repositories over HTTPS, and an SSH key is authorized on the nxp-robotics GitHub organization, make git use SSH instead. Mount the SSH directory when starting the container:

sudo docker run -it -v ~/robotics-workdir:/home/robotics \
		-v ~/.ssh:/home/robotics/.ssh:ro \
		robotics-sdk

Then, inside the container, rewrite GitHub HTTPS URLs to SSH before running west init / west update:

git config --global url."git@github.com:".insteadOf "https://github.com/"

This needs outbound SSH (port 22) to github.com; if the network blocks it, use a GitHub personal access token over HTTPS instead (see Troubleshooting).

Troubleshooting / FAQ

Docker build fails downloading the Zephyr SDK on WSL2 (Temporary failure in name resolution / unable to resolve host address 'github.com'). On WSL2, Docker containers run inside an extra virtualization layer (Hyper-V), whose isolated virtual network can lose DNS resolution for external hosts. Add --network=host to the docker build command so the container shares the WSL2 network stack directly (see the WSL2 warning under Flow B: building images from source).

docker build fails with No space left on device (often while unpacking vim-runtime or another apt package). The named package is incidental — the volume backing Docker’s storage (/var/lib/docker) ran out of room. Free space with docker system prune -af (and docker builder prune -f), and if the volume is too small, relocate Docker’s data-root to a larger one — see the disk-space warning.

docker run hello-world hangs or fails on the corporate network. Docker cannot reach Docker Hub without a proxy. Configure the Docker daemon proxy per the Docker documentation, then retry.

TLS / certificate-verification errors during docker build. The network performs TLS inspection and the corporate CA is not trusted inside the image. Install the corporate CA certificate as described in Corporate network.

The proxy example commands do not work. The http://<proxy>:<port> values are placeholders — substitute the proxy host and port for the local site. If no proxy is needed at all, drop the --build-arg http_proxy=... / -e http_proxy=... arguments.

git/west keeps asking for a username and password inside the container. Over HTTPS git prompts for credentials on every fetch from github.com/nxp-robotics. If an SSH key is authorized on the nxp-robotics organization, mount ~/.ssh into the container (-v ~/.ssh:/home/robotics/.ssh:ro) and rewrite GitHub HTTPS URLs to SSH with git config --global url."git@github.com:".insteadOf "https://github.com/" before running west init / west update (see the warning under Flow B: building images from source). This needs outbound SSH (port 22); if it is blocked, use a GitHub personal access token as the password over HTTPS and cache it with git config --global credential.helper 'cache --timeout=36000'.