NXP’s MCUXpresso Eclipse-based IDE is “supported” on Windows, Linux, and MacOS. As of v11.10.0 the officially supported OSs are:

• Linux: Ubuntu 20.04 LTS and 22.04 LTS (64-bit)
• Windows: Microsoft® Windows 10 and Windows 11
• macOS: v13 (Venture) / v14 (Sonoma)

To skip the explanation of why things don’t work and just get instructions for how to set everything up, jump below.

Although Ubuntu is the only officially supported Linux distribution, it should work correctly on most distributions since it’s just Eclipse with some plug-ins and customization. NXP have the following to say:

Due to the huge variation in capabilities of different Linux distributions and versions, MCUXpresso IDE may work on other distributions/versions but we cannot provide support if it does not.

In such circumstances, the MCUXpresso IDE forum is a good place to search for information or to post questions, as other users may be able to assist you.

MCUXpresso IDE Installation Guide

It’s in the Arch User Repository for Arch-based distro users and likely other distribution repos.

The IDE supports Linux, but this doesn’t mean that you can develop Zigbee firmware with it out of the box

If you try to import and build Zigbee examples such as AN-1243 / AN-1244 / AN-1257 etc., you’ll find that they won’t build under any platform. The IDE needs to be configured in a specific manner in order to run the examples. If you were lucky, you found the below document that describes the process. If not, you’re left to ask for help.

AN1260: Zigbee 3.0 Getting Started (Rev. 2.8 — Dec'23)

After following AN1260, you should be able to successfully build the Zigbee samples under Windows, but not Linux or macOS. NXP suggest to just use Windows, but there is a way.

NXP say it does’t work under Linux, but it easily could

There are several things stopping the build from working under Linux (and presumably macOS), but none of them are difficult to overcome. It took me a few hours to investigate the problems and get things working. It would be great if NXP could fix these issues upstream 🙏.

These are the four key problems

1) MCUXpresso installs itself in /opt, so non-root users can’t install plugins

Part of the setup process to build Zigbee apps in MCUXpresso (see AN1260) is installation of the Zigbee Configuration Editor plugin. This is an Eclipse-plugin for Zigbee config editing / code generation. Because MCUXpresso is installed in /opt, the plug-in installation fails when running MCUXpresso as a non-root user.

The error message provides no indication of the ultimate cause of the problem:

org.eclipse.equinox.p2.touchpoint.eclipse
Error
Fri Aug 09 18:05:21 HKT 2024
The artifact file for osgi.bundle,org.eclipse.jdt.core.manipulation,1.20.0.v20231115-2128 was not found.

The solution is to run MCUXpress via sudo, just for the plug-in installation. It seems users of other NXP SDKs might be experiencing the same problem.

The different install location also means that the Makefile paths for gcc, SDK location etc. need updating. That step is described below.

2) Two build scripts may not be executable and may be DOS CRLF formatted

As part of the build process, the PDUMConfig and ZPSConfig scripts are used for code generation. They are located in the SDK Zigbee tools folder (SDKPackages/[JN5189DK6]/middleware/wireless/zigbee/tools/).

The scripts are correctly written for Linux (bash scripts with embedded Python), but they may not be executable. I write may, because I’ve come across some that are. They may also be CRLF formatted if you forgot to select Linux in the SDK Builder.

The non-executable issue is reasonably obvious and presents with the following error:

make: /home/bob/nxp/SDKPackages/JN5189DK6/middleware/wireless/zigbee/tools/ZPSConfig/Source/ZPSConfig: Permission denied
...
Configuring the PDUM ...
make: /home/bob/nxp/SDKPackages/JN5189DK6/middleware/wireless/zigbee/tools/PDUMConfig/Source/PDUMConfig: Permission denied

It is easily fixed with a chmod +x.

The new line problem is far more subtle, producing the following cryptic error:

cannot execute: required file not found

Thankfully many people have encountered this before, and a search provided the solution.

3) Post-build scripts use py -3 to run Python 3

py is a utility on Windows that launches the various installed Python versions. py doesn’t exist on Linux, since it uses symlinks. py -3 runs Python 3 on Windows, which on Linux these days, is just python.

The post-build steps in a number of Makefiles use the py -3 command. E.g.:

py -3 $(K32W1_OTA_TOOL_PATH) -i $(APP_OUT_DIR)/$(TARGET_FULL).axf -d K32W1 -OtaMan $(MANUFACTURER_CODE) -OtaVersionStr $(OTA_STRING) -OtaImgTyp $(OTA_DEVICE_ID) -OtaFileVersion 1 --embed -o $(APP_OUT_DIR)/$(TARGET_FULL)_V1.axf
$(TOOLCHAIN_PATH)/$(OBJCOPY) -v -O binary $(APP_OUT_DIR)/$(TARGET_FULL)_V1.axf $(APP_OUT_DIR)/$(TARGET_FULL)_V1.bin
rm $(APP_OUT_DIR)/$(TARGET_FULL)_V1.axf

These need to be changed to python or python3. Use Eclipse’s file search to fix.

Interestingly, the Zigbee code gen scripts (PDUMConfig and ZPSConfig) correctly test for presence of the py command and fallback to python3:

which py 2>/dev/null 1>&2
if [ $? = 0 ];
then
  PYTHON="py -3"
else
  PYTHON="python3"

In general there seems to be a slow progression towards Linux support. PDUMConfig and ZPSConfig were Windows executables in older SDKs.

4) Several include files have case errors

In many of the examples, includes of headers from the SDK have case errors, which are ignored on Windows, but errors on Linux. For example, attempting compile AN-1257:

[HOME]/nxp/Workspace/JN-AN-1257/1-WindowCovering/Source/app_main.c:72:10: fatal error: PWR_interface.h: No such file or directory
   72 | #include "PWR_interface.h"
      |          ^~~~~~~~~~~~~~~~~
compilation terminated.

app_main.c includes PWR_interface.h, whereas the actual file from the [JN5189DK6] SDK is PWR_Interface.h:

$ find . -iname 'pwr_interface.h'
./middleware/wireless/framework/LowPower/Interface/jn5189dk6/PWR_Interface.h

There are several of these, which manifest as not found errors during the build and can be corrected by checking the correct case as above.

Done

Those are all of the problems that prevent building of the Zigbee sample applications on Linux. Once these are fixed, the build process is successful.

Step-by-step: How to setup NXP MCUXpresso to build the JN5189 Zigbee samples on Linux

Note: These instructions are for JN5189 MCU using the JN5189DK6 SDK. Change as required if using a different board. They were current as of SDK v2.6.15.

1) Follow the instructions in section 5 of AN1260: Zigbee 3.0 Getting Started to setup MCUExpresso, with the following changes:

1. Create an nxp folder in your home folder (MYHOME/nxp).
2. • 5.1: The Linux installer puts MCUExpresso in /opt. Leave it there.
   • 5.2: Create the Workspace folder as MYHOME/nxp/Workspace.
   • 5.3: Use MYHOME/nxp instead of C:\NXP.
   • 5.4: run MCUXpresso as root using sudo before installing the plug-in.

2) Fix the non-executable, DOS formatted config scripts

The two code gen scripts in the SDK may need to be marked executable and (possibly) converted to unix style line termination:

chmod +x [MYHOME]/SDKPackages/[JN5189DK6]/middleware/wireless/zigbee/tools/PDUMConfig/Source/PDUMConfig
dos2unix [MYHOME]/SDKPackages/[JN5189DK6]/middleware/wireless/zigbee/tools/PDUMConfig/Source/PDUMConfig
chmod +x [MYHOME]/SDKPackages/[JN5189DK6]/middleware/wireless/zigbee/tools/ZPSConfig/Source/ZPSConfig
dos2unix [MYHOME]/SDKPackages/[JN5189DK6]/middleware/wireless/zigbee/tools/ZPSConfig/Source/ZPSConfig

It can’t hurt to run these commands regardless, but you can always check if the files are CRLF formatted by running:

head -n 3 PDUMConfig | cat -e

> #!/bin/sh^M$
> ^M$
> SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)^M$

Lines ending in ^M$ are CRLF.

3) Update the makefiles to use the python command

Replace all py -3 instances in the base Makefiles with python.

4) Update the Makefile paths

AN-1260 describes updating the JENNIC_CHIP variable in the Makefile for the specific board/SDK you’re using. In addition to this, the toolchain path needs to be updated:

#TOOLCHAIN_DIR_PATH = ../../../../../MCUXpressoIDE_11.7.1_9221/ide/tools
# This depends on where you have the GNU ARM tools installed
# It should be the parent of the bin folder
TOOLCHAIN_DIR_PATH  = /usr

# You'll also need to update the gawk path if using. Your location may differ:
#AWK_EXE             = $(APP_BASE)/../../gawk-3.1.6-1-bin/bin/gawk.exe
AWK_EXE             = /usr/bin/gawk

Keep in mind that there are multiple base Makefiles. One for each build configuration (e.g. Coordinator, Router etc.)

5) Fix header include case errors

When you attempt to build, you will likely get file not found include errors like this:

[HOME]/nxp/Workspace/JN-AN-1257/1-WindowCovering/Source/app_main.c:72:10: fatal error: PWR_interface.h: No such file or directory
   72 | #include "PWR_interface.h"
      |          ^~~~~~~~~~~~~~~~~
compilation terminated.

This is because the filename has case errors. Find the correct name and update the source by doing a case-insensitive search such as this (from the SDK parent folder):

$ find . -iname 'pwr_interface.h'
./middleware/wireless/framework/LowPower/Interface/jn5189dk6/PWR_Interface.h

6) OPTIONAL: Change busybox cat to cat

Some makefiles call busybox cat xxx.txt to print various stats to the console during the build. Do a search/replace from busybox cat to cat to fix this. This is optional, as the failed calls won’t stop the build.

Problem (mostly) solved

With these issues resolved, everything should build correctly. Even if there are further errors, they are likely to be the same class of problems and should be easily resolved in the same way.

As mentioned at the beginning, you’ll still need Windows to produce encrypted images. You’ll also need Windows to program the device via serial ISP as I haven’t as yet been able to get the DK6Programmer working on Wine.

NXP have been “handling the matter internally” for the past four years, so I wouldn’t expect changes any time soon.